`nupp.codec.json.spi`

Module contents

Types

Type	Kind	Description
`EncodedString`	record	A JSON string whose immutable encoded bytes have already been produced or validated.
`EncodedValue`	record	A complete JSON value whose immutable bytes have already been encoded or validated.
`JSONEncodable`	interface	Values that can write one complete JSON value through a checked writer.
`MarkContainer`	type	Marks a table while returning the same generic table and ownership.
`Provider`	interface	JSON API 2, including portable encoding and optional compiled serde.
`Writer`	interface	A checked incremental JSON writer.

Types#

`EncodedString`record#

record EncodedString

A JSON string whose immutable encoded bytes have already been produced or validated.

Writer:key accepts this type without validating UTF-8 or escaping it again. Values produced by encodedString and verifiedString are interned.

`EncodedValue`record#

record EncodedValue

A complete JSON value whose immutable bytes have already been encoded or validated.

Values come from encoded or verified; the private token prevents checked callers from manufacturing an unverified fast-path value.

`JSONEncodable`interface#

interface JSONEncodable ...

Values that can write one complete JSON value through a checked writer.

nupp.codec.json names it for callers; it is declared here so the modules the facade reads, nupp.serde and nupp.derive among them, can name it without reading the facade. Writer below names the encoder newWriter() returns.

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

Members

Name	Kind	Description
`writeJSON`	method	Writes this value at the writer's current value position.

`writeJSON`method#

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

Writes this value at the writer's current value position.

Arguments

Name	Type	Description
`?`	`self`
`exclusive out`	`Writer`	the checked destination

Returns

Type	Description
`nil`

`MarkContainer`type#

type MarkContainer = function<T is table>(takes value: T): T preserves value

Marks a table while returning the same generic table and ownership.

The takes/preserves relation is intentional: an implementation must not copy the container or erase an affine owner while applying its JSON marker.

`Provider`interface#

interface Provider ...

JSON API 2, including portable encoding and optional compiled serde.

Arrays, objects, null sentinels, and verified fragments must agree across every member of this table. Keep marker identities stable for the loaded provider. The caller's nullValue controls null conversion; omission follows the public JSON API's nil behavior. Reject malformed syntax, invalid UTF-8, unsupported container shapes, and invalid raw fragments according to that API.

The three serde hooks are optional accelerators. If supplied together, compiled schemas and both decode entry points must share their representation and unknown-member policy. All buffer operations use the canonical shared Buffer; they must preserve the declared exclusive access and ownership guarantees.

Members

Name	Kind	Description
`priority`	field
`arrayOf`	method	Builds an array projection shape with the supplied element shape.
`asArray`	field	Marks and returns the same table as an array, preserving its ownership.
`asObject`	field	Marks and returns the same table as an object, preserving its ownership.
`isArray`	method	Reports whether a value has JSON array semantics.
`decode`	method	Parses JSON, applying the caller-selected representation of null.
`encode`	method	Serializes a value with this provider's markers and null convention.
`encoded`	method	Creates a validated encoded-value fragment for subsequent composition.
`encodedString`	method	Creates a fragment containing one escaped JSON string.
`pull`	method	Parses only the value projection described by shape.
`verified`	method	Validates raw JSON and retains a fragment suitable for composition.
`verifiedString`	method	Validates a raw encoded JSON string fragment.
`newWriter`	method	Creates a JSON writer over exclusive access to the canonical buffer.
`NULL`	field	Stable explicit null marker owned by this loaded implementation.
`EMPTY_ARRAY`	field	Stable empty-array marker value.
`EMPTY_OBJECT`	field	Stable empty-object marker value.
`compileSerde`	field	Optionally prepares a schema plan with its unknown-member policy.
`decodeSerde`	field	Optionally decodes a prepared schema, returning value or diagnostic.
`decodeSerdeBuffer`	field	Optionally decodes from exclusive access to the canonical buffer.

`priority`field#

priority: integer?

@readonly

`arrayOf`method#

arrayOf: function(shape: any?): any

@readonly

Builds an array projection shape with the supplied element shape.

Arguments

Name	Type	Description
`shape`	`any?`

Returns

Type	Description
`any`

`asArray`field#

asArray: MarkContainer

@readonly

Marks and returns the same table as an array, preserving its ownership.

`asObject`field#

asObject: MarkContainer

@readonly

Marks and returns the same table as an object, preserving its ownership.

`isArray`method#

isArray: function(value: any): boolean

@readonly

Reports whether a value has JSON array semantics.

Arguments

Name	Type	Description
`value`	`any`

Returns

Type	Description
`boolean`

`decode`method#

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

@readonly

Parses JSON, applying the caller-selected representation of null.

Arguments

Name	Type	Description
`text`	`string`
`nullValue`	`any?`

Returns

Type	Description
`any`

`encode`method#

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

@readonly

Serializes a value with this provider's markers and null convention.

Arguments

Name	Type	Description
`value`	`any`
`nullValue`	`any?`

Returns

Type	Description
`string`

`encoded`method#

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

@readonly

Creates a validated encoded-value fragment for subsequent composition.

Arguments

Name	Type	Description
`value`	`any`
`nullValue`	`any?`

Returns

Type	Description
`any`

`encodedString`method#

encodedString: function(value: string): any

@readonly

Creates a fragment containing one escaped JSON string.

Arguments

Name	Type	Description
`value`	`string`

Returns

Type	Description
`any`

`pull`method#

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

@readonly

Parses only the value projection described by shape.

Arguments

Name	Type	Description
`text`	`string`
`shape`	`any`
`nullValue`	`any?`

Returns

Type	Description
`any`

`verified`method#

verified: function(text: string): any

@readonly

Validates raw JSON and retains a fragment suitable for composition.

Arguments

Name	Type	Description
`text`	`string`

Returns

Type	Description
`any`

`verifiedString`method#

verifiedString: function(text: string): any

@readonly

Validates a raw encoded JSON string fragment.

Arguments

Name	Type	Description
`text`	`string`

Returns

Type	Description
`any`

`newWriter`method#

newWriter: function(exclusive out: SharedBuffer, nullValue: any?): any

@readonly

Creates a JSON writer over exclusive access to the canonical buffer.

Arguments

Name	Type	Description
`exclusive out`	`SharedBuffer`
`nullValue`	`any?`

Returns

Type	Description
`any`

`NULL`field#

NULL: any

@readonly

Stable explicit null marker owned by this loaded implementation.

`EMPTY_ARRAY`field#

EMPTY_ARRAY: table

@readonly

Stable empty-array marker value.

`EMPTY_OBJECT`field#

EMPTY_OBJECT: table

@readonly

Stable empty-object marker value.

`compileSerde`field#

compileSerde: (function(plan: any, unknownMembers: string): any)?

@readonly

Optionally prepares a schema plan with its unknown-member policy.

`decodeSerde`field#

decodeSerde: (function(schema: any, text: string): (any?, string?))?

@readonly

Optionally decodes a prepared schema, returning value or diagnostic.

`decodeSerdeBuffer`field#

decodeSerdeBuffer: (function(schema: any, exclusive input: SharedBuffer): (any?, string?))?

@readonly

Optionally decodes from exclusive access to the canonical buffer.

`Writer`interface#

interface Writer is nupp.Closeable ...

A checked incremental JSON writer.

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}]])

Members

Name	Kind	Description
`startArray`	method	Starts an array value.
`startObject`	method	Starts an object value.
`key`	method	Selects the next object member.
`write`	method	Appends one complete Lua value.
`null`	method	Appends JSON null.
`endArray`	method	Ends the current array.
`endObject`	method	Ends the current object.
`flush`	method	Publishes staged bytes without ending the document.
`close`	method	Verifies and publishes one complete root, then releases backing state.

`startArray`method#

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

Starts an array value.

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

Arguments

Name	Type	Description
`exclusive self`	`Writer`	the writer

Returns

Type	Description
`Writer borrows (self)`	this writer

`startObject`method#

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

Starts an object value.

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

Arguments

Name	Type	Description
`exclusive self`	`Writer`	the writer

Returns

Type	Description
`Writer borrows (self)`	this writer

`key`method#

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

Selects the next object member.

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}]])

Arguments

Name	Type	Description
`exclusive self`	`Writer`	the writer
`name`	`string`	the next member name

Returns

Type	Description
`Writer borrows (self)`	this writer

`write`method#

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)

Appends one complete Lua value.

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}]")

Arguments

Name	Type	Description
`exclusive self`	`Writer`	the writer
`value`	`string \| number \| boolean \| {any} \| {[string]: any}`	the next JSON value

Returns

Type	Description
`Writer borrows (self)`	this writer

`null`method#

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

Appends JSON null.

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

Arguments

Name	Type	Description
`exclusive self`	`Writer`	the writer

Returns

Type	Description
`Writer borrows (self)`	this writer

`endArray`method#

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

Ends the current array.

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

Arguments

Name	Type	Description
`exclusive self`	`Writer`	the writer

Returns

Type	Description
`Writer borrows (self)`	this writer

`endObject`method#

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

Ends the current object.

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":[]}]])

Arguments

Name	Type	Description
`exclusive self`	`Writer`	the writer

Returns

Type	Description
`Writer borrows (self)`	this writer

`flush`method#

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

Publishes staged bytes without ending the document.

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]")

Arguments

Name	Type	Description
`exclusive self`	`Writer`	the writer

Returns

Type	Description
`nil`

`close`method#

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

Verifies and publishes one complete root, then releases backing state.

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

Arguments

Name	Type	Description
`takes self`	`Writer`	the writer

Returns

Type	Description
`nil`

nupp.codec.json.spi

Module contents

Types

Types#

EncodedStringrecord#

EncodedValuerecord#

JSONEncodableinterface#

Members

writeJSONmethod#

Arguments

Returns

MarkContainertype#

Providerinterface#

Members

priorityfield#

arrayOfmethod#

Arguments

Returns

asArrayfield#

asObjectfield#

isArraymethod#

Arguments

Returns

decodemethod#

Arguments

Returns

encodemethod#

Arguments

Returns

encodedmethod#

Arguments

Returns

encodedStringmethod#

Arguments

Returns

pullmethod#

Arguments

Returns

verifiedmethod#

Arguments

Returns

verifiedStringmethod#

Arguments

Returns

newWritermethod#

Arguments

Returns

NULLfield#

EMPTY_ARRAYfield#

EMPTY_OBJECTfield#

compileSerdefield#

decodeSerdefield#

decodeSerdeBufferfield#

Writerinterface#

Members

startArraymethod#

Arguments

Returns

startObjectmethod#

Arguments

Returns

keymethod#

Arguments

Returns

writemethod#

Arguments

Returns

nullmethod#

Arguments

Returns

endArraymethod#

Arguments

Returns

endObjectmethod#

Arguments

Returns

flushmethod#

Arguments

Returns

closemethod#

`nupp.codec.json.spi`

`EncodedString`record#

`EncodedValue`record#

`JSONEncodable`interface#

`writeJSON`method#

`MarkContainer`type#

`Provider`interface#

`priority`field#

`arrayOf`method#

`asArray`field#

`asObject`field#

`isArray`method#

`decode`method#

`encode`method#

`encoded`method#

`encodedString`method#

`pull`method#

`verified`method#

`verifiedString`method#

`newWriter`method#

`NULL`field#

`EMPTY_ARRAY`field#

`EMPTY_OBJECT`field#

`compileSerde`field#

`decodeSerde`field#

`decodeSerdeBuffer`field#

`Writer`interface#

`startArray`method#

`startObject`method#

`key`method#

`write`method#

`null`method#

`endArray`method#

`endObject`method#

`flush`method#

`close`method#