@amritk/generate-parsers 0.15.0 → 0.16.1

package/README.md

@@ -134,6 +134,14 @@ Returns: `Promise<GeneratedFile[]>`.
 <tr>
 <td colspan="3">Build each parser's result from the schema's declared properties only, silently dropping undeclared input keys at every nesting level (zod's .strip()). Extras are never a validation error, so this composes with strict (which still throws on wrong types and missing required properties) and yields to additionalProperties: false, which rejects rather than strips in strict mode.</td>
 </tr>
+<tr>
+<td>🔡 <code>caseInsensitive</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<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>
 </tbody>
 </table>
 <!-- config-table-end -->
@@ -148,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);
+};

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

@@ -53,6 +53,12 @@ export type GeneratedFile = {
  *   stripping. Note the `mjst` CLI defaults this to `'ts'` (falling back to `'js'` only
  *   under `--build`, where tsc must compile the sources) so generated output runs under
  *   Node without a build step; direct callers of `buildSchema` opt in explicitly.
+ * @param caseInsensitive - When true, the generated coercing parsers 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. The normalization lives on
+ *   the coercion failure branch, so correctly-cased input keeps the exact-match fast path
+ *   and the hot path is unaffected.
  * @returns An array of generated TypeScript files
  *
  * @example
@@ -85,4 +91,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) => 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) => Promise<GeneratedFile[]>;

package/dist/generators/build-schema.js

@@ -89,6 +89,12 @@ const readHelperSource = async (helper, importExt) => {
  *   stripping. Note the `mjst` CLI defaults this to `'ts'` (falling back to `'js'` only
  *   under `--build`, where tsc must compile the sources) so generated output runs under
  *   Node without a build step; direct callers of `buildSchema` opt in explicitly.
+ * @param caseInsensitive - When true, the generated coercing parsers 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. The normalization lives on
+ *   the coercion failure branch, so correctly-cased input keeps the exact-match fast path
+ *   and the hot path is unaffected.
  * @returns An array of generated TypeScript files
  *
  * @example
@@ -121,7 +127,7 @@ const readHelperSource = async (helper, importExt) => {
  * });
  * ```
  */
-export const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = 'package', helpersImportPrefix = './', readonly = false, stripUnknown = false, typeSuffix = '', importExt = 'js') => {
+export const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = 'package', helpersImportPrefix = './', readonly = false, stripUnknown = false, typeSuffix = '', importExt = 'js', caseInsensitive = false) => {
     const files = [];
     const usedHelpers = new Set();
     walkRefGraph(rootSchema, rootTypeName, { typeSuffix }, (node) => {
@@ -145,6 +151,7 @@ export const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnl
             ...(logWarnings !== undefined ? { logWarnings } : {}),
             ...(strict !== undefined ? { strict } : {}),
             ...(stripUnknown ? { stripUnknown } : {}),
+            ...(caseInsensitive ? { caseInsensitive } : {}),
         });
         files.push({ filename: `${node.filename}.ts`, content: result.content });
         for (const helper of result.usedHelpers)

package/dist/generators/generate-enum-check.d.ts

@@ -11,3 +11,20 @@
  * differs from `===`), so the verdict is unchanged.
  */
 export declare const generateEnumCheck: (accessor: string, enumValues: readonly unknown[]) => string;
+/**
+ * Builds a case-insensitive coercion expression for a string `enum`/`const`
+ * value whose exact-match check has already failed. Only the *string* members
+ * participate (a number/boolean/null member has no case to fold): a value that
+ * matches one case-insensitively normalizes to that member's exact casing, and
+ * everything else yields `fallback`.
+ *
+ * This is emitted ONLY on the already-invalid branch of the coercion ternary, so
+ * a correctly-cased value never reaches it — the exact `===` fast path (and the
+ * shape validators / deep guards built on it) is unchanged, so the hot path pays
+ * nothing. Only a mis-cased value, which today coerces straight to the default,
+ * now takes a single `toLowerCase()` and an O(1) map lookup instead.
+ *
+ * Returns `null` when no member is a string (nothing to fold), so the caller
+ * keeps its plain fallback and emits no extra code.
+ */
+export declare const generateEnumCaseInsensitiveCoercion: (accessor: string, enumValues: readonly unknown[], fallback: string) => string | null;

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

@@ -20,3 +20,35 @@ export const generateEnumCheck = (accessor, enumValues) => {
     const serializedEnum = JSON.stringify(enumValues);
     return `${serializedEnum}.includes(${accessor} as never)`;
 };
+/**
+ * Builds a case-insensitive coercion expression for a string `enum`/`const`
+ * value whose exact-match check has already failed. Only the *string* members
+ * participate (a number/boolean/null member has no case to fold): a value that
+ * matches one case-insensitively normalizes to that member's exact casing, and
+ * everything else yields `fallback`.
+ *
+ * This is emitted ONLY on the already-invalid branch of the coercion ternary, so
+ * a correctly-cased value never reaches it — the exact `===` fast path (and the
+ * shape validators / deep guards built on it) is unchanged, so the hot path pays
+ * nothing. Only a mis-cased value, which today coerces straight to the default,
+ * now takes a single `toLowerCase()` and an O(1) map lookup instead.
+ *
+ * Returns `null` when no member is a string (nothing to fold), so the caller
+ * keeps its plain fallback and emits no extra code.
+ */
+export const generateEnumCaseInsensitiveCoercion = (accessor, enumValues, fallback) => {
+    const byLower = {};
+    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;
+    }
+    if (Object.keys(byLower).length === 0)
+        return null;
+    const map = JSON.stringify(byLower);
+    return `(typeof ${accessor} === "string" ? ((${map} as Record<string, string>)[(${accessor} as string).toLowerCase()] ?? ${fallback}) : ${fallback})`;
+};

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

@@ -78,6 +78,13 @@ type GenerateFileOptions = {
      * user-named root.
      */
     readonly isRoot?: boolean;
+    /**
+     * When true, a mis-cased string that matches a declared `enum`/`const` member
+     * case-insensitively is normalized to that member's exact casing (coerce mode
+     * only). The normalization is emitted on the coercion failure branch, so
+     * already-valid input keeps the exact-match fast path.
+     */
+    readonly caseInsensitive?: boolean;
 };
 /** Result of generating a single parser file. */
 export type GeneratedFileContent = {

package/dist/generators/generate-files.js

@@ -67,6 +67,7 @@ export const generateFile = (schema, typeName, options) => {
         ...(options?.logWarnings !== undefined ? { logWarnings: options.logWarnings } : {}),
         ...(options?.strict !== undefined ? { strict: options.strict } : {}),
         ...(options?.stripUnknown !== undefined ? { stripUnknown: options.stripUnknown } : {}),
+        ...(options?.caseInsensitive !== undefined ? { caseInsensitive: options.caseInsensitive } : {}),
     });
     const shapeValidator = generateShapeValidator(schema, typeName, true, typeSuffix, true, stripUnknown, reservedNames);
     const combinedFunctions = `${shapeValidator}\n\n${parserFunction}`;

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

@@ -58,6 +58,15 @@ type GenerateParserOptions = {
      * generate a validation-free pass-through parser.
      */
     readonly isRoot?: boolean;
+    /**
+     * When true, a mis-cased string that matches a declared `enum`/`const` member
+     * case-insensitively is normalized to that member's exact casing (e.g. `hElLo`
+     * → `hello`) instead of coercing to the default. Coerce mode only — strict
+     * parsers still reject a casing mismatch. The normalization lives on the
+     * failure branch of the coercion ternary, so a correctly-cased value keeps the
+     * exact `===` fast path and the hot path is unaffected.
+     */
+    readonly caseInsensitive?: boolean;
 };
 /**
  * Generates a safe parser as an arrow function that never throws.