@amritk/generate-parsers 0.13.0 → 0.15.0

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.15.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.12.0",
     "@amritk/generate-markdown": "0.4.1"
   },
   "devDependencies": {