serde

Built-in library for:

• serialization & deserialization
• encoding & decoding
• compression

Example usage

local fs = require("@lune/fs")
local serde = require("@lune/serde")

-- Parse different file formats into lua values
local someJson = serde.decode("json", fs.readFile("myFile.json"))
local someToml = serde.decode("toml", fs.readFile("myFile.toml"))
local someYaml = serde.decode("yaml", fs.readFile("myFile.yaml"))

-- Write lua values to files in different formats
fs.writeFile("myFile.json", serde.encode("json", someJson))
fs.writeFile("myFile.toml", serde.encode("toml", someToml))
fs.writeFile("myFile.yaml", serde.encode("yaml", someYaml))

Functions

encode

function serde.encode(format: EncodeDecodeFormat, value: any, pretty: boolean?): string

must_use

Encodes the given value using the given format.

See [EncodeDecodeFormat] for a list of supported formats.

Base64 and hex encoding accept strings and buffers.

JSON writes a buffer the way Roblox’s HttpService:JSONEncode does, as {"m":null,"t":"buffer","base64":"..."}, or with zbase64 and the bytes compressed with zstd when that is shorter. A game reads it back as a buffer.

Parameters

• format - The format to use
• value - The value to encode
• pretty - If the encoded string should be human-readable, including things such as newlines and spaces. Only supported for json and toml formats, and defaults to false

Returns

• The encoded string

decode

function serde.decode(format: EncodeDecodeFormat, encoded: buffer | string): any

must_use

Decodes the given string using the given format into a lua value.

See [EncodeDecodeFormat] for a list of supported formats.

JSON and JSONC read an object Roblox’s HttpService:JSONEncode wrote for a buffer, with base64 or zbase64, as a buffer - one stored in a DataStore and fetched through Open Cloud, for example.

Parameters

• format - The format to use
• encoded - The string or buffer to decode

Returns

• The decoded value

compress

function serde.compress(
  format: CompressDecompressFormat,
  s: buffer | string,
  level: number?
): string

must_use

Compresses the given string using the given format.

See [CompressDecompressFormat] for a list of supported formats.

Parameters

• format - The format to use
• s - The string to compress
• level - The compression level to use, clamped to the format’s limits. The best compression level is used by default

Returns

• The compressed string

decompress

function serde.decompress(format: CompressDecompressFormat, s: buffer | string): string

must_use

Decompresses the given string using the given format.

See [CompressDecompressFormat] for a list of supported formats.

Parameters

• format - The format to use
• s - The string to decompress

Returns

• The decompressed string

hash

function serde.hash(algorithm: HashAlgorithm, message: string | buffer): string

must_use

Hashes the given message using the given algorithm and returns the hash as a hex string.

See [HashAlgorithm] for a list of supported algorithms.

Parameters

• algorithm - The algorithm to use
• message - The message to hash

Returns

• The hash as a hex string

hmac

function serde.hmac(
  algorithm: HashAlgorithm,
  message: string | buffer,
  secret: string | buffer
): string

must_use

Hashes the given message using HMAC with the given secret and algorithm, returning the hash as a hex string.

See [HashAlgorithm] for a list of supported algorithms.

Parameters

• algorithm - The algorithm to use
• message - The message to hash
• secret - The secret key to use

Returns

• The hash as a hex string

Types

EncodeDecodeFormat

export type EncodeDecodeFormat = "base64" | "hex" | "json" | "jsonc" | "yaml" | "toml"

A serialization or binary-to-text encoding format supported by the Serde library.

Currently supported formats:

Name	Learn More	Note
base64	https://www.rfc-editor.org/rfc/rfc4648.html	Binary-to-text encoding
hex	https://www.rfc-editor.org/rfc/rfc4648.html	Binary-to-text encoding
json	https://www.json.org
jsonc	https://www.json.org	JSON, with comments allowed
yaml	https://yaml.org
toml	https://toml.io

CompressDecompressFormat

export type CompressDecompressFormat = "brotli" | "gzip" | "lz4" | "zlib" | "zstd"

A compression/decompression format supported by the Serde library.

Currently supported formats:

Name	Learn More
brotli	https://github.com/google/brotli
gzip	https://www.gnu.org/software/gzip
lz4	https://github.com/lz4/lz4
zlib	https://www.zlib.net
zstd	https://github.com/facebook/zstd

HashAlgorithm

export type HashAlgorithm =
  "md5"
  | "sha1"
  | "sha224"
  | "sha256"
  | "sha384"
  | "sha512"
  | "sha3-224"
  | "sha3-256"
  | "sha3-384"
  | "sha3-512"
  | "blake3"

A hash algorithm supported by the Serde library.

Currently supported algorithms:

Name	Learn More
md5	https://en.wikipedia.org/wiki/MD5
sha1	https://en.wikipedia.org/wiki/SHA-1
sha224	https://en.wikipedia.org/wiki/SHA-2
sha256	https://en.wikipedia.org/wiki/SHA-2
sha384	https://en.wikipedia.org/wiki/SHA-2
sha512	https://en.wikipedia.org/wiki/SHA-2
sha3-224	https://en.wikipedia.org/wiki/SHA-3
sha3-256	https://en.wikipedia.org/wiki/SHA-3
sha3-384	https://en.wikipedia.org/wiki/SHA-3
sha3-512	https://en.wikipedia.org/wiki/SHA-3
blake3	https://en.wikipedia.org/wiki/BLAKE3