Typed encode/decode: inferred types, the asn DSL, and ASN.1 code generation

[chtitux]

decode() returned unknown and encode() took unknown, so every caller wrote an interface by hand and cast. The schema already describes the shape; this makes TypeScript read it — three ways, over one interchange format.

SchemaNode is the interchange format. The ASN.1 parser, the DSL and hand-written literals all produce it; SchemaBuilder and the code generator both consume it. All three front-ends hand back the same TypedCodec<TOut, TIn, TNode>.

  ASN.1 text ──parseAsn1Module──┐
                                │
  asn DSL ─────asn.toSchemaNode─┼──▶  SchemaNode  ──┬── SchemaBuilder ──▶ codecs
                                │    (interchange)  │
  SchemaNode literal ───────────┘                   └── generateTypeScript ──▶ .ts

None of this runs at runtime: no validation was added, no dependency was added, and the emitted JavaScript is unchanged.

1. Types inferred from an inline schema

SchemaCodec, SchemaBuilder.build and the new createCodec/createCodecs take the schema as a const type parameter, so an inline schema keeps its literal types. Conditional types in src/schema/Infer.ts walk them:

Helper	Describes
Infer<S>	what decode() returns
InferInput<S>	what encode() accepts
InferInputRaw<S>	the same, allowing RawBytes at any node
InferMetadata<S>	the DecodedNode tree

ENUMERATED narrows to a literal union, CHOICE becomes a discriminated union on key, OPTIONAL fields become optional properties while DEFAULT fields stay required after decoding, and $ref resolves through the registry passed to createCodecs (bounded expansion, so recursive schemas terminate). stripMetadata() derives its return type from the node it is given.

2. The asn builder DSL

const Ticket = asn.sequence({
  id: asn.integer({ min: 0, max: 255 }),
  status: asn.enumerated(['pending', 'approved']),
  version: asn.integer({ min: 0, max: 10 }).default(1),
});

Types ride in the value's type parameters instead of being recomputed from literals, so a plain const keeps its type and schemas are reusable. Error messages name the offending field rather than printing a deferred conditional-type alias. Recursion goes through asn.ref<T>(name) + asn.compile; metadata trees stay typed.

SEQUENCE field order is object key order, so the builder rejects integer-like keys — engines hoist those, which would silently reorder the encoding rather than fail.

3. Code generation

npx asn1-per-ts types ticket.asn src/generated/ticket.ts

.asn or SchemaNode JSON to a module of named interfaces plus typed codecs. The parser resolves type references by inlining them, so the generator matches those expanded structures back to the types they came from — without that the output repeats whole structures and loses the point of naming them. ASN.1 hyphens are handled both ways: type names become PascalCase (collisions numbered, shadowing avoided), field names stay verbatim and quoted. Each type gets an Input variant where a DEFAULT is reachable, computed as a fixpoint so $ref cycles terminate.

On a 150-type schema, generated code costs ~20k type instantiations against ~109k for the equivalent inline literal.

The package now installs an asn1-per-ts binary with types and schema subcommands, replacing the cli/*.ts scripts that could only be run from a checkout. Argument handling sits behind a CliIo interface so the commands are tested with an in-memory filesystem.

Breaking changes (types)

Recorded in the new CHANGELOG.md under [Unreleased]. These warrant at least a minor bump, arguably major:

• RawBytes moved to codec.raw. The default encode signatures no longer accept it. Folding RawBytes into every node doubled the length of every type printed in an encode error, for a feature most values never use. The runtime is unchanged and still accepts RawBytes anywhere.
• encode() now rejects values that do not fit. The point of the change, but code that compiled against the old unknown signature may need fixing — usually an intermediate const widened a literal, which annotating with Infer<typeof schema> solves.
• SchemaNode's collections are readonly, so inline schemas keep their literal types. Code that mutated fields, alternatives or values after construction no longer compiles.
• cli/generate-schema.ts and cli/generate-types.ts removed in favour of the bin; from a checkout, npx tsx src/cli/main.ts <subcommand>.

A schema known only at runtime — parsed from JSON or ASN.1 text — stays the wide SchemaNode union and keeps the unknown-typed API it had before.

Docs

New guides examples/typed-api.md, examples/dsl.md and examples/codegen.md; examples/schema-parser.md reworked. A new CHANGELOG.md (there was none) with PUBLISH.md wired to it.

Several doc errors fixed along the way, some predating this branch: the CHOICE examples in encoding.md/decoding.md documented a { name: value } shape the codecs stopped producing, with hex that threw when decoded; schema-parser.md claimed cross-referenced types produce $ref when in fact only cycles do; the README omitted OBJECT IDENTIFIER entirely and its metadata example cast away the typing this PR adds.

Verification

587 tests across 33 suites. tsc --noEmit on library, CLI and website; build clean.

• Type-level assertions use a strict Equal<X, Y>, not extends, so any/unknown cannot make one pass vacuously; @ts-expect-error cases prove wrong values are rejected.
• tests/fixtures/generated/sampleModule.ts is checked-in generator output, imported by a test so ts-jest compiles it, with an assertion that the generator still reproduces it byte for byte.
• The bin was verified against a real install — npm pack, install the tarball into an empty project, run the linked binary, then compile and run the generated module against the packaged runtime under strict + noUnusedLocals + NodeNext.
• Every runnable snippet in the new and edited guides was compiled; the parser outputs and hex strings quoted in schema-parser.md come from running the parser.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KPw4YEzoKtskJR9n33a1yS