# json_utils Safe JSON decoding helpers and a WASM-safe number formatter. Wraps `Json.decode` with `pcall` so engine-provided JSON strings can't propagate parse errors into call sites. Also handles the engine convention of writing the literal string `"null"` when a JSON value is absent. ## Exports - `M.decodeOrNil(jsonStr: string?) -> any` — safe decode; returns `nil` on empty input, `"null"`, or parse failure. - `M.decodeOrEmptyTable(jsonStr: string?) -> table` — safe decode; returns `{}` on any failure or non-table result. - `M.safeDecode(jsonStr: string?) -> any` — historical alias for `decodeOrNil`. - `M.formatNumber(n: number, decimals?: number) -> string` — truncate a number to N decimal places using only string ops. WASM-safe. ## Usage ```luau local JsonUtils = require("@builtin::modules.json_utils") local payload = JsonUtils.decodeOrNil(engineJsonString) local table = JsonUtils.decodeOrEmptyTable(maybeMissing) local label = JsonUtils.formatNumber(3.14159, 2) -- "3.14" ``` ## Notes - `decodeOrNil` short-circuits on `nil`, empty string, and the literal string `"null"`. The Json.decode call itself is wrapped in `pcall`, so malformed input is never observable to callers. - `decodeOrEmptyTable` is intentionally strict: non-table decode results (numbers, strings, booleans, nil) collapse to `{}`. Use `decodeOrNil` if you need to distinguish those. - `formatNumber` uses `tostring` + `string.sub` so it avoids the `string.format` numeric specifiers that don't work reliably under WASM in Luau. Pass `decimals = 0` to drop the fractional part entirely; a count below `0` reads the same as `0`, and a fractional count counts the whole places in it. - `formatNumber` truncates the mantissa of a value `tostring` renders in exponent form (`1.5e-07`) and keeps the exponent, so the result still reads back through `tonumber`.

# json JSON encode/decode library for Luau. Encodes Lua values to JSON strings and decodes JSON strings back to Lua values. Used for communication with the Rust side of the engine, the VFS read/write bridge, and any wire-format that needs JSON. Pure Luau, no engine dependencies. Compact and pretty-printed encoders, plus a hand-rolled decoder that streams the input by position so it works under WASM as well as native. ## Exports - `Json.encode(value: any, indent?: string, currentIndent?: string) -> string` — compact encode. Functions / unknown types and NaN/Inf encode as `null`. - `Json.encodePretty(value: any, indentStr?: string) -> string` — pretty-printed encode with sorted object keys (diff-friendly). - `Json.encodeArgs(...: any) -> string` — encode varargs as a JSON array. - `Json.decode(str: string) -> any` — decode a JSON string. Returns the decoded value, or `nil` + error message on failure. ## Usage ```luau local Json = require("@builtin::modules.json") local widget = { type = "button", text = "Click Me" } local compact = Json.encode(widget) -- '{"text":"Click Me","type":"button"}' local pretty = Json.encodePretty(widget, " ") local decoded = Json.decode(compact) local v, err = Json.decode("oops") -- v = nil, err = error message ``` ## Notes - Object keys are sorted alphabetically in both encoders for consistent output across runs. - Numeric keys on objects are stringified at encode time (JSON has no numeric keys). Pure-integer key sets get detected as arrays via `isArray` and encoded with brackets. - NaN, +Inf, -Inf encode as `null` — JSON has no representation. Round trips through `decode` recover `null` (Lua `nil`), so they don't preserve. - Unicode `\uXXXX` escapes decode to UTF-8 by hand to stay WASM-safe. Only the BMP is covered; supplementary planes via surrogate pairs are not. - Functions encode as `null`. - Decode is character-streamed — no regex, no `string.match` patterns on the whole input — so the line-and-column information needs to be reconstructed from the position offset.