@eryx/data/json Module

JSON encoding and decoding.

Serialises Luau values to JSON text and parses JSON text back into Luau values. By default decoding follows RFC 8259 JSON, with optional flags for JSON5-style and JSONC-style extensions.

local json = require("@eryx/data/json")

local str = json.encode({ name = "Alice", scores = {100, 97} })
print(str)  -- '{"name":"Alice","scores":[100,97]}'

local tbl = json.decode('{"x":1,"y":2}')
print(tbl.x, tbl.y)  -- 1  2

local json5 = json.decode("{foo: 0x2A, bar: 'hi'}", json.JSON5)
print(json5.foo, json5.bar) -- 42  hi

Mapping rules:

Luau JSON
string string
number number
boolean true / false
nil null
Numeric table array []
Mixed table object {}

Summary

Functions

json.encode(value: any, options: EncodeOptions?) → string
json.decode(str: string, options: DecodeOptions?) → any
json.tableIsArray(table: { [any]: any }) → ()
json.tableAsArray<T>(table: { T }) → { T }

API Reference

Functions

json.encode

Encodes a Luau value as a JSON string.

Tables with sequential integer keys (1 .. n) are encoded as JSON arrays. Tables with string keys are encoded as JSON objects. Nested structures are fully supported.

Set options.pretty to true for indented, human-readable output. Set options.sortKeys to true to emit object keys in alphabetical order.

json.encode(value: any, options: EncodeOptions?) → string

Parameters

value: any

-- The value to encode.

options: EncodeOptions?

Optional formatting options.

Returns

string

The JSON string.

json.decode

Decodes a JSON string into a Luau value.

JSON Luau
string string
number number
true / false boolean
null nil
array [] Numeric table
object {} { [string]: any }

Note: JSON null values inside arrays will create holes in the resulting Luau table. Standalone null at the top level returns nil.

json.decode(str: string, options: DecodeOptions?) → any

Parameters

str: string

A valid JSON string.

Returns

any

The decoded Luau value.

json.tableIsArray

A Luau table with 0 entries could be a json object ({}) or a JSON array ([]).

Use this function on the values returned by decode if you need to decern the difference.

json.tableIsArray(table: { [any]: any }) → ()

json.tableAsArray

A Luau table with 0 entries could be a json object ({}) or a JSON array ([]).

Use this function on a value being passed to encode to explicitly mark it as an array

json.tableAsArray<T>(table: { T }) → { T }

Types

EncodeOptions
type EncodeOptions = { pretty: boolean?, indent: string?, sortKeys: boolean? }
pretty: boolean?

Insert newlines and indentation for readability.

indent: string?

Indentation string used when pretty is enabled (default " " - two spaces).

sortKeys: boolean?

Sort object keys alphabetically.

DecodeOptions
type DecodeOptions = { comments: boolean?, trailingComma: boolean?, singleQuotedStrings: boolean?, multilineStrings: boolean?, unquotedKeys: boolean?, json5Numbers: boolean?, json5Whitespace: boolean?, json5Escapes: boolean? }
comments: boolean?

Allow comments using // or /* ... */

trailingComma: boolean?

Allow trailing commas, eg [1, 2, 3, ]

singleQuotedStrings: boolean?

Allow single quoted strings, eg 'foo'

multilineStrings: boolean?

Allow escaping a newline in a string with a backslash

unquotedKeys: boolean?

Allow unquoted keys, eg {foo: "bar"}

json5Numbers: boolean?

Add support for JSON5's additional numbers (NaN, Infinity, 0xFF, +1, .5, 5.)

json5Whitespace: boolean?

Allow JSON5's additional whitespace characters such as NBSP, BOM, LS/PS, and other Zs characters.

json5Escapes: boolean?

Allow JSON5 string escapes such as \xNN, \v, and \0.