@amritk/generate-parsers 0.13.0 → 0.15.0

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

@@ -1,15 +1,16 @@
 import { escapeRegexPattern } from '@amritk/helpers/escape-regex-pattern';
+import { quoteJsString } from '@amritk/helpers/quote-js-string';
 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, hasItems, hasOneOf, hasProperties, hasRef, hasType, isObjectSchema, isSchemaObject, } from '@amritk/helpers/schema-guards';
+import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasEnum, hasItems, hasOneOf, hasProperties, hasRef, hasRequired, 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';
+import { canEnforceUnion, generatePropertyTypeCheck, generateUnionCheck, getUnionBranches, isInlineObjectArrayProperty, isInlineObjectProperty, shapeValidatorName, } from './generate-type-checks.js';
+import { generateValidationExpression, isCoercibleItemSchema } from './generate-validation-expression.js';
 /**
  * Generates the parser function name from a type name.
  * Converts "UserObject" to "parseUserObject".
@@ -350,7 +351,7 @@ const generateRefUnionDispatch = (functionName, typeName, branches, strict, ctx)
     // first branch's parser, preserving the coercing parser's lenient contract while
     // still running real validation/coercion instead of a blind cast.
     const fallback = strict
-        ? `(() => { throw new Error(${JSON.stringify(`[${typeName}] value does not match any union branch`)}); })()`
+        ? `(() => { throw new Error(${quoteJsString(`[${typeName}] value does not match any union branch`)}); })()`
         : `${cases[0]?.parser}(input)`;
     let expr = fallback;
     for (let i = cases.length - 1; i >= 0; i--) {
@@ -394,7 +395,7 @@ const generateNonObjectParser = (typeName, schema, strict, unionCtx) => {
         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};`;
+                return `export const ${functionName} = (input: unknown): ${typeName} => {\n  if (!(${check})) throw new Error(${quoteJsString(`[${typeName}] value does not match any union branch`)});\n  return input as ${typeName};\n};`;
             }
         }
     }
@@ -437,6 +438,50 @@ const generateNonObjectParser = (typeName, schema, strict, unionCtx) => {
             return `export const ${functionName} = (input: unknown): ${typeName} => input as ${typeName};`;
         }
     }
+    // Root-level arrays with rich item schemas delegate every element to a real
+    // parser, so nested enums and $refs inside array items are validated instead
+    // of spread through unchecked. $ref items call the imported parser; inline
+    // object items get a private item sub-parser in the same file. (Scalar and
+    // enum items are covered below: the lax switch coerces them element-wise and
+    // generateScalarStrictAssertion enforces them in strict mode.)
+    if (isSchemaObject(schema) &&
+        hasType(schema) &&
+        schema.type === 'array' &&
+        hasItems(schema) &&
+        !Array.isArray(schema.items)) {
+        const items = schema.items;
+        const notArrayThrow = `if (!Array.isArray(input)) throw new Error(\`[${typeName}] expected array, got \${input === null ? "null" : typeof input}\`);`;
+        // validateArray identity-returns the input array when every element parses
+        // to itself; this parser is EXPORTED, and exported parsers never alias the
+        // value the caller passed in (matching the scalar root-array path's
+        // `[...input]` copy), so materialize a copy exactly when that happens —
+        // element references are still shared, like every other fast path.
+        const delegatedBody = (itemParserName) => `  const _parsed = validateArray(input, ${itemParserName});\n  return (_parsed === input ? [..._parsed] : _parsed) as ${typeName};`;
+        const delegated = (itemParserName) => strict
+            ? `export const ${functionName} = (input: unknown): ${typeName} => {\n  ${notArrayThrow}\n${delegatedBody(itemParserName)}\n};`
+            : `export const ${functionName} = (input: unknown): ${typeName} => {\n${delegatedBody(itemParserName)}\n};`;
+        if (unionCtx?.useRefImports && isSchemaObject(items) && hasRef(items)) {
+            return delegated(generateParserName(refToName(items.$ref, unionCtx.suffix)));
+        }
+        if (isInlineObjectProperty(items)) {
+            const reserved = unionCtx?.reservedNames ?? NO_RESERVED_NAMES;
+            // Dedup against imported identifiers: a root `List` whose items carry a
+            // $ref to `#/$defs/listItem` imports parseListItem — a bare `ListItem`
+            // here would shadow it (TS2440) and self-recurse instead of delegating.
+            let itemName = `${typeName}_Item`;
+            while (reserved.has(itemName))
+                itemName = `${itemName}_`;
+            const useRefImports = unionCtx?.useRefImports ?? false;
+            const suffix = unionCtx?.suffix ?? '';
+            const stripUnknown = unionCtx?.stripUnknown ?? false;
+            const preamble = [
+                `type ${itemName} = ${typeName}[number];`,
+                generateShapeValidator(items, itemName, useRefImports, suffix, false, stripUnknown, reserved),
+                generateObjectParser(items, itemName, useRefImports, suffix, unionCtx?.logWarnings ?? false, strict, false, stripUnknown, unionCtx?.rootSchema, reserved),
+            ].join('\n\n');
+            return `${preamble}\n\n${delegated(generateParserName(itemName))}`;
+        }
+    }
     if (!isSchemaObject(schema) || !hasType(schema)) {
         // Schema without type information cannot be validated beyond a cast
         return `export const ${functionName} = (input: unknown): ${typeName} => input as ${typeName};`;
@@ -463,8 +508,8 @@ const generateNonObjectParser = (typeName, schema, strict, unionCtx) => {
         case 'boolean':
             return `export const ${functionName} = (input: unknown): ${typeName} => typeof input === "boolean" ? input as ${typeName} : false as ${typeName};`;
         case 'array': {
-            // Coerce each element when the item schema is a single scalar type.
-            if (hasItems(schema) && !Array.isArray(schema.items) && scalarItemTypeCheck(schema.items, '_it') !== null) {
+            // Coerce each element when the item schema is a single scalar type or an enum.
+            if (hasItems(schema) && !Array.isArray(schema.items) && isCoercibleItemSchema(schema.items)) {
                 const item = schema.items;
                 const itemExpr = generateValidationExpression('', item, getDefaultValue(item), true, undefined, undefined, '_it', true);
                 return `export const ${functionName} = (input: unknown): ${typeName} => Array.isArray(input) ? (input as unknown[]).map((_it) => ${itemExpr}) as ${typeName} : [] as ${typeName};`;
@@ -495,56 +540,55 @@ const toVarName = (key) => {
     const safe = key.replace(/[^a-zA-Z0-9_$]/g, '_');
     return `_${safe}`;
 };
+/** PascalCases a property key for use in a synthesized sub-type name. */
+const pascalCaseKey = (key) => key
+    .replace(/[^a-zA-Z0-9_$]/g, '_')
+    .split('_')
+    .filter((part) => part.length > 0)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+/** Shared empty reserved-name set for callers with no import context. */
+const NO_RESERVED_NAMES = new Set();
 /**
- * Matches an inline nested object property — an object schema written directly
- * under `properties` with its own `properties`, rather than referenced via
- * `$ref`. These get a private sub-parser (and shape predicate) in the same
- * generated file so their fields are actually parsed; anything involving
- * composition, conditionals, enums, or record semantics keeps the existing
- * code paths.
- */
-const isInlineObjectProperty = (propSchema) => {
-    if (!isSchemaObject(propSchema))
-        return false;
-    if (hasRef(propSchema) || hasEnum(propSchema) || hasConst(propSchema))
-        return false;
-    if (hasOneOf(propSchema) || hasAnyOf(propSchema) || hasAllOf(propSchema))
-        return false;
-    if ('patternProperties' in propSchema || 'not' in propSchema || 'if' in propSchema)
-        return false;
-    // additionalProperties-as-schema records go through the record paths instead
-    if (hasAdditionalProperties(propSchema) && typeof propSchema.additionalProperties !== 'boolean')
-        return false;
-    return isObjectSchema(propSchema) && hasProperties(propSchema);
-};
-/**
- * Builds the property-key → synthesized-type-name map for every inline nested
- * object property of a schema, e.g. parent `Order` + key `shipTo` →
- * `OrderShipTo`. Both the parser and the shape validator derive the map
- * independently, so the naming (including collision suffixes) is a pure
- * function of the schema and parent type name.
+ * Shared empty result for the common no-inline-sub-types case, so the per-node
+ * calls (parser and validator, for every object node, on every generation)
+ * allocate nothing. Callers only read from the maps.
  */
-const collectInlineObjectProperties = (schema, typeName) => {
-    const subTypeNames = new Map();
+const EMPTY_SUB_TYPES = { objects: new Map(), arrayItems: new Map() };
+const collectInlineSubTypes = (schema, typeName, reservedNames = NO_RESERVED_NAMES) => {
     if (!hasProperties(schema))
-        return subTypeNames;
-    const used = new Set();
-    for (const [key, propSchema] of Object.entries(schema.properties)) {
-        if (!isInlineObjectProperty(propSchema))
-            continue;
-        const pascal = key
-            .replace(/[^a-zA-Z0-9_$]/g, '_')
-            .split('_')
-            .filter((part) => part.length > 0)
-            .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-            .join('');
-        let subName = `${typeName}${pascal || 'Value'}`;
-        while (used.has(subName))
+        return EMPTY_SUB_TYPES;
+    const props = schema.properties;
+    // Single pass with lazy allocation: most object nodes have neither inline
+    // object properties nor inline-object array items, and this runs for every
+    // node in both the parser and the validator — so nothing is allocated until
+    // the first match, and the classification predicates run exactly once per
+    // property (an eager pre-scan would re-evaluate them for matching schemas).
+    let objects = null;
+    let arrayItems = null;
+    let used = null;
+    const claim = (base) => {
+        used ??= new Set();
+        let subName = base;
+        while (used.has(subName) || reservedNames.has(subName))
             subName = `${subName}_`;
         used.add(subName);
-        subTypeNames.set(key, subName);
+        return subName;
+    };
+    for (const key in props) {
+        const propSchema = props[key];
+        if (isInlineObjectProperty(propSchema)) {
+            objects ??= new Map();
+            objects.set(key, claim(`${typeName}_${pascalCaseKey(key) || 'Value'}`));
+        }
+        else if (isInlineObjectArrayProperty(propSchema)) {
+            arrayItems ??= new Map();
+            arrayItems.set(key, claim(`${typeName}_${pascalCaseKey(key) || 'Value'}Item`));
+        }
     }
-    return subTypeNames;
+    if (objects === null && arrayItems === null)
+        return EMPTY_SUB_TYPES;
+    return { objects: objects ?? EMPTY_SUB_TYPES.objects, arrayItems: arrayItems ?? EMPTY_SUB_TYPES.arrayItems };
 };
 /**
  * True when the parser must reject (strict mode) or strip (coerce mode) every
@@ -562,6 +606,44 @@ const hasStrictKeys = (schema) => {
         return false;
     return true;
 };
+/**
+ * When every declared property is required (and every required key is
+ * declared, with a real schema), the fast-path known-keys test can be an
+ * own-key *count* comparison instead of a per-key `for..in` walk: the typed
+ * property checks already prove all N declared keys are present, so
+ * `Object.keys(input).length === N` proves there are no undeclared extras —
+ * measurably cheaper on the hot path. Returns the declared-key count, or null
+ * when the cheaper form would be unsound (an optional or non-schema property
+ * breaks the presence proof).
+ */
+const exactKeyCountOf = (schema) => {
+    if (!isSchemaObject(schema) || !hasProperties(schema) || !hasRequired(schema))
+        return null;
+    const props = schema.properties;
+    const required = schema.required;
+    // Allocation-free for the common small object: this runs for every object
+    // node, in both the parser and the validator, on every generation, and the
+    // O(n²) `includes` beats building a Set for a handful of keys. Wide schemas
+    // (generated API models) flip to a one-time Set so a 200-property object
+    // doesn't pay ~20k string comparisons per node.
+    const requiredLookup = required.length > 16 ? new Set(required) : null;
+    let declaredCount = 0;
+    for (const key in props) {
+        declaredCount++;
+        // Every declared key must be required, and its check must prove presence —
+        // all schema-object checks fail on undefined, but a true/false schema
+        // literal emits no check at all.
+        const isRequired = requiredLookup !== null ? requiredLookup.has(key) : required.includes(key);
+        if (!isRequired || !isSchemaObject(props[key]))
+            return null;
+    }
+    // Every declared key is required (above) and the counts match, so the
+    // required list is exactly the declared keys (a duplicated required entry
+    // would leave some declared key uncovered and fail the loop).
+    if (declaredCount === 0 || required.length !== declaredCount)
+        return null;
+    return declaredCount;
+};
 /**
  * Determines if a property needs a local variable or can be inlined.
  * Schema-object properties are always cached: the slow-path ternary chain
@@ -582,7 +664,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, rootSchema) => {
+const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnings, strict, exported = true, stripUnknown = false, rootSchema, reservedNames = NO_RESERVED_NAMES) => {
     const functionName = generateParserName(typeName);
     const exportPrefix = exported ? 'export ' : '';
     if (!hasProperties(schema)) {
@@ -591,18 +673,35 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
         }
         return `${exportPrefix}const ${functionName} = (input: unknown): ${typeName} => isObject(input) ? input as ${typeName} : {} as ${typeName};`;
     }
-    const properties = Object.entries(schema.properties);
+    const schemaProps = schema.properties;
+    // Keys once, values via lookup — Object.entries allocates a tuple per
+    // property and this runs for every object node on every generation.
+    const propertyKeys = Object.keys(schemaProps);
     // Inline nested object properties get a private sub-parser (plus shape
     // predicate and type alias) in the same file, so their fields are parsed for
     // real instead of only passing an isObject check. The sub-parser recurses
-    // through this same generator, so nesting works to any depth.
-    const subTypeNames = collectInlineObjectProperties(schema, typeName);
+    // through this same generator, so nesting works to any depth. Array
+    // properties with inline object items get the same treatment for their
+    // element type, so nested enums and $refs *inside array items* are validated
+    // too (each element runs through the item sub-parser via validateArray).
+    const { objects: subTypeNames, arrayItems: subItemNames } = collectInlineSubTypes(schema, typeName, reservedNames);
     const preamble = [];
     for (const [key, subName] of subTypeNames) {
-        const propSchema = schema.properties[key];
+        const propSchema = schemaProps[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, rootSchema));
+        preamble.push(generateShapeValidator(propSchema, subName, useRefImports, suffix, false, stripUnknown, reservedNames));
+        preamble.push(generateObjectParser(propSchema, subName, useRefImports, suffix, logWarnings, strict, false, stripUnknown, rootSchema, reservedNames));
+    }
+    for (const [key, subName] of subItemNames) {
+        const propSchema = schemaProps[key];
+        const itemSchema = propSchema.items;
+        // NonNullable strips the `| undefined` an optional array property carries.
+        preamble.push(`type ${subName} = NonNullable<${typeName}[${JSON.stringify(key)}]>[number];`);
+        preamble.push(generateShapeValidator(itemSchema, subName, useRefImports, suffix, false, stripUnknown, reservedNames));
+        // Hand-rolled loop instead of Array.prototype.every on the guard path — the
+        // callback protocol costs a few percent on element-heavy hot paths.
+        preamble.push(`const _every${subName} = (arr: readonly unknown[]): boolean => {\n  for (let i = 0; i < arr.length; i++) if (!${shapeValidatorName(subName)}(arr[i])) return false;\n  return true;\n};`);
+        preamble.push(generateObjectParser(itemSchema, subName, useRefImports, suffix, logWarnings, strict, false, stripUnknown, rootSchema, reservedNames));
     }
     // 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
@@ -615,13 +714,25 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
     // `strictKeys` makes an extra a hard error (the throw block further down).
     const strictKeys = hasStrictKeys(schema);
     const stripKeys = strictKeys || stripUnknown;
-    const strictKeyCheck = unknownKeyCheck(properties.map(([key]) => key), `_knownKeys${typeName}`);
-    if (stripKeys) {
+    // When every declared property is required, the fast-path no-extras test is
+    // the cheaper own-key count (see exactKeyCountOf) and the `_hasOnlyKnownKeys`
+    // predicate is not emitted at all — the shape validator derives the same
+    // decision from the schema, so the cross-function contract stays in sync.
+    const exactKeyCount = stripKeys ? exactKeyCountOf(schema) : null;
+    const strictKeyCheck = unknownKeyCheck(propertyKeys, `_knownKeys${typeName}`);
+    if (stripKeys && exactKeyCount === null) {
         for (const declaration of strictKeyCheck.declarations) {
             preamble.push(`${declaration};`);
         }
         preamble.push(`const _hasOnlyKnownKeys${typeName} = (input: Record<string, unknown>): boolean => {\n  for (const _k in input) if (${strictKeyCheck.isUnknown('_k')}) return false;\n  return true;\n};`);
     }
+    else if (strict && strictKeys) {
+        // The unknown-key throw loop below still needs the hoisted Set (when the
+        // key list is long enough to use one).
+        for (const declaration of strictKeyCheck.declarations) {
+            preamble.push(`${declaration};`);
+        }
+    }
     const fallbackObject = generateFallbackObject(schema, useRefImports, typeName, suffix, subTypeNames);
     // First pass: gather per-property info and decide whether a fast path is
     // possible. A fast path returns the input (or a direct strip-build) for
@@ -641,7 +752,8 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
     // declarations (TS2451). Dedupe by suffixing `_` until unique — the same
     // approach `collectInlineObjectProperties` uses — so each key gets its own var.
     const usedVarNames = new Set();
-    for (const [key, propSchema] of properties) {
+    for (const key of propertyKeys) {
+        const propSchema = schemaProps[key];
         const isRequired = isPropertyRequired(key, schema);
         let varName = toVarName(key);
         while (usedVarNames.has(varName))
@@ -658,10 +770,15 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
         }
         const subName = subTypeNames.get(key);
         // Inline nested objects fast-path through their private shape predicate, the
-        // same way $ref properties use the imported one.
-        const check = subName
+        // same way $ref properties use the imported one. Arrays of inline objects
+        // additionally prove every element via the private item predicate.
+        let check = subName
             ? `${shapeValidatorName(subName)}(${varName})`
             : generatePropertyTypeCheck(varName, propSchema, useRefImports, suffix);
+        const itemSubName = subItemNames.get(key);
+        if (check !== null && itemSubName) {
+            check = `${check} && _every${itemSubName}(${varName})`;
+        }
         if (check === null) {
             canFastPath = false;
         }
@@ -676,9 +793,16 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
     // fire on inputs that carry no undeclared key. For strict + additionalProperties:
     // false the cold path rejects extras instead; folding the known-keys term into
     // the guard lets the guard run *before* that rejection, so a valid clean input
-    // never pays for the per-property assertions.
+    // never pays for the per-property assertions. With every declared property
+    // required, the own-key count is equivalent and cheaper than the per-key walk —
+    // but only for plain objects: a crafted prototype could satisfy the typed
+    // checks through inherited properties while the own-key count still matches,
+    // so non-plain inputs route to the slow path, where the for..in walk keeps
+    // the historical inherited-key rejection.
     if (stripKeys) {
-        fastPathChecks.push(`_hasOnlyKnownKeys${typeName}(input)`);
+        fastPathChecks.push(exactKeyCount !== null
+            ? `Object.getPrototypeOf(input) === Object.prototype && Object.keys(input).length === ${exactKeyCount}`
+            : `_hasOnlyKnownKeys${typeName}(input)`);
     }
     // The deep guard proves the whole shape (so `{ ...input }` can be returned),
     // using the nested shape predicates and the known-keys term above.
@@ -784,6 +908,21 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
                 }
                 continue;
             }
+            // Arrays of inline objects run every element through the private item
+            // sub-parser, the same way arrays of $refs delegate via validateArray.
+            // In strict mode the item parser throws on a bad element; in coerce mode
+            // it repairs the element to a valid instance.
+            const itemSubName = subItemNames.get(key);
+            if (itemSubName) {
+                const itemParserName = generateParserName(itemSubName);
+                if (isRequired) {
+                    objectLines.push(`    ${safeKey(key)}: validateArray(${accessor}, ${itemParserName}),`);
+                }
+                else {
+                    objectLines.push(`    ...(${accessor} !== undefined && { ${safeKey(key)}: validateArray(${accessor}, ${itemParserName}) }),`);
+                }
+                continue;
+            }
             // Handle direct $ref properties via imported parsers
             if (shouldUseRefImport(propSchema, useRefImports)) {
                 const ref = propSchema.$ref;
@@ -872,6 +1011,18 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
             lines.push(`  if (${deepGuard}) return { ...input } as ${typeName};`);
             return;
         }
+        // A *private* (nested-object / array-item) parser whose deep guard proved
+        // the input is exactly the declared shape — typed checks plus the
+        // no-undeclared-keys term, recursively via sub-predicates — can hand the
+        // input back by reference instead of allocating a literal. That is the
+        // same sharing the parent's own fast-path literal performs (`items:
+        // _items`), and it is what keeps clean array elements allocation-free.
+        // Exported root parsers keep returning a fresh object so callers never
+        // alias the value they passed in.
+        if (!exported) {
+            lines.push(`  if (${deepGuard}) return input as ${typeName};`);
+            return;
+        }
         const fields = [];
         for (const { key, varName, isRequired, propSchema } of propInfo) {
             if (!isSchemaObject(propSchema)) {
@@ -907,13 +1058,45 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
             ...(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).
-            lines.push(`  if (!(${shallowGuard})) {`);
-            for (const assertionLine of assertionLines) {
-                lines.push(`  ${assertionLine}`);
+            // A private sub-parser hands input that is already exactly the declared
+            // shape (no extras at any level) back by reference, so a clean array
+            // element or nested object costs no allocation. The deep guard is
+            // evaluated as the shallow guard plus only its *residual* terms (deeper
+            // per-property checks and the no-extras term), so a carries-extras input
+            // never runs the same typed checks twice before taking the strip build.
+            if (!exported && deepGuard) {
+                const residual = [];
+                for (let i = 0; i < fastPathChecks.length; i++) {
+                    const deep = fastPathChecks[i];
+                    const shallow = shallowChecks[i];
+                    if (deep === shallow)
+                        continue;
+                    // When the deep check extends the shallow one by conjunction (e.g.
+                    // `Array.isArray(_x) && _everyItem(_x)`), the shallow guard already
+                    // proved the prefix — re-evaluating it per clean parse was pure
+                    // waste on the hot path, so only the extension joins the residual.
+                    residual.push(shallow !== undefined && deep.startsWith(`${shallow} && `) ? deep.slice(shallow.length + 4) : deep);
+                }
+                lines.push(`  if (${shallowGuard}) {`);
+                lines.push(residual.length > 0
+                    ? `    if (${residual.join(' && ')}) return input as ${typeName};`
+                    : `    return input as ${typeName};`);
+                lines.push(`  } else {`);
+                for (const assertionLine of assertionLines) {
+                    lines.push(`  ${assertionLine}`);
+                }
+                lines.push(`  }`);
+            }
+            else {
+                // stripUnknown: a well-typed input skips the assertions and goes
+                // straight to the strip build (which removes extras and recurses into
+                // sub-parsers).
+                lines.push(`  if (!(${shallowGuard})) {`);
+                for (const assertionLine of assertionLines) {
+                    lines.push(`  ${assertionLine}`);
+                }
+                lines.push(`  }`);
             }
-            lines.push(`  }`);
             emitReturn(lines, buildObjectLines(true));
         }
         else {
@@ -924,6 +1107,13 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
                 lines.push(assertionLine);
             }
             if (strictKeys) {
+                // for..in (not Object.keys) deliberately: this loop is cold — the fast
+                // path already proved the key set — but swapping in the keys-array
+                // iterator here once regressed the *hot* path several percent on CI:
+                // the extra dead-path bytecode changed the engine's inlining of the
+                // whole parser. The fast-path no-extras test uses own-key semantics;
+                // an inherited-key mismatch merely lands here and keeps the historical
+                // for..in rejection.
                 lines.push(`  for (const _k in input) {`);
                 lines.push(`    if (${strictKeyCheck.isUnknown('_k')}) throw new Error(\`[${typeName}] unknown property "\${_k}"\`);`);
                 lines.push(`  }`);
@@ -1335,8 +1525,12 @@ const selectParserStrategy = (schema, typeName, options) => {
     const stripUnknown = options?.stripUnknown ?? false;
     const suffix = options?.typeSuffix ?? '';
     // Special case for the self-referential JSON Schema meta-schema type (e.g.
-    // `Schema` / `SchemaObject`) - it can be any JSON Schema.
-    if (typeName === `Schema${suffix}`) {
+    // `Schema` / `SchemaObject`) - it can be any JSON Schema. This is an OpenAPI
+    // heuristic for a `$defs`/`components.schemas` entry named `schema`; it must
+    // never fire for the root document, whose name is user-derived (a `schema.json`
+    // file naturally yields the root type `Schema`) and would otherwise collapse
+    // to a validation-free pass-through parser.
+    if (!options?.isRoot && typeName === `Schema${suffix}`) {
         return generateSchemaObjectParser(typeName);
     }
     const isObjectLikeSchema = isObjectSchema(schema) ||
@@ -1347,7 +1541,9 @@ const selectParserStrategy = (schema, typeName, options) => {
             useRefImports,
             suffix,
             stripUnknown,
+            logWarnings,
             ...(options?.rootSchema !== undefined ? { rootSchema: options.rootSchema } : {}),
+            ...(options?.reservedNames !== undefined ? { reservedNames: options.reservedNames } : {}),
         });
     }
     // Handle schemas with both properties AND patternProperties.
@@ -1361,7 +1557,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, options?.rootSchema);
+        return generateObjectParser(schema, typeName, useRefImports, suffix, logWarnings, strict, true, stripUnknown, options?.rootSchema, options?.reservedNames);
     }
     // Handle conditional schemas (if/then/else) for schemas without explicit properties.
     if (isSchemaObject(schema) && 'if' in schema && 'then' in schema && 'else' in schema) {
@@ -1379,7 +1575,9 @@ const selectParserStrategy = (schema, typeName, options) => {
             useRefImports,
             suffix,
             stripUnknown,
+            logWarnings,
             ...(options?.rootSchema !== undefined ? { rootSchema: options.rootSchema } : {}),
+            ...(options?.reservedNames !== undefined ? { reservedNames: options.reservedNames } : {}),
         });
     }
     // Handle schemas with patternProperties (but no properties)
@@ -1433,7 +1631,7 @@ export const shapeValidatorFunctionName = (typeName) => shapeValidatorName(typeN
  * in additionalProperties). The stub is safe: parents calling it will fall
  * through to the slow path, matching the pre-deep-fast-path behavior.
  */
-export const generateShapeValidator = (schema, typeName, useRefImports, suffix = '', exported = true, stripUnknown = false) => {
+export const generateShapeValidator = (schema, typeName, useRefImports, suffix = '', exported = true, stripUnknown = false, reservedNames = NO_RESERVED_NAMES) => {
     const fnName = shapeValidatorName(typeName);
     const exportPrefix = exported ? 'export ' : '';
     const stub = `${exportPrefix}const ${fnName} = (_input: unknown): boolean => false;`;
@@ -1477,18 +1675,26 @@ export const generateShapeValidator = (schema, typeName, useRefImports, suffix =
         'else' in schema) {
         return stub;
     }
-    const properties = Object.entries(schema.properties);
+    const schemaProps = schema.properties;
+    const propertyKeys = Object.keys(schemaProps);
     // Same deterministic naming as the parser's sub-parser generation, so the
     // referenced private shape predicates exist in the same file.
-    const subTypeNames = collectInlineObjectProperties(schema, typeName);
+    const { objects: subTypeNames, arrayItems: subItemNames } = collectInlineSubTypes(schema, typeName, reservedNames);
     // When the parser strips extras (additionalProperties: false or stripUnknown),
     // an input carrying an undeclared key is *not* fast-path eligible — the parser
     // would strip it rather than return `{ ...input }` — so the shape only matches
-    // when every key is declared. (The `_hasOnlyKnownKeys` predicate this calls is
-    // emitted by the parser under the same `stripKeys` condition.)
-    const strictKeysGuard = hasStrictKeys(schema) || stripUnknown ? `\n  if (!_hasOnlyKnownKeys${typeName}(input)) return false;` : '';
+    // when every key is declared. With every declared property required, the
+    // no-extras test is the cheaper own-key count appended after the typed checks
+    // (which prove all N keys present); otherwise it is the `_hasOnlyKnownKeys`
+    // walk the parser emits under the same `stripKeys` condition.
+    const validatorStripKeys = hasStrictKeys(schema) || stripUnknown;
+    const validatorKeyCount = validatorStripKeys ? exactKeyCountOf(schema) : null;
+    const strictKeysGuard = validatorStripKeys && validatorKeyCount === null
+        ? `\n  if (!_hasOnlyKnownKeys${typeName}(input)) return false;`
+        : '';
     const checks = [];
-    for (const [key, propSchema] of properties) {
+    for (const key of propertyKeys) {
+        const propSchema = schemaProps[key];
         // Records of refs require iterating every value — too expensive for the fast path.
         if (shouldUseRecordRefImport(propSchema, useRefImports)) {
             return stub;
@@ -1496,9 +1702,16 @@ export const generateShapeValidator = (schema, typeName, useRefImports, suffix =
         const accessor = safeAccessor('input', key);
         const isRequired = isPropertyRequired(key, schema);
         const subName = subTypeNames.get(key);
-        const check = subName
+        let check = subName
             ? `${shapeValidatorName(subName)}(${accessor})`
             : generatePropertyTypeCheck(accessor, propSchema, useRefImports, suffix);
+        // Arrays of inline objects prove every element via the private item loop
+        // helper (emitted alongside the item sub-parser), matching the parser's
+        // fast-path guard.
+        const itemSubName = subItemNames.get(key);
+        if (check !== null && itemSubName) {
+            check = `${check} && _every${itemSubName}(${accessor})`;
+        }
         if (check === null) {
             return stub;
         }
@@ -1509,6 +1722,14 @@ export const generateShapeValidator = (schema, typeName, useRefImports, suffix =
             checks.push(`(${accessor} === undefined || ${check})`);
         }
     }
+    // The count form is sound only in conjunction with the typed checks above
+    // (they prove every declared key present) and only for plain objects (a
+    // crafted prototype could satisfy those checks through inherited
+    // properties), so it joins the chain last, prototype-guarded like the
+    // parser's own fast path.
+    if (validatorKeyCount !== null) {
+        checks.push(`Object.getPrototypeOf(input) === Object.prototype && Object.keys(input).length === ${validatorKeyCount}`);
+    }
     if (checks.length === 0) {
         if (strictKeysGuard) {
             return `${exportPrefix}const ${fnName} = (input: unknown): boolean => {

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

@@ -1,6 +1,7 @@
 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 { quoteJsString } from '@amritk/helpers/quote-js-string';
 import { safeAccessor } from '@amritk/helpers/safe-accessor';
 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';
@@ -21,6 +22,11 @@ const wrongTypeCondition = (accessor, type) => {
             return `(typeof ${accessor} !== "number" || !Number.isInteger(${accessor}))`;
         case 'boolean':
             return `typeof ${accessor} !== "boolean"`;
+        case 'null':
+            // Missing from this switch historically, which meant a null-typed
+            // property was never enforced on the assertion path — the strict-mode
+            // differential fuzzer caught non-null values sailing through.
+            return `${accessor} !== null`;
         case 'array':
             return `!Array.isArray(${accessor})`;
         case 'object':
@@ -36,14 +42,13 @@ const wrongTypeCondition = (accessor, type) => {
 const typeLabel = (type) => (type === 'integer' ? 'number' : type);
 /**
  * Emits `throw new Error(<message>[ + <suffixExpr>])`. The static message may
- * contain schema-controlled text (property names, patterns, enum values), so it
- * is always serialized with `JSON.stringify` — a key like `it's` or a pattern
- * containing a quote or newline can no longer break out of the string literal or
- * inject code. `suffixExpr`, when given, is a runtime expression appended to the
- * message (e.g. `typeof input`).
+ * contain schema-controlled text (property names, patterns, enum values), so
+ * it goes through the shared {@link quoteJsString} escape-or-quote decision.
+ * `suffixExpr`, when given, is a runtime expression appended to the message
+ * (e.g. `typeof input`).
  */
 const throwError = (message, suffixExpr) => {
-    const literal = JSON.stringify(message);
+    const literal = quoteJsString(message);
     return suffixExpr ? `throw new Error(${literal} + (${suffixExpr}))` : `throw new Error(${literal})`;
 };
 /**
@@ -221,8 +226,9 @@ export const generateObjectStrictAssertion = (schema, typeName, context = {}) =>
     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, context));
+    const props = schema.properties;
+    for (const key in props) {
+        lines.push(...generatePropertyAssertion(key, props[key], required.has(key), typeName, context));
     }
     return lines;
 };