@amritk/generate-parsers 0.13.0 → 0.14.0

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

@@ -1,5 +1,6 @@
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
 import type { HelpersMode } from '../helpers/collect-helpers.js';
+import type { ImportExtension } from '../helpers/collect-imports.js';
 import type { SchemaExtensions } from '../types/schema-extensions.js';
 /**
  * Represents a generated file with its filename and content.
@@ -45,6 +46,10 @@ export type GeneratedFile = {
  * @param typeSuffix - Suffix appended to every type/parser name derived from a `$ref`
  *   (e.g. `'Object'` → `ContactObject`). Defaults to `''` (no suffix). The root type name
  *   is used verbatim and is not affected by this suffix.
+ * @param importExt - Extension used on every relative import specifier in the generated
+ *   output (cross-file `$ref` imports, the index barrel, and embedded-helper imports).
+ *   `'js'` (default) is the standard TS NodeNext form; `'ts'` emits the literal on-disk
+ *   paths so the generated sources run directly under Node's type stripping.
  * @returns An array of generated TypeScript files
  *
  * @example
@@ -77,4 +82,4 @@ export type GeneratedFile = {
  * });
  * ```
  */
-export declare const buildSchema: (rootSchema: JSONSchema, rootTypeName: string, extensions?: SchemaExtensions, typesOnly?: boolean, logWarnings?: boolean, strict?: boolean, helpersMode?: HelpersMode, helpersImportPrefix?: string, readonly?: boolean, stripUnknown?: boolean, typeSuffix?: string) => Promise<GeneratedFile[]>;
+export declare const buildSchema: (rootSchema: JSONSchema, rootTypeName: string, extensions?: SchemaExtensions, typesOnly?: boolean, logWarnings?: boolean, strict?: boolean, helpersMode?: HelpersMode, helpersImportPrefix?: string, readonly?: boolean, stripUnknown?: boolean, typeSuffix?: string, importExt?: ImportExtension) => Promise<GeneratedFile[]>;

package/dist/generators/build-schema.js

@@ -16,7 +16,7 @@ import { generateFile } from './generate-files.js';
  * 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 readHelperSource = async (helper, importExt) => {
     const require = createRequire(import.meta.url);
     const helpersRoot = dirname(require.resolve('@amritk/helpers/package.json'));
     try {
@@ -31,10 +31,17 @@ const readHelperSource = async (helper) => {
         // 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'") };
+        return { ext: 'ts', content: source.replace(/\bfrom '(\.\/[^'".]+)'/g, `from '$1.${importExt}'`) };
     }
     catch {
         const compiled = await readFile(resolvePath(helpersRoot, 'dist', `${helper}.js`), 'utf-8');
+        // With `.ts` import specifiers the on-disk file must literally be `.ts`, so
+        // ship the compiled JS (valid TS) under that name and retarget its own
+        // sibling imports to match. The pattern keeps the same `\bfrom` shape as
+        // above so tsc-alias's scanner can't corrupt it (see the comment there).
+        if (importExt === 'ts') {
+            return { ext: 'ts', content: compiled.replace(/\bfrom '(\.\/[^'"]+)\.js'/g, "from '$1.ts'") };
+        }
         return { ext: 'js', content: compiled };
     }
 };
@@ -75,6 +82,10 @@ const readHelperSource = async (helper) => {
  * @param typeSuffix - Suffix appended to every type/parser name derived from a `$ref`
  *   (e.g. `'Object'` → `ContactObject`). Defaults to `''` (no suffix). The root type name
  *   is used verbatim and is not affected by this suffix.
+ * @param importExt - Extension used on every relative import specifier in the generated
+ *   output (cross-file `$ref` imports, the index barrel, and embedded-helper imports).
+ *   `'js'` (default) is the standard TS NodeNext form; `'ts'` emits the literal on-disk
+ *   paths so the generated sources run directly under Node's type stripping.
  * @returns An array of generated TypeScript files
  *
  * @example
@@ -107,7 +118,7 @@ const readHelperSource = async (helper) => {
  * });
  * ```
  */
-export const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = 'package', helpersImportPrefix = './', readonly = false, stripUnknown = false, typeSuffix = '') => {
+export const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = 'package', helpersImportPrefix = './', readonly = false, stripUnknown = false, typeSuffix = '', importExt = 'js') => {
     const files = [];
     const usedHelpers = new Set();
     walkRefGraph(rootSchema, rootTypeName, { typeSuffix }, (node) => {
@@ -125,6 +136,7 @@ export const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnl
             helpersImportPrefix,
             readonly,
             typeSuffix,
+            importExt,
             ...(node.ref !== undefined ? { selfRef: node.ref } : {}),
             ...(logWarnings !== undefined ? { logWarnings } : {}),
             ...(strict !== undefined ? { strict } : {}),
@@ -139,10 +151,13 @@ 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 { ext, content } = await readHelperSource(helper);
+            const { ext, content } = await readHelperSource(helper, importExt);
             files.push({ filename: `_helpers/${helper}.${ext}`, content });
         }
     }
-    files.push({ filename: 'index.ts', content: generateIndexBarrel(files, { typesOnly: typesOnly ?? false }) });
+    files.push({
+        filename: 'index.ts',
+        content: generateIndexBarrel(files, { typesOnly: typesOnly ?? false, importExt }),
+    });
     return files;
 };

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

@@ -1,5 +1,6 @@
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
 import { type HelpersMode, type RuntimeHelperName } from '../helpers/collect-helpers.js';
+import { type ImportExtension } from '../helpers/collect-imports.js';
 /**
  * Options for controlling what gets generated in a file.
  */
@@ -63,6 +64,13 @@ type GenerateFileOptions = {
      * Defaults to `''` (no suffix). Set to e.g. `'Object'` to emit `ContactObject`.
      */
     readonly typeSuffix?: string;
+    /**
+     * Extension used on every relative import specifier (cross-file `$ref`
+     * imports and embedded-helper imports). Defaults to `'js'` (the TS NodeNext
+     * form); `'ts'` makes the generated sources runnable under Node's type
+     * stripping.
+     */
+    readonly importExt?: ImportExtension;
 };
 /** Result of generating a single parser file. */
 export type GeneratedFileContent = {

package/dist/generators/generate-files.js

@@ -1,6 +1,6 @@
 import { generateTypeDefinition } from '@amritk/helpers/generate-type-definition';
 import { collectHelpers, } from '../helpers/collect-helpers.js';
-import { collectImports } from '../helpers/collect-imports.js';
+import { collectImports, collectImportTypeNames } from '../helpers/collect-imports.js';
 import { generateParserFunction, generateShapeValidator } from './generate-parser-function.js';
 /**
  * Generates a complete TypeScript file from a JSON Schema.
@@ -37,10 +37,11 @@ export const generateFile = (schema, typeName, options) => {
     const rootSchema = options?.rootSchema;
     const helpersMode = options?.helpersMode ?? 'package';
     const typeSuffix = options?.typeSuffix ?? '';
+    const importExt = options?.importExt ?? 'js';
     const typeDefinition = generateTypeDefinition(schema, typeName, { readonly: options?.readonly ?? false, typeSuffix });
     if (typesOnly) {
         // In types-only mode, skip the parser function and use type-only imports
-        const imports = collectImports(schema, { typesOnly: true, selfRef, rootSchema, typeSuffix });
+        const imports = collectImports(schema, { typesOnly: true, selfRef, rootSchema, typeSuffix, importExt });
         let result = '';
         if (imports.length > 0) {
             result += imports[0];
@@ -52,18 +53,24 @@ export const generateFile = (schema, typeName, options) => {
         return { content: result + typeDefinition, usedHelpers: new Set() };
     }
     const stripUnknown = options?.stripUnknown ?? false;
+    // Names this file imports for its $refs: synthesized private sub-type names
+    // dedup against them so they can never shadow an imported identifier. The
+    // parser and the shape validator must receive the SAME set — their derived
+    // sub-names have to agree.
+    const reservedNames = collectImportTypeNames(schema, { selfRef, rootSchema, typeSuffix });
     const parserFunction = generateParserFunction(schema, typeName, {
         useRefImports: true,
         typeSuffix,
+        reservedNames,
         ...(rootSchema !== undefined ? { rootSchema } : {}),
         ...(options?.logWarnings !== undefined ? { logWarnings: options.logWarnings } : {}),
         ...(options?.strict !== undefined ? { strict: options.strict } : {}),
         ...(options?.stripUnknown !== undefined ? { stripUnknown: options.stripUnknown } : {}),
     });
-    const shapeValidator = generateShapeValidator(schema, typeName, true, typeSuffix, true, stripUnknown);
+    const shapeValidator = generateShapeValidator(schema, typeName, true, typeSuffix, true, stripUnknown, reservedNames);
     const combinedFunctions = `${shapeValidator}\n\n${parserFunction}`;
-    const helpers = collectHelpers(combinedFunctions, helpersMode, options?.helpersImportPrefix);
-    const imports = [...collectImports(schema, { selfRef, rootSchema, typeSuffix }), ...helpers.imports];
+    const helpers = collectHelpers(combinedFunctions, helpersMode, options?.helpersImportPrefix, importExt);
+    const imports = [...collectImports(schema, { selfRef, rootSchema, typeSuffix, importExt }), ...helpers.imports];
     // Build file output using string concatenation instead of array join for performance
     let result = '';
     if (imports.length > 0) {

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

@@ -42,6 +42,14 @@ type GenerateParserOptions = {
      * dispatch to the branch parsers, instead of falling back to a passthrough cast.
      */
     readonly rootSchema?: Record<string, unknown>;
+    /**
+     * Type names the generated file imports for its `$ref`s. Synthesized private
+     * sub-type names (nested objects, array items, the root array's `{Type}Item`)
+     * dedup against this set so they can never shadow an imported identifier —
+     * which would both fail to compile (duplicate declaration) and silently
+     * validate against the wrong schema.
+     */
+    readonly reservedNames?: ReadonlySet<string>;
 };
 /**
  * Generates a safe parser as an arrow function that never throws.
@@ -71,5 +79,5 @@ export declare const shapeValidatorFunctionName: (typeName: string) => string;
  * in additionalProperties). The stub is safe: parents calling it will fall
  * through to the slow path, matching the pre-deep-fast-path behavior.
  */
-export declare const generateShapeValidator: (schema: JSONSchema, typeName: string, useRefImports: boolean, suffix?: string, exported?: boolean, stripUnknown?: boolean) => string;
+export declare const generateShapeValidator: (schema: JSONSchema, typeName: string, useRefImports: boolean, suffix?: string, exported?: boolean, stripUnknown?: boolean, reservedNames?: ReadonlySet<string>) => string;
 export {};

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(`  }`);
@@ -1347,7 +1537,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 +1553,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 +1571,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 +1627,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 +1671,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 +1698,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 +1718,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;
 };

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

@@ -18,6 +18,23 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
  * whether `input` is already in the shape produced by the parser's fast path.
  */
 export declare const shapeValidatorName: (typeName: string) => string;
+/**
+ * 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.
+ */
+export declare const isInlineObjectProperty: (propSchema: JSONSchema) => propSchema is JSONSchema.Object;
+/**
+ * Matches an array property whose `items` is an inline object schema — the
+ * array-items analogue of {@link isInlineObjectProperty}. These get a private
+ * item sub-parser (and shape predicate) so element values — including nested
+ * enums and `$ref`s — are actually validated instead of only passing an
+ * `Array.isArray` check.
+ */
+export declare const isInlineObjectArrayProperty: (propSchema: JSONSchema) => boolean;
 /**
  * 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

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

@@ -25,6 +25,51 @@ import { scalarItemTypeCheck } from './generate-validation-expression.js';
  * whether `input` is already in the shape produced by the parser's fast path.
  */
 export 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
+ * `$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.
+ */
+export 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;
+    // `then`/`else` must be excluded even without `if`: generateShapeValidator
+    // stubs any schema carrying them, so admitting one here would wire an
+    // always-false predicate into parent guards — and into validators the
+    // strict-union trust walk treats as false-sound, making a strict union
+    // reject valid input.
+    if ('patternProperties' in propSchema || 'not' in propSchema)
+        return false;
+    if ('if' in propSchema || 'then' in propSchema || 'else' 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);
+};
+/**
+ * Matches an array property whose `items` is an inline object schema — the
+ * array-items analogue of {@link isInlineObjectProperty}. These get a private
+ * item sub-parser (and shape predicate) so element values — including nested
+ * enums and `$ref`s — are actually validated instead of only passing an
+ * `Array.isArray` check.
+ */
+export const isInlineObjectArrayProperty = (propSchema) => {
+    if (!isSchemaObject(propSchema))
+        return false;
+    if (!('type' in propSchema) || propSchema.type !== 'array')
+        return false;
+    if (!hasItems(propSchema) || Array.isArray(propSchema.items))
+        return false;
+    return isInlineObjectProperty(propSchema.items);
+};
 /**
  * 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
@@ -295,6 +340,33 @@ const canTrustPropertyCheck = (schema, rootSchema, visiting) => {
             return false;
     }
 };
+/**
+ * Mirrors the per-property check {@link generateShapeValidator} emits for a
+ * generated file's exported validator, which is *deeper* than
+ * {@link generatePropertyTypeCheck}: inline object properties and arrays of
+ * inline object items are checked through private sub-predicates generated
+ * from the same schema, and a sub-predicate is a conservative `=> false` stub
+ * whenever some nested property check cannot be built. A validator built on a
+ * stub returns false on *valid* input, so trusting it requires every reachable
+ * sub-predicate to be a real check, recursively.
+ */
+const canTrustShapeProperty = (propSchema, rootSchema, visiting) => {
+    if (!isSchemaObject(propSchema))
+        return false;
+    // Record-valued additionalProperties: records of refs stub the validator;
+    // stay conservative for any schema-valued record, matching the historical
+    // bail in canTrustReferencedValidator.
+    if (hasAdditionalProperties(propSchema) && typeof propSchema.additionalProperties !== 'boolean')
+        return false;
+    if (isInlineObjectProperty(propSchema)) {
+        return Object.values(propSchema.properties ?? {}).every((sub) => canTrustShapeProperty(sub, rootSchema, visiting));
+    }
+    if (isInlineObjectArrayProperty(propSchema)) {
+        const items = propSchema.items;
+        return Object.values(items.properties ?? {}).every((sub) => canTrustShapeProperty(sub, rootSchema, visiting));
+    }
+    return canTrustPropertyCheck(propSchema, rootSchema, visiting);
+};
 /** Mirrors {@link generateInlineObjectCheck}: non-null AND every property check is trustworthy. */
 const canTrustInlineObjectCheck = (schema, rootSchema, visiting) => {
     if (!isSchemaObject(schema) || !isObjectSchema(schema) || !hasProperties(schema))
@@ -354,15 +426,11 @@ const canTrustReferencedValidator = (ref, rootSchema, visiting) => {
             '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);
-        });
+        // Walk with the deep shape-validator mirror: the emitted validator routes
+        // inline object properties (and arrays of inline object items) through
+        // private sub-predicates, so trust must recurse the same way instead of
+        // stopping at a shallow isObject/Array.isArray reading.
+        return Object.values(resolved.properties).every((propSchema) => canTrustShapeProperty(propSchema, rootSchema, visiting));
     }
     finally {
         visiting.delete(ref);

package/dist/generators/generate-validation-expression.d.ts

@@ -6,6 +6,13 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
  * objects, arrays, unions, `$ref`s, and anything richer.
  */
 export declare const scalarItemTypeCheck: (itemSchema: JSONSchema, accessor: string) => string | null;
+/**
+ * True when an array's `items` schema can be coerced element-by-element by the
+ * mapping slow path: single scalar types (via {@link scalarItemTypeCheck}) and
+ * enums (whose validation expression coerces a non-member to the first member).
+ * Anything richer (objects, unions, `$ref`s) needs a real item parser instead.
+ */
+export declare const isCoercibleItemSchema: (itemSchema: JSONSchema) => boolean;
 /**
  * Generates a validation expression that checks if a value matches the expected type.
  * Returns the value if valid, coerces to the correct type if invalid, or uses default if required and missing.

package/dist/generators/generate-validation-expression.js

@@ -46,6 +46,17 @@ export const scalarItemTypeCheck = (itemSchema, accessor) => {
             return null;
     }
 };
+/**
+ * True when an array's `items` schema can be coerced element-by-element by the
+ * mapping slow path: single scalar types (via {@link scalarItemTypeCheck}) and
+ * enums (whose validation expression coerces a non-member to the first member).
+ * Anything richer (objects, unions, `$ref`s) needs a real item parser instead.
+ */
+export const isCoercibleItemSchema = (itemSchema) => {
+    if (scalarItemTypeCheck(itemSchema, '_it') !== null)
+        return true;
+    return isSchemaObject(itemSchema) && hasEnum(itemSchema) && itemSchema.enum.length > 0;
+};
 /**
  * A boolean type check for a single JSON Schema primitive type name. Unlike
  * {@link scalarItemTypeCheck} this also covers `array`/`object` (as inline shape
@@ -228,15 +239,16 @@ export const generateValidationExpression = (key, schema, defaultValue, isRequir
     if (!hasType(schema) && !hasEnum(schema)) {
         return `${accessor} ?? ${defaultValue}`;
     }
-    // An array of scalar items: coerce each element so e.g. `number[]` actually
-    // contains numbers. The fast path only takes a well-typed array, so a mistyped
-    // element reaches here. ($ref items use the caller's validateArray path;
-    // object/union items still pass through.)
+    // An array of scalar or enum items: coerce each element so e.g. `number[]`
+    // actually contains numbers and an enum member set holds. The fast path only
+    // takes a well-typed array, so a mistyped element reaches here. ($ref and
+    // inline-object items use the caller's validateArray path; union items still
+    // pass through.)
     if (hasType(schema) &&
         schema.type === 'array' &&
         hasItems(schema) &&
         !Array.isArray(schema.items) &&
-        scalarItemTypeCheck(schema.items, '_it') !== null) {
+        isCoercibleItemSchema(schema.items)) {
         const itemSchema = schema.items;
         const itemExpr = generateValidationExpression('', itemSchema, getDefaultValue(itemSchema), true, rootSchema, visitedRefs, '_it', true);
         const mapped = `(Array.isArray(${accessor}) ? (${accessor} as unknown[]).map((_it) => ${itemExpr}) : ${defaultValue})`;

package/dist/helpers/collect-helpers.d.ts

@@ -12,12 +12,4 @@ export type CollectedHelpers = {
      */
     readonly used: Set<RuntimeHelperName>;
 };
-/**
- * Detects which runtime helpers a generated parser body references.
- *
- * @param helpersImportPrefix - Relative path prefix to the shared `_helpers/`
- *   directory in embedded mode. Defaults to `'./'`. The recursive multi-schema
- *   build passes `'../'`, `'../../'`, etc. so nested parsers can reach a single
- *   `_helpers/` directory at the output root.
- */
-export declare const collectHelpers: (parserFunction: string, mode: HelpersMode, helpersImportPrefix?: string) => CollectedHelpers;
+export declare const collectHelpers: (parserFunction: string, mode: HelpersMode, helpersImportPrefix?: string, importExt?: 'js' | 'ts') => CollectedHelpers;

package/dist/helpers/collect-helpers.js

@@ -11,9 +11,9 @@ const EMBEDDED_NAMED_EXPORTS = {
     'validate-record': 'validateRecord',
     'has-ref': 'hasRef',
 };
-const embeddedImport = (helper, prefix) => 
-// `.js` extension so the embedded-helper import resolves under Node ESM, not only Bun.
-`import { ${EMBEDDED_NAMED_EXPORTS[helper]} } from '${prefix}_helpers/${helper}.js';`;
+const embeddedImport = (helper, prefix, ext) => 
+// An explicit extension so the embedded-helper import resolves under Node ESM, not only Bun.
+`import { ${EMBEDDED_NAMED_EXPORTS[helper]} } from '${prefix}_helpers/${helper}.${ext}';`;
 /**
  * Detects which runtime helpers a generated parser body references.
  *
@@ -21,16 +21,43 @@ const embeddedImport = (helper, prefix) =>
  *   directory in embedded mode. Defaults to `'./'`. The recursive multi-schema
  *   build passes `'../'`, `'../../'`, etc. so nested parsers can reach a single
  *   `_helpers/` directory at the output root.
+ * @param importExt - Extension used on embedded-helper import specifiers.
+ *   Defaults to `'js'` (the TS NodeNext form); `'ts'` makes the output runnable
+ *   under Node's type stripping.
  */
-export const collectHelpers = (parserFunction, mode, helpersImportPrefix = './') => {
+// One alternation pass over the generated source instead of four full-text
+// `.includes` scans — an absent helper name used to cost a complete rescan
+// each, which showed up at several percent of total generation time.
+const HELPER_USAGE = /validateArray|validateRecord|isObject|hasRef\(/g;
+export const collectHelpers = (parserFunction, mode, helpersImportPrefix = './', importExt = 'js') => {
     const imports = [];
     const used = new Set();
-    const importFor = (helper) => mode === 'embedded' ? embeddedImport(helper, helpersImportPrefix) : PACKAGE_IMPORTS[helper];
-    if (parserFunction.includes('validateArray')) {
+    const importFor = (helper) => mode === 'embedded' ? embeddedImport(helper, helpersImportPrefix, importExt) : PACKAGE_IMPORTS[helper];
+    let sawValidateArray = false;
+    let sawValidateRecord = false;
+    let sawIsObject = false;
+    let sawHasRef = false;
+    HELPER_USAGE.lastIndex = 0;
+    let match = HELPER_USAGE.exec(parserFunction);
+    while (match !== null) {
+        const token = match[0];
+        if (token === 'validateArray')
+            sawValidateArray = true;
+        else if (token === 'validateRecord')
+            sawValidateRecord = true;
+        else if (token === 'isObject')
+            sawIsObject = true;
+        else
+            sawHasRef = true;
+        if (sawValidateArray && sawValidateRecord && sawIsObject && sawHasRef)
+            break;
+        match = HELPER_USAGE.exec(parserFunction);
+    }
+    if (sawValidateArray) {
         imports.push(importFor('validate-array'));
         used.add('validate-array');
     }
-    if (parserFunction.includes('validateRecord')) {
+    if (sawValidateRecord) {
         imports.push(importFor('validate-record'));
         used.add('validate-record');
         // The embedded validate-record.ts imports is-object, so it must be shipped too —
@@ -38,11 +65,11 @@ export const collectHelpers = (parserFunction, mode, helpersImportPrefix = './')
         // parser body itself references `isObject` (handled below).
         used.add('is-object');
     }
-    if (parserFunction.includes('isObject')) {
+    if (sawIsObject) {
         imports.push(importFor('is-object'));
         used.add('is-object');
     }
-    if (parserFunction.includes('hasRef(')) {
+    if (sawHasRef) {
         imports.push(importFor('has-ref'));
         used.add('has-ref');
     }

package/dist/helpers/collect-imports.d.ts

@@ -1,4 +1,6 @@
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/** Extension emitted on every relative import specifier in generated code. */
+export type ImportExtension = 'js' | 'ts';
 /**
  * Options for controlling how imports are collected.
  */
@@ -26,6 +28,12 @@ type CollectImportsOptions = {
      * Defaults to `''` (no suffix).
      */
     readonly typeSuffix?: string;
+    /**
+     * Extension used on every relative import specifier. Defaults to `'js'`
+     * (the TS NodeNext form); `'ts'` makes the output runnable under Node's
+     * type stripping.
+     */
+    readonly importExt?: ImportExtension;
 };
 /**
  * Collects all import statements needed for a schema by finding $ref references
@@ -67,4 +75,11 @@ type CollectImportsOptions = {
  * ```
  */
 export declare const collectImports: (schema: JSONSchema, options?: CollectImportsOptions) => string[];
+/**
+ * The type names a generated file will import for its `$ref`s — the same
+ * dedup/skip rules as {@link collectImports}. Generators seed their private
+ * sub-type naming with this set so a synthesized name (e.g. a root array's
+ * `FooItem`) can never shadow an imported identifier.
+ */
+export declare const collectImportTypeNames: (schema: JSONSchema, options?: CollectImportsOptions) => Set<string>;
 export {};

package/dist/helpers/collect-imports.js

@@ -2,11 +2,12 @@ import { refToFilename } from '@amritk/helpers/ref-to-filename';
 import { refToName } from '@amritk/helpers/ref-to-name';
 import { resolveRef } from '@amritk/helpers/resolve-ref';
 import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasItems, hasOneOf, hasRef } from '@amritk/helpers/schema-guards';
-// Emit an explicit `.js` extension on the relative specifier. Node's ESM resolver
-// requires it (extensionless relative imports only work under a bundler or Bun),
-// and `./x.js` pointing at a sibling `x.ts` is the standard TS NodeNext form —
-// accepted by Bun, esbuild, webpack, and tsc alike.
-const getImportPathForFilename = (filename) => `./${filename}.js`;
+// Emit an explicit extension on the relative specifier. Node's ESM resolver
+// requires one (extensionless relative imports only work under a bundler or
+// Bun). `./x.js` pointing at a sibling `x.ts` is the standard TS NodeNext form
+// — accepted by Bun, esbuild, webpack, and tsc alike — while `./x.ts` is the
+// literal on-disk path Node's type stripping needs to run the sources directly.
+const getImportPathForFilename = (filename, ext) => `./${filename}.${ext}`;
 /**
  * Collects all import statements needed for a schema by finding $ref references
  * that are directly used in the type definition (from properties, items, etc.).
@@ -48,6 +49,32 @@ const getImportPathForFilename = (filename) => `./${filename}.js`;
  */
 export const collectImports = (schema, options) => {
     const typesOnly = options?.typesOnly === true;
+    const importExt = options?.importExt ?? 'js';
+    const importMap = new Map();
+    for (const [filename, typeName] of collectImportTargets(schema, options)) {
+        const importPath = getImportPathForFilename(filename, importExt);
+        // In types-only mode, omit the parser function import since there is no parser to call
+        const importStatement = typesOnly
+            ? `import type { ${typeName} } from '${importPath}';`
+            : `import { type ${typeName}, parse${typeName}, validate${typeName}Shape } from '${importPath}';`;
+        importMap.set(filename, importStatement);
+    }
+    return Array.from(importMap.values()).sort();
+};
+/**
+ * The type names a generated file will import for its `$ref`s — the same
+ * dedup/skip rules as {@link collectImports}. Generators seed their private
+ * sub-type naming with this set so a synthesized name (e.g. a root array's
+ * `FooItem`) can never shadow an imported identifier.
+ */
+export const collectImportTypeNames = (schema, options) => {
+    const names = new Set();
+    for (const [, typeName] of collectImportTargets(schema, options))
+        names.add(typeName);
+    return names;
+};
+/** Shared `$ref` walk: filename → derived type name for every import target. */
+const collectImportTargets = (schema, options) => {
     const selfFilename = options?.selfRef ? refToFilename(options.selfRef) : undefined;
     const rootSchema = options?.rootSchema;
     const typeSuffix = options?.typeSuffix;
@@ -194,8 +221,8 @@ export const collectImports = (schema, options) => {
     if (typeof schema === 'object' && schema !== null && 'else' in schema) {
         collectRefsFromValue(schema.else);
     }
-    // Convert refs to combined import statements, deduplicating by filename
-    const importMap = new Map();
+    // Convert refs to import targets, deduplicating by filename.
+    const targets = new Map();
     for (const ref of refs) {
         // For URI refs, skip if the base URI is not resolvable in the root schema.
         // This prevents generating imports for external schemas that were never generated as files.
@@ -209,12 +236,7 @@ export const collectImports = (schema, options) => {
         if (selfFilename !== undefined && filename === selfFilename) {
             continue;
         }
-        const importPath = getImportPathForFilename(filename);
-        // In types-only mode, omit the parser function import since there is no parser to call
-        const importStatement = typesOnly
-            ? `import type { ${typeName} } from '${importPath}';`
-            : `import { type ${typeName}, parse${typeName}, validate${typeName}Shape } from '${importPath}';`;
-        importMap.set(filename, importStatement);
+        targets.set(filename, typeName);
     }
-    return Array.from(importMap.values()).sort();
+    return targets;
 };

package/dist/index.d.ts

@@ -1 +1,2 @@
 export { buildSchema, type GeneratedFile } from './generators/build-schema.js';
+export type { ImportExtension } from './helpers/collect-imports.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/generate-parsers",
-  "version": "0.13.0",
+  "version": "0.14.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.3",
+    "@amritk/helpers": "0.11.0",
     "@amritk/generate-markdown": "0.4.1"
   },
   "devDependencies": {