nupp.serde.json

Codecinterface#

interface Codec ...

A JSON codec with its own policy and its own cache of what it selected for each binding.

The module-level functions use one shared codec with defaultPolicy. Hold a codec of your own to use another policy, or to bound and clear what it retains.

encodeDocument: function<D>(self, adapter: core.DocumentAdapter<D>, borrows value: D): string

decodeDocument: function<D>(self, adapter: core.DocumentAdapter<D>, bytes: string, context: core.Context?): D

writeValue: function<T>(self, binding: core.Binding<T>, borrows value: T, exclusive sink: json.Writer): nil

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

encodeInto: function<T>(self, binding: core.Binding<T>, borrows value: T, exclusive buffer: text.Buffer): nil

decode: function<T>(self, binding: core.Binding<T>, bytes: string, context: core.Context?): T

decodeBuffer: function<T>(self, binding: core.Binding<T>, exclusive input: text.Buffer, context: core.Context?): T

clear: function(self): nil

cachedBindings: function(self): integer

FieldNamerecord#

record FieldName is core.WireField ...

The wire field a JSON decoder reports for a member the model does not declare.

name: string

diagnosticLabel: function diagnosticLabel(self): string

Policyinterface#

interface Policy<M is core.Member> ...

Chooses each member's JSON name, whether it is written, and how its timestamps are represented.

A model library implements one to interpret the traits on its own members, such as a Smithy jsonName or timestampFormat.

Type parameters

name: function(self, member: M): string

select: function(self, member: M, direction: core.Direction): Selection

timestamp: function(self, member: M, borrows value: core.Timestamp): json.EncodedValue

parseTimestamp: function(self, member: M, text: string, kind: "string" | "number"): core.Timestamp

PolicyFactoryinterface#

interface PolicyFactory ...

Returns the Policy for a binding's member type.

policy: function<M is core.Member>(self, member: M): Policy<M>

Selectiontype#

type Selection = "traverse" | "omit" | "redact"

Whether a policy writes a member, leaves it out, or writes it redacted.

codecfunction#

function codec(policy: plans.PolicyFactory?, capacity: integer?): Codec

Makes a Codec.

local serde = require("nupp.serde")
local json = require("nupp.serde.json")
local record Item
    id: integer
end
local codec = json.codec(json.defaultPolicy, 16)
local items = serde.binding(Item)
assert(codec:decode(items, codec:encode(items, new Item(id = 3))).id == 3)
assert(codec:cachedBindings() == 1)
codec:clear()

Arguments

Returns

decodefunction#

function decode<T>(binding: core.Binding<T>, bytes: string, context: core.Context?): T

Decodes JSON text into a value.

The whole input must be one value; trailing text is an error. A decoded value the codec then has to reject is dropped through the binding.

local serde = require("nupp.serde")
local json = require("nupp.serde.json")
local record Range
    low: integer
    high: integer = 100
end
local range = json.decode(serde.binding(Range), '{"low":5}')
assert(range.low == 5 and range.high == 100)

Type parameters

Arguments

Returns

Raises

decodeBufferfunction#

function decodeBuffer<T>(binding: core.Binding<T>, exclusive input: text.Buffer, context: core.Context?): T

Decodes a caller-owned Buffer, reading it in place when the provider can.

Type parameters

Arguments

Returns

Raises

decodeDocumentfunction#

function decodeDocument<D>(adapter: core.DocumentAdapter<D>, bytes: string, context: core.Context?): D

Decodes JSON text as document contents, attaching the context it was read under.

Type parameters

Arguments

Returns

Raises

documentPolicyfunction#

function documentPolicy<M is core.Member>(member: M, epochTimestamps: boolean): plans.Policy<M>?

Returns the policy JSON applies inside a document-valued member, or nil when the member is not one of a document's own.

A model's PolicyFactory asks this first, so documents nested in its values are read and written the way defaultPolicy reads them.

Type parameters

Arguments

Returns

encodefunction#

function encode<T>(binding: core.Binding<T>, borrows value: T): string

Encodes a value as JSON text.

local serde = require("nupp.serde")
local json = require("nupp.serde.json")
local record Pair
    left: string
    right: string?
end
assert(json.encode(serde.binding(Pair), new Pair(left = "a")) == '{"left":"a","right":null}')

Type parameters

Arguments

Returns

Raises

encodeDocumentfunction#

function encodeDocument<D>(adapter: core.DocumentAdapter<D>, borrows value: D): string

Encodes a document's contents as JSON text.

Type parameters

Arguments

Returns

Raises

encodeIntofunction#

function encodeInto<T>(binding: core.Binding<T>, borrows value: T, exclusive buffer: text.Buffer): nil

Appends a value's JSON text to a caller-owned Buffer.

On failure the buffer is restored to what it held before the call.

Type parameters

Arguments

Returns

Raises

fieldNamefunction#

function fieldName(field: core.WireField): string

Returns the JSON member name of a wire field.

Arguments

Returns

writeValuefunction#

function writeValue<T>(binding: core.Binding<T>, borrows value: T, exclusive sink: json.Writer): nil

Writes one value at the current position of a nupp.codec.json.Writer, for embedding bound values in JSON assembled by hand.

local serde = require("nupp.serde")
local json = require("nupp.serde.json")
local record Tag
    name: string
end
local buffer = nupp.text.newBuffer()
local writer = nupp.codec.json.newWriter(buffer)
writer:startArray()
json.writeValue(serde.binding(Tag), new Tag(name = "x"), writer)
writer:endArray()
writer:close()
assert(buffer:tostring() == '[{"name":"x"}]')

Type parameters

Arguments

Returns

Raises

defaultPolicyvariable#

const defaultPolicy: plans.PolicyFactory

The policy for declaration bindings and documents, which the module-level functions use. A model's own factory can delegate to it for members it does not own.

identityvariable#

const identity: table

Identifies JSON as the codec in a nupp.serde.Context it attaches, so a protocol can tell a document it read from one another codec read.

memberNamePolicyvariable#

const memberNamePolicy: plans.PolicyFactory

The policy that writes every member under its own name, traverses every member, and writes timestamps as RFC 3339 strings.

defaultPolicy refuses a model's own members rather than guess at the traits they carry, so a model library has to say how its members are named. Use it for a model whose names are already the wire names.

local serde = require("nupp.serde")
local adapters = require("nupp.serde.adapters")
local json = require("nupp.serde.json")
local record Member is serde.Member
    @readonly name: string
    @readonly index: integer?
end
local title: serde.Binding<string> = new serde.Bound<string, Member>(
    adapter = adapters.text(new Member(name = "title"))
)
assert(not pcall(json.encode, title, "Dune"))
local plain = json.codec(json.memberNamePolicy)
assert(plain:encode(title, "Dune") == '"Dune"')