@amritk/generate-parsers 0.2.1 → 0.3.1

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

@@ -1,4 +1,5 @@
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+import type { HelpersMode } from '#helpers/collect-helpers';
 import type { SchemaExtensions } from '#types/schema-extensions';
 /**
  * Represents a generated file with its filename and content.
@@ -30,6 +31,9 @@ export type GeneratedFile = {
  * @param strict - When true, the generated parsers throw on type/shape mismatches
  *   (wrong type, missing required property, enum/pattern/min/max violations) instead
  *   of coercing invalid input to default values.
+ * @param helpersMode - `'package'` (default) emits `import ... from '@amritk/helpers/...'`.
+ *   `'embedded'` emits `import ... from './_helpers/...'` and appends the helper sources
+ *   as additional `GeneratedFile` entries so the output directory is self-contained.
  * @returns An array of generated TypeScript files
  *
  * @example
@@ -62,4 +66,4 @@ export type GeneratedFile = {
  * });
  * ```
  */
-export declare const buildSchema: (rootSchema: JSONSchema, rootTypeName: string, extensions?: SchemaExtensions, typesOnly?: boolean, logWarnings?: boolean, strict?: boolean) => Promise<GeneratedFile[]>;
+export declare const buildSchema: (rootSchema: JSONSchema, rootTypeName: string, extensions?: SchemaExtensions, typesOnly?: boolean, logWarnings?: boolean, strict?: boolean, helpersMode?: HelpersMode) => Promise<GeneratedFile[]>;

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

@@ -1,4 +1,5 @@
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+import { type HelpersMode, type RuntimeHelperName } from '#helpers/collect-helpers';
 /**
  * Options for controlling what gets generated in a file.
  */
@@ -29,6 +30,18 @@ type GenerateFileOptions = {
      * of coercing invalid input to default values.
      */
     readonly strict?: boolean;
+    /**
+     * Controls how runtime helpers are referenced.
+     * - `'package'` (default): emit imports from `@amritk/helpers/...`.
+     * - `'embedded'`: emit imports from `./_helpers/...` so the helper sources can
+     *   be shipped alongside the generated files.
+     */
+    readonly helpersMode?: HelpersMode;
+};
+/** Result of generating a single parser file. */
+export type GeneratedFileContent = {
+    readonly content: string;
+    readonly usedHelpers: ReadonlySet<RuntimeHelperName>;
 };
 /**
  * Generates a complete TypeScript file from a JSON Schema.
@@ -39,7 +52,7 @@ type GenerateFileOptions = {
  * @param schema - The JSON Schema to generate code from
  * @param typeName - The name to use for the generated TypeScript type
  * @param options - Optional settings to control what gets generated
- * @returns The complete TypeScript code
+ * @returns The generated file content and the set of runtime helpers it references
  *
  * @example
  * ```typescript
@@ -59,5 +72,5 @@ type GenerateFileOptions = {
  * // typesOnly contains only type-only imports and type User (no parser)
  * ```
  */
-export declare const generateFile: (schema: JSONSchema, typeName: string, options?: GenerateFileOptions) => string;
+export declare const generateFile: (schema: JSONSchema, typeName: string, options?: GenerateFileOptions) => GeneratedFileContent;
 export {};

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

@@ -1,2 +1,16 @@
-/** A more foolproof way to generate imports from the parserFunction */
-export declare const collectHelpers: (parserFunction: string) => string[];
+/** Names (without `.ts`) of runtime helpers that can be embedded into generated output. */
+export type RuntimeHelperName = 'is-object' | 'validate-array' | 'validate-record' | 'has-ref';
+/** Controls how generated parsers reference their runtime helpers. */
+export type HelpersMode = 'package' | 'embedded';
+export type CollectedHelpers = {
+    /** Import lines to splice into the generated file. */
+    readonly imports: string[];
+    /**
+     * Helper names that need to ship alongside the generated file in embedded mode.
+     * Includes transitive deps (e.g. `validate-record` pulls in `is-object`) so the
+     * orchestrator can emit a complete `_helpers/` directory.
+     */
+    readonly used: Set<RuntimeHelperName>;
+};
+/** Detects which runtime helpers a generated parser body references. */
+export declare const collectHelpers: (parserFunction: string, mode: HelpersMode) => CollectedHelpers;

package/dist/index.js

@@ -1,3 +1,8 @@
+// src/generators/build-schema.ts
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, resolve as resolvePath } from "node:path";
+
 // ../helpers/dist/build-dynamic-ref-map.js
 var isSchemaObject = (schema) => {
   return typeof schema === "object" && schema !== null && typeof schema !== "boolean";
@@ -792,24 +797,46 @@ var generateTypeDefinition = (schema, typeName) => {
 };
 
 // src/helpers/collect-helpers.ts
-var collectHelpers = (parserFunction) => {
+var PACKAGE_IMPORTS = {
+  "is-object": "import { isObject } from '@amritk/helpers/is-object';",
+  "validate-array": "import { validateArray } from '@amritk/helpers/validate-array';",
+  "validate-record": "import { validateRecord } from '@amritk/helpers/validate-record';",
+  "has-ref": "import { hasRef } from '@amritk/helpers/schema-guards';"
+};
+var EMBEDDED_IMPORTS = {
+  "is-object": "import { isObject } from './_helpers/is-object';",
+  "validate-array": "import { validateArray } from './_helpers/validate-array';",
+  "validate-record": "import { validateRecord } from './_helpers/validate-record';",
+  "has-ref": "import { hasRef } from './_helpers/has-ref';"
+};
+var collectHelpers = (parserFunction, mode) => {
   const imports = [];
+  const used = new Set;
+  const table = mode === "embedded" ? EMBEDDED_IMPORTS : PACKAGE_IMPORTS;
   if (parserFunction.includes("validateArray")) {
-    imports.push("import { validateArray } from '@amritk/helpers/validate-array';");
+    imports.push(table["validate-array"]);
+    used.add("validate-array");
   }
   if (parserFunction.includes("validateRecord")) {
-    imports.push("import { validateRecord } from '@amritk/helpers/validate-record';");
+    imports.push(table["validate-record"]);
+    used.add("validate-record");
+    used.add("is-object");
   }
   if (parserFunction.includes("isObject")) {
-    imports.push("import { isObject } from '@amritk/helpers/is-object';");
+    imports.push(table["is-object"]);
+    used.add("is-object");
   }
   if (parserFunction.includes("hasRef(")) {
-    imports.push("import { hasRef } from '@amritk/helpers/schema-guards';");
+    imports.push(table["has-ref"]);
+    used.add("has-ref");
   }
-  return imports;
+  return { imports, used };
 };
 
 // ../helpers/dist/schema-guards.js
+var hasRef = (value) => {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && "$ref" in value && typeof value.$ref === "string";
+};
 var isSchemaObject3 = (schema) => {
   return typeof schema === "object" && schema !== null && typeof schema !== "boolean";
 };
@@ -891,9 +918,6 @@ var hasMinProperties = (schema) => {
 var hasMaxProperties = (schema) => {
   return isSchemaObject3(schema) && "maxProperties" in schema && typeof schema.maxProperties === "number";
 };
-var hasRef = (schema) => {
-  return isSchemaObject3(schema) && "$ref" in schema && typeof schema.$ref === "string";
-};
 
 // src/helpers/collect-imports.ts
 var getImportPathForFilename = (filename) => `./${filename}`;
@@ -2418,6 +2442,7 @@ var generateFile = (schema, typeName, options) => {
   const typesOnly = options?.typesOnly === true;
   const selfRef = options?.selfRef;
   const rootSchema = options?.rootSchema;
+  const helpersMode = options?.helpersMode ?? "package";
   const typeDefinition = generateTypeDefinition(schema, typeName);
   if (typesOnly) {
     const imports2 = collectImports(schema, { typesOnly: true, selfRef, rootSchema });
@@ -2432,7 +2457,7 @@ var generateFile = (schema, typeName, options) => {
 
 `;
     }
-    return result2 + typeDefinition;
+    return { content: result2 + typeDefinition, usedHelpers: new Set };
   }
   const parserFunction = generateParserFunction(schema, typeName, {
     useRefImports: true,
@@ -2443,7 +2468,8 @@ var generateFile = (schema, typeName, options) => {
   const combinedFunctions = `${shapeValidator}
 
 ${parserFunction}`;
-  const imports = [...collectImports(schema, { selfRef, rootSchema }), ...collectHelpers(combinedFunctions)];
+  const helpers = collectHelpers(combinedFunctions, helpersMode);
+  const imports = [...collectImports(schema, { selfRef, rootSchema }), ...helpers.imports];
   let result = "";
   if (imports.length > 0) {
     result += imports[0];
@@ -2455,12 +2481,18 @@ ${parserFunction}`;
 
 `;
   }
-  return result + typeDefinition + `
+  return { content: result + typeDefinition + `
 
-` + combinedFunctions;
+` + combinedFunctions, usedHelpers: helpers.used };
 };
 
 // src/generators/build-schema.ts
+var readHelperSource = async (helper) => {
+  const require2 = createRequire(import.meta.url);
+  const helpersPkgPath = require2.resolve("@amritk/helpers/package.json");
+  const helpersRoot = dirname(helpersPkgPath);
+  return readFile(resolvePath(helpersRoot, "src", `${helper}.ts`), "utf-8");
+};
 var extractDynamicAnchorDefs = (schema) => {
   const refs = [];
   if (typeof schema !== "object" || schema === null) {
@@ -2480,18 +2512,20 @@ var extractDynamicAnchorDefs = (schema) => {
   }
   return refs;
 };
-var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict) => {
+var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = "package") => {
   rootSchema = upgradeDraft07Schema(rootSchema);
   const files = [];
   const processedRefs = new Set;
   const processedFilenames = new Set;
   const refsToProcess = [];
+  const usedHelpers = new Set;
   const dynamicRefMap = buildDynamicRefMap(rootSchema);
   const processedRootSchema = resolveDynamicRefs(rootSchema, dynamicRefMap);
   const extendedRootSchema = extensions ? applySchemaExtensions(processedRootSchema, rootTypeName.toLowerCase(), extensions) : processedRootSchema;
-  const rootContent = generateFile(extendedRootSchema, rootTypeName, {
+  const rootResult = generateFile(extendedRootSchema, rootTypeName, {
     typesOnly: typesOnly ?? false,
     rootSchema,
+    helpersMode,
     ...logWarnings !== undefined ? { logWarnings } : {},
     ...strict !== undefined ? { strict } : {}
   });
@@ -2499,8 +2533,10 @@ var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWar
   processedFilenames.add(rootFilename);
   files.push({
     filename: `${rootFilename}.ts`,
-    content: rootContent
+    content: rootResult.content
   });
+  for (const helper of rootResult.usedHelpers)
+    usedHelpers.add(helper);
   const rootRefs = extractRefs(rootSchema);
   refsToProcess.push(...rootRefs);
   const dynamicAnchorRefs = extractDynamicAnchorDefs(rootSchema);
@@ -2520,10 +2556,11 @@ var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWar
     const filename = refToFilename(ref);
     const processedSchema = resolveDynamicRefs(resolvedSchema, dynamicRefMap);
     const extendedSchema = extensions ? applySchemaExtensions(processedSchema, filename, extensions) : processedSchema;
-    const content = generateFile(extendedSchema, typeName, {
+    const fileResult = generateFile(extendedSchema, typeName, {
       typesOnly: typesOnly ?? false,
       selfRef: ref,
       rootSchema,
+      helpersMode,
       ...logWarnings !== undefined ? { logWarnings } : {},
       ...strict !== undefined ? { strict } : {}
     });
@@ -2531,9 +2568,11 @@ var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWar
       processedFilenames.add(filename);
       files.push({
         filename: `${filename}.ts`,
-        content
+        content: fileResult.content
       });
     }
+    for (const helper of fileResult.usedHelpers)
+      usedHelpers.add(helper);
     const nestedRefs = extractRefs(resolvedSchema);
     for (const nestedRef of nestedRefs) {
       if (!processedRefs.has(nestedRef)) {
@@ -2541,9 +2580,15 @@ var buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWar
       }
     }
   }
+  if (helpersMode === "embedded" && !typesOnly) {
+    for (const helper of usedHelpers) {
+      const source = await readHelperSource(helper);
+      files.push({ filename: `_helpers/${helper}.ts`, content: source });
+    }
+  }
   const TYPE_EXPORT_RE = /^export type (\w+)/gm;
   const CONST_EXPORT_RE = /^export const (\w+)/gm;
-  const sortedFiles = [...files].sort((a, b) => a.filename.localeCompare(b.filename));
+  const sortedFiles = [...files].filter((f) => !f.filename.startsWith("_helpers/")).sort((a, b) => a.filename.localeCompare(b.filename));
   let indexContent = "";
   for (const file of sortedFiles) {
     const moduleName = file.filename.replace(/\.ts$/, "");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/generate-parsers",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "module": "./dist/index.js",
   "type": "module",
@@ -23,7 +23,8 @@
     "url": "https://github.com/amritk/mjst/issues"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "publishConfig": {
     "access": "public"