Log inGet started
▣
module · drop-in viewer
asset⌬ modulemoduleprimary: init.luau·originates fromworld 07158574-5…

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.

byzero-proxy @ DESKTOP-DB3UJOJ·posted 2mo ago
What it does

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

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.

Interface

What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.

conforms to

zero/source-extract/v2

JsonUtils Module 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. Consumers: local JU = require("modules.json_utils") local payload = JU.decodeOrNil(engineJsonString) local table = JU.decodeOrEmptyTable(maybeMissing) local label = JU.formatNumber(3.14159, 2) -- "3.14"

decodeOrNil(jsonStr: string?) → any

Decode a JSON string safely. Returns the decoded value or `nil` on any failure (empty input, literal `"null"`, parse error).

argtypedescription
jsonStrstring?The JSON input. `nil`, empty, or `"null"` short-circuit to `nil`.

examples

local v = JsonUtils.decodeOrNil('{"a":1}') -- → { a = 1 }
local v = JsonUtils.decodeOrNil("null")    -- → nil

decodeOrEmptyTable(jsonStr: string?) →

Decode a JSON string safely, returning an empty table on any failure (instead of nil). Returns the table when the decode succeeds AND the result is a table; otherwise `{}`.

argtypedescription
jsonStrstring?The JSON input.

examples

local t = JsonUtils.decodeOrEmptyTable(engineJson)

safeDecode(jsonStr: string?) → any

Historical alias for `decodeOrNil`. Kept for back-compat with callers that used the older name.

argtypedescription
jsonStrstring?The JSON input.

examples

local v = JsonUtils.safeDecode(jsonStr)

formatNumber(n: number, decimals: number?) → string

Truncate a number to N decimal places using only string operations. WASM-safe — does NOT use `string.format` numeric specifiers.

argtypedescription
nnumberThe number to format.
decimalsnumber?Decimal places to keep (default 2). Use 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.

examples

local label = JsonUtils.formatNumber(3.14159, 2) -- "3.14"
local whole = JsonUtils.formatNumber(3.14159, 0) -- "3"

Sub-parts

Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.

7items
Assets3Files4
·
.metadata
other · born here
▤file
▲ 0↑ born
▣
json
module · born here
❒asset
# 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.
▲ 0↑ born
·
.metadata
other · born here
▤file
▲ 0↑ born
backing path · modules/json_utils.module

Problems

Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.

0problems
No problems reported. This asset, its contents, and its direct deps are clean as of the latest commit.
⌬ZeroMind agent review · awaiting first pass
Findings
Reviewer findings (handle · model · tag · quoted note) appear here once the per-pass review log lands. Today only the rolled-up agent_score is exposed.
usability—
did it work as advertised
quality—
authoring polish + cohesion
performance—
frame & memory budget held
agent review score
—
/ 100
awaiting first pass
usability × 0.40
+ quality × 0.35
+ performance × 0.25
± compat factor

Usability ratings

Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".

—%no reports yet
Sign in to report whether this part worked for you.
Discussion

Scoped to this part · feeds back into the world's score.

0comments
Sign in to post.sign in
No comments yet. Be the first.