nupp.serde

Bindinginterface#

sealed interface Binding<T>
    schema: function(self): Schema
    extension: function(self, key: any): any
end

A checked physical representation of a schema as T.

Type parameters

Methods

schema: function(self): Schema

extension: function(self, key: any): any

DynamicBindinginterface#

sealed interface DynamicBinding is Binding<DynamicValue>
    bind: function(self, value: {[string]: any}): DynamicValue
    newValue: function(self): DynamicValue
end

A binding that constructs dense run-time values.

Methods

bind: function(self, value: {[string]: any}): DynamicValue

newValue: function(self): DynamicValue

DynamicValuerecord#

record DynamicValue
    function get(self, member: Member): any end

    function get(self, name: string): any end

    function set(self, member: Member, value: any): nil end
end

An indexed value owned by a dynamic binding.

Methods

get: function get(self, member: Member): any

get: function get(self, name: string): any

set: function set(self, member: Member, value: any): nil

JsonCodecrecord#

record JsonCodec
    readonly profile: JsonProfile
    function prepare<T>(self, binding: Binding<T>): Prepared<T> end

    function encode<T>(self, binding: Binding<T>, value: T): string end

    function write<T>(self, binding: Binding<T>, value: T, exclusive out: Buffer): nil end

    function write<T>(self, binding: Binding<T>, value: T, exclusive out: Writer): nil end

    function decode<T>(self, binding: Binding<T>, text: string): (T?, string?) end

    function decodeBuffer<T>(self, binding: Binding<T>, exclusive input: Buffer): (T?, string?) end
end

A JSON codec that lazily prepares bindings.

Methods

prepare: function prepare<T>(self, binding: Binding<T>): Prepared<T>

encode: function encode<T>(self, binding: Binding<T>, value: T): string

write: function write<T>(self, binding: Binding<T>, value: T, exclusive out: Buffer): nil

write: function write<T>(self, binding: Binding<T>, value: T, exclusive out: Writer): nil

decode: function decode<T>(self, binding: Binding<T>, text: string): T?, string?

decodeBuffer: function decodeBuffer<T>(self, binding: Binding<T>, exclusive input: Buffer): T?, string?

Fields

profile: JsonProfile

JsonProfilerecord#

record JsonProfile
    readonly unknownMembers: "reject" | "ignore"
end

Immutable JSON wire-policy identity.

Fields

unknownMembers: "reject" | "ignore"

Kindtype#

type Kind = "unit"
| "null"
| "boolean"
| "integer"
| "unsigned"
| "number"
| "decimal"
| "string"
| "bytes"
| "timestamp"
| "optional"
| "list"
| "map"
| "structure"
| "tuple"
| "union"
| "stringEnum"
| "integerEnum"
| "document"

Memberrecord#

record Member
    readonly index: integer
    readonly name: string
    readonly target: any
    readonly required: boolean
    readonly hasDefault: boolean
    function metadata<T>(self, key: MetadataKey<T>): T? end
end

One structure member with a stable dense index.

Methods

metadata: function metadata<T>(self, key: MetadataKey<T>): T?

Fields

index: integer

name: string

target: any

required: boolean

hasDefault: boolean

MetadataKeyinterface#

interface MetadataKey<T>
    readonly id: integer
    readonly name: string?
end

A typed identity for format-neutral schema metadata.

It is a nupp.store.Key: its id is process-local, so applications retain the key, never its number, and may use the same key with static and run-time schemas.

Type parameters

Fields

id: integer

name: string?

Preparedinterface#

sealed interface Prepared<T>
    encode: function(self, value: T): string
    write: function(self, value: T, exclusive out: Buffer): nil & function(self, value: T, exclusive out: Writer): nil

    decode: function(self, text: string): (T?, string?)
    decodeBuffer: function(self, exclusive input: Buffer): (T?, string?)
end

A prepared JSON traversal for one binding and profile.

The recursive prepared traversal handles structures, lists, string-keyed maps, optionals, scalar constraints, defaults, literals, and document members.

Type parameters

Methods

encode: function(self, value: T): string

write: function(self, value: T, exclusive out: Buffer): nil & function(self, value: T, exclusive out: Writer): nil

decode: function(self, text: string): (T?, string?)

decodeBuffer: function(self, exclusive input: Buffer): (T?, string?)

PreparedDebuginterface#

sealed interface PreparedDebug<T>
    format: function(self, value: T): string
    write: function(self, value: T, exclusive out: Buffer): nil
end

A prepared schema-driven Debug formatter.

Type parameters

Methods

format: function(self, value: T): string

write: function(self, value: T, exclusive out: Buffer): nil

Schemarecord#

record Schema
    readonly kind: Kind
    readonly name: string?
    readonly members: {Member}
    function extension<T>(self, key: nupp.reflect.ExtensionKey<T>): T end

    function metadata<T>(self, key: MetadataKey<T>): T? end

    function member(self, name: string): Member? end

    function element(self): Schema? end

    function key(self): Schema? end

    function value(self): Schema? end

    function expectMember(self, name: string): Member end
end

One immutable logical schema node.

Methods

extension: function extension<T>(self, key: nupp.reflect.ExtensionKey<T>): T

metadata: function metadata<T>(self, key: MetadataKey<T>): T?

member: function member(self, name: string): Member?

element: function element(self): Schema?

key: function key(self): Schema?

value: function value(self): Schema?

expectMember: function expectMember(self, name: string): Member

Fields

kind: Kind

name: string?

members: {Member}

SchemaBuilderrecord#

record SchemaBuilder

    constructor(self) end

    function structure(self, name: string): SchemaBuilder end

    function required(self, name: string, target: Schema): SchemaBuilder end

    function optional(self, name: string, target: Schema): SchemaBuilder end

    function defaulted(self, name: string, target: Schema, value: any): SchemaBuilder end

    function metadata<T>(self, key: MetadataKey<T>, value: T): SchemaBuilder end

    function memberMetadata<T>(self, name: string, key: MetadataKey<T>, value: T): SchemaBuilder end

    function freeze(self): Schema end
end

Incrementally constructs and then freezes a run-time structure schema.

Methods

constructor: function constructor(self)

structure: function structure(self, name: string): SchemaBuilder

required: function required(self, name: string, target: Schema): SchemaBuilder

optional: function optional(self, name: string, target: Schema): SchemaBuilder

defaulted: function defaulted(self, name: string, target: Schema, value: any): SchemaBuilder

metadata: function metadata<T>(self, key: MetadataKey<T>, value: T): SchemaBuilder

memberMetadata: function memberMetadata<T>(self, name: string, key: MetadataKey<T>, value: T): SchemaBuilder

freeze: function freeze(self): Schema

Serializableinterface#

interface Serializable
end

Marker claimed by @derive(nupp.derive.Serde).

Serialization remains a property of a Binding<T>, not an instance method. The empty contract lets derive advertise checked participation without making values carry a codec API.

bindingOffunction#

local function bindingOf(type: any): any

Retrieves the binding registered by @derive(nupp.derive.Serde).

Arguments

Returns

Raises

• when the type did not derive Serde

dynamicfunction#

function dynamic(schema: Schema): DynamicBinding

Creates the indexed dynamic binding for a frozen schema.

Arguments

Returns

Raises

• when the schema is not a structure

jsonfunction#

function json(options: any?): JsonCodec

Creates an immutable-profile JSON codec.

fieldNames, when supplied, runs only during preparation. The fused traversal sees the resulting immutable wire names.

Arguments

Returns

Raises

• when unknownMembers is not reject or ignore

keyfunction#

function key<T>(name: string, binding: Binding<T>): store.Key<T>

Declares a named key whose value type is fixed by the binding that persists it.

The key is registered as nupp.store.newKey registers one, so the name is opaque and unique, and the binding is retained so saveStore and loadStore can carry the value under that name.

Type parameters

Arguments

Returns

Raises

• when the name is empty or already registered

listfunction#

function list(target: Schema): Schema

Creates an immutable list node.

Arguments

Returns

loadStorefunction#

function loadStore(exclusive value: store.Store, saved: {[string]: any}): nil

Decodes plain values written by saveStore back into a store.

Each name is looked up in this runtime state's registry and its value is decoded through the binding that key was declared with, so a value is checked against the schema this program gave the name. Keys the saved table does not mention are left as they are.

Arguments

Returns

Raises

• when a name is not registered, its key has no binding, or a value does not fit

mapfunction#

function map(key: Schema, value: Schema): Schema

Creates an immutable map node.

Arguments

Returns

Raises

• when the key schema is not string-valued: document keys are strings, and the codec can neither emit nor read back any other kind

metadataKeyfunction#

function metadataKey<T>(): MetadataKey<T>

Creates a typed schema metadata identity.

Type parameters

Returns

offunction#

function of<T>(type: Type<T>): Binding<T>

Type parameters

Arguments

Returns

optionalfunction#

function optional(target: Schema): Schema

Creates an immutable optional node.

Arguments

Returns

prepareDebugfunction#

function prepareDebug<T>(binding: Binding<T>): PreparedDebug<T>

Prepares and memoizes Debug formatting for a binding.

Type parameters

Arguments

Returns

saveStorefunction#

function saveStore(borrows value: store.Store): {[string]: any}

Encodes every occupied key of a store into plain values under its name.

The values are the documents a JSON codec with default field names writes, so a saved store rides inside whatever document the application encodes.

Arguments

Returns

Raises

• when an occupied key is anonymous or was declared without a binding

booleanvariable#

const boolean

debugRedactvariable#

const debugRedact: MetadataKey<boolean>

debugSkipvariable#

const debugSkip: MetadataKey<boolean>

Standard Debug policy metadata shared by derived and dynamic schemas.

documentvariable#

const document

int16variable#

const int16

int32variable#

const int32

int8variable#

const int8

integervariable#

const integer

nullvariable#

const null

numbervariable#

const number

stringvariable#

const string

uint16variable#

const uint16

uint32variable#

const uint32

uint8variable#

const uint8

unitvariable#

const unit

Format-neutral scalar schema singletons.