@amritk/generate-parsers 0.12.3 → 0.13.0

package/dist/generators/build-schema.js

@@ -21,7 +21,17 @@ const readHelperSource = async (helper) => {
     const helpersRoot = dirname(require.resolve('@amritk/helpers/package.json'));
     try {
         const source = await readFile(resolvePath(helpersRoot, 'src', `${helper}.ts`), 'utf-8');
-        return { ext: 'ts', content: source.replace(/from '(/./[^'".]+)'/g, "from '$1.js'") };
+        // 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');

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

@@ -1,14 +1,14 @@
 import { escapeRegexPattern } from '@amritk/helpers/escape-regex-pattern';
-import { multipleOfPassExpr } from '@amritk/helpers/multiple-of-check';
 import { refToName } from '@amritk/helpers/ref-to-name';
 import { resolveRef } from '@amritk/helpers/resolve-ref';
 import { safeAccessor, safeKey } from '@amritk/helpers/safe-accessor';
-import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasEnum, hasExclusiveMaximum, hasExclusiveMinimum, hasItems, hasMaxItems, hasMaximum, hasMaxLength, hasMinItems, hasMinimum, hasMinLength, hasMultipleOf, hasOneOf, hasPattern, hasProperties, hasRef, hasType, hasUniqueItems, isObjectSchema, isSchemaObject, } from '@amritk/helpers/schema-guards';
+import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasEnum, hasItems, hasOneOf, hasProperties, hasRef, hasType, isObjectSchema, isSchemaObject, } from '@amritk/helpers/schema-guards';
 import { unknownKeyCheck } from '@amritk/helpers/unknown-key-check';
 import { findDiscriminator } from '../helpers/find-discriminator.js';
 import { getDefaultValue } from '../helpers/get-default-value.js';
 import { getDiscriminatorValue } from '../helpers/get-discriminator-value.js';
 import { generateObjectStrictAssertion, generateScalarStrictAssertion } from './generate-strict-assertion.js';
+import { canEnforceUnion, generatePropertyTypeCheck, generateUnionCheck, getUnionBranches, shapeValidatorName, } from './generate-type-checks.js';
 import { generateValidationExpression, scalarItemTypeCheck } from './generate-validation-expression.js';
 /**
  * Generates the parser function name from a type name.
@@ -374,6 +374,30 @@ const generateNonObjectParser = (typeName, schema, strict, unionCtx) => {
                 return dispatch;
         }
     }
+    // An alias definition (a bare `$ref` with no shape of its own, e.g. a root
+    // schema that is just `$ref: '#/$defs/expr'`) delegates to the referenced
+    // parser instead of blindly casting, in both modes. Guarded against
+    // self-reference: delegating to ourselves would recurse forever.
+    if (unionCtx?.useRefImports && isSchemaObject(schema) && hasRef(schema) && !hasProperties(schema)) {
+        const refName = refToName(schema.$ref, unionCtx.suffix);
+        if (refName !== typeName) {
+            return `export const ${functionName} = (input: unknown): ${typeName} => ${generateParserName(refName)}(input) as ${typeName};`;
+        }
+    }
+    // Strict union enforcement for inline (or mixed) branches: membership is the
+    // disjunction of per-branch checks, and a non-member throws. Only emitted
+    // when every branch check is false-sound (see canEnforceUnion) — otherwise a
+    // conservative stub validator somewhere in the graph could reject valid
+    // input — and never when stripping unknown keys (see UnionParserContext).
+    if (strict && unionCtx && isSchemaObject(schema)) {
+        const branches = getUnionBranches(schema);
+        if (branches && !unionCtx.stripUnknown && canEnforceUnion(branches, unionCtx.rootSchema)) {
+            const check = generateUnionCheck('input', branches, unionCtx.useRefImports, unionCtx.suffix);
+            if (check !== null) {
+                return `export const ${functionName} = (input: unknown): ${typeName} => {\n  if (!(${check})) throw new Error(${JSON.stringify(`[${typeName}] value does not match any union branch`)});\n  return input as ${typeName};\n};`;
+            }
+        }
+    }
     // `const`/`enum` define the value space directly (the generated type is a
     // literal / literal-union), so a non-member must coerce to a valid member —
     // otherwise the returned value would not be of the declared type. This runs
@@ -471,12 +495,6 @@ const toVarName = (key) => {
     const safe = key.replace(/[^a-zA-Z0-9_$]/g, '_');
     return `_${safe}`;
 };
-/**
- * Returns the shape-predicate function name for a given type name.
- * The predicate is generated alongside each parser and tells callers
- * whether `input` is already in the shape produced by the parser's fast path.
- */
-const shapeValidatorName = (typeName) => `validate${typeName}Shape`;
 /**
  * Matches an inline nested object property — an object schema written directly
  * under `properties` with its own `properties`, rather than referenced via
@@ -544,119 +562,6 @@ const hasStrictKeys = (schema) => {
         return false;
     return true;
 };
-/**
- * Generates a fast-path type check expression for a property.
- * Returns null if the schema is too complex for a simple type check
- * (e.g. has unions, enums that require more elaborate validation).
- *
- * When `useRefImports` is true, $ref properties (and arrays of $refs) are
- * checked by calling the imported shape predicate, allowing parent parsers
- * to fast-path through nested ref types without recursing into their parsers.
- */
-const generatePropertyTypeCheck = (varName, schema, useRefImports, suffix) => {
-    if (!isSchemaObject(schema))
-        return null;
-    // $ref via shape predicate (deep fast-path through nested types).
-    if (useRefImports && hasRef(schema)) {
-        const refName = refToName(schema.$ref, suffix);
-        return `${shapeValidatorName(refName)}(${varName})`;
-    }
-    // Skip fast path for complex schemas that need more elaborate validation
-    if (hasEnum(schema) ||
-        hasOneOf(schema) ||
-        hasAnyOf(schema) ||
-        hasAllOf(schema) ||
-        hasRef(schema) ||
-        'not' in schema) {
-        return null;
-    }
-    // A `const` property (the usual discriminated-union tag, e.g. `kind: "lit"`) has
-    // no `type`, but is fast-path predicable via strict equality. Handling it here is
-    // what lets a discriminated branch's shape validator be a real predicate instead
-    // of the `=> false` stub. Structural consts need deep equality, so skip those.
-    if (hasConst(schema)) {
-        const c = schema.const;
-        return c === null || typeof c !== 'object' ? `${varName} === ${JSON.stringify(c)}` : null;
-    }
-    if (!hasType(schema))
-        return null;
-    // Array of $refs: each item must satisfy the imported shape predicate.
-    if (useRefImports &&
-        schema.type === 'array' &&
-        hasItems(schema) &&
-        isSchemaObject(schema.items) &&
-        hasRef(schema.items)) {
-        const refName = refToName(schema.items.$ref, suffix);
-        return `Array.isArray(${varName}) && ${varName}.every(${shapeValidatorName(refName)})`;
-    }
-    const checks = [];
-    switch (schema.type) {
-        case 'string': {
-            checks.push(`typeof ${varName} === "string"`);
-            if (hasPattern(schema))
-                checks.push(`/${escapeRegexPattern(schema.pattern)}/.test(${varName})`);
-            if (hasMinLength(schema))
-                checks.push(`${varName}.length >= ${schema.minLength}`);
-            if (hasMaxLength(schema))
-                checks.push(`${varName}.length <= ${schema.maxLength}`);
-            break;
-        }
-        case 'number':
-        case 'integer': {
-            checks.push(`typeof ${varName} === "number"`);
-            // `integer` must reject non-integral numbers on the fast path too, otherwise
-            // `1.5` would pass through uncoerced.
-            if (schema.type === 'integer')
-                checks.push(`Number.isInteger(${varName})`);
-            if (hasMinimum(schema))
-                checks.push(`${varName} >= ${schema.minimum}`);
-            if (hasMaximum(schema))
-                checks.push(`${varName} <= ${schema.maximum}`);
-            if (hasExclusiveMinimum(schema))
-                checks.push(`${varName} > ${schema.exclusiveMinimum}`);
-            if (hasExclusiveMaximum(schema))
-                checks.push(`${varName} < ${schema.exclusiveMaximum}`);
-            if (hasMultipleOf(schema))
-                checks.push(multipleOfPassExpr(varName, schema.multipleOf));
-            break;
-        }
-        case 'boolean':
-            checks.push(`typeof ${varName} === "boolean"`);
-            break;
-        case 'array': {
-            checks.push(`Array.isArray(${varName})`);
-            if (hasMinItems(schema))
-                checks.push(`${varName}.length >= ${schema.minItems}`);
-            if (hasMaxItems(schema))
-                checks.push(`${varName}.length <= ${schema.maxItems}`);
-            if (hasUniqueItems(schema) && schema.uniqueItems === true) {
-                checks.push(`new Set(${varName}).size === ${varName}.length`);
-            }
-            // For a scalar item type, every element must already be well-typed to take
-            // the fast path; a mistyped element routes the array to the slow path where
-            // each element is coerced.
-            if (hasItems(schema) && !Array.isArray(schema.items)) {
-                const itemCheck = scalarItemTypeCheck(schema.items, '_it');
-                if (itemCheck)
-                    checks.push(`${varName}.every((_it) => ${itemCheck})`);
-            }
-            break;
-        }
-        case 'object':
-            checks.push(`isObject(${varName})`);
-            break;
-        default:
-            return null;
-    }
-    if (checks.length === 0)
-        return null;
-    // checks[0] is safe: we guard with checks.length === 0 above
-    let result = checks[0];
-    for (let i = 1; i < checks.length; i++) {
-        result += ' && ' + checks[i];
-    }
-    return result;
-};
 /**
  * Determines if a property needs a local variable or can be inlined.
  * Schema-object properties are always cached: the slow-path ternary chain
@@ -677,7 +582,7 @@ const shouldCacheVariable = (propSchema, _canFastPath, _useRefImports) => {
  * - Fast path that returns input directly when all properties are already valid
  * - Slow path with optimized expressions
  */
-const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnings, strict, exported = true, stripUnknown = false) => {
+const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnings, strict, exported = true, stripUnknown = false, rootSchema) => {
     const functionName = generateParserName(typeName);
     const exportPrefix = exported ? 'export ' : '';
     if (!hasProperties(schema)) {
@@ -697,7 +602,7 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
         const propSchema = schema.properties[key];
         preamble.push(`type ${subName} = ${typeName}[${JSON.stringify(key)}];`);
         preamble.push(generateShapeValidator(propSchema, subName, useRefImports, suffix, false, stripUnknown));
-        preamble.push(generateObjectParser(propSchema, subName, useRefImports, suffix, logWarnings, strict, false, stripUnknown));
+        preamble.push(generateObjectParser(propSchema, subName, useRefImports, suffix, logWarnings, strict, false, stripUnknown, rootSchema));
     }
     // additionalProperties: false — the per-key "is this undeclared" test inlines
     // `!==` comparisons for a short key list and hoists a Set only for a long one
@@ -995,7 +900,12 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
         lines.push(...varDeclLines);
         lines.push(...warnLines);
         // The first assertion line is the `isObject` check, already done above.
-        const assertionLines = generateObjectStrictAssertion(schema, typeName).slice(1);
+        const assertionLines = generateObjectStrictAssertion(schema, typeName, {
+            useRefImports,
+            suffix,
+            stripUnknown,
+            ...(rootSchema !== undefined ? { rootSchema } : {}),
+        }).slice(1);
         if (shallowGuard) {
             // stripUnknown: a well-typed input skips the assertions and goes straight
             // to the strip build (which removes extras and recurses into sub-parsers).
@@ -1436,6 +1346,7 @@ const selectParserStrategy = (schema, typeName, options) => {
         return generateNonObjectParser(typeName, schema, strict, {
             useRefImports,
             suffix,
+            stripUnknown,
             ...(options?.rootSchema !== undefined ? { rootSchema: options.rootSchema } : {}),
         });
     }
@@ -1450,7 +1361,7 @@ const selectParserStrategy = (schema, typeName, options) => {
     // properties AND conditional keywords use all declared properties rather than
     // only the if/then fragment.
     if (hasProperties(schema)) {
-        return generateObjectParser(schema, typeName, useRefImports, suffix, logWarnings, strict, true, stripUnknown);
+        return generateObjectParser(schema, typeName, useRefImports, suffix, logWarnings, strict, true, stripUnknown, options?.rootSchema);
     }
     // Handle conditional schemas (if/then/else) for schemas without explicit properties.
     if (isSchemaObject(schema) && 'if' in schema && 'then' in schema && 'else' in schema) {
@@ -1467,6 +1378,7 @@ const selectParserStrategy = (schema, typeName, options) => {
         return generateNonObjectParser(typeName, schema, strict, {
             useRefImports,
             suffix,
+            stripUnknown,
             ...(options?.rootSchema !== undefined ? { rootSchema: options.rootSchema } : {}),
         });
     }
@@ -1527,6 +1439,31 @@ export const generateShapeValidator = (schema, typeName, useRefImports, suffix =
     const stub = `${exportPrefix}const ${fnName} = (_input: unknown): boolean => false;`;
     if (!isSchemaObject(schema))
         return stub;
+    // An alias definition (a bare `$ref` with no shape of its own) delegates to
+    // the referenced type's validator. Guarded against self-reference.
+    if (useRefImports && hasRef(schema) && !hasProperties(schema)) {
+        const refName = refToName(schema.$ref, suffix);
+        if (refName !== typeName) {
+            return `${exportPrefix}const ${fnName} = (input: unknown): boolean => ${shapeValidatorName(refName)}(input);`;
+        }
+        return stub;
+    }
+    // A pure union definition (file-level oneOf/anyOf without properties) gets a
+    // real membership predicate when every branch is checkable. A recursive
+    // union (e.g. `expr` whose branches $ref `expr` itself) works because the
+    // branch checks call this very validator by name at runtime. Skipped under
+    // stripUnknown: the branch checks carry no known-keys terms, so a `true`
+    // could not guarantee the parser's strip build would be a no-op.
+    if (!hasProperties(schema) && !('patternProperties' in schema) && !('if' in schema) && !stripUnknown) {
+        const branches = getUnionBranches(schema);
+        if (branches) {
+            const check = generateUnionCheck('input', branches, useRefImports, suffix);
+            if (check !== null) {
+                return `${exportPrefix}const ${fnName} = (input: unknown): boolean => ${check};`;
+            }
+        }
+        return stub;
+    }
     if (!hasProperties(schema))
         return stub;
     // Composition / conditional schemas can match in many shapes — bail.

package/dist/generators/generate-strict-assertion.d.ts

@@ -1,4 +1,19 @@
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Context for assertions that reach beyond the property's own schema: union
+ * membership checks may call imported `validate{X}Shape` predicates ($ref
+ * branches), which requires knowing the ref-import mode, the type-name suffix,
+ * and the root document (to prove those validators are real — see
+ * canEnforceUnion). `stripUnknown` disables union enforcement entirely, since
+ * shape validators then treat undeclared keys as a mismatch while the
+ * stripUnknown contract is to drop them.
+ */
+export type StrictAssertionContext = {
+    readonly useRefImports?: boolean;
+    readonly suffix?: string;
+    readonly rootSchema?: Record<string, unknown>;
+    readonly stripUnknown?: boolean;
+};
 /**
  * Generates strict-mode assertions for the body of an object parser.
  * Throws on:
@@ -10,7 +25,7 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
  * Properties with a `$ref` are validated by the nested parser's own strict
  * check when that parser is invoked downstream.
  */
-export declare const generateObjectStrictAssertion: (schema: JSONSchema, typeName: string) => string[];
+export declare const generateObjectStrictAssertion: (schema: JSONSchema, typeName: string, context?: StrictAssertionContext) => string[];
 /**
  * Generates a single strict-mode assertion line for a non-object scalar parser.
  * Returns null when the schema has no type information to assert on.

package/dist/generators/generate-strict-assertion.js

@@ -2,7 +2,10 @@ import { escapeRegexPattern } from '@amritk/helpers/escape-regex-pattern';
 import { getMjstInstanceOf, getMjstPrimitive } from '@amritk/helpers/mjst-extension';
 import { multipleOfFailExpr } from '@amritk/helpers/multiple-of-check';
 import { safeAccessor } from '@amritk/helpers/safe-accessor';
-import { hasEnum, hasExclusiveMaximum, hasExclusiveMinimum, hasMaxItems, hasMaximum, hasMaxLength, hasMinItems, hasMinimum, hasMinLength, hasMultipleOf, hasPattern, hasProperties, hasRef, hasRequired, hasType, hasUniqueItems, isSchemaObject, } from '@amritk/helpers/schema-guards';
+import { hasEnum, hasExclusiveMaximum, hasExclusiveMinimum, hasItems, hasMaxItems, hasMaximum, hasMaxLength, hasMinItems, hasMinimum, hasMinLength, hasMultipleOf, hasPattern, hasProperties, hasRef, hasRequired, hasType, hasUniqueItems, isSchemaObject, } from '@amritk/helpers/schema-guards';
+import { generateEnumCheck } from './generate-enum-check.js';
+import { canEnforceUnion, generateUnionCheck, getUnionBranches } from './generate-type-checks.js';
+import { scalarItemTypeCheck } from './generate-validation-expression.js';
 /**
  * Returns the inline condition that is true when `accessor` is the wrong type
  * for the given JSON Schema primitive type.
@@ -94,15 +97,41 @@ const generateConstraintChecks = (acc, propSchema, typeName, key) => {
             // a plain `new Set` would only catch primitive duplicates, not equal objects.
             lines.push(`  if (Array.isArray(${acc}) && new Set(${acc}.map((_u) => JSON.stringify(_u))).size !== ${acc}.length) ${throwError(`${field} must NOT have duplicate items`)};`);
         }
+        // Item types: the fast path proves them via `.every`, but this slow path
+        // used to check only length/uniqueness, letting e.g. a number slip into a
+        // declared `string[]`. Enforce scalar and enum item schemas here; richer
+        // item schemas ($refs, objects) are validated by their own parsers.
+        const itemCheck = generateItemCheck(propSchema);
+        if (itemCheck) {
+            lines.push(`  if (Array.isArray(${acc}) && !${acc}.every((_it) => ${itemCheck.check})) ${throwError(`${field} ${itemCheck.message}`)};`);
+        }
     }
     return lines;
 };
+/**
+ * Boolean per-item check (bound to `_it`) for an array schema's `items`, with
+ * the error-message fragment describing what was expected. Only scalar types
+ * and enums are checked — returns null for anything richer.
+ */
+const generateItemCheck = (schema) => {
+    if (!isSchemaObject(schema) || !hasItems(schema) || Array.isArray(schema.items))
+        return null;
+    const items = schema.items;
+    if (isSchemaObject(items) && hasEnum(items) && items.enum.length > 0) {
+        const label = items.enum.map((v) => JSON.stringify(v)).join(', ');
+        return { check: generateEnumCheck('_it', items.enum), message: `items must be one of: ${label}` };
+    }
+    const scalarCheck = scalarItemTypeCheck(items, '_it');
+    if (scalarCheck === null || !isSchemaObject(items) || !hasType(items))
+        return null;
+    return { check: scalarCheck, message: `items expected ${typeLabel(items.type)}` };
+};
 /**
  * Generates strict-mode lines for a single property of an object schema.
  * Properties with a `$ref` are skipped here — the nested parser handles its own
  * strict check when called from the parent's slow path.
  */
-const generatePropertyAssertion = (key, propSchema, isRequired, typeName) => {
+const generatePropertyAssertion = (key, propSchema, isRequired, typeName, context = {}) => {
     const acc = safeAccessor('input', key);
     const field = `[${typeName}] field '${key}'`;
     const lines = [];
@@ -113,6 +142,21 @@ const generatePropertyAssertion = (key, propSchema, isRequired, typeName) => {
         return lines;
     if (hasRef(propSchema))
         return lines;
+    // Union properties: enforce membership when every branch check is
+    // false-sound (canEnforceUnion), so a value matching no variant throws
+    // instead of passing through untyped. Left unenforced (pass-through, the
+    // historical behavior) when any branch is too complex to check safely.
+    const unionBranches = getUnionBranches(propSchema);
+    if (unionBranches) {
+        if (!context.stripUnknown && canEnforceUnion(unionBranches, context.rootSchema)) {
+            const check = generateUnionCheck(acc, unionBranches, context.useRefImports ?? false, context.suffix ?? '');
+            if (check !== null) {
+                const failure = throwError(`${field} does not match any allowed variant`);
+                lines.push(isRequired ? `  if (!(${check})) ${failure};` : `  if (${acc} !== undefined && !(${check})) ${failure};`);
+            }
+        }
+        return lines;
+    }
     const instanceOf = getMjstInstanceOf(propSchema);
     if (instanceOf) {
         if (isRequired) {
@@ -171,14 +215,14 @@ const generatePropertyAssertion = (key, propSchema, isRequired, typeName) => {
  * Properties with a `$ref` are validated by the nested parser's own strict
  * check when that parser is invoked downstream.
  */
-export const generateObjectStrictAssertion = (schema, typeName) => {
+export const generateObjectStrictAssertion = (schema, typeName, context = {}) => {
     const lines = [];
     lines.push(`  if (!isObject(input)) ${throwError(`[${typeName}] expected object, got `, 'input === null ? "null" : typeof input')};`);
     if (!hasProperties(schema) || !isSchemaObject(schema))
         return lines;
     const required = new Set(hasRequired(schema) ? schema.required : []);
     for (const [key, propSchema] of Object.entries(schema.properties)) {
-        lines.push(...generatePropertyAssertion(key, propSchema, required.has(key), typeName));
+        lines.push(...generatePropertyAssertion(key, propSchema, required.has(key), typeName, context));
     }
     return lines;
 };
@@ -202,5 +246,14 @@ export const generateScalarStrictAssertion = (schema, typeName) => {
     const wrongType = wrongTypeCondition('input', t);
     if (!wrongType)
         return null;
-    return `  if (${wrongType}) ${throwError(`[${typeName}] expected ${typeLabel(t)}, got `, got)};`;
+    const lines = [`  if (${wrongType}) ${throwError(`[${typeName}] expected ${typeLabel(t)}, got `, got)};`];
+    // Root-level arrays enforce scalar/enum item types too — the same gap the
+    // property path closes in generateConstraintChecks.
+    if (t === 'array') {
+        const itemCheck = generateItemCheck(schema);
+        if (itemCheck) {
+            lines.push(`  if (!(input as readonly unknown[]).every((_it) => ${itemCheck.check})) ${throwError(`[${typeName}] ${itemCheck.message}`)};`);
+        }
+    }
+    return lines.join('\n');
 };

package/dist/generators/generate-type-checks.d.ts

@@ -0,0 +1,65 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Boolean type-check expression builders shared by the shape validators, the
+ * parsers' fast paths, and the strict-mode assertions. They live in their own
+ * module (rather than generate-parser-function) so generate-strict-assertion
+ * can use them without an import cycle.
+ *
+ * Every expression built here is *true-sound*: when it evaluates to true the
+ * value definitely matches the schema fragment. That is all a fast path needs.
+ * The reverse direction — false definitely means invalid — only holds when
+ * {@link canEnforceUnion} approves the schema, because a check may call an
+ * imported `validate{X}Shape` that was generated as a conservative `=> false`
+ * stub. Strict-mode code that *throws* on a false check must gate on it.
+ */
+/**
+ * Returns the shape-predicate function name for a given type name.
+ * The predicate is generated alongside each parser and tells callers
+ * whether `input` is already in the shape produced by the parser's fast path.
+ */
+export declare const shapeValidatorName: (typeName: string) => string;
+/**
+ * Extracts the branch list of a `oneOf`/`anyOf` union, or `null` when the
+ * schema is not a union (or mixes in other composition keywords we cannot
+ * turn into a membership check).
+ */
+export declare const getUnionBranches: (schema: JSONSchema) => readonly JSONSchema[] | null;
+/**
+ * Generates a fast-path type check expression for a property.
+ * Returns null if the schema is too complex for a simple type check.
+ *
+ * When `useRefImports` is true, $ref properties (and arrays of $refs) are
+ * checked by calling the imported shape predicate, allowing parent parsers
+ * to fast-path through nested ref types without recursing into their parsers.
+ */
+export declare const generatePropertyTypeCheck: (varName: string, schema: JSONSchema, useRefImports: boolean, suffix: string) => string | null;
+/**
+ * Generates a boolean check that `varName` matches an inline object schema —
+ * `isObject` plus a per-property check for every declared property (and a
+ * presence check for `required` keys without a declared schema). Used for
+ * union branches written inline, where no named shape validator exists to
+ * call. Returns null when any property is too complex to check.
+ */
+export declare const generateInlineObjectCheck: (varName: string, schema: JSONSchema, useRefImports: boolean, suffix: string) => string | null;
+/**
+ * Generates a union membership check: true when `varName` matches at least one
+ * branch of a `oneOf`/`anyOf`. Inline object branches get a per-property check;
+ * everything else goes through {@link generatePropertyTypeCheck} ($refs call
+ * the imported shape validator, consts/enums/scalars check directly). Returns
+ * null when any branch cannot be checked.
+ */
+export declare const generateUnionCheck: (varName: string, branches: readonly JSONSchema[], useRefImports: boolean, suffix: string) => string | null;
+/**
+ * True when the union membership check emitted by {@link generateUnionCheck}
+ * is also *false-sound* — a false result definitely means the value is invalid
+ * — so strict mode may throw on it.
+ *
+ * The risk is `$ref`s: a branch (or a property inside one) whose check calls
+ * an imported `validate{X}Shape` is only trustworthy when that validator was
+ * generated as a real predicate. This walks every reachable ref (mirroring
+ * generateShapeValidator's stub conditions) and rejects the union when any of
+ * them would have produced the conservative `=> false` stub, or is itself
+ * built on one. Cycles (e.g. a recursive `expr` union) are assumed sound —
+ * the recursion bottoms out on the data, not the schema.
+ */
+export declare const canEnforceUnion: (branches: readonly JSONSchema[], rootSchema: Record<string, unknown> | undefined) => boolean;

package/dist/generators/generate-type-checks.js

@@ -0,0 +1,370 @@
+import { escapeRegexPattern } from '@amritk/helpers/escape-regex-pattern';
+import { multipleOfPassExpr } from '@amritk/helpers/multiple-of-check';
+import { refToName } from '@amritk/helpers/ref-to-name';
+import { resolveRef } from '@amritk/helpers/resolve-ref';
+import { safeAccessor } from '@amritk/helpers/safe-accessor';
+import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasEnum, hasExclusiveMaximum, hasExclusiveMinimum, hasItems, hasMaxItems, hasMaximum, hasMaxLength, hasMinItems, hasMinimum, hasMinLength, hasMultipleOf, hasOneOf, hasPattern, hasProperties, hasRef, hasType, hasUniqueItems, isObjectSchema, isSchemaObject, } from '@amritk/helpers/schema-guards';
+import { generateEnumCheck } from './generate-enum-check.js';
+import { scalarItemTypeCheck } from './generate-validation-expression.js';
+/**
+ * Boolean type-check expression builders shared by the shape validators, the
+ * parsers' fast paths, and the strict-mode assertions. They live in their own
+ * module (rather than generate-parser-function) so generate-strict-assertion
+ * can use them without an import cycle.
+ *
+ * Every expression built here is *true-sound*: when it evaluates to true the
+ * value definitely matches the schema fragment. That is all a fast path needs.
+ * The reverse direction — false definitely means invalid — only holds when
+ * {@link canEnforceUnion} approves the schema, because a check may call an
+ * imported `validate{X}Shape` that was generated as a conservative `=> false`
+ * stub. Strict-mode code that *throws* on a false check must gate on it.
+ */
+/**
+ * Returns the shape-predicate function name for a given type name.
+ * The predicate is generated alongside each parser and tells callers
+ * whether `input` is already in the shape produced by the parser's fast path.
+ */
+export const shapeValidatorName = (typeName) => `validate${typeName}Shape`;
+/**
+ * Extracts the branch list of a `oneOf`/`anyOf` union, or `null` when the
+ * schema is not a union (or mixes in other composition keywords we cannot
+ * turn into a membership check).
+ */
+export const getUnionBranches = (schema) => {
+    if (!isSchemaObject(schema))
+        return null;
+    if (hasAllOf(schema) || 'not' in schema)
+        return null;
+    if (hasOneOf(schema) && schema.oneOf.length > 0)
+        return schema.oneOf;
+    if (hasAnyOf(schema) && schema.anyOf.length > 0)
+        return schema.anyOf;
+    return null;
+};
+/**
+ * Generates a fast-path type check expression for a property.
+ * Returns null if the schema is too complex for a simple type check.
+ *
+ * When `useRefImports` is true, $ref properties (and arrays of $refs) are
+ * checked by calling the imported shape predicate, allowing parent parsers
+ * to fast-path through nested ref types without recursing into their parsers.
+ */
+export const generatePropertyTypeCheck = (varName, schema, useRefImports, suffix) => {
+    if (!isSchemaObject(schema))
+        return null;
+    // $ref via shape predicate (deep fast-path through nested types).
+    if (useRefImports && hasRef(schema)) {
+        const refName = refToName(schema.$ref, suffix);
+        return `${shapeValidatorName(refName)}(${varName})`;
+    }
+    if (hasRef(schema))
+        return null;
+    // A fixed member set is directly predicable regardless of `type` — this is
+    // what lets a nested object carrying an enum property (e.g. `axiom.kind`)
+    // keep a real shape validator instead of the `=> false` stub.
+    if (hasEnum(schema)) {
+        return schema.enum.length > 0 ? generateEnumCheck(varName, schema.enum) : null;
+    }
+    // A union property is predicable when every branch is: membership is the
+    // disjunction of the branch checks.
+    const branches = getUnionBranches(schema);
+    if (branches) {
+        return generateUnionCheck(varName, branches, useRefImports, suffix);
+    }
+    // Remaining composition (allOf, not, or a union mixed with them) cannot be
+    // expressed as a simple boolean check.
+    if (hasOneOf(schema) || hasAnyOf(schema) || hasAllOf(schema) || 'not' in schema) {
+        return null;
+    }
+    // A `const` property (the usual discriminated-union tag, e.g. `kind: "lit"`) has
+    // no `type`, but is fast-path predicable via strict equality. Handling it here is
+    // what lets a discriminated branch's shape validator be a real predicate instead
+    // of the `=> false` stub. Structural consts need deep equality, so skip those.
+    if (hasConst(schema)) {
+        const c = schema.const;
+        return c === null || typeof c !== 'object' ? `${varName} === ${JSON.stringify(c)}` : null;
+    }
+    if (!hasType(schema))
+        return null;
+    // Array of $refs: each item must satisfy the imported shape predicate.
+    if (useRefImports &&
+        schema.type === 'array' &&
+        hasItems(schema) &&
+        isSchemaObject(schema.items) &&
+        hasRef(schema.items)) {
+        const refName = refToName(schema.items.$ref, suffix);
+        return `Array.isArray(${varName}) && ${varName}.every(${shapeValidatorName(refName)})`;
+    }
+    const checks = [];
+    switch (schema.type) {
+        case 'string': {
+            checks.push(`typeof ${varName} === "string"`);
+            if (hasPattern(schema))
+                checks.push(`/${escapeRegexPattern(schema.pattern)}/.test(${varName})`);
+            if (hasMinLength(schema))
+                checks.push(`${varName}.length >= ${schema.minLength}`);
+            if (hasMaxLength(schema))
+                checks.push(`${varName}.length <= ${schema.maxLength}`);
+            break;
+        }
+        case 'number':
+        case 'integer': {
+            checks.push(`typeof ${varName} === "number"`);
+            // `integer` must reject non-integral numbers on the fast path too, otherwise
+            // `1.5` would pass through uncoerced.
+            if (schema.type === 'integer')
+                checks.push(`Number.isInteger(${varName})`);
+            if (hasMinimum(schema))
+                checks.push(`${varName} >= ${schema.minimum}`);
+            if (hasMaximum(schema))
+                checks.push(`${varName} <= ${schema.maximum}`);
+            if (hasExclusiveMinimum(schema))
+                checks.push(`${varName} > ${schema.exclusiveMinimum}`);
+            if (hasExclusiveMaximum(schema))
+                checks.push(`${varName} < ${schema.exclusiveMaximum}`);
+            if (hasMultipleOf(schema))
+                checks.push(multipleOfPassExpr(varName, schema.multipleOf));
+            break;
+        }
+        case 'boolean':
+            checks.push(`typeof ${varName} === "boolean"`);
+            break;
+        case 'array': {
+            checks.push(`Array.isArray(${varName})`);
+            if (hasMinItems(schema))
+                checks.push(`${varName}.length >= ${schema.minItems}`);
+            if (hasMaxItems(schema))
+                checks.push(`${varName}.length <= ${schema.maxItems}`);
+            if (hasUniqueItems(schema) && schema.uniqueItems === true) {
+                checks.push(`new Set(${varName}).size === ${varName}.length`);
+            }
+            // For a scalar or enum item type, every element must already be well-typed
+            // to take the fast path; a mismatched element routes the array to the slow
+            // path where each element is coerced (or, in strict mode, throws).
+            if (hasItems(schema) && !Array.isArray(schema.items)) {
+                const items = schema.items;
+                const itemCheck = scalarItemTypeCheck(items, '_it') ??
+                    (isSchemaObject(items) && hasEnum(items) && items.enum.length > 0
+                        ? generateEnumCheck('_it', items.enum)
+                        : null);
+                if (itemCheck)
+                    checks.push(`${varName}.every((_it) => ${itemCheck})`);
+            }
+            break;
+        }
+        case 'object':
+            checks.push(`isObject(${varName})`);
+            break;
+        default:
+            return null;
+    }
+    if (checks.length === 0)
+        return null;
+    // checks[0] is safe: we guard with checks.length === 0 above
+    let result = checks[0];
+    for (let i = 1; i < checks.length; i++) {
+        result += ' && ' + checks[i];
+    }
+    return result;
+};
+/**
+ * Generates a boolean check that `varName` matches an inline object schema —
+ * `isObject` plus a per-property check for every declared property (and a
+ * presence check for `required` keys without a declared schema). Used for
+ * union branches written inline, where no named shape validator exists to
+ * call. Returns null when any property is too complex to check.
+ */
+export const generateInlineObjectCheck = (varName, schema, useRefImports, suffix) => {
+    if (!isSchemaObject(schema) || !isObjectSchema(schema) || !hasProperties(schema))
+        return null;
+    if (hasAllOf(schema) || hasOneOf(schema) || hasAnyOf(schema) || 'not' in schema)
+        return null;
+    if ('patternProperties' in schema || 'if' in schema)
+        return null;
+    // additionalProperties-as-schema (records) would leave the record values
+    // unchecked, breaking the "true means valid" guarantee.
+    if (hasAdditionalProperties(schema) && typeof schema.additionalProperties !== 'boolean')
+        return null;
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const checks = [`isObject(${varName})`];
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+        const acc = safeAccessor(varName, key);
+        const check = generatePropertyTypeCheck(acc, propSchema, useRefImports, suffix);
+        if (check === null)
+            return null;
+        checks.push(required.has(key) ? check : `(${acc} === undefined || ${check})`);
+        required.delete(key);
+    }
+    // `required` keys without a declared property schema still need a presence check.
+    for (const key of required) {
+        checks.push(`${JSON.stringify(key)} in ${varName}`);
+    }
+    // additionalProperties: false — extras make the value invalid for this branch.
+    if (hasAdditionalProperties(schema) && schema.additionalProperties === false) {
+        const allowedKeys = JSON.stringify(Object.keys(schema.properties));
+        checks.push(`Object.keys(${varName}).every((_k) => ${allowedKeys}.includes(_k))`);
+    }
+    return checks.join(' && ');
+};
+/**
+ * Generates a union membership check: true when `varName` matches at least one
+ * branch of a `oneOf`/`anyOf`. Inline object branches get a per-property check;
+ * everything else goes through {@link generatePropertyTypeCheck} ($refs call
+ * the imported shape validator, consts/enums/scalars check directly). Returns
+ * null when any branch cannot be checked.
+ */
+export const generateUnionCheck = (varName, branches, useRefImports, suffix) => {
+    if (branches.length === 0)
+        return null;
+    const parts = [];
+    for (const branch of branches) {
+        if (!isSchemaObject(branch))
+            return null;
+        const check = isObjectSchema(branch) && hasProperties(branch) && !hasRef(branch)
+            ? generateInlineObjectCheck(varName, branch, useRefImports, suffix)
+            : generatePropertyTypeCheck(varName, branch, useRefImports, suffix);
+        if (check === null)
+            return null;
+        parts.push(`(${check})`);
+    }
+    // Callers conjoin this with other checks, so a multi-branch disjunction must
+    // carry its own parentheses — `a || b && c` binds the wrong way without them.
+    return parts.length === 1 ? parts[0] : `(${parts.join(' || ')})`;
+};
+/**
+ * True when the union membership check emitted by {@link generateUnionCheck}
+ * is also *false-sound* — a false result definitely means the value is invalid
+ * — so strict mode may throw on it.
+ *
+ * The risk is `$ref`s: a branch (or a property inside one) whose check calls
+ * an imported `validate{X}Shape` is only trustworthy when that validator was
+ * generated as a real predicate. This walks every reachable ref (mirroring
+ * generateShapeValidator's stub conditions) and rejects the union when any of
+ * them would have produced the conservative `=> false` stub, or is itself
+ * built on one. Cycles (e.g. a recursive `expr` union) are assumed sound —
+ * the recursion bottoms out on the data, not the schema.
+ */
+export const canEnforceUnion = (branches, rootSchema) => {
+    const visiting = new Set();
+    return (branches.length > 0 &&
+        branches.every((branch) => {
+            if (!isSchemaObject(branch))
+                return false;
+            return isObjectSchema(branch) && hasProperties(branch) && !hasRef(branch)
+                ? canTrustInlineObjectCheck(branch, rootSchema, visiting)
+                : canTrustPropertyCheck(branch, rootSchema, visiting);
+        }));
+};
+/** Mirrors {@link generatePropertyTypeCheck}: non-null AND every embedded validator call is real. */
+const canTrustPropertyCheck = (schema, rootSchema, visiting) => {
+    if (!isSchemaObject(schema))
+        return false;
+    if (hasRef(schema)) {
+        return canTrustReferencedValidator(schema.$ref, rootSchema, visiting);
+    }
+    if (hasEnum(schema))
+        return schema.enum.length > 0;
+    const branches = getUnionBranches(schema);
+    if (branches) {
+        return branches.every((branch) => {
+            if (!isSchemaObject(branch))
+                return false;
+            return isObjectSchema(branch) && hasProperties(branch) && !hasRef(branch)
+                ? canTrustInlineObjectCheck(branch, rootSchema, visiting)
+                : canTrustPropertyCheck(branch, rootSchema, visiting);
+        });
+    }
+    if (hasOneOf(schema) || hasAnyOf(schema) || hasAllOf(schema) || 'not' in schema)
+        return false;
+    if (hasConst(schema))
+        return schema.const === null || typeof schema.const !== 'object';
+    if (!hasType(schema))
+        return false;
+    if (schema.type === 'array' && hasItems(schema) && isSchemaObject(schema.items) && hasRef(schema.items)) {
+        return canTrustReferencedValidator(schema.items.$ref, rootSchema, visiting);
+    }
+    switch (schema.type) {
+        case 'string':
+        case 'number':
+        case 'integer':
+        case 'boolean':
+        case 'array':
+        case 'object':
+            return true;
+        default:
+            return false;
+    }
+};
+/** Mirrors {@link generateInlineObjectCheck}: non-null AND every property check is trustworthy. */
+const canTrustInlineObjectCheck = (schema, rootSchema, visiting) => {
+    if (!isSchemaObject(schema) || !isObjectSchema(schema) || !hasProperties(schema))
+        return false;
+    if (hasAllOf(schema) || hasOneOf(schema) || hasAnyOf(schema) || 'not' in schema)
+        return false;
+    if ('patternProperties' in schema || 'if' in schema)
+        return false;
+    if (hasAdditionalProperties(schema) && typeof schema.additionalProperties !== 'boolean')
+        return false;
+    return Object.values(schema.properties).every((propSchema) => canTrustPropertyCheck(propSchema, rootSchema, visiting));
+};
+/**
+ * True when the file generated for `ref`'s target carries a *real* (non-stub)
+ * shape validator whose result can be trusted in both directions. Mirrors the
+ * schema classes generateShapeValidator (and its new union/alias paths) turns
+ * into real predicates, recursing into every reachable ref.
+ */
+const canTrustReferencedValidator = (ref, rootSchema, visiting) => {
+    if (visiting.has(ref))
+        return true;
+    if (!rootSchema)
+        return false;
+    const resolved = resolveRef(ref, rootSchema);
+    if (!resolved || !isSchemaObject(resolved))
+        return false;
+    visiting.add(ref);
+    try {
+        // Alias definition (bare $ref): its validator delegates to the target's.
+        if (hasRef(resolved) && !hasProperties(resolved)) {
+            return canTrustReferencedValidator(resolved.$ref, rootSchema, visiting);
+        }
+        // Pure union definition: real when the membership check is enforceable.
+        if (!hasProperties(resolved)) {
+            const branches = getUnionBranches(resolved);
+            if (!branches)
+                return false;
+            if ('patternProperties' in resolved || 'if' in resolved)
+                return false;
+            return branches.every((branch) => {
+                if (!isSchemaObject(branch))
+                    return false;
+                return isObjectSchema(branch) && hasProperties(branch) && !hasRef(branch)
+                    ? canTrustInlineObjectCheck(branch, rootSchema, visiting)
+                    : canTrustPropertyCheck(branch, rootSchema, visiting);
+            });
+        }
+        // Object definition: real when generateShapeValidator emits a predicate —
+        // no composition/conditional keywords, and every property check resolves.
+        if (hasOneOf(resolved) ||
+            hasAnyOf(resolved) ||
+            hasAllOf(resolved) ||
+            'not' in resolved ||
+            'patternProperties' in resolved ||
+            'if' in resolved ||
+            'then' in resolved ||
+            'else' in resolved) {
+            return false;
+        }
+        return Object.values(resolved.properties).every((propSchema) => {
+            // Records of refs make generateShapeValidator bail to the stub.
+            if (isSchemaObject(propSchema) &&
+                hasAdditionalProperties(propSchema) &&
+                typeof propSchema.additionalProperties !== 'boolean') {
+                return false;
+            }
+            return canTrustPropertyCheck(propSchema, rootSchema, visiting);
+        });
+    }
+    finally {
+        visiting.delete(ref);
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/generate-parsers",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "module": "./dist/index.js",
   "type": "module",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "json-schema-typed": "^8.0.1",
-    "@amritk/helpers": "0.10.2",
+    "@amritk/helpers": "0.10.3",
     "@amritk/generate-markdown": "0.4.1"
   },
   "devDependencies": {