@amritk/generate-parsers 0.12.2 → 0.13.0

package/README.md

@@ -97,52 +97,42 @@ Returns: `Promise<GeneratedFile[]>`.
 <thead>
 <tr>
 <th>Property</th>
-<th>CLI Flag</th>
 <th>Type</th>
-<th align="center">Required</th>
 <th align="center">Default</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td>🏷️ <code>typesOnly</code></td>
-<td>—</td>
 <td><code>boolean</code></td>
-<td align="center">—</td>
 <td align="center"><code>false</code></td>
 </tr>
 <tr>
-<td colspan="5">Generate only TypeScript type definitions without parser functions. Runtime helper files (validators, isObject) are also omitted since they are only needed for parsers.</td>
+<td colspan="3">Generate only TypeScript type definitions without parser functions. Runtime helper files (validators, isObject) are also omitted since they are only needed for parsers.</td>
 </tr>
 <tr>
 <td>⚠️ <code>logWarnings</code></td>
-<td>—</td>
 <td><code>boolean</code></td>
-<td align="center">—</td>
 <td align="center"><code>false</code></td>
 </tr>
 <tr>
-<td colspan="5">Emit a console.warn in the generated parsers for every input key that is not declared in the schema's properties. Useful for detecting schema drift or unexpected data shapes at runtime.</td>
+<td colspan="3">Emit a console.warn in the generated parsers for every input key that is not declared in the schema's properties. Useful for detecting schema drift or unexpected data shapes at runtime.</td>
 </tr>
 <tr>
 <td>🚫 <code>strict</code></td>
-<td>—</td>
 <td><code>boolean</code></td>
-<td align="center">—</td>
 <td align="center"><code>false</code></td>
 </tr>
 <tr>
-<td colspan="5">Generate parsers that throw on type/shape mismatches (wrong type, missing required property, enum/pattern/min/max violations) instead of coercing invalid input to default values. When a schema sets additionalProperties: false, undeclared keys throw too; otherwise they are still allowed.</td>
+<td colspan="3">Generate parsers that throw on type/shape mismatches (wrong type, missing required property, enum/pattern/min/max violations) instead of coercing invalid input to default values. When a schema sets additionalProperties: false, undeclared keys throw too; otherwise they are still allowed.</td>
 </tr>
 <tr>
 <td>🧹 <code>stripUnknown</code></td>
-<td>—</td>
 <td><code>boolean</code></td>
-<td align="center">—</td>
 <td align="center"><code>false</code></td>
 </tr>
 <tr>
-<td colspan="5">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>
+<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>
 </tbody>
 </table>

package/dist/generators/build-schema.js

@@ -5,13 +5,38 @@ import { generateIndexBarrel } from '@amritk/helpers/generate-index-barrel';
 import { walkRefGraph } from '@amritk/helpers/walk-ref-graph';
 import { applySchemaExtensions } from '../helpers/apply-schema-extensions.js';
 import { generateFile } from './generate-files.js';
-/** Locate the @amritk/helpers package on disk so we can copy its runtime
- * helper source files into the generated output when in embedded mode. */
+/**
+ * Loads a runtime helper's source to copy into `_helpers/` in embedded mode.
+ *
+ * Prefers the TypeScript source (`src/<helper>.ts`), rewriting any extensionless
+ * sibling import (e.g. `validate-record` → `./is-object`) to `./is-object.js` so
+ * the embedded copy resolves under Node ESM, not only Bun. When the resolved
+ * `@amritk/helpers` is a published/cached tarball that ships only `dist/` (its
+ * `files` historically excluded `src/`, which is exactly why `bunx mjst` crashed
+ * on this lookup), it falls back to the always-published compiled `dist/<helper>.js`
+ * — which tsc already emits with `.js`-extension imports — and writes it verbatim.
+ */
 const readHelperSource = async (helper) => {
     const require = createRequire(import.meta.url);
-    const helpersPkgPath = require.resolve('@amritk/helpers/package.json');
-    const helpersRoot = dirname(helpersPkgPath);
-    return readFile(resolvePath(helpersRoot, 'src', `${helper}.ts`), 'utf-8');
+    const helpersRoot = dirname(require.resolve('@amritk/helpers/package.json'));
+    try {
+        const source = await readFile(resolvePath(helpersRoot, 'src', `${helper}.ts`), 'utf-8');
+        // The leading `\b` in this pattern is load-bearing beyond its regex meaning.
+        // Our build runs tsc-alias --resolveFullPaths over the compiled output, and its
+        // scanner rewrites anything that looks like `from '<path>'` — even inside a
+        // regex literal. Without the `\b`, normalize-path turned this pattern's
+        // backslashes into slashes and v0.12.3 shipped with an unparseable regex that
+        // crashed the CLI on load. The `\b` blocks that scan (in the emitted text,
+        // `from` is preceded by the word character `b`, so tsc-alias's own `\bfrom`
+        // never matches) and is also semantically correct: an import keyword always
+        // sits at a word boundary. The dist smoke test (scripts/dist-smoke.test.ts)
+        // fails the build if this ever regresses.
+        return { ext: 'ts', content: source.replace(/\bfrom '(\.\/[^'".]+)'/g, "from '$1.js'") };
+    }
+    catch {
+        const compiled = await readFile(resolvePath(helpersRoot, 'dist', `${helper}.js`), 'utf-8');
+        return { ext: 'js', content: compiled };
+    }
 };
 /**
  * Builds all TypeScript files from a JSON Schema by traversing its entire
@@ -114,8 +139,8 @@ export const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnl
     // typesOnly skips parser generation entirely, so no runtime helpers are needed.
     if (helpersMode === 'embedded' && !typesOnly) {
         for (const helper of usedHelpers) {
-            const source = await readHelperSource(helper);
-            files.push({ filename: `_helpers/${helper}.ts`, content: source });
+            const { ext, content } = await readHelperSource(helper);
+            files.push({ filename: `_helpers/${helper}.${ext}`, content });
         }
     }
     files.push({ filename: 'index.ts', content: generateIndexBarrel(files, { typesOnly: typesOnly ?? false }) });

package/dist/generators/generate-discriminated-union-validation.d.ts

@@ -2,5 +2,14 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
 /**
  * Generates a discriminated union validation expression.
  * Uses a discriminator property to efficiently choose the correct schema.
+ *
+ * The emitted expression is a single *nested* ternary in schema order — for
+ * branches `dog`, `cat` it reads `disc === "dog" ? v : disc === "cat" ? v :
+ * <fallback>`. Each branch tests its discriminant (plus any per-branch shape
+ * checks) and, on a match, passes the value through; the innermost `else` is the
+ * shared fallback taken when no discriminant matches. The previous
+ * `cases[i] + ' : ' + result` folding spliced complete ternaries together
+ * (`c1 ? v : d1 : c0 ? v : d0`), which is a parse error for >=2 branches and
+ * also evaluated branches in reverse with the wrong per-case default.
  */
 export declare const generateDiscriminatedUnionValidation: (accessor: string, schemas: readonly JSONSchema[], discriminatorKey: string, defaultValue: string, isRequired: boolean) => string;

package/dist/generators/generate-discriminated-union-validation.js

@@ -1,38 +1,49 @@
-import { getDefaultValue } from '../helpers/get-default-value.js';
+import { safeAccessor } from '@amritk/helpers/safe-accessor';
 import { getDiscriminatorValue } from '../helpers/get-discriminator-value.js';
 import { generateSchemaChecks } from './generate-schema-checks.js';
 /**
  * Generates a discriminated union validation expression.
  * Uses a discriminator property to efficiently choose the correct schema.
+ *
+ * The emitted expression is a single *nested* ternary in schema order — for
+ * branches `dog`, `cat` it reads `disc === "dog" ? v : disc === "cat" ? v :
+ * <fallback>`. Each branch tests its discriminant (plus any per-branch shape
+ * checks) and, on a match, passes the value through; the innermost `else` is the
+ * shared fallback taken when no discriminant matches. The previous
+ * `cases[i] + ' : ' + result` folding spliced complete ternaries together
+ * (`c1 ? v : d1 : c0 ? v : d0`), which is a parse error for >=2 branches and
+ * also evaluated branches in reverse with the wrong per-case default.
  */
 export const generateDiscriminatedUnionValidation = (accessor, schemas, discriminatorKey, defaultValue, isRequired) => {
-    const cases = [];
+    // A non-identifier discriminator key (e.g. `x-type`) must use bracket access;
+    // `${accessor}?.${key}` would emit broken TS. `safeAccessor` picks dot vs
+    // bracket notation and JSON.stringifies the literal so quotes-in-keys are safe.
+    const discAccessor = safeAccessor(`${accessor}?`, discriminatorKey);
+    // Each branch contributes its guard condition and the value to yield on a
+    // match; the value is `accessor` because `generateSchemaChecks` has already
+    // proven the branch's shape (no coercion happens here).
+    const branches = [];
     for (const schema of schemas) {
         const discriminatorValue = getDiscriminatorValue(schema, discriminatorKey);
-        if (discriminatorValue !== null) {
-            const schemaDefault = getDefaultValue(schema);
-            const checks = generateSchemaChecks(accessor, schema);
-            if (checks.length > 0) {
-                // checks[0] is safe: we guard with checks.length > 0 above
-                let combinedChecks = checks[0];
-                for (let i = 1; i < checks.length; i++) {
-                    combinedChecks += ' && ' + checks[i];
-                }
-                cases.push(`${accessor}?.${discriminatorKey} === ${JSON.stringify(discriminatorValue)} && ${combinedChecks} ? ${accessor} : ${schemaDefault}`);
-            }
-            else {
-                cases.push(`${accessor}?.${discriminatorKey} === ${JSON.stringify(discriminatorValue)} ? ${accessor} : ${schemaDefault}`);
-            }
+        if (discriminatorValue === null)
+            continue;
+        let condition = `${discAccessor} === ${JSON.stringify(discriminatorValue)}`;
+        const checks = generateSchemaChecks(accessor, schema);
+        for (const check of checks) {
+            condition += ' && ' + check;
         }
+        branches.push(condition);
     }
-    if (cases.length === 0) {
+    if (branches.length === 0) {
         return isRequired ? `${accessor} ?? ${defaultValue}` : accessor;
     }
-    // Chain the cases together with ternary operators using a for loop instead of .reduce()
-    // cases[0] is safe: we guard with cases.length === 0 above
-    let result = cases[0];
-    for (let i = 1; i < cases.length; i++) {
-        result = cases[i] + ' : ' + result;
+    // When no discriminant matches, a required union coerces to the shared default;
+    // an optional one keeps the raw value untouched.
+    let result = isRequired ? defaultValue : accessor;
+    // Fold from the last branch inward so the final text lists branches in schema
+    // order: `cond0 ? accessor : cond1 ? accessor : <fallback>`.
+    for (let i = branches.length - 1; i >= 0; i--) {
+        result = `${branches[i]} ? ${accessor} : ${result}`;
     }
     return result;
 };

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

@@ -1,5 +1,13 @@
 /**
  * Generates an enum validation check expression.
  * Returns a string that checks if the value is in the allowed enum values.
+ *
+ * For the common all-primitive case this emits a parenthesized `x === a || x ===
+ * b` chain rather than `[a, b].includes(x)`. The `.includes` form allocates a
+ * fresh array on every call (this expression runs on the parser hot path); the
+ * `===` chain is allocation-free and matches the validators package's
+ * `enumMembershipExpr`. It falls back to `.includes` when a member is an
+ * object/array (reference equality) or `NaN` (where `includes`'s SameValueZero
+ * differs from `===`), so the verdict is unchanged.
  */
 export declare const generateEnumCheck: (accessor: string, enumValues: readonly unknown[]) => string;

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

@@ -1,8 +1,22 @@
 /**
  * Generates an enum validation check expression.
  * Returns a string that checks if the value is in the allowed enum values.
+ *
+ * For the common all-primitive case this emits a parenthesized `x === a || x ===
+ * b` chain rather than `[a, b].includes(x)`. The `.includes` form allocates a
+ * fresh array on every call (this expression runs on the parser hot path); the
+ * `===` chain is allocation-free and matches the validators package's
+ * `enumMembershipExpr`. It falls back to `.includes` when a member is an
+ * object/array (reference equality) or `NaN` (where `includes`'s SameValueZero
+ * differs from `===`), so the verdict is unchanged.
  */
 export const generateEnumCheck = (accessor, enumValues) => {
+    const allPrimitive = enumValues.length > 0 &&
+        enumValues.every((v) => (v === null || typeof v !== 'object') && typeof v !== 'function') &&
+        !enumValues.some((v) => typeof v === 'number' && Number.isNaN(v));
+    if (allPrimitive) {
+        return `(${enumValues.map((v) => `${accessor} === ${JSON.stringify(v)}`).join(' || ')})`;
+    }
     const serializedEnum = JSON.stringify(enumValues);
     return `${serializedEnum}.includes(${accessor} as never)`;
 };

package/dist/generators/generate-files.js

@@ -55,6 +55,7 @@ export const generateFile = (schema, typeName, options) => {
     const parserFunction = generateParserFunction(schema, typeName, {
         useRefImports: true,
         typeSuffix,
+        ...(rootSchema !== undefined ? { rootSchema } : {}),
         ...(options?.logWarnings !== undefined ? { logWarnings: options.logWarnings } : {}),
         ...(options?.strict !== undefined ? { strict: options.strict } : {}),
         ...(options?.stripUnknown !== undefined ? { stripUnknown: options.stripUnknown } : {}),

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

@@ -36,6 +36,12 @@ type GenerateParserOptions = {
      * the suffix used when generating the referenced files. Defaults to `''`.
      */
     readonly typeSuffix?: string;
+    /**
+     * The root schema document. When present, a top-level `oneOf`/`anyOf` whose
+     * branches are `$ref`s can be resolved to find a shared discriminator and emit a
+     * dispatch to the branch parsers, instead of falling back to a passthrough cast.
+     */
+    readonly rootSchema?: Record<string, unknown>;
 };
 /**
  * Generates a safe parser as an arrow function that never throws.