@amritk/generate-parsers 0.20.0 → 0.21.0

package/AI.md

@@ -22,9 +22,11 @@ const files = await buildSchema(schema, 'Document')
 
 1. **`buildSchema` is `async` and takes POSITIONAL args, no options object.** The
    full signature is
-   `buildSchema(rootSchema, rootTypeName, extensions?, typesOnly?, logWarnings?, strict?, helpersMode?, helpersImportPrefix?, readonly?, stripUnknown?, typeSuffix?, importExt?, caseInsensitive?)`.
+   `buildSchema(rootSchema, rootTypeName, extensions?, typesOnly?, logWarnings?, strict?, helpersMode?, helpersImportPrefix?, readonly?, stripUnknown?, typeSuffix?, importExt?, caseInsensitive?, schemas?, unknownKeys?)`.
    To set a later flag you must pass every intervening positional. (The README's
-   short form omits the trailing seven.)
+   short form omits the trailing seven.) `unknownKeys` (`'count-keys'` by default,
+   `'count-enumerable'` for Node-only output) picks how a closed object's fast
+   path counts keys; nothing in the generated code detects its runtime.
 2. **It returns files in memory — it does NOT write to disk.** You write the
    `GeneratedFile[]` (`{ filename, content }`) yourself. `rootTypeName` becomes
    that filename (lowercased) as well as the `export type` name, so it must be a

package/README.md

@@ -95,6 +95,7 @@ Every option after the first two is **positional** — pass them in this order:
 | 12 | `importExt` | `'js' \| 'ts'` | `'js'` | Extension emitted on relative import specifiers. `'js'` is the NodeNext form for output you compile; `'ts'` emits the literal on-disk paths so the sources run unbuilt. |
 | 13 | `caseInsensitive` | `boolean` | `false` | Normalize a mis-cased string to the exact casing of an enum/const member it matches case-insensitively. Coerce mode only. |
 | 14 | `schemas` | `Record<string, unknown>` | — | Documents you have **already loaded**, keyed by the absolute URI a `$ref` names them by. See below. |
+| 15 | `unknownKeys` | `'count-keys' \| 'count-enumerable'` | `'count-keys'` | How a fast path proves a closed object (`additionalProperties: false`, or a `stripUnknown` build) has no undeclared key: a prototype-guarded `Object.keys(input).length` (fastest on Bun) or a `for…in` count (fastest on Node). See [Counting keys on the fast path](#counting-keys-on-the-fast-path). |
 
 Returns: `Promise<GeneratedFile[]>`.
 
@@ -184,6 +185,14 @@ nobody registered still stops the build, with a message naming the ref.
 <tr>
 <td colspan="3">Normalize a mis-cased string to the exact casing of a declared enum/const member it matches case-insensitively (e.g. hElLo → hello) instead of coercing to the default. Coerce mode only — strict parsers still reject a casing mismatch. Correctly-cased input keeps the exact-match fast path, so the hot path is unaffected.</td>
 </tr>
+<tr>
+<td>🔢 <code>unknownKeys</code></td>
+<td><code>string</code></td>
+<td align="center"><code>"count-keys"</code></td>
+</tr>
+<tr>
+<td colspan="3">How a fast path proves a closed object (additionalProperties: false, or a stripUnknown build) carries no undeclared key. 'count-keys' is a prototype-guarded Object.keys(input).length comparison, the faster form on JavaScriptCore (Bun); 'count-enumerable' is a for…in count that allocates nothing; it was the faster form on Node 22, but on Node 26 'count-keys' ties or wins there too. Keep the default unless you are pinned to an older V8 and have measured your own shapes; nothing detects the runtime at runtime.<br><strong>Allowed:</strong> <code>"count-enumerable"</code>, <code>"count-keys"</code></td>
+</tr>
 </tbody>
 </table>
 <!-- config-table-end -->
@@ -237,9 +246,10 @@ Three deliberate departures:
   Ajv accepts `"a string"` against `{ properties: { a: {} } }`; a parser has to
   return the type it declares, and the declared type is an object.
 
-If a strict parser cannot enforce something — a `$ref` cycle it would have to
-inline because the build emits a single file, a subschema using a keyword it
-cannot prove — generation **fails with an error naming the keyword** rather than
+If a strict parser cannot enforce something — a `$ref` cycle inside a subschema it
+has to match inline (`contains`, `not`, `propertyNames`, `dependentSchemas`, or an
+`unevaluated*` backstop), which the inline matcher will not unroll; a subschema
+using a keyword it cannot prove — generation **fails with an error naming the keyword** rather than
 emitting a parser that quietly accepts what the schema forbids. Coercing
 (non-strict) parsers are documented to repair rather than reject, so they ignore
 the rejecting keywords by design.
@@ -266,8 +276,9 @@ no I/O to answer the retrieval step. Everything else — applying the base URIs,
 walking anchors across documents, emitting a parser per definition and an import
 graph that links — the generator still has to do.
 
-Of the 41 that do not, **18** are the `ignores a non-object` cases that follow
-from the third departure above, and **12** are a keyword strict mode will not
+Of the 41 that do not, **18** follow from the third departure above — the
+`ignores a non-object` cases plus three `ref.json` cases where a recursive `$ref`
+lands on a root that declares `properties` — and **12** are a keyword strict mode will not
 approximate (a cyclic `$ref` with siblings, a cyclic `unevaluatedProperties`) —
 those cost a build error naming the cause, never a wrong verdict. The rest: **8**
 `$dynamicRef`s whose binding depends on the evaluation path (a generator emits one
@@ -296,20 +307,34 @@ keys) and `parseStrict` (assert + reject undeclared keys) halves of
 [`moltar/typescript-runtime-type-benchmarks`](https://github.com/moltar/typescript-runtime-type-benchmarks)
 against the other *pure* parsers — the ones that return a new typed value rather
 than mutating in place — [zod](https://zod.dev) and
-[TypeBox](https://github.com/sinclairzx81/typebox). Measured on Bun 1.4 (Linux
-x64), parsing valid input at steady state:
-
-| case | mode | mjst (generated) | zod | typebox |
-|:--|:--|--:|--:|--:|
-| user (4 fields) | parseSafe | **~18M** ops/s | ~3.7M ops/s | ~1.6M ops/s |
-| order (nested + array) | parseSafe | **~6.9M** ops/s | ~0.71M ops/s | ~0.24M ops/s |
-| user (4 fields) | parseStrict | **~14M** ops/s | ~2.3M ops/s | ~2.04M ops/s |
-| order (nested + array) | parseStrict | **~7M** ops/s | ~0.43M ops/s | ~0.36M ops/s |
-
-The upstream `assert` case (seven scalar roots plus a nested object) runs faster
-still — ~51M ops/s strict, ~127M safe — but at that size the numbers swing enough
-run-to-run that the ratio, not the absolute, is the honest signal: mjst lands
-~5–29× ahead of zod across every case above.
+[TypeBox](https://github.com/sinclairzx81/typebox).
+
+Both runtimes were measured together on one machine (Linux x64, a 4-vCPU cloud
+box, Bun 1.4.0 and Node 26.8.1 — the same machine and runtimes as every table in
+this repo), each cell the median of three separate runs of the whole suite.
+Within one sitting a cell repeats to within a few percent; the same suite
+measured hours later moved ~60% across every case at once, so read the ratios
+and treat the absolutes as a property of that box.
+
+Parsing valid input at steady state:
+
+| case | mode | Bun: mjst | Bun: zod | Bun: typebox | Node: mjst | Node: zod | Node: typebox |
+|:--|:--|--:|--:|--:|--:|--:|--:|
+| user (4 fields) | parseSafe | **~163M** | ~3.3M | ~1.7M | **~88M** | ~4.0M | ~0.67M |
+| order (nested + array) | parseSafe | **~7.7M** | ~0.60M | ~0.26M | **~8.2M** | ~0.64M | ~0.15M |
+| assert (moltar shape) | parseSafe | **~120M** | ~3.5M | ~0.87M | **~66M** | ~5.3M | ~0.35M |
+| user (4 fields) | parseStrict | **~43M** | ~1.9M | ~2.2M | **~55M** | ~2.7M | ~1.5M |
+| order (nested + array) | parseStrict | **~13M** | ~0.36M | ~0.43M | **~8.7M** | ~0.55M | ~0.25M |
+| assert (moltar shape) | parseStrict | **~44M** | ~1.4M | ~1.2M | **~34M** | ~3.5M | ~0.80M |
+
+<sub>ops/s, higher is better.</sub>
+
+Unlike the validator suite — where TypeBox's compiled checker takes the loose
+moltar shape on V8 — the generated parser leads every case on both engines:
+~12–49× over zod on Bun and ~13–22× on Node. The two `user`/`assert` safe cells
+are the ones to read as ratios rather than absolutes: stripping to four declared
+keys builds one small object and nothing else, which is fast enough that the
+engine's inlining, not the parser, sets the number.
 
 What is replicated upstream is the *cases* — the two parse modes and their
 shapes — not the harness. These numbers come from this repo's own measurement
@@ -321,9 +346,9 @@ reproducible run of both harnesses:
 [Against the moltar harness](../generate-validators#against-the-moltar-harness).
 
 The trade is a one-shot **prepare** cost that only mjst pays — generating the
-parser source — which measures **~0.2–0.8 ms** per schema here (zod and TypeBox
-author or interpret their parsers with no separate build step, so there is
-nothing to time). That is trivially amortized: you generate once at build time
+parser source — which measures **~0.20–0.74 ms** per schema on Bun and
+**~0.16–0.72 ms** on Node (zod and TypeBox author or interpret their parsers
+with no separate build step, so there is nothing to time). That is trivially amortized: you generate once at build time
 and run the emitted code forever.
 
 Every library is checked for agreement — same stripped/rejected output, same
@@ -333,9 +358,48 @@ the optimiser can't hoist the work away. Micro-benchmark figures vary by machine
 and runtime — reproduce with:
 
 ```bash
-bun run bench
+bun run bench        # Bun / JavaScriptCore
+bun run bench:node   # Node / V8 (builds the package first, then runs it under node)
 ```
 
+### Counting keys on the fast path
+
+A closed object whose declared properties are all required proves "no undeclared
+key" by counting: the typed checks ahead of the count have already proven every
+declared key present, so exactly *n* keys means no extra. `unknownKeys` (the 15th
+positional argument, `--unknown-keys` on the CLI) picks how the count is spelled,
+because the two spellings trade places between the engines:
+
+- **`'count-keys'`** (default) — `Object.getPrototypeOf(input) === Object.prototype
+  && Object.keys(input).length === n`, one more term of the fast-path guard. The
+  prototype guard keeps an own-key count sound: a crafted prototype could satisfy
+  the typed checks through an inherited declared key while an own extra kept the
+  count at *n*, so a non-plain object takes the cold path instead, whose `for…in`
+  rejection sees the inherited key.
+- **`'count-enumerable'`** — `let c = 0; for (const k in input) c++`, as
+  statements behind the guard. It allocates nothing and needs no prototype guard
+  (the count sees inherited keys too), and on V8 it is answered from the enum
+  cache. On JavaScriptCore a `for…in` over a non-extensible object is the engine's
+  slow path, and the strict parse runs at half speed.
+
+A nested object's shape is proven on the parent's fast path by the same checks
+its own shape validator makes, spelled out over the cached local rather than
+called — `typeof _nested === "object" && … && Object.keys(_nested).length === n`
+— one level deep and within a size budget, because a call was the one thing
+left on the strict fast path that JavaScriptCore would not see through. Under
+the moltar harness (each case alone in its own process) `parseStrict` reaches
+the harness floor on Bun 1.4.0 (~360M ops/s, the call eliminated) with
+`count-keys` against ~22M with `count-enumerable`.
+
+On Node the answer has moved with the engine. On Node 22 the two spellings were
+level (~14M either way, which is where the advice to flip it came from); on
+Node 26.8.1 `count-keys` measures ~29M against `count-enumerable`'s ~26M, so the
+default now ties or wins on both engines. Keep the default unless you are
+pinned to an older V8 and have measured your own shapes. See
+[Choosing how keys are counted](../generate-validators#choosing-how-keys-are-counted)
+in the sister package for the validator numbers and the full trade-off. Whichever
+you pick, every verdict on a value that could have come from JSON is the same.
+
 ---
 
 ## Related packages

package/dist/generators/build-schema.d.ts

@@ -1,3 +1,4 @@
+import { type UnknownKeysStrategy } from '@amritk/helpers/unknown-keys-strategy';
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
 import type { HelpersMode } from '../helpers/collect-helpers.js';
 import type { ImportExtension } from '../helpers/collect-imports.js';
@@ -70,6 +71,11 @@ export type GeneratedFile = {
  *   is yours to do (or `@amritk/resolve-refs`'), and a `$ref` to a URI nobody registered still
  *   stops generation. Only the documents actually referenced get files, so registering more
  *   than the schema uses costs nothing in the output.
+ * @param unknownKeys - How the generated fast paths prove a closed object
+ *   (`additionalProperties: false`, or a `stripUnknown` build) carries no undeclared key:
+ *   `'count-keys'` (the default) compares `Object.keys(input).length` behind a plain-prototype
+ *   guard, `'count-enumerable'` counts with `for…in`. The first is the faster form on
+ *   JavaScriptCore (Bun), the second on V8 (Node) — see the README for the measurements.
  * @returns An array of generated TypeScript files
  *
  * @example
@@ -102,4 +108,4 @@ export type GeneratedFile = {
  * });
  * ```
  */
-export declare const buildSchema: (rootSchema: JSONSchema, rootTypeName: string, extensions?: SchemaExtensions, typesOnly?: boolean, logWarnings?: boolean, strict?: boolean, helpersMode?: HelpersMode, helpersImportPrefix?: string, readonly?: boolean, stripUnknown?: boolean, typeSuffix?: string, importExt?: ImportExtension, caseInsensitive?: boolean, schemas?: Readonly<Record<string, unknown>>) => Promise<GeneratedFile[]>;
+export declare const buildSchema: (rootSchema: JSONSchema, rootTypeName: string, extensions?: SchemaExtensions, typesOnly?: boolean, logWarnings?: boolean, strict?: boolean, helpersMode?: HelpersMode, helpersImportPrefix?: string, readonly?: boolean, stripUnknown?: boolean, typeSuffix?: string, importExt?: ImportExtension, caseInsensitive?: boolean, schemas?: Readonly<Record<string, unknown>>, unknownKeys?: UnknownKeysStrategy) => Promise<GeneratedFile[]>;

package/dist/generators/build-schema.js

@@ -3,6 +3,7 @@ import { createRequire } from "node:module";
 import { dirname, resolve as resolvePath } from "node:path";
 import { foldNullable } from "@amritk/helpers/fold-nullable";
 import { generateIndexBarrel } from "@amritk/helpers/generate-index-barrel";
+import { DEFAULT_UNKNOWN_KEYS } from "@amritk/helpers/unknown-keys-strategy";
 import { walkRefGraph } from "@amritk/helpers/walk-ref-graph";
 import { applySchemaExtensions } from "../helpers/apply-schema-extensions.js";
 import { generateFile } from "./generate-files.js";
@@ -26,7 +27,7 @@ const assertRootTypeName = (rootTypeName) => {
     return;
   throw new Error(`Invalid root type name ${JSON.stringify(rootTypeName)}: expected a TypeScript identifier. The name is emitted as \`export type <name>\` and, lowercased, used as the output filename, so anything else either fails to compile or escapes the output directory. Derive it with @amritk/helpers' \`deriveRootTypeName\`, which always produces one.`);
 };
-const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = "package", helpersImportPrefix = "./", readonly = false, stripUnknown = false, typeSuffix = "", importExt = "js", caseInsensitive = false, schemas) => {
+const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = "package", helpersImportPrefix = "./", readonly = false, stripUnknown = false, typeSuffix = "", importExt = "js", caseInsensitive = false, schemas, unknownKeys = DEFAULT_UNKNOWN_KEYS) => {
   assertRootTypeName(rootTypeName);
   const files = [];
   const usedHelpers = /* @__PURE__ */ new Set();
@@ -49,7 +50,8 @@ const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logW
       ...logWarnings !== void 0 ? { logWarnings } : {},
       ...strict !== void 0 ? { strict } : {},
       ...stripUnknown ? { stripUnknown } : {},
-      ...caseInsensitive ? { caseInsensitive } : {}
+      ...caseInsensitive ? { caseInsensitive } : {},
+      unknownKeys
     });
     files.push({ filename: `${node.filename}.ts`, content: result.content });
     for (const helper of result.usedHelpers)

package/dist/generators/generate-files.d.ts

@@ -1,3 +1,4 @@
+import { type UnknownKeysStrategy } from '@amritk/helpers/unknown-keys-strategy';
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
 import { type HelpersMode, type RuntimeHelperName } from '../helpers/collect-helpers.js';
 import { type ImportExtension } from '../helpers/collect-imports.js';
@@ -92,6 +93,12 @@ type GenerateFileOptions = {
      * already-valid input keeps the exact-match fast path.
      */
     readonly caseInsensitive?: boolean;
+    /**
+     * How the generated fast paths prove a closed object carries no undeclared
+     * key — `Object.keys` (the default) or a `for…in` count. See
+     * {@link UnknownKeysStrategy} for the trade-off between the two.
+     */
+    readonly unknownKeys?: UnknownKeysStrategy;
 };
 /** Result of generating a single parser file. */
 export type GeneratedFileContent = {

package/dist/generators/generate-files.js

@@ -1,4 +1,5 @@
 import { generateTypeDefinition } from "@amritk/helpers/generate-type-definition";
+import { DEFAULT_UNKNOWN_KEYS } from "@amritk/helpers/unknown-keys-strategy";
 import { collectHelpers } from "../helpers/collect-helpers.js";
 import { collectImports, collectImportTypeNames } from "../helpers/collect-imports.js";
 import { generateParserFunction, generateShapeValidator } from "./generate-parser-function.js";
@@ -40,12 +41,14 @@ const generateFile = (schema, typeName, options) => {
     rootSchema,
     typeSuffix
   });
-  const shapeValidator = generateShapeValidator(schema, typeName, true, typeSuffix, true, stripUnknown, reservedNames);
+  const unknownKeys = options?.unknownKeys ?? DEFAULT_UNKNOWN_KEYS;
+  const shapeValidator = generateShapeValidator(schema, typeName, true, typeSuffix, true, stripUnknown, reservedNames, unknownKeys);
   const parserFunction = generateParserFunction(schema, typeName, {
     useRefImports: true,
     typeSuffix,
     reservedNames,
     shapeValidatorSource: shapeValidator,
+    unknownKeys,
     ...options?.isRoot !== void 0 ? { isRoot: options.isRoot } : {},
     ...rootSchema !== void 0 ? { rootSchema } : {},
     ...options?.logWarnings !== void 0 ? { logWarnings: options.logWarnings } : {},

package/dist/generators/generate-parser-function.d.ts

@@ -1,3 +1,4 @@
+import { type UnknownKeysStrategy } from '@amritk/helpers/unknown-keys-strategy';
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
 /**
  * Options for controlling parser function generation behavior.
@@ -67,6 +68,13 @@ type GenerateParserOptions = {
      * exact `===` fast path and the hot path is unaffected.
      */
     readonly caseInsensitive?: boolean;
+    /**
+     * How the fast paths prove a closed object carries no undeclared key —
+     * `Object.getPrototypeOf(input) === Object.prototype && Object.keys(input).length`
+     * (the default) or a `for…in` count. See {@link UnknownKeysStrategy} for the
+     * trade-off, and {@link keyCountCheck} for what each form emits.
+     */
+    readonly unknownKeys?: UnknownKeysStrategy;
     /**
      * The exact source of the `validate{TypeName}Shape` predicate emitted into
      * the same file as this parser (generate-files produces it for the root
@@ -108,5 +116,5 @@ export declare const shapeValidatorFunctionName: (typeName: string) => string;
  * in additionalProperties). The stub is safe: parents calling it will fall
  * through to the slow path, matching the pre-deep-fast-path behavior.
  */
-export declare const generateShapeValidator: (schema: JSONSchema, typeName: string, useRefImports: boolean, suffix?: string, exported?: boolean, stripUnknown?: boolean, reservedNames?: ReadonlySet<string>) => string;
+export declare const generateShapeValidator: (schema: JSONSchema, typeName: string, useRefImports: boolean, suffix?: string, exported?: boolean, stripUnknown?: boolean, reservedNames?: ReadonlySet<string>, unknownKeys?: UnknownKeysStrategy) => string;
 export {};