---@meta
---@diagnostic disable: missing-return
-- Type stubs for the NATIVE half of the `utils` module: the JSON codec, the
-- NULL sentinel and the pretty-printer. The Lua-implemented half (utils.try,
-- utils.tryn) lives in lua/stdlib/utils.lua and needs no stub.
-- Reference: docs/utils.md

utils = {}

---Sentinel standing for an explicit null in tables (a Lua nil would mean "key
---absent" — assigning nil deletes the key). Produced by fromJSON for JSON
---null; serialized back to null by toJSON and the http helpers; binds SQL
---NULL in sqlite. Compare with utils.isNull.
---@type userdata
utils.NULL = nil

---Serialize a Lua value to a JSON string. A table with keys exactly 1..#t
---becomes an array, any other table an object; utils.NULL becomes null.
---Raises on NaN/infinity, values with no JSON form, or nesting beyond 64.
---@param value any
---@param pretty boolean? indented multi-line output (default compact)
---@return string
function utils.toJSON(value, pretty) end

---Parse a JSON string into a Lua value. JSON null decodes to utils.NULL (not
---nil), so nulls inside arrays do not create gaps. Invalid JSON raises.
---@param str string
---@return any
function utils.fromJSON(str) end

---True if value is the utils.NULL sentinel. isNull(nil) is false.
---@param value any
---@return boolean
function utils.isNull(value) end

---Render any Lua value as a readable string, for logging and inspection.
---Cycles print as <circular>; nesting is capped at 20 levels.
---@param value any
---@return string
function utils.dump(value) end