@amritk/generate-parsers 0.12.3 → 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,15 +16,32 @@ 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 {
         const source = await readFile(resolvePath(helpersRoot, 'src', `${helper}.ts`), 'utf-8');
-        return { ext: 'ts', content: source.replace(/from '(/./[^'".]+)'/g, "from '$1.js'") };
+        // The leading `\b` in this pattern is load-bearing beyond its regex meaning.
+        // Our build runs tsc-alias --resolveFullPaths over the compiled output, and its
+        // scanner rewrites anything that looks like `from '<path>'` — even inside a
+        // regex literal. Without the `\b`, normalize-path turned this pattern's
+        // backslashes into slashes and v0.12.3 shipped with an unparseable regex that
+        // crashed the CLI on load. The `\b` blocks that scan (in the emitted text,
+        // `from` is preceded by the word character `b`, so tsc-alias's own `\bfrom`
+        // never matches) and is also semantically correct: an import keyword always
+        // sits at a word boundary. The dist smoke test (scripts/dist-smoke.test.ts)
+        // fails the build if this ever regresses.
+        return { ext: 'ts', content: source.replace(/\bfrom '(\.\/[^'".]+)'/g, `from '$1.${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 };
     }
 };
@@ -65,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
@@ -97,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) => {
@@ -115,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 } : {}),
@@ -129,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 {};