nupp.derive

nupp.derive.Debug adds a checked debug method to a record or struct. Packages publish additional providers through the same recipe API.

@derive(nupp.derive.Debug)
local record User
    id: integer
    name: string = "anonymous"
    tags: {string} = {}
end
local user = new User(id = 1)
print(user:debug())

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. nupp.derive.Debug adds debug(self): string and nupp.Debug conformance. Serialization uses explicit bindings and needs no derive.

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 method forwards the declaration witness to the value visitor, which caches its Debug policy 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 owns its selection policy. Skipped and redacted fields are never read, and a field that Debug can render need not have a JSON representation. A caller can also render an explicit binding or append to an existing Buffer:

local serde = require("nupp.serde")
local debug = require("nupp.serde.debug")
local struct Vec2
    x: float
    y: float
end
local binding = serde.binding(Vec2)
local output = nupp.text.newBuffer()
debug.write(binding, new Vec2(1.25, 2.5), output)
assert(output:tostring() == "Vec2 { x = 1.25, y = 2.5 }")

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) returns; 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.

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 @comptime export 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 returns 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. Parameter names are non-empty and unique, and every recipe array is dense.

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 readable stored field.
• constant(value) embeds a bounded quotable value.
• witness(annotationType(argument)) passes the Type<T> witness named by an @ref annotation argument from the owner or one of its fields.
• array(arguments) constructs a fresh array from argument recipes.

annotationType accepts only a kind = "type" argument taken from the provider's immutable Info. The referenced record remains typed across the comptime boundary instead of being reduced to a name string.

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.

Generates checked members on a declaration while that declaration is checked.

@derive(Provider, ...) names providers on a record or struct. Each one reads an immutable semantic view of the declaration and returns a closed recipe; the compiler generates members from that recipe and checks them the way it checks written ones. This is a declaration-augmentation phase rather than a text macro. A provider adds no imports, top-level declarations, modules, or independently nameable types, and it observes no tokens, source positions, ordinary comments, mutable syntax objects, or another provider's output. It does see normalized declaration and field docblocks.

The shipped Debug provider crosses the same boundary as a package provider. Serialization uses explicit bindings instead of derive recipes.

Derive the shipped providers#

@derive(nupp.derive.Debug)
local record Settings
    host: string = "localhost"
    port: integer = 8080
end

local settings = new Settings()
assert(settings:debug() == 'Settings { host = "localhost", port = 8080 }')

Write a package provider#

A provider is an exported, nongeneric @comptime function whose signature names the one interface it implements. Info describes the owner, implement returns the recipe, and a consumer applies the resolved export rather than a runtime function value. Applying it also claims that interface.

local M = {}

interface M.Named
    named: function(self): string
end

function M.nameValue(value: string): string
    return "name=" .. value
end

@comptime function M.derive(info: nupp.derive.Info): nupp.derive.Result<M.Named>
    local field = info.fields[1]
    if not field or field.name ~= "name" then
        return nupp.derive.error("Named needs a first field named name", info.reference)
    end

    return nupp.derive.implement{
        methods = {
            named = nupp.derive.forward{
                helper = nupp.derive.helper(M, "nameValue"),
                arguments = {nupp.derive.field(field)},
            },
        },
    }
end

@derive(M.derive)
record M.User
    name: string
end

local user = new M.User(name = "ada")
assert(user:named() == "name=ada")

return M

Recipe vocabulary#

The interface owns every generated signature, so a recipe chooses only which runtime function stands behind a requirement and which values reach it. forward names one ordinary exported Nupp function and a closed argument list built from receiver, argument, field, constant, and array. There are no nested calls, operators, branches, loops, assignments, or provider-chosen signatures, so behavior stays in ordinary type-checked Nupp rather than in a macro IR, and the generated call is checked against the helper's declaration the way any other call is.

forward.v1 fills only bodyless, unoverloaded callable requirements, and cannot replace an interface default. A provider that refuses a declaration returns error rather than raising.

Providers run inside the bounded comptime worker, once per owner rather than once per generic instantiation, and a recipe is memoized on the Info fingerprint. claims asks whether a type already writes or requests an interface, which lets mutually recursive derives plan without depending on evaluation order.

record Argument

interface DebugOptions ...

skip: boolean?

redact: boolean?

record derive.Entry ...

key: string?

mt: any

schema: {
    data: {[string]: any},
    [string]: any
}

interface EventOptions ...

name: string?

record Field ...

name: string

documentation: string?

readable: boolean

writable: boolean

readType: any?

writeType: any?

hasDefault: boolean

defaultValue: any

annotations: {nupp.reflect.Annotation}

reference: Reference

record Forward

record Info ...

schema: integer

kind: string

name: string

qualifiedName: string

visibility: string

documentation: string?

providerIdentity: string

ownerIdentity: string

ownerType: any

interfaceType: any

fields: {Field}

annotations: {nupp.reflect.Annotation}

hasConstructor: boolean

reference: Reference

fingerprint: string

record Member

record Provider

record Reference

record Result<I>

record RuntimeHelper

local annotationType: function(argument: nupp.reflect.AnnotationArgument): any

local argument: function(name: string): Argument

local array: function(arguments: {Argument}): Argument

local claims: function(subject: any, interface: any): boolean

local constant: function(value: any): Argument

@comptime function derive.Debug(info: nupp.derive.Info): nupp.derive.Result<nupp.Debug>

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

local credentials = new Credentials(user = "ada", password = "hunter2")
assert(credentials:debug() == 'Credentials { user = "ada", password = <redacted> }')

function derive.debug(target: unknown, borrows value: unknown): string

function derive.install(namespace: any): nil

local entry: function(): Argument

local error: function(message: string, reference: Reference?, code: string?): any

local field: function(field: Field): Argument

local file: function(path: string): string

local forward: function(specification: any): Forward

local helper: function(module: any, name: string): RuntimeHelper

local implement: function(specification: any): any

local member: function(specification: any): Member

local receiver: function(): Argument

local witness: function(subject: any): Argument