@amritk/generate-parsers 0.16.0 → 0.16.2

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 | **~16M** ops/s | ~3.3M ops/s | ~1.3M ops/s |
+| order (nested + array) | parseSafe | **~5.8M** ops/s | ~0.6M ops/s | ~0.18M ops/s |
+| user (4 fields) | parseStrict | **~13M** ops/s | ~1.8M ops/s | ~1.85M ops/s |
+| order (nested + array) | parseStrict | **~7.5M** ops/s | ~0.36M ops/s | ~0.28M 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);
+};

package/dist/generators/generate-enum-check.js

@@ -37,18 +37,27 @@ export const generateEnumCheck = (accessor, enumValues) => {
  * keeps its plain fallback and emits no extra code.
  */
 export const generateEnumCaseInsensitiveCoercion = (accessor, enumValues, fallback) => {
-    const byLower = {};
+    const entries = [];
+    const seen = new Set();
     for (const value of enumValues) {
         if (typeof value !== 'string')
             continue;
         const lower = value.toLowerCase();
         // First writer wins, so declaration order breaks ties between members that
-        // fold to the same key (e.g. `"on"` and `"ON"`).
-        if (!(lower in byLower))
-            byLower[lower] = value;
+        // fold to the same key (e.g. `"on"` and `"ON"`). `Set` membership is used
+        // instead of `lower in obj` so a member folding to an inherited name like
+        // `constructor` or `toString` is not wrongly treated as already-present.
+        if (seen.has(lower))
+            continue;
+        seen.add(lower);
+        entries.push([lower, value]);
     }
-    if (Object.keys(byLower).length === 0)
+    if (entries.length === 0)
         return null;
-    const map = JSON.stringify(byLower);
-    return `(typeof ${accessor} === "string" ? ((${map} as Record<string, string>)[(${accessor} as string).toLowerCase()] ?? ${fallback}) : ${fallback})`;
+    // A `Map` — not a plain object — so a folded key that collides with an
+    // inherited member (`constructor`, `toString`, `__proto__`, …) resolves to
+    // `undefined` (→ `fallback`) rather than an `Object.prototype` value. A
+    // plain-object lookup would return the inherited function/object for such a key.
+    const map = `new Map(${JSON.stringify(entries)})`;
+    return `(typeof ${accessor} === "string" ? (${map}.get((${accessor} as string).toLowerCase()) ?? ${fallback}) : ${fallback})`;
 };