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

package/dist/esm/utils/omit.js

@@ -1,10 +1,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.omit = void 0;
-const omit = (obj, ...keys) => Object.keys(obj).reduce((acc, key) => {
+export const omit = (obj, ...keys) => Object.keys(obj).reduce((acc, key) => {
     if (!keys.includes(key)) {
         acc[key] = obj[key];
     }
     return acc;
 }, {});
-exports.omit = omit;

package/dist/esm/utils/resolveUri.js

@@ -0,0 +1,12 @@
+export const resolveUri = (base, ref) => {
+    try {
+        // If ref is absolute, new URL will accept it; otherwise resolves against base
+        return new URL(ref, base).toString();
+    }
+    catch {
+        // Fallback: simple concatenation to avoid throwing; keep ref as-is
+        if (ref.startsWith("#"))
+            return `${base}${ref}`;
+        return ref;
+    }
+};

package/dist/esm/utils/withMessage.js

@@ -1,7 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.withMessage = withMessage;
-function withMessage(schema, key, get) {
+export function withMessage(schema, key, get) {
     const value = schema[key];
     let r = "";
     if (value !== undefined) {

package/dist/esm/zodToJsonSchema.js

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Post-processor for Zod's z.toJSONSchema() output.
  *
@@ -15,8 +14,6 @@
  * - patternProperties (stored in __jsonSchema.patternProperties)
  * - if/then/else conditionals (stored in __jsonSchema.conditional)
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.reconstructJsonSchema = reconstructJsonSchema;
 /**
  * Recursively process a JSON Schema to reconstruct original features from __jsonSchema meta.
  *
@@ -24,7 +21,7 @@ exports.reconstructJsonSchema = reconstructJsonSchema;
  * - allOf[object, {__jsonSchema: {conditional: ...}}] -> object with if/then/else at top level
  * - patternProperties meta -> patternProperties at current level
  */
-function reconstructJsonSchema(schema) {
+export function reconstructJsonSchema(schema) {
     if (typeof schema !== "object" || schema === null) {
         return schema;
     }

package/dist/types/Types.d.ts

@@ -99,6 +99,16 @@ export type Options = {
      * Can be used to log or throw on unknown formats.
      */
     onUnknownFormat?: (format: string, path: (string | number)[]) => void;
+    /**
+     * Called when a $ref/$dynamicRef cannot be resolved.
+     * Can be used to log or throw on unknown references.
+     */
+    onUnresolvedRef?: (ref: string, path: (string | number)[]) => void;
+    /**
+     * Optional resolver for external $ref URIs.
+     * Return a JsonSchema to register, or undefined if not found.
+     */
+    resolveExternalRef?: (uri: string) => JsonSchema | Promise<JsonSchema> | undefined;
 };
 export type Refs = Options & {
     path: (string | number)[];
@@ -115,6 +125,24 @@ export type Refs = Options & {
     currentSchemaName?: string;
     cycleRefNames?: Set<string>;
     cycleComponentByName?: Map<string, number>;
+    /** Base URI in scope while traversing */
+    currentBaseUri?: string;
+    /** Root/base URI for the document */
+    rootBaseUri?: string;
+    /** Prebuilt registry of resolved URIs/anchors */
+    refRegistry?: Map<string, {
+        schema: JsonSchema;
+        path: (string | number)[];
+        baseUri: string;
+        dynamic?: boolean;
+        anchor?: string;
+    }>;
+    /** Stack of active dynamic anchors (nearest last) */
+    dynamicAnchors?: {
+        name: string;
+        uri: string;
+        path: (string | number)[];
+    }[];
 };
 export type SimpleDiscriminatedOneOfSchema<D extends string = string> = JsonSchemaObject & {
     oneOf: (JsonSchemaObject & {

package/dist/types/core/analyzeSchema.d.ts

@@ -0,0 +1,24 @@
+import { Options, JsonSchema } from "../Types.js";
+export type NormalizedOptions = Options & {
+    exportRefs: boolean;
+    withMeta: boolean;
+};
+export type AnalysisResult = {
+    schema: JsonSchema;
+    options: NormalizedOptions;
+    refNameByPointer: Map<string, string>;
+    usedNames: Set<string>;
+    declarations: Map<string, string>;
+    dependencies: Map<string, Set<string>>;
+    cycleRefNames: Set<string>;
+    cycleComponentByName: Map<string, number>;
+    refRegistry: Map<string, {
+        schema: JsonSchema;
+        path: (string | number)[];
+        baseUri: string;
+        dynamic?: boolean;
+        anchor?: string;
+    }>;
+    rootBaseUri: string;
+};
+export declare const analyzeSchema: (schema: JsonSchema, options?: Options) => AnalysisResult;

package/dist/types/core/emitZod.d.ts

@@ -0,0 +1,2 @@
+import { AnalysisResult } from "./analyzeSchema.js";
+export declare const emitZod: (analysis: AnalysisResult) => string;

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

@@ -29,6 +29,11 @@ export type RefResolutionOptions = {
         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;

package/dist/types/index.d.ts

@@ -1,4 +1,6 @@
 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";
@@ -20,10 +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/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/resolveUri.d.ts

@@ -0,0 +1 @@
+export declare const resolveUri: (base: string, ref: string) => 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.8.0",
+  "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'}));\""
   }
 }