@amritk/generate-validators 0.15.1 → 0.16.0

package/AI.md

@@ -27,9 +27,11 @@ const files = await buildValidatorSchema(schema, 'Document')
    `validateFoo` returns `true | { valid: false; errors: ValidationError[] }`.
    Check `if (result !== true)` for the failure path — `if (result.valid)` is
    wrong.
-2. **Small signature:** `buildValidatorSchema(rootSchema, rootTypeName, typeSuffix?)`
-   — async, no `strict`/`typesOnly`/options. Returns `GeneratedFile[]` in memory
-   (you write them).
+2. **Small signature:** `buildValidatorSchema(rootSchema, rootTypeName, typeSuffix?, schemas?, unknownKeys?)`
+   — async, no `strict`/`typesOnly`/options object. Returns `GeneratedFile[]` in
+   memory (you write them). `unknownKeys` (`'count-keys'` by default,
+   `'count-enumerable'` for Node-only output) picks how a closed object's guard
+   counts keys; nothing in the generated code detects its runtime.
 3. **Output includes a shared `validation-result.ts`** (`ValidationError`,
    `ValidationResult`, helpers) plus the `index.ts` barrel.
 4. **`NaN` fails a *constrained* number** (`minimum`/`maximum`/`multipleOf` all

package/README.md

@@ -84,7 +84,7 @@ if (!result.valid) {
 
 ## API
 
-### `buildValidatorSchema(rootSchema, rootTypeName, typeSuffix?, schemas?)`
+### `buildValidatorSchema(rootSchema, rootTypeName, typeSuffix?, schemas?, unknownKeys?)`
 
 | Parameter | Type | Default | Description |
 |:---|:---|:---|:---|
@@ -92,6 +92,7 @@ if (!result.valid) {
 | `rootTypeName` | `string` | — | Name used for the root type (e.g. `"Document"`). |
 | `typeSuffix` | `string` | `''` | Suffix appended to every `$ref`-derived type name (`'Object'` turns `Contact` into `ContactObject`). The root type name is unaffected. |
 | `schemas` | `Record<string, unknown>` | — | Documents you have **already loaded**, keyed by the absolute URI a `$ref` names them by. See below. |
+| `unknownKeys` | `'count-keys' \| 'count-enumerable'` | `'count-keys'` | How the fast paths prove a closed object (`additionalProperties: false`) has no undeclared key: `Object.keys(obj).length` (fastest on Bun) or a `for…in` count (fastest on Node). See [Choosing how keys are counted](#choosing-how-keys-are-counted). |
 
 Returns: `Promise<GeneratedFile[]>` where `GeneratedFile = { filename: string; content: string }`.
 
@@ -244,30 +245,64 @@ of it is published.
 Generated validators are straight-line, monomorphic TypeScript with no generic
 dispatch. The exported `validateX` is split into a hot and a cold half: on the
 happy path it runs a single allocation-free boolean guard — a pure `&&` chain of
-`typeof` checks (plus an `Object.keys().length` count when an object is closed
-with `additionalProperties: false`) — and `return true`s straight away, only
-calling a separate error-collecting function when something is actually wrong.
-Keeping the hot function tiny lets the JIT optimise it aggressively, so a valid-input
-check beats every other library measured — including the build-time transformer
-typia — while still emitting full JSON-Pointer errors for invalid input, and
-emitting the validator stays far cheaper than compiling a schema at startup.
-Measured on Bun 1.4 (Linux x64), validating valid input at steady state:
+`typeof` checks, every nested object loaded once into a local, plus a key count
+when an object is closed with `additionalProperties: false` — and `return true`s
+straight away, only calling a separate error-collecting function when something
+is actually wrong.
+Keeping the hot function tiny lets the JIT optimise it aggressively, so a
+valid-input check beats every other library measured on JavaScriptCore — the
+build-time transformer typia included — while still emitting full JSON-Pointer
+errors for invalid input, and emitting the validator stays far cheaper than
+compiling a schema at startup. On V8 that lead is not universal: TypeBox's
+compiled checker wins the `assert-loose` shape outright and draws level on
+`assert-strict`, which is why both engines get a table rather than one standing
+in for the other.
+
+Both 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 is the median of three separate runs of the whole suite. Treat
+the absolutes as a property of that box: within one sitting a cell repeats to
+within a few percent, but the same suite measured again hours later moved by
+~60% across every case at once, so the ratios are the durable part and a
+remembered number is not a baseline.
+
+**Bun 1.4.0 / JavaScriptCore**, validating valid input at steady state:
 
 | schema | mjst (generated) | typia (transformed) | ajv (compiled) | typebox (compiled) | zod |
 |:--|--:|--:|--:|--:|--:|
-| small (4 fields) | **~59M** ops/s | ~5.8M ops/s | ~10M ops/s | ~7.6M ops/s | ~2.2M ops/s |
-| order (nested + array) | **~9.5M** ops/s | ~2M ops/s | ~3.9M ops/s | ~3.3M ops/s | ~0.54M ops/s |
-| assert-loose | **~189M** ops/s | ~170M ops/s | ~44M ops/s | ~78M ops/s | ~5M ops/s |
-| assert-strict | **~104M** ops/s | ~68M ops/s | ~21M ops/s | ~42M ops/s | ~1.8M ops/s |
+| small (4 fields) | **~59M** ops/s | ~6.7M ops/s | ~11M ops/s | ~8.9M ops/s | ~2.4M ops/s |
+| order (nested + array) | **~10M** ops/s | ~2.6M ops/s | ~4.1M ops/s | ~3.6M ops/s | ~0.50M ops/s |
+| assert-loose | **~190M** ops/s | ~170M ops/s | ~46M ops/s | ~80M ops/s | ~3.6M ops/s |
+| assert-strict | **~171M** ops/s | ~58M ops/s | ~23M ops/s | ~45M ops/s | ~1.4M ops/s |
+
+**Node 26.8.1 / V8**, the same cases. typia is absent because its checks come
+from a compile-time transform delivered as a Bun preload, so the Node run cannot
+build one at all:
+
+| schema | mjst (generated) | ajv (compiled) | typebox (compiled) | zod |
+|:--|--:|--:|--:|--:|
+| small (4 fields) | **~56M** ops/s | ~7.0M ops/s | ~6.6M ops/s | ~2.2M ops/s |
+| order (nested + array) | **~8.9M** ops/s | ~2.8M ops/s | ~2.9M ops/s | ~0.48M ops/s |
+| assert-loose | ~90M ops/s | ~71M ops/s | **~138M** ops/s | ~6.0M ops/s |
+| assert-strict | ~37M ops/s | ~25M ops/s | **~37M** ops/s | ~3.6M ops/s |
+
+Read the two together. On the object schemas — the shapes an application
+actually validates — the generated validator leads on both engines, by 5–9× over
+the next-fastest on Bun and 2.4–8× on Node. On the moltar shapes it leads
+everything on JavaScriptCore and loses the loose one to TypeBox on V8 (~138M
+against ~90M), with `assert-strict` a coin toss. Those two cases are seven
+scalar roots and a nested object: near-trivial work where the engine's own
+inlining decides the winner, not the validator's design.
 
 The `assert-loose` / `assert-strict` rows use the same *shape* as
 [`moltar/typescript-runtime-type-benchmarks`](https://github.com/moltar/typescript-runtime-type-benchmarks)
-(seven scalar roots plus a nested object): the boolean guard keeps mjst ahead of
-typia on both, by ~11% on `assert-loose` — close enough that the two can trade
-the lead run-to-run — and by ~52% on `assert-strict` (with
+(seven scalar roots plus a nested object): on JavaScriptCore the boolean guard
+keeps mjst ahead of typia on both, by ~12% on `assert-loose` — close enough that
+the two trade the lead run-to-run — and by ~3× on `assert-strict` (with
 `additionalProperties: false`), where mjst counts keys once and typia does not.
-(typia and TypeBox still win the *invalid* path, where they bail on the first
-error rather than collecting a full error list.)
+On V8 the same two rows go the other way against TypeBox, as the tables above
+show. (typia and TypeBox still win the *invalid* path on both engines, where
+they bail on the first error rather than collecting a full error list.)
 
 They are **not** that project's numbers and they do not belong next to its
 leaderboard: the shape is shared, the harness is not, and the harness is worth
@@ -275,9 +310,16 @@ an order of magnitude. See
 [Against the moltar harness](#against-the-moltar-harness) for the same functions
 measured under benny, the way the leaderboard measures them.
 
-Preparing a validator costs ~0.3–0.7 ms for mjst codegen and ~0.05–0.2 ms for a
-TypeBox `TypeCompiler` compile, versus ~13–17 ms for an Ajv compile. Every library
-agrees on every verdict; parity is asserted before timing.
+Preparing a validator, by runtime (medians over the four cases above):
+
+| | mjst codegen | TypeBox compile | Ajv compile |
+|:--|--:|--:|--:|
+| Bun 1.4.0 | ~0.30–0.66 ms | ~0.04–0.23 ms | ~9.7–13 ms |
+| Node 26.8.1 | ~0.27–0.58 ms | ~0.04–0.11 ms | ~5.3–6.4 ms |
+
+Ajv's compile is the one prepare cost that roughly halves on V8; the other two
+are within a whisker of each other on both engines. Every library agrees on
+every verdict; parity is asserted before timing.
 
 One caveat on the first two rows: their schemas declare `format` (`uuid`,
 `email`), and Ajv, typia, zod, and TypeBox all check it, while mjst's generated
@@ -292,7 +334,8 @@ numbers stay reproducible. 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)
 ```
 
 ### Against the moltar harness
@@ -313,22 +356,27 @@ measured.
 `bun run bench:moltar` runs exactly that harness over the same functions, always
 alongside a **no-op** control — a "validator" that checks nothing, which is the
 fastest number the harness can physically produce. One run on this machine
-(Linux x64, Bun 1.3.11 / Node 22.22, valid input):
+(Linux x64, Bun 1.4.0 / Node 26.8.1, valid input):
 
 | harness | runtime | `assert-loose` | `assert-strict` |
 |:--|:--|--:|--:|
-| this package (`measure.ts`) | Bun | ~200M ops/s | ~185M ops/s |
-| benny, moltar's `Benchmark` | Node | ~100M ops/s | ~38M ops/s |
-| benny, moltar's `Benchmark` | Bun | ~70M ops/s | ~2.4M ops/s |
-| *no-op control, benny* | *Node* | *~120M ops/s* | *~120M ops/s* |
-| *no-op control, benny* | *Bun* | *~325M ops/s (±75%)* | *~325M ops/s (±75%)* |
-
-Read two things out of that. First, on Node the `assert-loose` figure sits
-within 20% of a validator that does nothing, so under that harness it is not a
+| this package (`measure.ts`) | Bun | ~190M ops/s | ~171M ops/s |
+| this package (`measure.ts`) | Node | ~90M ops/s | ~37M ops/s |
+| benny, moltar's `Benchmark` | Bun | ~90M ops/s | ~76M ops/s |
+| benny, moltar's `Benchmark` | Node | ~80M ops/s | ~34M ops/s |
+| *no-op control, benny* | *Node* | *~91M ops/s* | *~96M ops/s* |
+| *no-op control, benny* | *Bun* | *~508M ops/s (±46%)* | *~449M ops/s (±48%)* |
+
+Read three things out of that. First, on Node the `assert-loose` figure sits
+within 12% of a validator that does nothing, so under that harness it is not a
 validator measurement at all: above that floor a faster validator cannot show
 up as a faster number, and the published leaderboard runs on CI hardware slower
-than this box, where the floor sits lower still. Second, `assert-strict` on Bun collapses to
-~2.4M because moltar's fixture is `Object.freeze({ … })` — see
+than this box, where the floor sits lower still. Second, the harness reorders
+the field: under benny on Node this validator leads TypeBox (~80M against
+~54M), the reverse of what `measure.ts` reports for the same two functions on
+the same engine, because benny's floor compresses the top of the range. Third,
+moltar's fixture is `Object.freeze({ … })`: under Bun 1.3 that collapsed the Bun
+`assert-strict` cell to ~2.4M, and Bun 1.4.0 has closed that cliff — see
 [Frozen inputs](#frozen-inputs).
 
 The harness makes no difference to correctness and every difference to the
@@ -343,45 +391,101 @@ bun run bench:moltar   # benny, under the leaderboard's conditions
 
 Closing an object with `additionalProperties: false` means proving no
 undeclared key is present, and every library answers that by enumerating keys:
-mjst's guard counts them (`Object.keys(obj).length === n`, exact because each
-declared property is required and already proven present), Ajv and Zod sweep
-with `for...in`, TypeBox runs its own sweep. On V8 that costs the same whatever
-the input looks like.
-
-On JavaScriptCore (Bun) it does not. Making an object non-extensible —
-`Object.freeze`, `Object.seal` or a bare `Object.preventExtensions` — turns off
+mjst's guard counts them (`Object.keys(obj).length === n` by default, exact
+because each declared property is required and already proven present — see
+[Choosing how keys are counted](#choosing-how-keys-are-counted) for the
+`for...in` alternative), Ajv and Zod sweep with `for...in`, TypeBox runs its own
+sweep. On V8 that costs the same whatever the input looks like.
+
+On JavaScriptCore under Bun 1.3 it did not. Making an object non-extensible —
+`Object.freeze`, `Object.seal` or a bare `Object.preventExtensions` — turned off
 the engine's cached own-keys fast path, and *every* form of key enumeration
-falls back to a generic walk: `Object.keys`, `Object.getOwnPropertyNames`,
-`Reflect.ownKeys` and `for...in` alike. Property reads are untouched (a frozen
-object reads at full speed), so the whole cost lands on the extra-key sweep, and
-therefore on strict schemas only. Frozen inputs are ordinary — a config object
-frozen at startup, a shared fixture, a module-level constant — so `bun run bench`
-carries `small (4 fields, frozen)` and `assert-strict (frozen)` cases to keep it
-measured. One run on this machine (Linux x64, Bun 1.3.11), valid input:
-
-| `assert-strict` | mutable input | frozen input |
-|:--|--:|--:|
-| mjst (generated) | ~185M ops/s | ~1.7M ops/s |
-| typia (transformed) | ~68M ops/s | ~1.7M ops/s |
-| typebox (compiled) | ~46M ops/s | ~1.7M ops/s |
-| ajv (compiled) | ~24M ops/s | ~1.5M ops/s |
-| zod | ~1.4M ops/s | ~0.7M ops/s |
-
-It is an engine-level cliff, not an mjst one: every compiled or generated strict
-validator lands within a hair of the same number, because they are all paying
-the same engine slow path. The generated code keeps the key count anyway. Every
-alternative was measured and every one is worse overall. `Object.values(obj)`
-and `Object.keys({ ...obj })` sidestep the cliff, but on the ordinary mutable
-path they cost 28–37× under JSC and 2–7× under V8. Branching on
-`Object.isExtensible(obj)` first keeps the mutable path recognisable, at ~4×
-under JSC — and makes V8 slower in *both* directions (~2× mutable, ~7× frozen),
-where there was no cliff to fix in the first place. Trading a large, portable
-regression for a smaller win on one engine is not a good deal, so the sweep
-stays as it is.
-
-If it matters for your workload: validate before freezing (the verdict is the
-same either way — `src/generators/frozen-input.test.ts` pins that), or run on a
-V8 runtime, where the cliff does not exist.
+fell back to a generic walk: `Object.keys`, `Object.getOwnPropertyNames`,
+`Reflect.ownKeys` and `for...in` alike. Property reads were untouched (a frozen
+object read at full speed), so the whole cost landed on the extra-key sweep, and
+therefore on strict schemas only. Bun 1.4.0 no longer shows the cliff — frozen
+and mutable input run at the same speed for every library. Frozen inputs are
+ordinary — a config object frozen at startup, a shared fixture, a module-level
+constant — so `bun run bench` keeps carrying `small (4 fields, frozen)` and
+`assert-strict (frozen)` cases to keep it measured. Medians of three runs on
+this machine (Linux x64), valid input, on both current runtimes and on the Bun
+version that had the cliff:
+
+| `assert-strict` | Bun 1.4.0 mutable | Bun 1.4.0 frozen | Node 26 mutable | Node 26 frozen | Bun 1.3.11 mutable | Bun 1.3.11 frozen |
+|:--|--:|--:|--:|--:|--:|--:|
+| mjst (generated) | ~171M ops/s | ~166M ops/s | ~37M ops/s | ~35M ops/s | ~82M ops/s | ~1.5M ops/s |
+| typia (transformed) | ~58M ops/s | ~89M ops/s | n/a | n/a | ~37M ops/s | ~1.5M ops/s |
+| typebox (compiled) | ~45M ops/s | ~46M ops/s | ~37M ops/s | ~35M ops/s | ~27M ops/s | ~1.4M ops/s |
+| ajv (compiled) | ~23M ops/s | ~22M ops/s | ~25M ops/s | ~25M ops/s | ~12M ops/s | ~1.2M ops/s |
+| zod | ~1.4M ops/s | ~1.4M ops/s | ~3.6M ops/s | ~3.6M ops/s | ~0.91M ops/s | ~0.47M ops/s |
+
+<sub>typia is Bun-only: its checks come from a compile-time transform delivered
+as a Bun preload, so the Node run cannot build one.</sub>
+
+It was an engine-level cliff, not an mjst one: on Bun 1.3 every compiled or
+generated strict validator lands within a hair of the same number, because they
+are all paying the same engine slow path. The Node 26 columns are flat, frozen
+or not, which is what "V8 never had it" looks like measured rather than
+asserted. The generated code keeps the key count
+anyway. Every alternative was measured (on Bun 1.3.11) and every one is worse
+overall. `Object.values(obj)` and `Object.keys({ ...obj })` sidestep the cliff,
+but on the ordinary mutable path they cost 28–37× under JSC and 2–7× under V8.
+Branching on `Object.isExtensible(obj)` first keeps the mutable path
+recognisable, at ~4× under JSC — and makes V8 slower in *both* directions (~2×
+mutable, ~7× frozen), where there was no cliff to fix in the first place.
+Trading a large, portable regression for a smaller win on one engine is not a
+good deal, so the sweep stays as it is — and Bun 1.4 has since closed the cliff
+on its own.
+
+If it matters for your workload on an older Bun: validate before freezing (the
+verdict is the same either way — `src/generators/frozen-input.test.ts` pins
+that), or run on Bun ≥ 1.4 or a V8 runtime, where the cliff does not exist.
+
+### Choosing how keys are counted
+
+The count itself can be spelled two ways, and the two trade places between the
+engines. `unknownKeys` — the last argument of `buildValidatorSchema`, the
+`--unknown-keys` flag of the CLI, the same option on `@amritk/generate-parsers` —
+picks one at generation time:
+
+- **`'count-keys'`** (default) — `Object.keys(obj).length === n`. Builds a keys
+  array per call, which V8 scalar-replaces when only the length is read.
+- **`'count-enumerable'`** — `let c = 0; for (const k in obj) c++`. Allocates
+  nothing, and on V8 is answered straight from the shape's enum cache. On
+  JavaScriptCore a `for...in` over a non-extensible object is the slow path
+  described above, and even on a mutable one it trails `Object.keys`.
+
+Measured under the moltar harness (benny, the frozen fixture, each case alone in
+its own process — `bun run bench:moltar:leaderboard` prints one row per strategy
+on every runtime it finds), Linux x64. The Node 22 column is the earlier
+measurement this option was introduced against; the Node 26 column is the same
+harness on the current runtime:
+
+| case | `unknownKeys` | Bun 1.4 | Node 22 | Node 26 |
+|:--|:--|--:|--:|--:|
+| `assertStrict` (`isX`) | `count-keys` | ~441M ops/s (the harness floor — the call is eliminated) | ~19M ops/s | ~31M ops/s |
+| `assertStrict` (`isX`) | `count-enumerable` | ~42M ops/s | ~22M ops/s | ~30M ops/s |
+| `parseStrict` (`@amritk/generate-parsers`) | `count-keys` | ~359M ops/s (the harness floor again) | ~14M ops/s | ~29M ops/s |
+| `parseStrict` (`@amritk/generate-parsers`) | `count-enumerable` | ~22M ops/s | ~14M ops/s | ~26M ops/s |
+
+The default is `count-keys` because it is never the slower form on Bun and,
+with the nested shape check spelled out on the parse fast path, lets
+JavaScriptCore eliminate the strict parse as well. The Node case has changed
+with the engine: on Node 22 `count-enumerable` was level or slightly ahead,
+which is where the advice to flip it for Node-only builds came from, but on
+Node 26 the default is ahead in both rows. Keep it unless you are pinned to an
+older V8 and have measured your own shapes. The choice is made once, when the
+code is generated: nothing in the emitted file detects its runtime. (On Bun 1.3, where a frozen object puts
+`Object.keys` on the same slow path as `for...in`, both strategies sit at ~2M
+ops/s under this fixture and the default is a wash.)
+
+The two strategies also read different key sets — `Object.keys` sees own keys,
+`for...in` sees enumerable ones, inherited included — which no value parsed from
+JSON can tell apart. The `for...in` count agrees with the cold path exactly, so
+`isX` and `validateX` answer alike on a crafted prototype; the own-key count can
+accept an *inherited* extra that `validateXErrors` would report, and `isX` under
+it declines an inherited declared key that `validateX` accepts through its cold
+path. Neither strategy ever accepts a value the interpreter rejects on JSON data.
 
 ---
 

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';
 /**
  * Represents a generated TypeScript file with its filename and content.
@@ -11,7 +12,7 @@ export type GeneratedFile = {
  * types plus the helpers emitted code calls as free identifiers. Exported so tests
  * can evaluate the very source that ships instead of reimplementing it.
  */
-export declare const VALIDATION_RESULT_CONTENT = "/**\n * A single validation error with a human-readable message and a JSON Pointer\n * path indicating where in the document the error occurred.\n */\nexport type ValidationError = {\n  message: string\n  path: string\n}\n\n/**\n * The result of a generated validator function.\n * Returns `true` when the input is valid, or an object with `valid: false`\n * and a list of errors when it is not.\n */\nexport type ValidationResult = true | { valid: false; errors: ValidationError[] }\n\n/**\n * How deep a structural comparison walks before it gives up and answers \"not\n * equal\".\n *\n * JSON data is acyclic, but a generated validator is a plain function applied to\n * whatever in-memory value a caller hands it \u2014 and a self-referential object\n * reaching a `const` / `enum` / `uniqueItems` check used to recurse until the\n * stack overflowed, so `validateFoo` threw a `RangeError` instead of returning\n * the `ValidationResult` its signature promises. The cap turns that into an\n * ordinary \"these are different\" without ever coming near real data;\n * `@amritk/runtime-validators` guards its own `deepEqual` at the same depth.\n */\nconst MAX_EQUAL_DEPTH = 512\n\n/**\n * Structural deep equality used by generated `const` checks. Objects compare by\n * their key sets rather than serialization, so `{ a: 1, b: 2 }` and\n * `{ b: 2, a: 1 }` are equal \u2014 unlike `JSON.stringify`, which is key-order\n * sensitive and would reject a reordered-but-equal value.\n */\nexport const valuesEqual = (a: unknown, b: unknown, depth = 0): boolean => {\n  // SameValueZero: `===` settles every primitive except `NaN`, which counts as\n  // equal to itself here. That is what the native `Set` in {@link allUnique} does,\n  // what Ajv does, and what the interpreter's `deepEqual` does \u2014 leaving it out\n  // made a `NaN` nested inside an object compare unequal to itself, so the same\n  // array was \"unique\" here and \"duplicated\" everywhere else.\n  if (a === b || (Number.isNaN(a) && Number.isNaN(b))) return true\n  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false\n  if (depth >= MAX_EQUAL_DEPTH) return false\n  const aArray = Array.isArray(a)\n  const bArray = Array.isArray(b)\n  if (aArray !== bArray) return false\n  if (aArray) {\n    const aa = a as unknown[]\n    const bb = b as unknown[]\n    if (aa.length !== bb.length) return false\n    for (let i = 0; i < aa.length; i++) if (!valuesEqual(aa[i], bb[i], depth + 1)) return false\n    return true\n  }\n  const ao = a as Record<string, unknown>\n  const bo = b as Record<string, unknown>\n  const keys = Object.keys(ao)\n  if (keys.length !== Object.keys(bo).length) return false\n  for (const key of keys) {\n    if (!Object.hasOwn(bo, key) || !valuesEqual(ao[key], bo[key], depth + 1)) return false\n  }\n  return true\n}\n\n/**\n * A cheap, order-independent structural hash consistent with {@link valuesEqual}:\n * equal values always hash the same. It buckets candidate-equal elements in\n * {@link allUnique} so the exact comparison only ever runs inside a bucket.\n *\n * Object keys are folded commutatively (XOR) so key order does not change the\n * hash, and `NaN` / `-0` collapse the way SameValueZero does. Depth-capped like\n * {@link valuesEqual}: an over-deep value simply shares a bucket and is settled by\n * the (also capped) comparison, so the cap can cost a little time and never a\n * wrong answer. This is the same hash `@amritk/runtime-validators` uses.\n */\nconst structuralHash = (value: unknown, depth = 0): number => {\n  if (value === null) return 0x1a2b3c\n  const t = typeof value\n  if (t === 'number') {\n    const n = value as number\n    return Number.isNaN(n) ? 0x7ff8 : n === 0 ? 0 : Math.trunc(n * 2654435761) | 0\n  }\n  if (t === 'string') {\n    const s = value as string\n    let h = 0x811c9dc5\n    for (let i = 0; i < s.length; i++) h = Math.imul(h ^ s.charCodeAt(i), 0x01000193)\n    return h | 0\n  }\n  if (t === 'boolean') return value ? 1 : 2\n  if (t !== 'object') return 0x5eed\n  if (depth >= MAX_EQUAL_DEPTH) return 0xdee9\n  if (Array.isArray(value)) {\n    let h = 0x12345 ^ value.length\n    for (let i = 0; i < value.length; i++) h = (Math.imul(h, 31) + structuralHash(value[i], depth + 1)) | 0\n    return h | 0\n  }\n  const obj = value as Record<string, unknown>\n  const keys = Object.keys(obj)\n  let h = 0xabcde ^ keys.length\n  for (const k of keys) {\n    let kh = 0x811c9dc5\n    for (let i = 0; i < k.length; i++) kh = Math.imul(kh ^ k.charCodeAt(i), 0x01000193)\n    h = (h ^ (Math.imul(kh, 0x9e3779b1) + structuralHash(obj[k], depth + 1))) | 0\n  }\n  return h | 0\n}\n\n/**\n * True when every element of `arr` is distinct under structural equality\n * ({@link valuesEqual}). Backs generated `uniqueItems` checks whose items may be\n * objects or arrays, where a `JSON.stringify` dedupe key would be key-order\n * sensitive and let a reordered-but-equal duplicate (`{ a: 1, b: 2 }` vs\n * `{ b: 2, a: 1 }`) slip through.\n *\n * A native `Set` dedupes the all-primitive case in one linear pass. Object and\n * array elements are bucketed by {@link structuralHash} first, so the exact\n * comparison runs only against elements that could actually be equal: an array of\n * distinct objects costs ~O(n) instead of the O(n\u00B2) an exhaustive pairwise sweep\n * charged \u2014 4 000 rows took over half a second of pure comparison before, which\n * is a lot to hand an unauthenticated caller.\n */\nexport const allUnique = (arr: readonly unknown[]): boolean => {\n  const len = arr.length\n  if (len < 2) return true\n  let allPrimitive = true\n  for (let i = 0; i < len; i++) {\n    const v = arr[i]\n    if (v !== null && typeof v === 'object') {\n      allPrimitive = false\n      break\n    }\n  }\n  if (allPrimitive) return new Set(arr).size === len\n  const buckets = new Map<number, unknown[]>()\n  for (let i = 0; i < len; i++) {\n    const item = arr[i]\n    const hash = structuralHash(item)\n    const bucket = buckets.get(hash)\n    if (bucket === undefined) {\n      buckets.set(hash, [item])\n      continue\n    }\n    for (const seen of bucket) if (valuesEqual(seen, item)) return false\n    bucket.push(item)\n  }\n  return true\n}\n\n/**\n * Escapes one JSON Pointer segment (RFC 6901): `~` \u2192 `~0`, `/` \u2192 `~1`, in that\n * order. Generated error paths are built from *runtime* keys wherever the schema\n * did not name them \u2014 a `patternProperties` match, an `additionalProperties`\n * sweep, a `propertyNames` loop \u2014 and a key containing a `/` would otherwise read\n * back as two segments, so an error on `{\"a/b\": \u2026}` pointed at `/a/b`, which is\n * the child `b` of a property `a`. Keys the schema *does* name are escaped at\n * generation time instead, and `@amritk/runtime-validators` escapes the same way,\n * so all three agree.\n *\n * The `indexOf` pre-test keeps the common key \u2014 no `/`, no `~` \u2014 off the replace\n * path entirely, which is what the interpreter does for the same reason.\n */\nexport const escapePointer = (key: string): string =>\n  key.indexOf('/') !== -1 || key.indexOf('~') !== -1 ? key.replace(/~/g, '~0').replace(/\\//g, '~1') : key\n";
+export declare const VALIDATION_RESULT_CONTENT = "/**\n * A single validation error with a human-readable message and a JSON Pointer\n * path indicating where in the document the error occurred.\n */\nexport type ValidationError = {\n  message: string\n  path: string\n}\n\n/**\n * The result of a generated validator function.\n * Returns `true` when the input is valid, or an object with `valid: false`\n * and a list of errors when it is not.\n */\nexport type ValidationResult = true | { valid: false; errors: ValidationError[] }\n\n/**\n * How deep a structural comparison walks before it gives up and answers \"not\n * equal\".\n *\n * JSON data is acyclic, but a generated validator is a plain function applied to\n * whatever in-memory value a caller hands it \u2014 and a self-referential object\n * reaching a `const` / `enum` / `uniqueItems` check used to recurse until the\n * stack overflowed, so `validateFoo` threw a `RangeError` instead of returning\n * the `ValidationResult` its signature promises. The cap turns that into an\n * ordinary \"these are different\" without ever coming near real data;\n * `@amritk/runtime-validators` guards its own `deepEqual` at the same depth.\n */\nconst MAX_EQUAL_DEPTH = 512\n\n/**\n * Structural deep equality used by generated `const` checks. Objects compare by\n * their key sets rather than serialization, so `{ a: 1, b: 2 }` and\n * `{ b: 2, a: 1 }` are equal \u2014 unlike `JSON.stringify`, which is key-order\n * sensitive and would reject a reordered-but-equal value.\n */\nexport const valuesEqual = (a: unknown, b: unknown, depth = 0): boolean => {\n  // SameValueZero: `===` settles every primitive except `NaN`, which counts as\n  // equal to itself here. That is what the native `Set` in {@link allUnique} does,\n  // what Ajv does, and what the interpreter's `deepEqual` does \u2014 leaving it out\n  // made a `NaN` nested inside an object compare unequal to itself, so the same\n  // array was \"unique\" here and \"duplicated\" everywhere else.\n  if (a === b || (Number.isNaN(a) && Number.isNaN(b))) return true\n  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false\n  if (depth >= MAX_EQUAL_DEPTH) return false\n  const aArray = Array.isArray(a)\n  const bArray = Array.isArray(b)\n  if (aArray !== bArray) return false\n  if (aArray) {\n    const aa = a as unknown[]\n    const bb = b as unknown[]\n    if (aa.length !== bb.length) return false\n    for (let i = 0; i < aa.length; i++) if (!valuesEqual(aa[i], bb[i], depth + 1)) return false\n    return true\n  }\n  const ao = a as Record<string, unknown>\n  const bo = b as Record<string, unknown>\n  const keys = Object.keys(ao)\n  if (keys.length !== Object.keys(bo).length) return false\n  for (const key of keys) {\n    if (!Object.hasOwn(bo, key) || !valuesEqual(ao[key], bo[key], depth + 1)) return false\n  }\n  return true\n}\n\n/**\n * A cheap, order-independent structural hash consistent with {@link valuesEqual}:\n * equal values always hash the same. It buckets candidate-equal elements in\n * {@link allUnique} so the exact comparison only ever runs inside a bucket.\n *\n * Object keys are folded commutatively (XOR) so key order does not change the\n * hash, and `NaN` / `-0` collapse the way SameValueZero does. Depth-capped like\n * {@link valuesEqual}: an over-deep value simply shares a bucket and is settled by\n * the (also capped) comparison, so the cap can cost a little time and never a\n * wrong answer. This is the same hash `@amritk/runtime-validators` uses.\n */\nconst structuralHash = (value: unknown, depth = 0): number => {\n  if (value === null) return 0x1a2b3c\n  const t = typeof value\n  if (t === 'number') {\n    const n = value as number\n    return Number.isNaN(n) ? 0x7ff8 : n === 0 ? 0 : Math.trunc(n * 2654435761) | 0\n  }\n  if (t === 'string') {\n    const s = value as string\n    let h = 0x811c9dc5\n    for (let i = 0; i < s.length; i++) h = Math.imul(h ^ s.charCodeAt(i), 0x01000193)\n    return h | 0\n  }\n  if (t === 'boolean') return value ? 1 : 2\n  if (t !== 'object') return 0x5eed\n  if (depth >= MAX_EQUAL_DEPTH) return 0xdee9\n  if (Array.isArray(value)) {\n    let h = 0x12345 ^ value.length\n    for (let i = 0; i < value.length; i++) h = (Math.imul(h, 31) + structuralHash(value[i], depth + 1)) | 0\n    return h | 0\n  }\n  const obj = value as Record<string, unknown>\n  const keys = Object.keys(obj)\n  let h = 0xabcde ^ keys.length\n  for (const k of keys) {\n    let kh = 0x811c9dc5\n    for (let i = 0; i < k.length; i++) kh = Math.imul(kh ^ k.charCodeAt(i), 0x01000193)\n    h = (h ^ (Math.imul(kh, 0x9e3779b1) + structuralHash(obj[k], depth + 1))) | 0\n  }\n  return h | 0\n}\n\n/**\n * True when every element of `arr` is distinct under structural equality\n * ({@link valuesEqual}). Backs generated `uniqueItems` checks whose items may be\n * objects or arrays, where a `JSON.stringify` dedupe key would be key-order\n * sensitive and let a reordered-but-equal duplicate (`{ a: 1, b: 2 }` vs\n * `{ b: 2, a: 1 }`) slip through.\n *\n * A native `Set` dedupes the all-primitive case in one linear pass. Object and\n * array elements are bucketed by {@link structuralHash} first, so the exact\n * comparison runs only against elements that could actually be equal: an array of\n * distinct objects costs ~O(n) instead of the O(n\u00B2) an exhaustive pairwise sweep\n * charged \u2014 4 000 rows took over half a second of pure comparison before, which\n * is a lot to hand an unauthenticated caller.\n */\nexport const allUnique = (arr: readonly unknown[]): boolean => {\n  const len = arr.length\n  if (len < 2) return true\n  let allPrimitive = true\n  for (let i = 0; i < len; i++) {\n    const v = arr[i]\n    if (v !== null && typeof v === 'object') {\n      allPrimitive = false\n      break\n    }\n  }\n  if (allPrimitive) return new Set(arr).size === len\n  const buckets = new Map<number, unknown[]>()\n  for (let i = 0; i < len; i++) {\n    const item = arr[i]\n    const hash = structuralHash(item)\n    const bucket = buckets.get(hash)\n    if (bucket === undefined) {\n      buckets.set(hash, [item])\n      continue\n    }\n    for (const seen of bucket) if (valuesEqual(seen, item)) return false\n    bucket.push(item)\n  }\n  return true\n}\n\n/**\n * True when `test` holds for every element of `arr`, holes included. Backs the\n * item check inside a generated boolean guard.\n *\n * Not `Array.prototype.every`, because that *skips holes* in a sparse array\n * (`[, 'x']`), whereas the validator's index-based loop reads a hole as\n * `undefined` and rejects it \u2014 and the guard must never accept what the validator\n * rejects. The guard used to get that by materialising `Array.from(arr)` first,\n * which copied every array it looked at; an index loop reads a hole the same way\n * and copies nothing.\n */\nexport const everyItem = (arr: readonly unknown[], test: (item: unknown) => boolean): boolean => {\n  for (let i = 0; i < arr.length; i++) if (!test(arr[i])) return false\n  return true\n}\n\n/**\n * Escapes one JSON Pointer segment (RFC 6901): `~` \u2192 `~0`, `/` \u2192 `~1`, in that\n * order. Generated error paths are built from *runtime* keys wherever the schema\n * did not name them \u2014 a `patternProperties` match, an `additionalProperties`\n * sweep, a `propertyNames` loop \u2014 and a key containing a `/` would otherwise read\n * back as two segments, so an error on `{\"a/b\": \u2026}` pointed at `/a/b`, which is\n * the child `b` of a property `a`. Keys the schema *does* name are escaped at\n * generation time instead, and `@amritk/runtime-validators` escapes the same way,\n * so all three agree.\n *\n * The `indexOf` pre-test keeps the common key \u2014 no `/`, no `~` \u2014 off the replace\n * path entirely, which is what the interpreter does for the same reason.\n */\nexport const escapePointer = (key: string): string =>\n  key.indexOf('/') !== -1 || key.indexOf('~') !== -1 ? key.replace(/~/g, '~0').replace(/\\//g, '~1') : key\n";
 /**
  * Builds all TypeScript validator files from a JSON Schema by traversing all
  * `$ref` / `$dynamicRef` references recursively (via the shared
@@ -37,6 +38,11 @@ export declare const VALIDATION_RESULT_CONTENT = "/**\n * A single validation er
  *   loading 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.
+ * @param unknownKeys - How the generated fast paths prove a closed object
+ *   (`additionalProperties: false`) carries no undeclared key: `'count-keys'`
+ *   (the default) compares `Object.keys(obj).length`, `'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
@@ -50,4 +56,4 @@ export declare const VALIDATION_RESULT_CONTENT = "/**\n * A single validation er
  * })
  * ```
  */
-export declare const buildValidatorSchema: (rootSchema: JSONSchema, rootTypeName: string, typeSuffix?: string, schemas?: Readonly<Record<string, unknown>>) => Promise<GeneratedFile[]>;
+export declare const buildValidatorSchema: (rootSchema: JSONSchema, rootTypeName: string, typeSuffix?: string, schemas?: Readonly<Record<string, unknown>>, unknownKeys?: UnknownKeysStrategy) => Promise<GeneratedFile[]>;

package/dist/generators/build-schema.js

@@ -1,4 +1,5 @@
 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 { generateValidatorFile } from "./generate-files.js";
 const VALIDATION_RESULT_CONTENT = `/**
@@ -150,6 +151,22 @@ export const allUnique = (arr: readonly unknown[]): boolean => {
   return true
 }
 
+/**
+ * True when \`test\` holds for every element of \`arr\`, holes included. Backs the
+ * item check inside a generated boolean guard.
+ *
+ * Not \`Array.prototype.every\`, because that *skips holes* in a sparse array
+ * (\`[, 'x']\`), whereas the validator's index-based loop reads a hole as
+ * \`undefined\` and rejects it \u2014 and the guard must never accept what the validator
+ * rejects. The guard used to get that by materialising \`Array.from(arr)\` first,
+ * which copied every array it looked at; an index loop reads a hole the same way
+ * and copies nothing.
+ */
+export const everyItem = (arr: readonly unknown[], test: (item: unknown) => boolean): boolean => {
+  for (let i = 0; i < arr.length; i++) if (!test(arr[i])) return false
+  return true
+}
+
 /**
  * Escapes one JSON Pointer segment (RFC 6901): \`~\` \u2192 \`~0\`, \`/\` \u2192 \`~1\`, in that
  * order. Generated error paths are built from *runtime* keys wherever the schema
@@ -208,7 +225,7 @@ const RESERVED_WORDS = /* @__PURE__ */ new Set([
   "with",
   "yield"
 ]);
-const buildValidatorSchema = async (rootSchema, rootTypeName, typeSuffix = "", schemas) => {
+const buildValidatorSchema = async (rootSchema, rootTypeName, typeSuffix = "", schemas, unknownKeys = DEFAULT_UNKNOWN_KEYS) => {
   const files = [];
   walkRefGraph(rootSchema, rootTypeName, { typeSuffix, ...schemas !== void 0 ? { schemas } : {} }, (node) => {
     if (node.filename === "validation-result" || node.filename === "index") {
@@ -228,6 +245,7 @@ const buildValidatorSchema = async (rootSchema, rootTypeName, typeSuffix = "", s
     const content = generateValidatorFile(node.schema, node.typeName, {
       rootSchema: node.rootSchema,
       typeSuffix,
+      unknownKeys,
       ...node.ref !== void 0 ? { selfRef: node.ref } : {}
     });
     files.push({ filename: `${node.filename}.ts`, content });

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';
 /**
  * Options for controlling what gets generated in a validator file.
@@ -17,6 +18,12 @@ type GenerateValidatorFileOptions = {
      * Defaults to `''` (no suffix).
      */
     readonly typeSuffix?: string;
+    /**
+     * How the fast paths prove a closed object carries no undeclared key —
+     * `Object.keys(obj).length` (the default) or a `for…in` count. See
+     * {@link UnknownKeysStrategy} for the trade-off between the two.
+     */
+    readonly unknownKeys?: UnknownKeysStrategy;
 };
 /**
  * Generates a complete TypeScript validator file from a JSON Schema.

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 { collectValidatorImports } from "./collect-validator-imports.js";
 import { generateBooleanGuard, generateValidatorFunction } from "./generate-validator-function.js";
 const escapeForWordMatch = (name) => name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -8,8 +9,9 @@ const generateValidatorFile = (schema, typeName, options) => {
     typeSuffix,
     ...options?.rootSchema !== void 0 ? { rootSchema: options.rootSchema } : {}
   });
-  const validatorFunction = generateValidatorFunction(schema, typeName, typeSuffix, options?.rootSchema);
-  const booleanGuard = generateBooleanGuard(schema, typeName, typeSuffix);
+  const unknownKeys = options?.unknownKeys ?? DEFAULT_UNKNOWN_KEYS;
+  const validatorFunction = generateValidatorFunction(schema, typeName, typeSuffix, options?.rootSchema, unknownKeys);
+  const booleanGuard = generateBooleanGuard(schema, typeName, typeSuffix, unknownKeys);
   const body = validatorFunction + booleanGuard;
   const emitted = typeDefinition + body;
   const mentions = (name) => new RegExp(`\\b${escapeForWordMatch(name)}\\b`).test(emitted);
@@ -25,7 +27,7 @@ const generateValidatorFile = (schema, typeName, options) => {
   const resultTypes = ["ValidationResult", .../\bValidationError\b/.test(body) ? ["ValidationError"] : []];
   let result = `import type { ${resultTypes.join(", ")} } from './validation-result.js'
 `;
-  const runtimeHelpers = ["valuesEqual", "allUnique", "escapePointer"].filter((name) => body.includes(`${name}(`));
+  const runtimeHelpers = ["valuesEqual", "allUnique", "escapePointer", "everyItem"].filter((name) => body.includes(`${name}(`));
   if (runtimeHelpers.length > 0) {
     result += `import { ${runtimeHelpers.join(", ")} } from './validation-result.js'
 `;

package/dist/generators/generate-validator-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';
 /**
  * Generates the exported boolean guard `isTypeName`.
@@ -11,8 +12,11 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
  *
  * The signature is `input is TypeName` whenever that narrowing is sound, and a
  * plain `boolean` when it is not — see {@link typeDescribesEveryAcceptedValue}.
+ *
+ * `unknownKeys` picks how a closed object's no-extras test counts keys — see
+ * {@link UnknownKeysStrategy}.
  */
-export declare const generateBooleanGuard: (schema: JSONSchema, typeName: string, _suffix?: string) => string;
+export declare const generateBooleanGuard: (schema: JSONSchema, typeName: string, _suffix?: string, unknownKeys?: UnknownKeysStrategy) => string;
 /**
  * Generates a TypeScript validator function from a JSON Schema.
  *
@@ -35,4 +39,4 @@ export declare const generateBooleanGuard: (schema: JSONSchema, typeName: string
  * // }
  * ```
  */
-export declare const generateValidatorFunction: (schema: JSONSchema, typeName: string, suffix?: string, rootSchema?: Record<string, unknown>) => string;
+export declare const generateValidatorFunction: (schema: JSONSchema, typeName: string, suffix?: string, rootSchema?: Record<string, unknown>, unknownKeys?: UnknownKeysStrategy) => string;

package/dist/generators/generate-validator-function.js

@@ -8,6 +8,7 @@ import { safeAccessor } from "@amritk/helpers/safe-accessor";
 import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasDependentRequired, hasEnum, hasExclusiveMaximum, hasExclusiveMinimum, hasItems, hasMaxItems, hasMaximum, hasMaxLength, hasMaxProperties, hasMinItems, hasMinimum, hasMinLength, hasMinProperties, hasMultipleOf, hasOneOf, hasPattern, hasProperties, hasPropertyNames, hasRef, hasRequired, hasStrictExclusiveMaximum, hasStrictExclusiveMinimum, hasType, hasUniqueItems, isObjectSchema, isSchemaObject } from "@amritk/helpers/schema-guards";
 import { maxLengthFailExpr, maxLengthPassExpr, minLengthFailExpr, minLengthPassExpr } from "@amritk/helpers/string-length-check";
 import { unknownKeyCheck } from "@amritk/helpers/unknown-key-check";
+import { DEFAULT_UNKNOWN_KEYS } from "@amritk/helpers/unknown-keys-strategy";
 import { assertGeneratableRefs } from "./assert-generatable-refs.js";
 import { assertUnevaluatedGeneratable, UNPROVABLE_COVERAGE_MESSAGE } from "./assert-unevaluated-generatable.js";
 import { declaresKeywordOutside } from "./enforced-keywords.js";
@@ -856,7 +857,54 @@ const carriesUnevaluated = (schema) => {
   const s = schema;
   return declaresKey(s, "unevaluatedProperties") && s["unevaluatedProperties"] !== true || declaresKey(s, "unevaluatedItems") && s["unevaluatedItems"] !== true;
 };
-const guardPropConditions = (key, propSchema, objAcc) => {
+const createGuardContext = (unknownKeys) => ({ unknownKeys, locals: 0, loops: 0 });
+const emptyGuardBlock = () => ({ conditions: [], nested: [], keyChecks: [] });
+const isFlatGuardBlock = (block) => block.nested.length === 0 && block.keyChecks.length === 0;
+const keySetCheckLines = (check, bail, indent, unknownKeys) => {
+  const key = `_k${check.index}`;
+  if (check.count === null) {
+    const unknown = unknownKeyCheck(check.known, "", Number.POSITIVE_INFINITY).isUnknown(key);
+    return [`${indent}for (const ${key} in ${check.obj}) if (${unknown}) ${bail}`];
+  }
+  if (unknownKeys === "count-keys") {
+    return [`${indent}if (Object.keys(${check.obj}).length !== ${check.count}) ${bail}`];
+  }
+  const count = `_c${check.index}`;
+  return [
+    `${indent}let ${count} = 0`,
+    `${indent}for (const ${key} in ${check.obj}) ${count}++`,
+    `${indent}if (${count} !== ${check.count}) ${bail}`
+  ];
+};
+const renderChainBail = (conditions, bail, indent, layout) => layout === "inline" ? [`if (!(${conditions.join(" && ")})) ${bail}`] : [`${indent}if (!(`, conditions.map((condition) => `${indent}  ${condition}`).join(" &&\n"), `${indent})) ${bail}`];
+const renderGuardBlock = (block, bail, indent, layout, unknownKeys) => {
+  const lines = [];
+  if (block.conditions.length > 0)
+    lines.push(...renderChainBail(block.conditions, bail, indent, layout));
+  for (const nested of block.nested) {
+    lines.push(`${indent}const ${nested.local} = ${nested.read} as Record<string, unknown>`);
+    if (nested.optional) {
+      lines.push(`${indent}if (${nested.local} !== undefined) {`);
+      lines.push(...renderGuardBlock(nested.block, bail, `${indent}  `, layout, unknownKeys));
+      lines.push(`${indent}}`);
+    } else {
+      lines.push(...renderGuardBlock(nested.block, bail, indent, layout, unknownKeys));
+    }
+  }
+  for (const check of block.keyChecks)
+    lines.push(...keySetCheckLines(check, bail, indent, unknownKeys));
+  return lines;
+};
+const joinInline = (lines) => {
+  const trimmed = lines.map((line) => line.trim());
+  return trimmed.reduce((text, line, i) => {
+    if (i === 0)
+      return line;
+    const previous = trimmed[i - 1];
+    return `${text}${previous.endsWith("{") || line === "}" ? " " : "; "}${line}`;
+  }, "");
+};
+const guardPropConditions = (key, propSchema, objAcc, block, ctx) => {
   if (!isSchemaObject(propSchema))
     return null;
   const raw = safeAccessor(objAcc, key);
@@ -876,8 +924,14 @@ const guardPropConditions = (key, propSchema, objAcc) => {
       return [`typeof ${raw} === 'boolean'`];
     case "null":
       return [`${raw} === null`];
-    case "object":
-      return guardObjectConditions(propSchema, raw, `(${raw} as Record<string, unknown>)`);
+    case "object": {
+      const local = `_n${ctx.locals++}`;
+      const nested = guardObjectConditions(propSchema, local, local, ctx);
+      if (nested === null)
+        return null;
+      block.nested.push({ local, read: raw, optional: false, block: nested });
+      return [];
+    }
     // Arrays need a per-item loop the guard can't express, and any other type
     // (null, multi-type, untyped) is left to the slow path.
     default:
@@ -897,7 +951,7 @@ const arrayRejectedByRequiredProp = (keys, required, properties) => {
   }
   return false;
 };
-const guardObjectConditions = (schema, raw, objAcc) => {
+const guardObjectConditions = (schema, raw, objAcc, ctx) => {
   if (!isObjectSchema(schema))
     return null;
   if (hasDependentRequired(schema) || hasPropertyNames(schema) || declaresKey(schema, "dependentSchemas"))
@@ -925,23 +979,24 @@ const guardObjectConditions = (schema, raw, objAcc) => {
       return null;
   }
   const arrayCheck = arrayRejectedByRequiredProp(keys, required, properties) ? "" : ` && !Array.isArray(${raw})`;
-  const conditions = [`typeof ${raw} === 'object' && ${raw} !== null${arrayCheck}`];
+  const block = emptyGuardBlock();
+  block.conditions.push(`typeof ${raw} === 'object' && ${raw} !== null${arrayCheck}`);
   for (const key of keys) {
     if (!required.has(key))
       return null;
-    const propConditions = guardPropConditions(key, properties[key], objAcc);
+    const propConditions = guardPropConditions(key, properties[key], objAcc, block, ctx);
     if (propConditions === null)
       return null;
-    conditions.push(...propConditions);
+    block.conditions.push(...propConditions);
   }
   if (strict) {
     if (!keys.every((key) => required.has(key)))
       return null;
-    conditions.push(`Object.keys(${objAcc}).length === ${keys.length}`);
+    block.keyChecks.push({ obj: objAcc, count: keys.length, known: keys, index: ctx.loops++ });
   }
-  return conditions;
+  return block;
 };
-const generateObjectValidator = (schema, typeName, suffix, rootSchema) => {
+const generateObjectValidator = (schema, typeName, suffix, rootSchema, unknownKeys) => {
   const vName = validatorName(typeName);
   const required = new Set(hasRequired(schema) ? schema.required : []);
   const properties = hasProperties(schema) ? schema.properties : {};
@@ -970,7 +1025,7 @@ const generateObjectValidator = (schema, typeName, suffix, rootSchema) => {
     propertyLines.push(...objectCombinators);
   }
   const body = propertyLines.length > 0 ? "\n" + propertyLines.join("\n") + "\n" : "";
-  const guard = guardObjectConditions(schema, "input", "obj");
+  const guard = guardObjectConditions(schema, "input", "obj", createGuardContext(unknownKeys));
   const objBinding = readsObjBinding(body) ? [`  const obj = input as Record<string, unknown>`] : [];
   const collectBody = (name, exported) => [
     `${exported ? "export " : ""}const ${name} = (input: unknown, _path = ''): ValidationResult => {`,
@@ -987,19 +1042,22 @@ const generateObjectValidator = (schema, typeName, suffix, rootSchema) => {
   if (!guard) {
     return withHoisted(ctx.hoisted, collectBody(vName, true));
   }
-  const guardText = guard.join("\n");
   const collectName = `${vName}Errors`;
-  return withHoisted(ctx.hoisted, [
-    collectBody(collectName, false),
-    ``,
-    `export const ${vName} = (input: unknown, _path = ''): ValidationResult => {`,
-    ...readsObjBinding(guardText) ? [`  const obj = input as Record<string, unknown>`] : [],
+  const bail = `return ${collectName}(input, _path)`;
+  const guardLines = isFlatGuardBlock(guard) ? [
     `  if (`,
-    guard.map((condition) => `    ${condition}`).join(" &&\n"),
+    guard.conditions.map((condition) => `    ${condition}`).join(" &&\n"),
     `  ) {`,
     `    return true`,
     `  }`,
-    `  return ${collectName}(input, _path)`,
+    `  ${bail}`
+  ] : [...renderGuardBlock(guard, bail, "  ", "lines", unknownKeys), `  return true`];
+  return withHoisted(ctx.hoisted, [
+    collectBody(collectName, false),
+    ``,
+    `export const ${vName} = (input: unknown, _path = ''): ValidationResult => {`,
+    ...readsObjBinding(guardLines.join("\n")) ? [`  const obj = input as Record<string, unknown>`] : [],
+    ...guardLines,
     `}`
   ].join("\n"));
 };
@@ -1024,16 +1082,16 @@ const valueCanHaveType = (value, type) => {
       return true;
   }
 };
-const booleanLeafExpr = (schema, acc, narrowable = true) => {
+const flatLeafBails = (schema) => hasRef(schema) || hasConst(schema) || hasOneOf(schema) || declaresKey(schema, "anyOf") || declaresKey(schema, "allOf") || declaresKey(schema, "not") || declaresKey(schema, "if") || declaresKey(schema, "contains") || declaresKey(schema, "prefixItems") || // A draft-07 tuple: the fixed positions live in an *array* `items` and the
+// tail in `additionalItems`. Neither is expressible flat, and reading past
+// them let the guard accept tuples `validateX` rejects.
+Array.isArray(readKey(schema, "items")) || declaresKey(schema, "additionalItems") || carriesUnevaluated(schema) || getMjstInstanceOf(schema) !== void 0 || getMjstPrimitive(schema) !== void 0;
+const isNestedObjectLeaf = (schema) => isSchemaObject(schema) && !flatLeafBails(schema) && hasType(schema) && schema.type === "object";
+const booleanLeafExpr = (schema, acc, ctx) => {
   if (!isSchemaObject(schema))
     return null;
-  const typed = (type) => narrowable ? acc : `(${acc} as ${type})`;
-  if (hasRef(schema) || hasConst(schema) || hasOneOf(schema) || declaresKey(schema, "anyOf") || declaresKey(schema, "allOf") || declaresKey(schema, "not") || declaresKey(schema, "if") || declaresKey(schema, "contains") || declaresKey(schema, "prefixItems") || // A draft-07 tuple: the fixed positions live in an *array* `items` and the
-  // tail in `additionalItems`. Neither is expressible flat, and reading past
-  // them let the guard accept tuples `validateX` rejects.
-  Array.isArray(readKey(schema, "items")) || declaresKey(schema, "additionalItems") || carriesUnevaluated(schema) || getMjstInstanceOf(schema) !== void 0 || getMjstPrimitive(schema) !== void 0) {
+  if (flatLeafBails(schema))
     return null;
-  }
   if (!hasType(schema)) {
     if (!hasEnum(schema))
       return null;
@@ -1051,62 +1109,62 @@ const booleanLeafExpr = (schema, acc, narrowable = true) => {
     // written as the pass condition (`x >= min`) because the validator's error
     // condition is its negation; the length checks come from the same
     // `string-length-check` emitter the validator uses, for the same reason.
+    // A constrained check reads `acc` again after the `typeof`, and TypeScript
+    // narrows it there because every `acc` is a *reference* — `obj.a`, `_n0.b`,
+    // `_it` — never a cast expression: nested members read through a hoisted
+    // local (see {@link NestedGuard}), and a narrowing does not survive two
+    // spellings of `(obj.a as Record<string, unknown>).b`.
     case "string": {
-      const str = typed("string");
       const parts = [`typeof ${acc} === 'string'`];
       if (hasPattern(schema))
-        parts.push(`${regexLiteral(schema.pattern)}.test(${str})`);
+        parts.push(`${regexLiteral(schema.pattern)}.test(${acc})`);
       if (hasMinLength(schema))
-        parts.push(minLengthPassExpr(str, schema.minLength));
+        parts.push(minLengthPassExpr(acc, schema.minLength));
       if (hasMaxLength(schema))
-        parts.push(maxLengthPassExpr(str, schema.maxLength));
+        parts.push(maxLengthPassExpr(acc, schema.maxLength));
       return withMembership(parts.join(" && "));
     }
     case "number":
     case "integer": {
-      const num = typed("number");
       const parts = [`typeof ${acc} === 'number'`];
       if (t === "integer")
         parts.push(`Number.isInteger(${acc})`);
       if (hasMinimum(schema))
-        parts.push(boundPassExpr(num, "minimum", schema.minimum, hasStrictExclusiveMinimum(schema)));
+        parts.push(boundPassExpr(acc, "minimum", schema.minimum, hasStrictExclusiveMinimum(schema)));
       if (hasMaximum(schema))
-        parts.push(boundPassExpr(num, "maximum", schema.maximum, hasStrictExclusiveMaximum(schema)));
+        parts.push(boundPassExpr(acc, "maximum", schema.maximum, hasStrictExclusiveMaximum(schema)));
       if (hasExclusiveMinimum(schema))
-        parts.push(boundPassExpr(num, "minimum", schema.exclusiveMinimum, true));
+        parts.push(boundPassExpr(acc, "minimum", schema.exclusiveMinimum, true));
       if (hasExclusiveMaximum(schema))
-        parts.push(boundPassExpr(num, "maximum", schema.exclusiveMaximum, true));
+        parts.push(boundPassExpr(acc, "maximum", schema.exclusiveMaximum, true));
       if (hasMultipleOf(schema))
-        parts.push(multipleOfPassExpr(num, schema.multipleOf));
+        parts.push(multipleOfPassExpr(acc, schema.multipleOf));
       return withMembership(parts.join(" && "));
     }
     case "boolean":
       return withMembership(`typeof ${acc} === 'boolean'`);
     case "null":
       return withMembership(`${acc} === null`);
-    case "object": {
-      const parts = booleanObjectParts(schema, acc, `(${acc} as Record<string, unknown>)`, false);
-      return parts === null ? null : withMembership(parts.join(" && "));
-    }
+    case "object":
+      return null;
     case "array":
-      return withMembership(booleanArrayExpr(schema, acc, narrowable));
+      return withMembership(booleanArrayExpr(schema, acc, ctx));
     default:
       return null;
   }
 };
-const booleanArrayExpr = (schema, acc, narrowable = true) => {
-  const arr = narrowable ? acc : `(${acc} as unknown[])`;
+const booleanArrayExpr = (schema, acc, ctx) => {
   const parts = [`Array.isArray(${acc})`];
   if (hasMinItems(schema))
-    parts.push(`${arr}.length >= ${schema.minItems}`);
+    parts.push(`${acc}.length >= ${schema.minItems}`);
   if (hasMaxItems(schema))
-    parts.push(`${arr}.length <= ${schema.maxItems}`);
+    parts.push(`${acc}.length <= ${schema.maxItems}`);
   if (hasUniqueItems(schema) && schema.uniqueItems === true) {
-    parts.push(arrayItemsAreScalarOnly(schema) ? `new Set(${acc} as unknown[]).size === ${arr}.length` : `allUnique(${acc} as unknown[])`);
+    parts.push(arrayItemsAreScalarOnly(schema) ? `new Set(${acc} as unknown[]).size === ${acc}.length` : `allUnique(${acc} as unknown[])`);
   }
   const base = parts.join(" && ");
   if (readKey(schema, "items") === false)
-    return `${base} && ${arr}.length === 0`;
+    return `${base} && ${acc}.length === 0`;
   if (!hasItems(schema))
     return base;
   const items = schema.items;
@@ -1114,12 +1172,24 @@ const booleanArrayExpr = (schema, acc, narrowable = true) => {
     return base;
   if (hasRef(items))
     return null;
-  const itemExpr = booleanLeafExpr(items, "_it");
+  if (isNestedObjectLeaf(items)) {
+    const local = `_n${ctx.locals++}`;
+    const block = booleanObjectParts(items, local, local, ctx);
+    if (block === null)
+      return null;
+    const body = joinInline([
+      `const ${local} = _it as Record<string, unknown>`,
+      ...renderGuardBlock(block, "return false", "", "inline", ctx.unknownKeys),
+      `return true`
+    ]);
+    return `${base} && everyItem(${acc} as unknown[], (_it) => { ${body} })`;
+  }
+  const itemExpr = booleanLeafExpr(items, "_it", ctx);
   if (itemExpr === null)
     return null;
-  return `${base} && Array.from(${acc} as unknown[]).every((_it) => (${itemExpr}))`;
+  return `${base} && everyItem(${acc} as unknown[], (_it) => (${itemExpr}))`;
 };
-const booleanObjectParts = (schema, raw, objAcc, narrowable = true) => {
+const booleanObjectParts = (schema, raw, objAcc, ctx) => {
   if (!isObjectSchema(schema))
     return null;
   if (hasRef(schema) || hasConst(schema) || hasEnum(schema))
@@ -1147,7 +1217,8 @@ const booleanObjectParts = (schema, raw, objAcc, narrowable = true) => {
   const properties = hasProperties(schema) ? schema.properties : {};
   const keys = Object.keys(properties);
   const arrayCheck = arrayRejectedByRequiredProp(keys, required, properties) ? "" : ` && !Array.isArray(${raw})`;
-  const parts = [`typeof ${raw} === 'object' && ${raw} !== null${arrayCheck}`];
+  const block = emptyGuardBlock();
+  block.conditions.push(`typeof ${raw} === 'object' && ${raw} !== null${arrayCheck}`);
   for (const key of keys) {
     const propSchema = properties[key];
     if (propSchema === void 0 || !isSchemaObject(propSchema))
@@ -1155,27 +1226,29 @@ const booleanObjectParts = (schema, raw, objAcc, narrowable = true) => {
     if (PROTOTYPE_MEMBERS.has(key))
       return null;
     const member = safeAccessor(objAcc, key);
-    const expr = booleanLeafExpr(propSchema, member, narrowable);
+    if (isNestedObjectLeaf(propSchema)) {
+      const local = `_n${ctx.locals++}`;
+      const nested = booleanObjectParts(propSchema, local, local, ctx);
+      if (nested === null)
+        return null;
+      block.nested.push({ local, read: member, optional: !required.has(key), block: nested });
+      continue;
+    }
+    const expr = booleanLeafExpr(propSchema, member, ctx);
     if (expr === null)
       return null;
-    parts.push(required.has(key) ? expr : `(${member} === undefined || (${expr}))`);
+    block.conditions.push(required.has(key) ? expr : `(${member} === undefined || (${expr}))`);
   }
   for (const key of required) {
     if (Object.hasOwn(properties, key))
       continue;
-    parts.push(hasOwnCheck(objAcc, key));
+    block.conditions.push(hasOwnCheck(objAcc, key));
   }
   if (strict) {
-    if (keys.length === 0) {
-      parts.push(`Object.keys(${objAcc}).length === 0`);
-    } else if (keys.every((key) => required.has(key))) {
-      parts.push(`Object.keys(${objAcc}).length === ${keys.length}`);
-    } else {
-      const known = keys.map((key) => `_k === ${JSON.stringify(key)}`).join(" || ");
-      parts.push(`Object.keys(${objAcc}).every((_k) => ${known})`);
-    }
+    const allRequired = keys.every((key) => required.has(key));
+    block.keyChecks.push({ obj: objAcc, count: allRequired ? keys.length : null, known: keys, index: ctx.loops++ });
   }
-  return parts;
+  return block;
 };
 const IMPLICIT_OBJECT_KEYWORDS = ["properties", "patternProperties", "additionalProperties"];
 const typeDescribesEveryAcceptedValue = (schema) => {
@@ -1193,27 +1266,29 @@ const typeDescribesEveryAcceptedValue = (schema) => {
   }
   return !IMPLICIT_OBJECT_KEYWORDS.some((keyword) => declaresKey(s, keyword));
 };
-const generateBooleanGuard = (schema, typeName, _suffix = "") => {
+const generateBooleanGuard = (schema, typeName, _suffix = "", unknownKeys = DEFAULT_UNKNOWN_KEYS) => {
   const name = guardName(typeName);
   const returns = typeDescribesEveryAcceptedValue(rewriteNullable(schema)) ? `input is ${typeName}` : "boolean";
   const fallback = `export const ${name} = (input: unknown): ${returns} => ${validatorName(typeName)}(input) === true`;
   const rewritten = rewriteNullable(schema);
-  if (declaresObjectType(rewritten) && objectRootIsSelfContained(rewritten)) {
-    const parts = booleanObjectParts(rewritten, "input", "obj");
-    if (parts === null)
+  const ctx = createGuardContext(unknownKeys);
+  if (declaresObjectType(rewritten)) {
+    if (!objectRootIsSelfContained(rewritten))
+      return fallback;
+    const block = booleanObjectParts(rewritten, "input", "obj", ctx);
+    if (block === null)
       return fallback;
+    const body = isFlatGuardBlock(block) ? [`  return (`, block.conditions.map((part) => `    ${part}`).join(" &&\n"), `  )`] : [...renderGuardBlock(block, "return false", "  ", "lines", unknownKeys), `  return true`];
     return [
       `export const ${name} = (input: unknown): ${returns} => {`,
       // Same unused-local as the validator's hot guard: a node with no property
       // to read guards on the shape alone and never touches the narrowing.
-      ...readsObjBinding(parts.join("\n")) ? [`  const obj = input as Record<string, unknown>`] : [],
-      `  return (`,
-      parts.map((part) => `    ${part}`).join(" &&\n"),
-      `  )`,
+      ...readsObjBinding(body.join("\n")) ? [`  const obj = input as Record<string, unknown>`] : [],
+      ...body,
       `}`
     ].join("\n");
   }
-  const expr = booleanLeafExpr(rewritten, "input");
+  const expr = booleanLeafExpr(rewritten, "input", ctx);
   if (expr === null)
     return fallback;
   return `export const ${name} = (input: unknown): ${returns} => ${expr}`;
@@ -1471,7 +1546,7 @@ const rewriteNullable = (node) => {
     return { anyOf: [{ type: "null" }, out] };
   return out;
 };
-const generateValidatorFunction = (schema, typeName, suffix = "", rootSchema) => {
+const generateValidatorFunction = (schema, typeName, suffix = "", rootSchema, unknownKeys = DEFAULT_UNKNOWN_KEYS) => {
   assertGeneratableRefs(schema, typeName);
   const rewritten = rewriteNullable(schema);
   const document = rootSchema ?? schema;
@@ -1480,7 +1555,7 @@ const generateValidatorFunction = (schema, typeName, suffix = "", rootSchema) =>
     return generateGeneralRootValidator(rewritten, typeName, suffix, document);
   }
   if (declaresObjectType(rewritten) && objectRootIsSelfContained(rewritten)) {
-    return generateObjectValidator(rewritten, typeName, suffix, document);
+    return generateObjectValidator(rewritten, typeName, suffix, document, unknownKeys);
   }
   return generateScalarValidator(rewritten, typeName, suffix, document);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/generate-validators",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "Generate TypeScript validation functions from JSON Schemas.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -41,8 +41,12 @@
     "prepublishOnly": "node ../../scripts/check-publishable.mjs",
     "types:check": "tsgo -p . --noEmit",
     "test": "NODE_ENV=production vitest run --root ../.. generate-validators",
+    "prebench": "bun run --filter='@amritk/helpers' build && bun run build",
     "bench": "bun --conditions development ./bench/run.ts",
-    "bench:moltar": "bun --conditions development ./bench/moltar.ts"
+    "prebench:node": "bun run --filter='@amritk/helpers' build && bun run build",
+    "bench:node": "node ./bench/run.ts",
+    "bench:moltar": "bun --conditions development ./bench/moltar.ts",
+    "bench:moltar:leaderboard": "bun --conditions development ./bench/moltar-leaderboard.ts"
   },
   "imports": {
     "#generators/*": "./src/generators/*.ts"
@@ -55,10 +59,11 @@
   },
   "dependencies": {
     "json-schema-typed": "^8.0.1",
-    "@amritk/helpers": "^0.18.0"
+    "@amritk/helpers": "^0.19.0"
   },
   "devDependencies": {
-    "@amritk/runtime-validators": "^0.13.0",
+    "@amritk/generate-parsers": "^0.21.0",
+    "@amritk/runtime-validators": "^0.13.1",
     "@ryoppippi/unplugin-typia": "^2.6.5",
     "@scalar/openapi-parser": "^0.26.1",
     "@sinclair/typebox": "^0.34.49",