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.