@amritk/generate-parsers 0.16.0 → 0.16.1

package/README.md

@@ -156,6 +156,51 @@ The generator handles:
 
 ---
 
+## Benchmarks
+
+Generated parsers are plain, straight-line TypeScript — no schema walking and no
+generic dispatch at runtime, because the schema was already spent at build time.
+Each parser reads the exact keys it declares, coerces or asserts them inline, and
+returns a fresh typed object, so on valid input it runs several times faster than
+libraries that interpret a schema (or a schema-shaped object graph) on every
+call. The `bench/` suite replicates the `parseSafe` (assert + strip undeclared
+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.3 (Linux
+x64), parsing valid input at steady state:
+
+| case | mode | mjst (generated) | zod | typebox |
+|:--|:--|--:|--:|--:|
+| user (4 fields) | parseSafe | **~11M** ops/s | ~2.5M ops/s | ~1.0M ops/s |
+| order (nested + array) | parseSafe | **~3.9M** ops/s | ~0.46M ops/s | ~0.13M ops/s |
+| user (4 fields) | parseStrict | **~9M** ops/s | ~1.4M ops/s | ~1.3M ops/s |
+| order (nested + array) | parseStrict | **~5.4M** ops/s | ~0.27M ops/s | ~0.20M ops/s |
+
+The upstream `assert` case (seven scalar roots plus a nested object) runs faster
+still — tens of millions of ops/s — but at that size the numbers swing enough
+run-to-run that the ratio, not the absolute, is the honest signal: mjst lands
+~5–30× ahead of zod across every case above.
+
+The trade is a one-shot **prepare** cost that only mjst pays — generating the
+parser source — which measures **~0.1–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
+and run the emitted code forever.
+
+Every library is checked for agreement — same stripped/rejected output, same
+throws on bad input — before it is timed, and each is timed in its own isolated
+process over a pool of distinct inputs, reporting the median of many trials, so
+the optimiser can't hoist the work away. Micro-benchmark figures vary by machine
+and runtime — reproduce with:
+
+```bash
+bun run bench
+```
+
+---
+
 ## Related packages
 
 - [`@amritk/mjst`](../cli) — CLI wrapping this generator

package/dist/generators/assert-supported-keywords.d.ts

@@ -0,0 +1,26 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Throws when a schema (anywhere in its subtree) uses a keyword the *strict*
+ * parser generator cannot enforce but which narrows the set of valid documents.
+ * Mirrors generate-validators' `assertNoUnsupportedKeywords`: failing loudly at
+ * generation time is strictly better than silently emitting a parser that
+ * accepts input the schema forbids — a strict parser promises to "throw on
+ * violations".
+ *
+ * Two families are rejected:
+ *
+ *  - `unevaluatedProperties` / `unevaluatedItems` with a constraining value
+ *    (`false` or a subschema). The generator has no support for the "which
+ *    properties/items were evaluated" bookkeeping these require; only the
+ *    runtime interpreter does. A `true` value permits everything and is allowed.
+ *
+ *  - `contains`, `propertyNames`, or `dependentSchemas` whose subschema uses a
+ *    form {@link canMatchSubschema} cannot prove inline (a `$ref`, a combinator,
+ *    a schema-valued record, …). The parser enforces these keywords only for
+ *    subschemas it can match exactly; anything else would be silently ignored.
+ *
+ * This runs for strict generation only — coercing parsers are documented to be
+ * permissive (they repair rather than reject), so ignoring these keywords there
+ * is the contract, not a lie.
+ */
+export declare const assertNoUnsupportedKeywords: (schema: JSONSchema, typeName: string) => void;

package/dist/generators/assert-supported-keywords.js

@@ -0,0 +1,74 @@
+import { isSchemaObject } from '@amritk/helpers/schema-guards';
+import { canMatchSubschema } from './subschema-match.js';
+/**
+ * Throws when a schema (anywhere in its subtree) uses a keyword the *strict*
+ * parser generator cannot enforce but which narrows the set of valid documents.
+ * Mirrors generate-validators' `assertNoUnsupportedKeywords`: failing loudly at
+ * generation time is strictly better than silently emitting a parser that
+ * accepts input the schema forbids — a strict parser promises to "throw on
+ * violations".
+ *
+ * Two families are rejected:
+ *
+ *  - `unevaluatedProperties` / `unevaluatedItems` with a constraining value
+ *    (`false` or a subschema). The generator has no support for the "which
+ *    properties/items were evaluated" bookkeeping these require; only the
+ *    runtime interpreter does. A `true` value permits everything and is allowed.
+ *
+ *  - `contains`, `propertyNames`, or `dependentSchemas` whose subschema uses a
+ *    form {@link canMatchSubschema} cannot prove inline (a `$ref`, a combinator,
+ *    a schema-valued record, …). The parser enforces these keywords only for
+ *    subschemas it can match exactly; anything else would be silently ignored.
+ *
+ * This runs for strict generation only — coercing parsers are documented to be
+ * permissive (they repair rather than reject), so ignoring these keywords there
+ * is the contract, not a lie.
+ */
+export const assertNoUnsupportedKeywords = (schema, typeName) => {
+    const fail = (keyword, detail) => {
+        throw new Error(`[${typeName}] unsupported keyword "${keyword}": the strict parser generator ${detail}, and would ` +
+            `silently accept documents the schema rejects. Generate a coercing (non-strict) parser, validate this ` +
+            `schema with @amritk/generate-validators, or remove the keyword.`);
+    };
+    const visit = (node) => {
+        if (typeof node !== 'object' || node === null)
+            return;
+        if (Array.isArray(node)) {
+            for (const item of node)
+                visit(item);
+            return;
+        }
+        const record = node;
+        // `true` permits everything → no constraint → safe to ignore.
+        if ('unevaluatedProperties' in record && record['unevaluatedProperties'] !== true) {
+            fail('unevaluatedProperties', 'does not implement it');
+        }
+        if ('unevaluatedItems' in record && record['unevaluatedItems'] !== true) {
+            fail('unevaluatedItems', 'does not implement it');
+        }
+        if ('contains' in record && !canMatchSubschema(record['contains'])) {
+            fail('contains', 'cannot prove its subschema inline');
+        }
+        if ('propertyNames' in record && isSchemaObject(record['propertyNames'])) {
+            if (!canMatchSubschema(record['propertyNames'])) {
+                fail('propertyNames', 'cannot prove its subschema inline');
+            }
+        }
+        const dependentSchemas = record['dependentSchemas'];
+        if (typeof dependentSchemas === 'object' && dependentSchemas !== null && !Array.isArray(dependentSchemas)) {
+            for (const sub of Object.values(dependentSchemas)) {
+                // Boolean subschemas are enforced directly (see generateDependentSchemasChecks).
+                if (typeof sub === 'boolean')
+                    continue;
+                if (!canMatchSubschema(sub)) {
+                    fail('dependentSchemas', 'cannot prove one of its subschemas inline');
+                }
+            }
+        }
+        // `for..in` (not `Object.values`) to recurse without allocating an array per
+        // node — this walk runs for every strict parser generated.
+        for (const key in record)
+            visit(record[key]);
+    };
+    visit(schema);
+};