Declaration derives

nupp.derive holds the three bundled derive providers and the recipe API a package uses to publish its own. @derive names a provider on a record or struct declaration. The provider decides which targets it admits and adds the closed set of checked members or data that it returns.

The bundled recipes render by appending into a string.buffer, so a lua51 target needs a text.buffer provider selected. Without one, a @derive naming a provider reports NUPP3012 on the annotation that named it. The browser backend selects one, so a page needs nothing further.

@derive(nupp.derive.Debug, nupp.derive.JSON)
local record User
    @json(name = "user_id")
    id: integer

    name: string = "anonymous"

    tags: {string} = {}
end

local user = new User()
local out = string.buffer.new()
local writer = nupp.codec.json.writer(out)
user:writeJSON(writer)
writer:close()
print(user:debug(), out:tostring())

Applying a provider is a declaration-augmentation phase, not a text macro: it cannot add imports, top-level declarations, modules, records, interfaces, or independently nameable types. The bundled providers are:

• nupp.derive.Debug: debug(self): string and nupp.Debug conformance.
• nupp.derive.JSON: writeJSON(writer), a static fromJSON, fieldCodec, and nupp.codec.json.JSONEncodable conformance.
• nupp.derive.Serde: one format-neutral schema and physical binding for a record or struct, with no generated format methods.

nupp.events.Event is applied the same way and marks a record or a fixed-layout struct as an event a nupp.events source constructs and delivers.

Generated members participate in normal member lookup, generic inference, and interface checking. A written member of the same name is a compile-time conflict. Stacked @derive applications combine, but a provider cannot be requested twice. See Annotations for where @derive sits among the built-in annotations.

Debug#

debug(self): string renders a record or fixed-layout struct the way the declaration reads, so what comes back names the declaration and its fields in declaration order. The derive records a format-neutral schema and physical binding; the generic formatter prepares and caches its traversal on first use.

@derive(nupp.derive.Debug)
local record Point
    x: integer
    y: integer
end

local p = new Point(x = 3, y = -1)
print(p:debug())

Point { x = 3, y = -1 }

Strings are quoted, map keys are sorted by byte order so two runs agree, nested records render through their own debug, and a runtime table that reaches itself renders as <cycle>.

@derive(nupp.derive.Debug)
local record Tag
    name: string
end

@derive(nupp.derive.Debug)
local record Post
    title: string
    views: integer
    tags: {Tag}
    scores: {[string]: integer}
end

local post = new Post(
    title = "hello",
    views = 12,
    tags = {new Tag(name = "a"), new Tag(name = "b")},
    scores = {zeta = 1, alpha = 2}
)
print(post:debug())

Post { title = "hello", views = 12, tags = {Tag { name = "a" }, Tag { name = "b" }}, scores = {["alpha"] = 2, ["zeta"] = 1} }

Field visibility#

A @debug field annotation decides what a field contributes. redact keeps the name and replaces the value, which is what a secret wants; skip removes the field from the output entirely.

@derive(nupp.derive.Debug)
local record Credentials
    user: string
    @debug(redact = true)
    password: string
    @debug(skip = true)
    cache: any
end

local c = new Credentials(user = "ada", password = "hunter2", cache = {1, 2})
print(c:debug())

Credentials { user = "ada", password = <redacted> }

Debug and Serde on the same declaration share one schema recipe. Debug alone keeps that binding internal and does not make the declaration nupp.serde.Serializable. Code that already retains a public binding can prepare the same formatter explicitly and append without constructing the final string:

@derive(nupp.derive.Debug, nupp.derive.Serde)
local struct Vec2
    x: float
    y: float
end

local prepared = nupp.serde.prepareDebug(nupp.serde.of(Vec2))
local output = string.buffer.new()
prepared:write(new Vec2(1.25, 2.5), output)
assert(output:tostring() == "Vec2 { x = 1.25, y = 2.5 }")

Serde#

Serde derives one logical nupp.serde.Schema and one nupp.serde.Binding<T>. It applies to records and fixed-layout structs, and generates no writeJSON, fromJSON, XML, or CBOR methods. A codec prepares the binding separately and caches its format-specific data.

@derive(nupp.derive.Serde)
local record User
    id: uint32
    name: string?
end

local binding = nupp.serde.of(User)
local prepared = nupp.serde.json():prepare(binding)
local text = prepared:encode(new User(id = 7, name = "ada"))
local restored, problem = prepared:decode(text)

assert(problem == nil)
assert(restored and restored.id == 7)

The same type witness works for a struct:

@derive(nupp.derive.Serde)
local struct Vec3
    x: float
    y: float
    z: float
end

local binding: nupp.serde.Binding<Vec3> = nupp.serde.of(Vec3)

Derived fields currently admit booleans, strings, finite numbers, integers through 32 bits, optionals, arrays, string-keyed maps, and other declarations that also derive Serde. Pointer-bearing struct fields are rejected because a pointer does not describe its extent or ownership. See Schema-driven serde for dynamic schemas, profiles, extensions, and the prepared JSON path.

Event#

nupp.events.Event records an event's name and representation and asks the compiler for the declaration's initializer, so a source can construct the event into storage it already holds. It generates no members; what it adds is the nupp.events.Emittable contract that every Type<E> an event source takes is bounded by.

local events = require("nupp.events")

@derive(events.Event)
@event(name = "combat.Damage")
local record Damage
    amount: number
    source: integer
    kind: string = "physical"
end

local bus: events.MessageBus<integer> = events.newMessageBus()
bus:observe(7, Damage, |event| -> print(event.kind))
bus:emit(7, Damage, amount = 10, source = 3)

@event(name = "...") sets the name events.name(Damage) answers; the declaration's own name is the default. The name is what something outside the program pins, such as a debug protocol, which is why it is written rather than derived from a path that a refactor would move.

The derive admits a concrete record or a fixed-layout struct with one construction contract. It refuses a declaration with several constructors, a constructor that lets self escape or moves an owned parameter into a field, an affine field, and a generic owner, because none of those can run against storage that is reused: the next lease would find the reference, the moved obligation, or the shared identity already there.

JSON#

JSON generates writeJSON(writer), a static fromJSON, a fieldCodec, and nupp.codec.json.JSONEncodable conformance. Encoding writes through the checked buffer-backed writer; it does not allocate a complete result string. Record and shape fields follow declaration order and string map keys sort by byte order, so the same value always produces the same bytes. Encoded field names and literal values are cached lazily on the derived schema. If encoding fails, bytes appended before the failure remain in the buffer; reset or discard it when the surrounding operation needs atomic output.

@derive(nupp.derive.JSON, nupp.derive.Debug)
local record User
    @json(name = "user_id")
    id: integer
    name: string
end

local user = new User(id = 7, name = "ada")
local out = string.buffer.new()
local writer = nupp.codec.json.writer(out)
user:writeJSON(writer)
writer:close()
print(out:tostring())

local decoded = User.fromJSON('{"user_id": 7, "name": "ada"}')
print(decoded and decoded:debug())

{"user_id":7,"name":"ada"}
User { id = 7, name = "ada" }

Decoding errors#

fromJSON returns T?, string?, and the error names the path that failed rather than saying the document was bad:

@derive(nupp.derive.JSON)
local record User
    @json(name = "user_id")
    id: integer
    name: string
end

print(select(2, User.fromJSON('{"user_id": 7, "name": "ada", "nmae": 1}')))
print(select(2, User.fromJSON('{"user_id": "seven", "name": "ada"}')))
print(select(2, User.fromJSON('{"user_id": 1e300, "name": "ada"}')))
print(select(2, User.fromJSON('{"name": "ada"}')))

$: unknown field "nmae"
$.user_id: expected finite number
$.user_id: expected integer in range
$.user_id: required field is absent

Options#

A record decides what happens to keys it does not know.

A field decides how it appears on the wire.

omitEmpty is encoding only, which is the part worth knowing: a field left out of the output is still required coming back in.

@derive(nupp.derive.JSON)
local record User
    id: integer
    @json(omitEmpty = true)
    tags: {string}
end

local user = new User(id = 7, tags = {})
local out = string.buffer.new()
local writer = nupp.codec.json.writer(out)
user:writeJSON(writer)
writer:close()
local text = out:tostring()
print(text)
print(select(2, User.fromJSON(text)))

{"id":7}
$.tags: required field is absent

Use omit with an explicit field default when a field should disappear from both directions:

@json(omit = true)
secret: string = "redacted"

Schemas#

Booleans, strings, finite numbers, exactly representable integer widths, optionals, arrays, tuples, string-keyed maps, finite shapes, and records deriving JSON are all supported. int64 and uint64 are rejected, because a JSON number cannot round-trip their full range, and the erased integer type is checked against the safe interval at run time.

Strings must be valid UTF-8, and a cycle or excessive nesting fails with the JSON path that reached it. Decoding uses Nupp's strict SIMD-accelerated codec and preserves null with nupp.codec.json.NULL while it validates the raw value.

The JSON field codec is allocated lazily as a runtime reflection extension. Use nupp.codec.json.writeRecord, writeAs(User, value, writer), and decodeAs(User, text) when a type-witness API fits better than generated members. The allocating encodeRecord and encodeAs wrappers remain available when a complete string is specifically required. See Reflection for the witness and allocation model, and nupp.codec.json for the rest of the codec.

Package providers#

A package may export a derive provider as a comptime function. Its exact signature names the one existing interface it implements:

comptime function M.derive(info: nupp.derive.Info): nupp.derive.Result<M.Inspect>
    -- inspect info and return a closed recipe
end

In a declared module, write export comptime function derive(...) instead of qualifying the function through a module table. Exported annotation declarations may accompany the provider and remain compile-time metadata, not runtime values.

A consumer applies the resolved exported symbol, not a runtime function value:

local inspect = require("inspect")

@derive(inspect.derive)
local record Credentials
    username: string
    password: string
end

Applying the provider also claims M.Inspect. An equal written is inspect.Inspect is redundant and coalesced. Interface defaults are inherited normally and associated requirements are checked normally. A provider can fill a bodyless callable requirement or declare a new function member with a closed comptime-built signature. Generic, variadic, overloaded, and effectful provider declarations are not part of the first recipe version.

Provider inputs#

Every provider on an owner receives the same immutable pre-merge Info view. It contains the owner and interface type handles, ordered stored fields with read/write handles, semantic identities, and opaque diagnostic references. It contains no tokens, locations, comments, AST, CST, mutable compiler objects, or previous provider output. nupp.derive.claims(T, I) asks whether a nominal type writes or requests contract I, which lets mutually recursive derives plan without depending on provider execution order.

Info.name names the declaration. Info.qualifiedName combines its module and declaration path, giving providers a default identity without a source filename. Packages that persist this identity should offer an explicit override: renaming a declaration or moving it to another module changes its qualified name.

A generic owner is planned once, not per instantiation. A type parameter exposes its bound, or unknown, so providers cannot specialize for future concrete arguments.

Providers run through the bounded comptime worker. Their sealed source and reachable comptime helper closure travel in the module interface; they do not remain runtime functions. A provider failure may return nupp.derive.error(message, reference, code) to point at the owner or contributing field without observing a filename or source position. The code is optional and defaults to the generic provider diagnostic NUPP2810.

Initializers#

A provider may ask for the owner's initializer with initializer = true beside methods, statics, and data. The compiler then mints the declaration's constructor body, or its field list when it declares none, as a hidden member taking the instance first: initializer(storage, ...) fills storage the caller already holds and answers it, and new allocates and calls the same body. The runtime reaches it through nupp.derive.initializer(Type). A field-list initializer applies a field default where its argument is nil, which is the one place that can, since a positional call never passes through the checker's default filling.

The compiler refuses the request on a declaration whose body could notice the reuse: several constructors, a constructor that lets self escape or moves a takes parameter into a field, an affine field, or a generic owner, each reported as NUPP2810 on the application.

Filesystem inputs#

A provider that generates a recipe from a schema or other immutable project file reads it with nupp.derive.file:

comptime function M.derive(info: nupp.derive.Info): nupp.derive.Result<M.Inspect>
    local schema = nupp.derive.file("schemas/inspect.txt")
    return nupp.derive.implement {
        methods = {
            inspect = nupp.derive.forward {
                helper = nupp.derive.helper(M, "renderSchema"),
                arguments = {nupp.derive.constant(schema)},
            },
        },
    }
end

The path must be a string literal and remain within the consumer project root. The compiler reads it before the isolated worker starts, fingerprints its bytes with the provider input, and records it in the incremental dependency graph. Changing the file invalidates only provider consumers, and watch mode observes the canonical path and refuses to patch over changed generated state without a restart. Missing files are diagnostics.

Providers have no general host I/O, so network resources, environment variables, clocks, mutable tables, and hidden filesystem reads cannot silently enter a cache or a hot-reload guarantee.

Closed forwarding recipes#

nupp.derive.implement returns instance methods and static functions. A bare Forward fills an interface requirement and inherits its signature. A nupp.derive.member supplies a function type built with nupp.types and its parameter names, allowing a provider to add a member that is not declared by the result interface.

return nupp.derive.implement {
    methods = {
        inspect = nupp.derive.forward {
            helper = nupp.derive.helper(M, "renderRecord"),
            arguments = {
                nupp.derive.constant(names),
                nupp.derive.array(values),
            },
        },
    },
}

Both forms lower through forward.v1, which names one ordinary runtime helper and supplies a closed argument list:

• receiver() passes the generated method receiver.
• argument(name) passes a named interface method parameter.
• entry() passes the derived type's private runtime schema entry.
• field(fieldInfo) directly reads one admitted stored field.
• constant(value) embeds a bounded quotable value.
• array(arguments) constructs a fresh array from argument recipes.

There are no nested calls, operators, branches, assignments, loops, arbitrary member accesses, or source fragments in a forwarding recipe. Table-shaped constants and arrays are fresh for each call, so mutation by one invocation cannot affect the next.

The first version refuses overloaded requirements, interface defaults, properties, setters, and metamethods. Those require separate versioned recipe capabilities rather than silently widening forward.v1.

Runtime helpers#

Runtime behavior stays in ordinary exported Nupp functions. Helpers are type checked at their declarations, and the generated call is checked again against the interface-owned argument and result packs, ownership, effects, and suspension contract. forward.v1 refuses generic runtime helpers; a later recipe version can admit them once symbolic helper identity and caching are specified. A helper module becomes an ordinary runtime dependency of the consumer even when the comptime provider itself would otherwise erase.