@gabrielbryk/json-schema-to-zod 2.7.4 → 2.9.0

package/dist/types/generators/generateBundle.d.ts

@@ -0,0 +1,62 @@
+import { JsonSchema, Options } from "../Types.js";
+export type SplitDefsOptions = {
+    /** Include a root schema file in addition to $defs */
+    includeRoot?: boolean;
+    /** Override file name for each schema (default: `${def}.schema.ts`) */
+    fileName?: (defName: string, ctx: {
+        isRoot: boolean;
+    }) => string;
+    /** Override exported schema const name (default: PascalCase(def) + "Schema") */
+    schemaName?: (defName: string, ctx: {
+        isRoot: boolean;
+    }) => string;
+    /** Override exported type name (default: PascalCase(def)) */
+    typeName?: (defName: string, ctx: {
+        isRoot: boolean;
+    }) => string | undefined;
+    /** Optional root schema name (defaults to provided `name` option or "RootSchema") */
+    rootName?: string;
+    /** Optional root type name (defaults to provided `type` option if string) */
+    rootTypeName?: string;
+};
+export type RefResolutionResult = string;
+export type RefResolutionOptions = {
+    /** Called for each internal $ref that targets a known $def */
+    onRef?: (ctx: {
+        ref: string;
+        refName: string;
+        currentDef: string | null;
+        path: (string | number)[];
+        isCycle: boolean;
+    }) => RefResolutionResult | undefined;
+    /**
+     * When true, cross-def references that participate in a cycle are emitted as z.lazy(() => Ref)
+     * to avoid TDZ issues across files.
+     */
+    lazyCrossRefs?: boolean;
+    /** Called for unknown $refs (outside of $defs/definitions) */
+    onUnknownRef?: (ctx: {
+        ref: string;
+        currentDef: string | null;
+    }) => RefResolutionResult | undefined;
+};
+export type NestedTypesOptions = {
+    enable?: boolean;
+    fileName?: string;
+};
+export type GenerateBundleOptions = Options & {
+    splitDefs?: SplitDefsOptions;
+    refResolution?: RefResolutionOptions;
+    nestedTypes?: NestedTypesOptions;
+    /** Force module kind for generated files (defaults to esm) */
+    module?: "esm" | "cjs" | "none";
+};
+export type GeneratedFile = {
+    fileName: string;
+    contents: string;
+};
+export type SchemaBundleResult = {
+    files: GeneratedFile[];
+    defNames: string[];
+};
+export declare const generateSchemaBundle: (schema: JsonSchema, options?: GenerateBundleOptions) => SchemaBundleResult;

package/dist/types/index.d.ts

@@ -1,4 +1,7 @@
 export * from "./Types.js";
+export * from "./core/analyzeSchema.js";
+export * from "./core/emitZod.js";
+export * from "./generators/generateBundle.js";
 export * from "./jsonSchemaToZod.js";
 export * from "./parsers/parseAllOf.js";
 export * from "./parsers/parseAnyOf.js";
@@ -19,9 +22,12 @@ export * from "./parsers/parseSchema.js";
 export * from "./parsers/parseSimpleDiscriminatedOneOf.js";
 export * from "./parsers/parseString.js";
 export * from "./utils/anyOrUnknown.js";
+export * from "./utils/buildRefRegistry.js";
+export * from "./utils/cycles.js";
 export * from "./utils/half.js";
 export * from "./utils/jsdocs.js";
 export * from "./utils/omit.js";
+export * from "./utils/resolveUri.js";
 export * from "./utils/withMessage.js";
 export * from "./zodToJsonSchema.js";
 import { jsonSchemaToZod } from "./jsonSchemaToZod.js";

package/dist/types/jsonSchemaToZod.d.ts

@@ -1,2 +1,2 @@
 import { Options, JsonSchema } from "./Types.js";
-export declare const jsonSchemaToZod: (schema: JsonSchema, { module, name, type, noImport, ...rest }?: Options) => string;
+export declare const jsonSchemaToZod: (schema: JsonSchema, options?: Options) => string;

package/dist/types/parsers/parseSchema.d.ts

@@ -29,7 +29,8 @@ export declare const its: {
             not: JsonSchema;
         };
         ref: (x: JsonSchemaObject) => x is JsonSchemaObject & {
-            $ref: string;
+            $ref?: string;
+            $dynamicRef?: string;
         };
         const: (x: JsonSchemaObject) => x is JsonSchemaObject & {
             const: Serializable;

package/dist/types/parsers/parseString.d.ts

@@ -1,4 +1,4 @@
-import { JsonSchemaObject } from "../Types.js";
+import { JsonSchemaObject, Refs } from "../Types.js";
 export declare const parseString: (schema: JsonSchemaObject & {
     type: "string";
-}) => string;
+}, refs?: Refs) => string;

package/dist/types/utils/buildRefRegistry.d.ts

@@ -0,0 +1,12 @@
+import { JsonSchema, Options } from "../Types.js";
+export type RefRegistryEntry = {
+    schema: JsonSchema;
+    path: (string | number)[];
+    baseUri: string;
+    dynamic?: boolean;
+    anchor?: string;
+};
+export declare const buildRefRegistry: (schema: JsonSchema, rootBaseUri?: string, opts?: Options) => {
+    registry: Map<string, RefRegistryEntry>;
+    rootBaseUri: string;
+};

package/dist/types/utils/cycles.d.ts

@@ -0,0 +1,7 @@
+import { JsonSchema } from "../Types.js";
+export declare const findRefDependencies: (schema: JsonSchema | undefined, validDefNames: string[]) => Set<string>;
+export declare const detectCycles: (defNames: string[], deps: Map<string, Set<string>>) => Set<string>;
+export declare const computeScc: (defNames: string[], deps: Map<string, Set<string>>) => {
+    cycleMembers: Set<string>;
+    componentByName: Map<string, number>;
+};

package/dist/types/utils/jsdocs.d.ts

@@ -1,3 +1,3 @@
-import { JsonSchemaObject } from "../Types";
+import { JsonSchemaObject } from "../Types.js";
 export declare const expandJsdocs: (jsdocs: string) => string;
 export declare const addJsdocs: (schema: JsonSchemaObject, parsed: string) => string;

package/dist/types/utils/resolveUri.d.ts

@@ -0,0 +1 @@
+export declare const resolveUri: (base: string, ref: string) => string;

package/dist/types/utils/withMessage.d.ts

@@ -2,7 +2,12 @@ import { JsonSchemaObject } from "../Types.js";
 type Opener = string;
 type MessagePrefix = string;
 type Closer = string;
-type Builder = [Opener, Closer] | [Opener, MessagePrefix, Closer];
+type Builder = {
+    opener: Opener;
+    closer: Closer;
+    messagePrefix?: MessagePrefix;
+    messageCloser?: Closer;
+};
 export declare function withMessage(schema: JsonSchemaObject, key: string, get: (props: {
     value: unknown;
     json: string;

package/docs/proposals/bundle-refactor.md

@@ -0,0 +1,43 @@
+# Schema Bundling Refactor (Analyzer + Emitters)
+
+## Context
+- `generateSchemaBundle` currently recurses via `parserOverride` and can overflow the stack when inline `$defs` are present (root hits immediately). Inline `$defs` inside `$defs` are also overwritten when stitching schemas.
+- The conversion pipeline mixes concerns: parsing/analysis, code emission, and bundling strategy live together in `jsonSchemaToZod` and the bundle generator.
+
+## Goals
+- Single responsibility: analyze JsonSchema once, emit code through pluggable strategies (single file, bundle, nested types).
+- Open for extension: new emitters (e.g., type-only), new ref resolution policies, without touching the analyzer.
+- Safer bundling: no recursive parser overrides; import-aware ref resolution; preserve inline `$defs`.
+- Testable units: analyzer IR and emitters have focused tests; bundle strategy tested with snapshots.
+
+## Proposed Architecture
+- **Analyzer (`analyzeSchema`)**: Convert JsonSchema + options into an intermediate representation (IR) containing symbols, ref pointer map, dependency graph, cycle info, and metadata flags. No code strings.
+- **Emitters**:
+  - `emitZod(ir, emitOptions)`: IR → zod code (esm/cjs/none), with naming hooks and export policies.
+  - `emitTypes(ir, typeOptions)`: optional type-only exports (for nested types or barrel typing).
+- **Strategies**:
+  - `SingleFileStrategy`: analyze root → emit zod once.
+  - `BundleStrategy`: analyze root once → slice IR per `$def` + root → emit per-file zod using an import-capable RefResolutionStrategy. Inline `$defs` remain scoped; cross-def `$ref`s become imports; unknown refs handled via policy.
+  - `NestedTypesStrategy`: walk IR titles/property paths to emit a dedicated types file.
+- **Public API**:
+  - `analyzeSchema(schema, options): AnalysisResult`
+  - `emitZod(ir, emitOptions): string`
+  - `generateSchemaBundle(schema, bundleOptions): { files }` implemented via BundleStrategy
+  - `jsonSchemaToZod(schema, options): string` becomes a thin wrapper (analyze + emit single file).
+
+## SOLID Alignment
+- SRP: analyzer, emitter, strategy are separate modules.
+- OCP: new emitters/strategies plug in without changing analyzer.
+- LSP/ISP: narrow contracts (naming hooks, ref resolution hooks) instead of monolithic option bags.
+- DIP: bundle strategy depends on IR abstractions, not on concrete `jsonSchemaToZod` string output.
+
+## Migration Plan
+1) **Foundations**: Extract analyzer + zod emitter modules; make `jsonSchemaToZod` call them. Preserve output parity and option validation. Add tests around analyzer/emitter.
+2) **Bundle Strategy**: Rework `generateSchemaBundle` to use the analyzer IR and an import-aware ref strategy; remove recursive `parserOverride`; preserve inline `$defs` within defs.
+3) **Nested Types**: Move nested type extraction to IR-based walker; emit via `emitTypes`.
+4) **Cleanups & API polish**: Reduce option bag coupling; document new APIs; consider default export ergonomics.
+
+## Risks / Mitigations
+- Risk: Output regressions. Mitigation: snapshot tests for single-file and bundle outputs.
+- Risk: Bundle import mapping errors. Mitigation: ref-strategy unit tests (cycles, unknown refs, cross-def).
+- Risk: Incremental refactor churn. Mitigation: keep `jsonSchemaToZod` wrapper stable while internals shift; land in stages with tests.

package/docs/proposals/ref-anchor-support.md

@@ -0,0 +1,65 @@
+# Proposal: Robust `$ref` / `$id` / `$anchor` / `$dynamicRef` Support
+
+## Goals
+- Resolve `$ref` using full URI semantics (RFC 3986), not just `#/` pointers.
+- Support `$id`/`$anchor`/`$dynamicAnchor`/`$dynamicRef` (and legacy `$recursiveRef/$recursiveAnchor`).
+- Keep resolver logic in the analyzer/IR layer so emitters/strategies stay SOLID (SRP/OCP).
+- Provide hooks for external schema resolution and unresolved-ref handling.
+- Preserve existing `$defs`/JSON Pointer behavior for compatibility.
+
+## Architecture alignment (with bundle refactor)
+- Implement ref/anchor logic in the analyzer; emitters consume IR edges, not URIs.
+- Define a pluggable `RefResolutionStrategy` used by the analyzer:
+  - Inputs: `ref`, `contextBaseUri`, `dynamicStack`, `registry`, optional `externalResolver`, `onUnresolvedRef`.
+  - Output: resolved IR node (or unresolved marker/fallback).
+- Registry and dynamic stacks are built/maintained during analysis; IR carries resolved targets keyed by URI+fragment.
+
+## Plan
+
+### 1) Build a URI/anchor registry (analyzer prepass)
+- Walk the schema once, tracking base URI (respect `$id`).
+- Register base URI entries, `$anchor` (base#anchor), `$dynamicAnchor` (base#anchor, dynamic flag).
+- Handle relative `$id` resolution per RFC 3986.
+- Attach registry to IR/context.
+
+### 2) URI-based ref resolution
+- `resolveRef(ref, contextBaseUri, registry, dynamicStack)`:
+  - Resolve against `contextBaseUri` → absolute URI; split base/fragment.
+  - For `$dynamicRef`, search `dynamicStack` top-down for matching anchor; else fallback to registry lookup.
+  - For normal `$ref`, look up base+fragment in registry; empty fragment hits base entry.
+  - On miss: invoke `onUnresolvedRef` hook and return unresolved marker.
+- Analyzer produces IR references keyed by resolved URI+fragment; name generation uses this key.
+
+### 3) Thread base URI & dynamic stack in analyzer
+- Extend analyzer traversal context (similar to Refs) with `currentBaseUri`, `dynamicAnchors`.
+- On `$id`, compute new base; pass to children.
+- On `$dynamicAnchor`, push onto stack for node scope; pop on exit.
+- Emitters receive IR that already encodes resolved refs.
+
+### 4) Legacy recursive keywords
+- Treat `$recursiveAnchor` as a special dynamic anchor name.
+- Treat `$recursiveRef` like `$dynamicRef` targeting that name.
+
+### 5) External refs (optional, pluggable)
+- Analyzer option `resolveExternalRef(uri)` (sync/async) to fetch external schemas.
+- On external base URI miss, call resolver, prewalk and cache registry for that URI, then resolve.
+- Guard against cycles with in-progress cache.
+
+### 6) Naming & cycles
+- Key ref names by resolved URI+fragment; store map in IR for consistent imports/aliases.
+- Preserve cycle detection using these names.
+
+### 7) Error/warning handling
+- Option `onUnresolvedRef(uri, path)` for logging/throwing.
+- Policy for fallback (`z.any()`/`z.unknown()` or error) lives in emitter/strategy but is driven by analyzer’s unresolved marker.
+
+### 8) Tests
+- Analyzer-level tests: `$id`/`$anchor` resolution (absolute/relative), `$dynamicAnchor`/`$dynamicRef` scoping, legacy recursive, external resolver stub, cycles, backward-compatible `#/` refs.
+- Strategy/emitter tests: bundle imports for cross-file refs, naming stability with URI keys.
+
+### 9) Migration steps
+- Add registry prepass and URI resolver in analyzer.
+- Thread `currentBaseUri`/`dynamicAnchors` through analysis context.
+- Produce IR refs keyed by resolved URI; update naming map/cycle tracking.
+- Add resolver hooks and unresolved handling.
+- Add tests/fixtures; keep emitters unchanged except to consume new IR ref keys.

package/eslint.config.js

@@ -0,0 +1,26 @@
+import parser from "@typescript-eslint/parser";
+import pluginTs from "@typescript-eslint/eslint-plugin";
+
+export default [
+  {
+    ignores: ["dist", "node_modules"],
+  },
+  {
+    files: ["**/*.ts", "**/*.tsx"],
+    languageOptions: {
+      parser,
+      parserOptions: {
+        ecmaVersion: "latest",
+        sourceType: "module",
+      },
+    },
+    plugins: {
+      "@typescript-eslint": pluginTs,
+    },
+    rules: {
+      ...pluginTs.configs.recommended.rules,
+      "@typescript-eslint/no-require-imports": "error",
+      "@typescript-eslint/no-var-requires": "error",
+    },
+  },
+];

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@gabrielbryk/json-schema-to-zod",
-  "version": "2.7.4",
+  "version": "2.9.0",
   "description": "Converts JSON schema objects or files into Zod schemas",
+  "type": "module",
   "types": "./dist/types/index.d.ts",
   "bin": "./dist/cjs/cli.js",
   "main": "./dist/cjs/index.js",
@@ -62,9 +63,12 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
+    "@typescript-eslint/eslint-plugin": "^8.49.0",
+    "@typescript-eslint/parser": "^8.49.0",
     "@types/json-schema": "^7.0.15",
     "@types/node": "^20.9.0",
     "fast-diff": "^1.3.0",
+    "eslint": "^9.39.1",
     "js-yaml": "^4.1.0",
     "rimraf": "^5.0.5",
     "tsx": "^4.1.1",
@@ -73,12 +77,14 @@
   },
   "scripts": {
     "build:types": "tsc -p tsconfig.types.json",
-    "build:cjs": "tsc -p tsconfig.cjs.json && node postcjs.js",
-    "build:esm": "tsc -p tsconfig.esm.json && node postesm.js",
+    "build:cjs": "tsc -p tsconfig.cjs.json && node postcjs.cjs",
+    "build:esm": "tsc -p tsconfig.esm.json && node postesm.cjs",
     "build": "pnpm gen && pnpm test && rimraf ./dist && pnpm build:types && pnpm build:cjs && pnpm build:esm",
     "dry": "pnpm build && pnpm publish --dry-run",
     "dev": "tsx watch test/index.ts",
     "gen": "tsx ./createIndex.ts",
-    "test": "tsx test/index.ts"
+    "test": "tsx test/index.ts",
+    "lint": "eslint \"src/**/*.{ts,tsx}\" \"test/**/*.ts\"",
+    "smoke:esm": "pnpm build:esm && node --input-type=module -e \"import { jsonSchemaToZod } from './dist/esm/index.js'; console.log(jsonSchemaToZod({type:'string'}));\""
   }
 }