nupp.codec.json

nupp.codec.json is a strict Nupp JSON codec. Its performance provider is SIMD-accelerated through @aot; compiler and browser targets select a pure-Lua provider behind the same API. It parses, pulls selected fields, serializes, and streams.

local encoded = nupp.codec.json.encode({name = "Nupp", ready = true})
local decoded = assert(nupp.codec.json.decode(encoded))
assert(decoded.name == "Nupp")

The codec accepts one complete UTF-8 JSON document and rejects invalid numbers, sparse arrays, mixed-key containers, cycles, and excessive nesting. An object that names one member twice is refused at the second occurrence, as I-JSON requires, even when the first held a null that decoding drops. A number too large for binary64, such as 1e400, is refused with its byte position rather than read as an infinity the encoder would refuse to write back; one too small, such as 1e-400, is zero.

Empty containers#

A plain empty Lua table has no shape to read, so it encodes as {}. Mark it when it must encode as an array, or use the two sentinels:

const json = nupp.codec.json

assert(json.encode({}) == "{}")
assert(json.encode(json.asArray({})) == "[]")
assert(json.encode(json.EMPTY_ARRAY) == "[]")
assert(json.encode(json.EMPTY_OBJECT) == "{}")

local emptyArray = assert(json.decode("[]"))
assert(json.isArray(emptyArray))
assert(not json.isArray(assert(json.decode("{}"))))

asObject is the corresponding mark for a table that must encode as an object. isArray reads the shape retained by decoded containers, including when they are empty.

JSON null#

Decoding drops JSON null by default, including from inside an array. Pass a replacement value to preserve it. NULL is the round-trippable choice, because it encodes back as null:

const json = nupp.codec.json

local value = assert(json.decode([[{"items":[1,null,2]}]], json.NULL))
assert(value.items[2] == json.NULL)
assert(json.encode(value) == [[{"items":[1,null,2]}]])

Pulling selected values#

pull validates the complete document while applying its selection. true selects a complete value, an object shape selects named fields, and arrayOf(shape) applies a shape to every member of an array. Missing and unselected fields are omitted:

const json = nupp.codec.json

local source = '[{"id": 1, "role": "admin", "profile": {"name": "Ada", "age": 36}}]'
local users, reason = json.pull(source, json.arrayOf({id = true, profile = {name = true}}))

This is the lower-level path for pull deserializers: it validates the complete input but constructs only the Lua values the shape asks for.

Streaming output#

The nupp.Closeable writer emits checked JSON into caller-owned storage without first building a Lua table or a complete result string. endArray() and endObject() end containers, flush() publishes a bounded staged batch while leaving the document open, and consuming close() requires one complete root:

local out = nupp.text.newBuffer()
local writer = nupp.codec.json.newWriter(out)
writer:startObject():key("items"):startArray():write(1):write(2):endArray():endObject()
writer:close()

Lexical destruction closes a live writer automatically. The public writer identity is single-use. Closing publishes its final staged parts and leaves that identity closed; untyped stale references therefore cannot affect a later document.

A prepared nupp.serde JSON traversal can write at the current value position. Its recursive walk drains completed fields and list members at the same threshold, so a large root does not need to exist as one staged string.

encoded(value) performs ordinary encoding once. verified(text) instead validates an existing immutable JSON string without decoding or re-encoding it. Both return a value that write appends without another walk or validation. encodedString(value) and verifiedString(text) provide the corresponding string-only form accepted by both key and write; these handles are interned, so repeated schema keys share their encoded representation.

Typed values#

Select a declaration binding and pass it to the typed JSON codec. A binding chooses the model independently of the format.

local serde = require("nupp.serde")
local json = require("nupp.serde.json")
local record User
    id: uint32
end
local users = serde.binding(User)
local value = json.decode(users, '{"id":41}')
assert(json.encode(users, value) == '{"id":41}')

See Serialization bindings for mappings, documents, and external models.

record EncodedString

record EncodedValue

interface JSONEncodable ...

local record Money is nupp.codec.json.JSONEncodable
    cents: integer

    function writeJSON(self, exclusive out: nupp.codec.json.Writer): nil
        out:startObject():key("cents"):write(self.cents):endObject()
    end
end

writeJSON: function(self, exclusive out: Writer): nil

interface Writer is nupp.Closeable ...

local out = nupp.text.newBuffer()
local writer = nupp.codec.json.newWriter(out)
writer:startObject():key("ok"):write(true):endObject()
writer:close()
assert(out:tostring() == [[{"ok":true}]])

startArray: function(exclusive self: Writer): Writer borrows (self)

local out = nupp.text.newBuffer()
local writer = nupp.codec.json.newWriter(out)
writer:startArray():write("first"):endArray()
writer:close()
assert(out:tostring() == "[\"first\"]")

startObject: function(exclusive self: Writer): Writer borrows (self)

local out = nupp.text.newBuffer()
local writer = nupp.codec.json.newWriter(out)
writer:startObject():endObject()
writer:close()
assert(out:tostring() == "{}")

key: function(exclusive self: Writer, name: string): Writer borrows (self)
& function(exclusive self: Writer, name: EncodedString): Writer borrows (self)

local out = nupp.text.newBuffer()
local writer = nupp.codec.json.newWriter(out)
writer:startObject():key("answer"):write(42):endObject()
writer:close()
assert(out:tostring() == [[{"answer":42}]])

write: function(
    exclusive self: Writer,
    value: string | number | boolean | {any} | {[string]: any}
): Writer borrows (self)
    & function(
        exclusive self: Writer,
        value: EncodedValue | EncodedString
    ): Writer borrows (self)

local out = nupp.text.newBuffer()
local writer = nupp.codec.json.newWriter(out)
writer:startArray():write({id = 41}):endArray()
writer:close()
assert(out:tostring() == "[{\"id\":41}]")

null: function(exclusive self: Writer): Writer borrows (self)

local out = nupp.text.newBuffer()
local writer = nupp.codec.json.newWriter(out)
writer:startArray():null():endArray()
writer:close()
assert(out:tostring() == "[null]")

endArray: function(exclusive self: Writer): Writer borrows (self)

local out = nupp.text.newBuffer()
local writer = nupp.codec.json.newWriter(out)
writer:startArray():startObject():endObject():endArray()
writer:close()
assert(out:tostring() == "[{}]")

endObject: function(exclusive self: Writer): Writer borrows (self)

local out = nupp.text.newBuffer()
local writer = nupp.codec.json.newWriter(out)
writer:startObject():key("items"):startArray():endArray():endObject()
writer:close()
assert(out:tostring() == [[{"items":[]}]])

flush: @nosuspend function(exclusive self: Writer): nil

local out = nupp.text.newBuffer()
local writer = nupp.codec.json.newWriter(out)
writer:startArray():write(1)
writer:flush()
assert(out:tostring() == "[1")
writer:endArray()
writer:close()
assert(out:tostring() == "[1]")

abort: @nosuspend function(exclusive self: Writer): nil

close: @nosuspend function(takes self: Writer): nil

local out = nupp.text.newBuffer()
local writer = nupp.codec.json.newWriter(out)
writer:write({ok = true})
writer:close()
assert(out:tostring() == [[{"ok":true}]])

function arrayOf(shape: any?): table

const json = nupp.codec.json
local users = assert(json.pull(
    [[{"users":[{"id":1,"name":"Ada"},{"id":2,"name":"Lin"}]}]],
    {users = json.arrayOf({id = true})}
))
assert(users.users[1].id == 1 and users.users[1].name == nil)
assert(users.users[2].id == 2)

function asArray<T is table>(takes value: T): T preserves value

local values = nupp.codec.json.asArray({})
assert(nupp.codec.json.encode(values) == "[]")

function asObject<T is table>(takes value: T): T preserves value

const json = nupp.codec.json
local object = json.asObject(json.asArray({}))
assert(json.encode(object) == "{}")

function decode(text: string, nullValue: any?): any, string?

local value, reason = nupp.codec.json.decode([[{"id":41}]])
assert(reason == nil and value.id == 41)
local broken, why = nupp.codec.json.decode([[{"id":]])
assert(broken == nil and why ~= nil)

function encode(value: any, nullValue: any?): string

local text = nupp.codec.json.encode({answer = 42})
assert(text == [[{"answer":42}]])

function encoded(value: any, nullValue: any?): EncodedValue

local cached = nupp.codec.json.encoded({1, 2, 3})

function encodedString(value: string): EncodedString

local key = nupp.codec.json.encodedString("user_id")

function isArray(value: any): boolean

const json = nupp.codec.json
assert(json.isArray(assert(json.decode("[]"))))
assert(not json.isArray(assert(json.decode("{}"))))
assert(json.isArray({1, 2}))

function newWriter(exclusive out: Buffer, nullValue: any?): Writer

local out = nupp.text.newBuffer()
local writer = nupp.codec.json.newWriter(out)
writer:startObject():key("id"):write(41):endObject()
writer:close()
assert(out:tostring() == [[{"id":41}]])

function numberToken(text: string): EncodedValue

local json = nupp.codec.json
assert(json.encode(json.numberToken("12345678901234567890")) == "12345678901234567890")

function pull(text: string, shape: any, nullValue: any?): any, string?

local value = assert(nupp.codec.json.pull(
    [[{"id":41,"profile":{"name":"Ada","admin":true}}]],
    {id = true, profile = {name = true}}
))
assert(value.id == 41 and value.profile.name == "Ada")
assert(value.profile.admin == nil)

function verified(text: string): EncodedValue

local cached = nupp.codec.json.verified([[{"id":41}]])

function verifiedString(text: string): EncodedString

local key = nupp.codec.json.verifiedString([["user_id"]])

const EMPTY_ARRAY: table

const EMPTY_OBJECT: table

const NULL: any