@amritk/generate-parsers 0.13.0 → 0.15.0

package/README.md

@@ -9,7 +9,7 @@
 ![license](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square) 
 ![JSON Schema](https://img.shields.io/badge/JSON%20Schema-2020--12-f97316?style=flat-square) 
 ![node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=flat-square&logo=node.js&logoColor=white) 
-![vibe coded](https://img.shields.io/badge/vibe%20coded-84%25-a855f7?style=flat-square)
+![vibe coded](https://img.shields.io/badge/vibe-coded-a855f7?style=flat-square)
 
 </div>
 

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,13 @@ 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'` (this function's 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. Note the `mjst` CLI defaults this to `'ts'` (falling back to `'js'` only
+ *   under `--build`, where tsc must compile the sources) so generated output runs under
+ *   Node without a build step; direct callers of `buildSchema` opt in explicitly.
  * @returns An array of generated TypeScript files
  *
  * @example
@@ -77,4 +85,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,13 @@ 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'` (this function's 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. Note the `mjst` CLI defaults this to `'ts'` (falling back to `'js'` only
+ *   under `--build`, where tsc must compile the sources) so generated output runs under
+ *   Node without a build step; direct callers of `buildSchema` opt in explicitly.
  * @returns An array of generated TypeScript files
  *
  * @example
@@ -107,7 +121,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 +139,8 @@ export const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnl
             helpersImportPrefix,
             readonly,
             typeSuffix,
+            importExt,
+            isRoot: node.isRoot,
             ...(node.ref !== undefined ? { selfRef: node.ref } : {}),
             ...(logWarnings !== undefined ? { logWarnings } : {}),
             ...(strict !== undefined ? { strict } : {}),
@@ -139,10 +155,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,20 @@ 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;
+    /**
+     * True when this file is the root document rather than a `$ref`-reached
+     * definition. Forwarded to the parser generator so the JSON Schema
+     * meta-schema special case (type name `Schema`) never applies to a
+     * user-named root.
+     */
+    readonly isRoot?: boolean;
 };
 /** 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,25 @@ 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,
+        ...(options?.isRoot !== undefined ? { isRoot: options.isRoot } : {}),
         ...(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,22 @@ 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>;
+    /**
+     * True when this schema is the root document (not a `$ref`-reached definition).
+     * The root type name is user-derived (schema `title`, filename, or `--root-type`),
+     * so the JSON Schema meta-schema special case — keyed on the literal name
+     * `Schema` — must not apply to it, or a common `schema.json` root would silently
+     * generate a validation-free pass-through parser.
+     */
+    readonly isRoot?: boolean;
 };
 /**
  * Generates a safe parser as an arrow function that never throws.
@@ -71,5 +87,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 {};