@gabrielbryk/json-schema-to-zod 2.10.1 → 2.11.1

package/dist/{esm/parsers → parsers}/parseString.js

@@ -3,24 +3,26 @@ import { parseSchema } from "./parseSchema.js";
 export const parseString = (schema, refs) => {
     const formatError = schema.errorMessage?.format;
     const refContext = ensureRefs(refs);
+    // Map formats to top-level Zod functions and their return types
     const topLevelFormatMap = {
-        email: "z.email",
-        ipv4: "z.ipv4",
-        ipv6: "z.ipv6",
-        uri: "z.url",
-        uuid: "z.uuid",
-        cuid: "z.cuid",
-        cuid2: "z.cuid2",
-        nanoid: "z.nanoid",
-        ulid: "z.ulid",
-        jwt: "z.jwt",
-        e164: "z.e164",
-        base64url: "z.base64url",
-        base64: "z.base64",
-        emoji: "z.emoji",
-        "idn-email": "z.email",
+        email: { fn: "z.email", zodType: "z.ZodEmail" },
+        ipv4: { fn: "z.ipv4", zodType: "z.ZodIPv4" },
+        ipv6: { fn: "z.ipv6", zodType: "z.ZodIPv6" },
+        uri: { fn: "z.url", zodType: "z.ZodURL" },
+        uuid: { fn: "z.uuid", zodType: "z.ZodUUID" },
+        cuid: { fn: "z.cuid", zodType: "z.ZodCUID" },
+        cuid2: { fn: "z.cuid2", zodType: "z.ZodCUID2" },
+        nanoid: { fn: "z.nanoid", zodType: "z.ZodNanoID" },
+        ulid: { fn: "z.ulid", zodType: "z.ZodULID" },
+        jwt: { fn: "z.jwt", zodType: "z.ZodJWT" },
+        e164: { fn: "z.e164", zodType: "z.ZodE164" },
+        base64url: { fn: "z.base64url", zodType: "z.ZodBase64URL" },
+        base64: { fn: "z.base64", zodType: "z.ZodBase64" },
+        emoji: { fn: "z.emoji", zodType: "z.ZodEmoji" },
+        "idn-email": { fn: "z.email", zodType: "z.ZodEmail" },
     };
-    const formatFn = schema.format && topLevelFormatMap[schema.format];
+    const formatInfo = schema.format ? topLevelFormatMap[schema.format] : undefined;
+    const formatFn = formatInfo?.fn;
     const formatParam = formatError !== undefined ? `{ error: ${JSON.stringify(formatError)} }` : "";
     let r = formatFn ? `${formatFn}(${formatParam})` : "z.string()";
     const formatHandled = Boolean(formatFn);
@@ -287,8 +289,12 @@ export const parseString = (schema, refs) => {
         r += contentMediaType;
         r += withMessage(schema, "contentSchema", ({ value }) => {
             if (value && typeof value === "object") {
+                const parsedContent = parseSchema(value, refContext);
+                const contentExpr = typeof parsedContent === "string"
+                    ? parsedContent
+                    : parsedContent.expression;
                 return {
-                    opener: `.pipe(${parseSchema(value, refContext)}`,
+                    opener: `.pipe(${contentExpr}`,
                     closer: ")",
                     messagePrefix: ", { error: ",
                     messageCloser: " })",
@@ -296,7 +302,12 @@ export const parseString = (schema, refs) => {
             }
         });
     }
-    return r;
+    // Use the correct Zod type based on whether a format function was used
+    const zodType = formatInfo?.zodType ?? "z.ZodString";
+    return {
+        expression: r,
+        type: zodType,
+    };
 };
 function ensureRefs(refs) {
     if (refs)

package/dist/types/Types.d.ts

@@ -1,6 +1,16 @@
 export type Serializable = {
     [key: string]: Serializable;
 } | Serializable[] | string | number | boolean | null;
+/**
+ * Dual representation of a Zod schema - tracks both the runtime expression
+ * and its TypeScript type annotation for proper recursive schema typing.
+ */
+export interface SchemaRepresentation {
+    /** The Zod runtime expression, e.g., "z.array(MySchema).optional()" */
+    expression: string;
+    /** The Zod TypeScript type, e.g., "z.ZodOptional<z.ZodArray<typeof MySchema>>" */
+    type: string;
+}
 export type JsonSchema = JsonSchemaObject | boolean;
 export type JsonSchemaObject = {
     type?: string | string[];
@@ -59,11 +69,10 @@ export type JsonSchemaObject = {
         [key: string]: string | undefined;
     };
 } & Record<string, unknown>;
-export type ParserSelector = (schema: JsonSchemaObject, refs: Refs) => string;
+export type ParserSelector = (schema: JsonSchemaObject, refs: Refs) => SchemaRepresentation;
 export type ParserOverride = (schema: JsonSchemaObject, refs: Refs) => string | void;
 export type Options = {
     name?: string;
-    module?: "cjs" | "esm" | "none";
     withoutDefaults?: boolean;
     withoutDescribes?: boolean;
     withJsdocs?: boolean;
@@ -112,15 +121,34 @@ export type Options = {
      * Return a JsonSchema to register, or undefined if not found.
      */
     resolveExternalRef?: (uri: string) => JsonSchema | Promise<JsonSchema> | undefined;
+    /**
+     * Lift inline object schemas into top-level defs to improve reusability.
+     * Default is ON; set enable: false to opt out.
+     */
+    liftInlineObjects?: {
+        /** Whether to enable lifting inline object schemas (default: true). */
+        enable?: boolean;
+        /** Optional hook to override generated names for lifted defs. */
+        nameForPath?: (path: (string | number)[], ctx: {
+            parentName?: string;
+            existingNames: Set<string>;
+            branchInfo?: unknown;
+        }) => string;
+        /** Deduplicate lifted shapes by structural hash (ignoring titles/descriptions). Default: false. */
+        dedup?: boolean;
+        /** Allow hoisting inside $defs content (default: true). */
+        allowInDefs?: boolean;
+    };
 };
 export type Refs = Options & {
     path: (string | number)[];
     seen: Map<object | boolean, {
         n: number;
-        r: string | undefined;
+        r: SchemaRepresentation | undefined;
     }>;
     root?: JsonSchema;
-    declarations?: Map<string, string>;
+    /** Stores schema declarations with both expression and type */
+    declarations?: Map<string, SchemaRepresentation>;
     dependencies?: Map<string, Set<string>>;
     inProgress?: Set<string>;
     refNameByPointer?: Map<string, string>;

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

@@ -1,14 +1,15 @@
-import { Options, JsonSchema } from "../Types.js";
+import { Options, JsonSchema, SchemaRepresentation } from "../Types.js";
 export type NormalizedOptions = Options & {
     exportRefs: boolean;
     withMeta: boolean;
+    module: "esm";
 };
 export type AnalysisResult = {
     schema: JsonSchema;
     options: NormalizedOptions;
     refNameByPointer: Map<string, string>;
     usedNames: Set<string>;
-    declarations: Map<string, string>;
+    declarations: Map<string, SchemaRepresentation>;
     dependencies: Map<string, Set<string>>;
     cycleRefNames: Set<string>;
     cycleComponentByName: Map<string, number>;

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

@@ -48,8 +48,6 @@ 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;

package/dist/types/index.d.ts

@@ -24,10 +24,16 @@ export * from "./parsers/parseString.js";
 export * from "./utils/anyOrUnknown.js";
 export * from "./utils/buildRefRegistry.js";
 export * from "./utils/cycles.js";
+export * from "./utils/esmEmitter.js";
+export * from "./utils/extractInlineObject.js";
 export * from "./utils/half.js";
 export * from "./utils/jsdocs.js";
+export * from "./utils/liftInlineObjects.js";
+export * from "./utils/namingService.js";
 export * from "./utils/omit.js";
+export * from "./utils/resolveRef.js";
 export * from "./utils/resolveUri.js";
+export * from "./utils/schemaRepresentation.js";
 export * from "./utils/withMessage.js";
 export * from "./zodToJsonSchema.js";
 import { jsonSchemaToZod } from "./jsonSchemaToZod.js";

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

@@ -1,4 +1,4 @@
-import { JsonSchemaObject, JsonSchema, Refs } from "../Types.js";
+import { JsonSchemaObject, JsonSchema, Refs, SchemaRepresentation } from "../Types.js";
 export declare function parseAllOf(schema: JsonSchemaObject & {
     allOf: JsonSchema[];
-}, refs: Refs): string;
+}, refs: Refs): SchemaRepresentation;

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

@@ -1,4 +1,4 @@
-import { JsonSchemaObject, JsonSchema, Refs } from "../Types.js";
+import { JsonSchemaObject, JsonSchema, Refs, SchemaRepresentation } from "../Types.js";
 export declare const parseAnyOf: (schema: JsonSchemaObject & {
     anyOf: JsonSchema[];
-}, refs: Refs) => string;
+}, refs: Refs) => SchemaRepresentation;

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

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

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

@@ -1 +1,2 @@
-export declare const parseBoolean: () => string;
+import { SchemaRepresentation } from "../Types.js";
+export declare const parseBoolean: () => SchemaRepresentation;

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

@@ -1,4 +1,4 @@
-import { JsonSchemaObject, Serializable } from "../Types.js";
+import { JsonSchemaObject, SchemaRepresentation, Serializable } from "../Types.js";
 export declare const parseConst: (schema: JsonSchemaObject & {
     const: Serializable;
-}) => string;
+}) => SchemaRepresentation;

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

@@ -1,2 +1,2 @@
-import { JsonSchemaObject, Refs } from "../Types.js";
-export declare const parseDefault: (_schema: JsonSchemaObject, refs?: Refs) => string;
+import { JsonSchemaObject, Refs, SchemaRepresentation } from "../Types.js";
+export declare const parseDefault: (_schema: JsonSchemaObject, refs?: Refs) => SchemaRepresentation;

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

@@ -1,4 +1,4 @@
-import { JsonSchemaObject, Serializable } from "../Types.js";
+import { JsonSchemaObject, SchemaRepresentation, Serializable } from "../Types.js";
 export declare const parseEnum: (schema: JsonSchemaObject & {
     enum: Serializable[];
-}) => string;
+}) => SchemaRepresentation;

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

@@ -1,6 +1,6 @@
-import { JsonSchemaObject, JsonSchema, Refs } from "../Types.js";
+import { JsonSchemaObject, JsonSchema, Refs, SchemaRepresentation } from "../Types.js";
 export declare const parseIfThenElse: (schema: JsonSchemaObject & {
     if: JsonSchema;
     then: JsonSchema;
     else: JsonSchema;
-}, refs: Refs) => string;
+}, refs: Refs) => SchemaRepresentation;

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

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

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

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

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

@@ -1 +1,2 @@
-export declare const parseNull: () => string;
+import { SchemaRepresentation } from "../Types.js";
+export declare const parseNull: () => SchemaRepresentation;

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

@@ -1,7 +1,7 @@
-import { JsonSchemaObject, Refs } from "../Types.js";
+import { JsonSchemaObject, Refs, SchemaRepresentation } from "../Types.js";
 /**
  * For compatibility with open api 3.0 nullable
  */
 export declare const parseNullable: (schema: JsonSchemaObject & {
     nullable: true;
-}, refs: Refs) => string;
+}, refs: Refs) => SchemaRepresentation;

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

@@ -1,4 +1,4 @@
-import { JsonSchemaObject } from "../Types.js";
+import { JsonSchemaObject, SchemaRepresentation } from "../Types.js";
 export declare const parseNumber: (schema: JsonSchemaObject & {
     type: "number" | "integer";
-}) => string;
+}) => SchemaRepresentation;

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

@@ -1,4 +1,4 @@
-import { JsonSchemaObject, Refs } from "../Types.js";
+import { JsonSchemaObject, Refs, SchemaRepresentation } from "../Types.js";
 export declare function parseObject(objectSchema: JsonSchemaObject & {
     type: "object";
-}, refs: Refs): string;
+}, refs: Refs): SchemaRepresentation;

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

@@ -1,4 +1,4 @@
-import { JsonSchemaObject, JsonSchema, Refs } from "../Types.js";
+import { JsonSchemaObject, JsonSchema, Refs, SchemaRepresentation } from "../Types.js";
 export declare const parseOneOf: (schema: JsonSchemaObject & {
     oneOf: JsonSchema[];
-}, refs: Refs) => string;
+}, refs: Refs) => SchemaRepresentation;

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

@@ -1,5 +1,5 @@
-import { Refs, JsonSchemaObject, JsonSchema, Serializable, SimpleDiscriminatedOneOfSchema } from "../Types.js";
-export declare const parseSchema: (schema: JsonSchema, refs?: Refs, blockMeta?: boolean) => string;
+import { Refs, JsonSchemaObject, JsonSchema, Serializable, SimpleDiscriminatedOneOfSchema, SchemaRepresentation } from "../Types.js";
+export declare const parseSchema: (schema: JsonSchema, refs?: Refs, blockMeta?: boolean) => SchemaRepresentation;
 export declare const its: {
     an: {
         object: (x: JsonSchemaObject) => x is JsonSchemaObject & {

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

@@ -1,2 +1,2 @@
-import { SimpleDiscriminatedOneOfSchema, Refs } from "../Types.js";
-export declare const parseSimpleDiscriminatedOneOf: (schema: SimpleDiscriminatedOneOfSchema, refs: Refs) => string;
+import { SimpleDiscriminatedOneOfSchema, Refs, SchemaRepresentation } from "../Types.js";
+export declare const parseSimpleDiscriminatedOneOf: (schema: SimpleDiscriminatedOneOfSchema, refs: Refs) => SchemaRepresentation;

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

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

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

@@ -1,9 +1,10 @@
-import type { Refs } from "../Types.js";
+import type { Refs, SchemaRepresentation } from "../Types.js";
 /**
- * Returns "z.unknown()" if the useUnknown option is enabled, otherwise "z.any()".
+ * Returns a SchemaRepresentation for z.unknown() if the useUnknown option is enabled,
+ * otherwise returns a SchemaRepresentation for z.any().
  * This helper is used throughout the library for fallback cases.
  *
  * @param refs - The refs object containing options
- * @returns The appropriate Zod schema string
+ * @returns The appropriate Zod schema representation
  */
-export declare const anyOrUnknown: (refs?: Refs) => string;
+export declare const anyOrUnknown: (refs?: Refs) => SchemaRepresentation;

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

@@ -0,0 +1,29 @@
+/**
+ * Small structured emitter for ESM/TypeScript snippets using the TS printer.
+ * Keeps formatting deterministic (double newlines between statements, trailing newline)
+ * while avoiding ad-hoc string concatenation.
+ */
+export type ConstStatement = {
+    name: string;
+    expression: string;
+    exported?: boolean;
+    typeAnnotation?: string;
+    jsdoc?: string;
+};
+export type DefaultExport = {
+    expression: string;
+    jsdoc?: string;
+};
+export type TypeExport = {
+    name: string;
+    type: string;
+    jsdoc?: string;
+};
+export declare class EsmEmitter {
+    #private;
+    addNamedImport(name: string, source: string): void;
+    addConst(statement: ConstStatement): void;
+    addDefaultExport(statement: DefaultExport): void;
+    addTypeExport(statement: TypeExport): void;
+    render(): string;
+}

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

@@ -0,0 +1,15 @@
+import { JsonSchema, Refs } from "../Types.js";
+/**
+ * Rule 1 from Zod v4: Put Object Types at Top-Level
+ *
+ * Extracts inline object schemas to top-level declarations when they have a title.
+ * This prevents embedding object schema declarations inside unions/intersections
+ * which can break recursive type inference.
+ *
+ * We extract any titled object schema, including those with:
+ * - $refs to other schemas (dependency ordering handles this)
+ * - Composition keywords (oneOf/anyOf/allOf for validation or extension)
+ *
+ * @returns The reference name if extracted, or null if not extractable
+ */
+export declare const extractInlineObject: (schema: JsonSchema, refs: Refs, path: (string | number)[]) => string | null;

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

@@ -0,0 +1,21 @@
+import { JsonSchema } from "../Types.js";
+import { NameForPathHook } from "./namingService.js";
+type LiftOptions = {
+    enable?: boolean;
+    nameForPath?: NameForPathHook;
+    parentName?: string;
+    dedup?: boolean;
+    allowInDefs?: boolean;
+};
+export type LiftResult = {
+    schema: JsonSchema;
+    defs: Record<string, JsonSchema>;
+    addedDefNames: string[];
+    pathToDefName: Map<string, string>;
+};
+/**
+ * Conservatively lift inline object-like schemas into top-level $defs.
+ * Skips when disabled or when candidates are ambiguous (contains $ref/dynamicRef).
+ */
+export declare const liftInlineObjects: (schema: JsonSchema, options: LiftOptions) => LiftResult;
+export {};

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

@@ -0,0 +1,21 @@
+export type NameForPathHook = (path: (string | number)[], ctx: {
+    parentName?: string;
+    existingNames: Set<string>;
+    branchInfo?: unknown;
+}) => string;
+export type GenerateNameOptions = {
+    parentName?: string;
+    path: (string | number)[];
+    existingNames: Set<string>;
+    branchInfo?: unknown;
+    nameForPath?: NameForPathHook;
+    schemaTitle?: string;
+};
+/**
+ * Generate a stable PascalCase name for a lifted inline schema.
+ * - Uses parentName as a base (default: Root).
+ * - Adds path segments (properties/indices) to disambiguate.
+ * - Applies suffixes to avoid collisions.
+ * - Allows an optional hook to override naming.
+ */
+export declare const generateNameFromPath: (options: GenerateNameOptions) => string;

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

@@ -0,0 +1,7 @@
+import { JsonSchemaObject, JsonSchema, Refs } from "../Types.js";
+export declare const resolveRef: (schemaNode: JsonSchemaObject, ref: string, refs: Refs) => {
+    schema: JsonSchema;
+    path: (string | number)[];
+    baseUri: string;
+    pointerKey: string;
+} | undefined;

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

@@ -0,0 +1,71 @@
+import { SchemaRepresentation } from "../Types.js";
+/**
+ * Builder functions for composing SchemaRepresentation objects.
+ * These track both the Zod expression and its TypeScript type simultaneously.
+ */
+export declare const zodString: () => SchemaRepresentation;
+export declare const zodNumber: () => SchemaRepresentation;
+export declare const zodBoolean: () => SchemaRepresentation;
+export declare const zodNull: () => SchemaRepresentation;
+export declare const zodUndefined: () => SchemaRepresentation;
+export declare const zodAny: () => SchemaRepresentation;
+export declare const zodUnknown: () => SchemaRepresentation;
+export declare const zodNever: () => SchemaRepresentation;
+export declare const zodBigInt: () => SchemaRepresentation;
+export declare const zodDate: () => SchemaRepresentation;
+export declare const zodRef: (schemaName: string) => SchemaRepresentation;
+export declare const zodLazy: (schemaName: string) => SchemaRepresentation;
+export declare const zodLazyTyped: (schemaName: string, innerType: string) => SchemaRepresentation;
+export declare const zodArray: (inner: SchemaRepresentation) => SchemaRepresentation;
+export declare const zodOptional: (inner: SchemaRepresentation) => SchemaRepresentation;
+export declare const zodNullable: (inner: SchemaRepresentation) => SchemaRepresentation;
+export declare const zodNullableWrapper: (inner: SchemaRepresentation) => SchemaRepresentation;
+export declare const zodDefault: (inner: SchemaRepresentation, defaultValue: string) => SchemaRepresentation;
+export declare const zodReadonly: (inner: SchemaRepresentation) => SchemaRepresentation;
+export declare const zodDescribe: (inner: SchemaRepresentation, description: string) => SchemaRepresentation;
+export declare const zodMeta: (inner: SchemaRepresentation, meta: string) => SchemaRepresentation;
+export declare const zodLiteral: (value: string) => SchemaRepresentation;
+export declare const zodEnum: (values: string[]) => SchemaRepresentation;
+export declare const zodUnion: (options: SchemaRepresentation[]) => SchemaRepresentation;
+export declare const zodDiscriminatedUnion: (discriminator: string, options: SchemaRepresentation[]) => SchemaRepresentation;
+export declare const zodIntersection: (left: SchemaRepresentation, right: SchemaRepresentation) => SchemaRepresentation;
+export declare const zodAnd: (base: SchemaRepresentation, other: SchemaRepresentation) => SchemaRepresentation;
+export declare const zodTuple: (items: SchemaRepresentation[]) => SchemaRepresentation;
+export declare const zodRecord: (key: SchemaRepresentation, value: SchemaRepresentation) => SchemaRepresentation;
+export declare const zodMap: (key: SchemaRepresentation, value: SchemaRepresentation) => SchemaRepresentation;
+export declare const zodSet: (value: SchemaRepresentation) => SchemaRepresentation;
+export declare const zodObject: (shape: Array<{
+    key: string;
+    rep: SchemaRepresentation;
+    isGetter?: boolean;
+}>) => SchemaRepresentation;
+export declare const zodStrictObject: (shape: Array<{
+    key: string;
+    rep: SchemaRepresentation;
+    isGetter?: boolean;
+}>) => SchemaRepresentation;
+export declare const zodCatchall: (base: SchemaRepresentation, catchallSchema: SchemaRepresentation) => SchemaRepresentation;
+export declare const zodSuperRefine: (base: SchemaRepresentation, refineFn: string) => SchemaRepresentation;
+export declare const zodRefine: (base: SchemaRepresentation, refineFn: string) => SchemaRepresentation;
+export declare const zodTransform: (base: SchemaRepresentation, transformFn: string) => SchemaRepresentation;
+export declare const zodPipe: (first: SchemaRepresentation, second: SchemaRepresentation) => SchemaRepresentation;
+export declare const zodCoerceString: () => SchemaRepresentation;
+export declare const zodCoerceNumber: () => SchemaRepresentation;
+export declare const zodCoerceBoolean: () => SchemaRepresentation;
+export declare const zodCoerceDate: () => SchemaRepresentation;
+export declare const zodChain: (base: SchemaRepresentation, method: string) => SchemaRepresentation;
+export declare const fromExpression: (expression: string) => SchemaRepresentation;
+/**
+ * Infers the TypeScript type from a Zod expression string.
+ * This is used for backward compatibility during migration.
+ */
+export declare const inferTypeFromExpression: (expr: string) => string;
+/**
+ * Check if an expression contains a reference to a recursive schema.
+ */
+export declare const containsRecursiveRef: (expr: string, cycleRefNames: Set<string> | undefined) => boolean;
+/**
+ * Determines if a property should use getter syntax based on its representation
+ * and the current schema context.
+ */
+export declare const shouldUseGetter: (rep: SchemaRepresentation, currentSchemaName: string | undefined, cycleRefNames: Set<string> | undefined, cycleComponentByName: Map<string, number> | undefined) => boolean;

package/dist/utils/anyOrUnknown.js

@@ -0,0 +1,13 @@
+/**
+ * Returns a SchemaRepresentation for z.unknown() if the useUnknown option is enabled,
+ * otherwise returns a SchemaRepresentation for z.any().
+ * This helper is used throughout the library for fallback cases.
+ *
+ * @param refs - The refs object containing options
+ * @returns The appropriate Zod schema representation
+ */
+export const anyOrUnknown = (refs) => {
+    return refs?.useUnknown
+        ? { expression: "z.unknown()", type: "z.ZodUnknown" }
+        : { expression: "z.any()", type: "z.ZodAny" };
+};

package/dist/{esm/utils → utils}/buildRefRegistry.js

@@ -1,9 +1,13 @@
 import { resolveUri } from "./resolveUri.js";
 export const buildRefRegistry = (schema, rootBaseUri = "root:///") => {
     const registry = new Map();
+    const seen = new WeakSet();
     const walk = (node, baseUri, path) => {
         if (typeof node !== "object" || node === null)
             return;
+        if (seen.has(node))
+            return;
+        seen.add(node);
         const obj = node;
         const nextBase = obj.$id ? resolveUri(baseUri, obj.$id) : baseUri;
         // Legacy recursive anchor

package/dist/utils/esmEmitter.js

@@ -0,0 +1,87 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _EsmEmitter_imports, _EsmEmitter_statements;
+import ts from "typescript";
+const normalizeJsdoc = (jsdoc) => {
+    if (!jsdoc)
+        return undefined;
+    const trimmed = jsdoc.trim();
+    if (!trimmed.startsWith("/**"))
+        return `* ${trimmed}`;
+    // Strip /** and */ and keep inner content
+    const withoutStart = trimmed.replace(/^\/\*\*/, "");
+    const withoutEnd = withoutStart.replace(/\*\/$/, "");
+    return withoutEnd.trim();
+};
+const attachJsdoc = (node, jsdoc) => {
+    const normalized = normalizeJsdoc(jsdoc);
+    if (!normalized)
+        return node;
+    return ts.addSyntheticLeadingComment(node, ts.SyntaxKind.MultiLineCommentTrivia, normalized, true);
+};
+const parseExpression = (expression) => {
+    const sf = ts.createSourceFile("expr.ts", `${expression};`, ts.ScriptTarget.ES2020, false, ts.ScriptKind.TS);
+    const stmt = sf.statements[0];
+    if (stmt && ts.isExpressionStatement(stmt)) {
+        return stmt.expression;
+    }
+    throw new Error(`Failed to parse expression: ${expression}`);
+};
+const parseType = (type) => {
+    const sf = ts.createSourceFile("type.ts", `type __T = ${type};`, ts.ScriptTarget.ES2020, false, ts.ScriptKind.TS);
+    const stmt = sf.statements[0];
+    if (stmt && ts.isTypeAliasDeclaration(stmt)) {
+        return stmt.type;
+    }
+    throw new Error(`Failed to parse type: ${type}`);
+};
+export class EsmEmitter {
+    constructor() {
+        _EsmEmitter_imports.set(this, new Map());
+        _EsmEmitter_statements.set(this, []);
+    }
+    addNamedImport(name, source) {
+        const set = __classPrivateFieldGet(this, _EsmEmitter_imports, "f").get(source) ?? new Set();
+        set.add(name);
+        __classPrivateFieldGet(this, _EsmEmitter_imports, "f").set(source, set);
+    }
+    addConst(statement) {
+        const initializer = parseExpression(statement.expression);
+        const typeNode = statement.typeAnnotation ? parseType(statement.typeAnnotation) : undefined;
+        const decl = ts.factory.createVariableDeclaration(statement.name, undefined, typeNode, initializer);
+        const modifiers = statement.exported ? [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)] : undefined;
+        const varStmt = ts.factory.createVariableStatement(modifiers, ts.factory.createVariableDeclarationList([decl], ts.NodeFlags.Const));
+        __classPrivateFieldGet(this, _EsmEmitter_statements, "f").push({ node: attachJsdoc(varStmt, statement.jsdoc) });
+    }
+    addDefaultExport(statement) {
+        const assignment = ts.factory.createExportAssignment(undefined, false, parseExpression(statement.expression));
+        __classPrivateFieldGet(this, _EsmEmitter_statements, "f").push({ node: attachJsdoc(assignment, statement.jsdoc) });
+    }
+    addTypeExport(statement) {
+        const modifiers = [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)];
+        const typeAlias = ts.factory.createTypeAliasDeclaration(modifiers, statement.name, undefined, parseType(statement.type));
+        __classPrivateFieldGet(this, _EsmEmitter_statements, "f").push({ node: attachJsdoc(typeAlias, statement.jsdoc), compact: true });
+    }
+    render() {
+        const printer = ts.createPrinter({
+            newLine: ts.NewLineKind.LineFeed,
+        });
+        const sf = ts.createSourceFile("out.ts", "", ts.ScriptTarget.ES2020, false, ts.ScriptKind.TS);
+        const importStmts = [...__classPrivateFieldGet(this, _EsmEmitter_imports, "f").entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([source, names]) => ts.factory.createImportDeclaration(undefined, ts.factory.createImportClause(false, undefined, ts.factory.createNamedImports([...names].sort().map((name) => ts.factory.createImportSpecifier(false, undefined, ts.factory.createIdentifier(name))))), ts.factory.createStringLiteral(source)));
+        const allStatements = [
+            ...importStmts.map((node) => ({ node })),
+            ...__classPrivateFieldGet(this, _EsmEmitter_statements, "f"),
+        ];
+        if (allStatements.length === 0)
+            return "";
+        const file = ts.factory.updateSourceFile(sf, ts.factory.createNodeArray(allStatements.map((s) => s.node)));
+        const printed = printer.printFile(file);
+        return printed.endsWith("\n") ? printed : `${printed}\n`;
+    }
+}
+_EsmEmitter_imports = new WeakMap(), _EsmEmitter_statements = new WeakMap();