@cerios/openapi-to-zod 1.5.0 → 1.6.0

package/README.md

@@ -188,6 +188,7 @@ Examples:
 | `name`                | `string`                               | Optional identifier for logging                                                                                   |
 | `input`               | `string`                               | Input OpenAPI YAML file path (required)                                                                           |
 | `outputTypes`         | `string`                               | Preferred output TypeScript file path (required unless deprecated `output` is set)                                |
+| `outputZodSchemas`    | `string`                               | Separate output path for Zod schemas (recommended for circular references, see below)                             |
 | `output`              | `string`                               | Deprecated alias for `outputTypes`; allowed for backward compatibility                                            |
 | `mode`                | `"strict"` \| `"normal"` \| `"loose"`  | Validation mode for top-level schemas (default: `"normal"`)                                                       |
 | `emptyObjectBehavior` | `"strict"` \| `"loose"` \| `"record"`  | How to handle empty objects (default: `"loose"`)                                                                  |
@@ -1087,6 +1088,54 @@ export default defineConfig({
 4. **Better Code Completion**: Easier to find schemas in IDE autocomplete
 5. **Flexible Pattern Matching**: Use regex for dynamic prefixes
 
+## Circular References and `z.lazy()`
+
+When your OpenAPI spec contains circular references (schemas that reference themselves or each other), Zod requires using `z.lazy()` for recursive types. However, this creates a TypeScript challenge:
+
+```typescript
+// Combined mode - can cause TypeScript errors
+export const nodeSchema = z.object({
+	id: z.string(),
+	parent: z.lazy(() => nodeSchema).optional(), // ❌ Type errors with circular inference
+});
+export type Node = z.infer<typeof nodeSchema>; // Circular type reference
+```
+
+**Recommendation:** Use separate type and schema files (`outputZodSchemas`) for specs with circular references:
+
+```typescript
+import { defineConfig } from "@cerios/openapi-to-zod";
+
+export default defineConfig({
+	specs: [
+		{
+			input: "openapi.yaml",
+			outputTypes: "src/generated/types.ts", // TypeScript types
+			outputZodSchemas: "src/generated/schemas.ts", // Zod schemas
+		},
+	],
+});
+```
+
+This generates proper forward-declared types:
+
+```typescript
+// types.ts
+export interface Node {
+	id?: string;
+	parent?: Node;
+}
+
+// schemas.ts
+import type { Node } from "./types";
+export const nodeSchema: z.ZodType<Node> = z.object({
+	id: z.string().optional(),
+	parent: z.lazy(() => nodeSchema).optional(),
+});
+```
+
+This approach also helps avoid "Type instantiation is excessively deep" errors (TS2589) with large schemas.
+
 ## Generation Statistics
 
 Statistics are **included by default** in generated files. Use `showStats: false` to disable:

package/dist/cli.js

@@ -5132,9 +5132,11 @@ function isDiscriminatorRequired(schemas, discriminator, context) {
   };
 }
 function generateUnion(schemas, discriminator, isNullable2, context, options, currentSchema) {
+  var _a, _b;
   if (schemas.length === 0) {
-    console.warn(
-      "[openapi-to-zod] Warning: Empty oneOf/anyOf array encountered. This is likely a malformed OpenAPI spec. Generating z.never() as fallback."
+    (_a = context.warn) == null ? void 0 : _a.call(
+      context,
+      "Empty oneOf/anyOf array encountered. This is likely a malformed OpenAPI spec. Generating z.never() as fallback."
     );
     return wrapNullable(
       'z.never().describe("Empty oneOf/anyOf in OpenAPI spec - no valid schema defined")',
@@ -5155,8 +5157,9 @@ function generateUnion(schemas, discriminator, isNullable2, context, options, cu
     }
     const discriminatorCheck = isDiscriminatorRequired(resolvedSchemas, discriminator, context);
     if (!discriminatorCheck.valid) {
-      console.warn(
-        `[openapi-to-zod] Warning: Discriminator "${discriminator}" is not required in schemas: ${discriminatorCheck.invalidSchemas.join(", ")}. Falling back to z.union() instead of z.discriminatedUnion().`
+      (_b = context.warn) == null ? void 0 : _b.call(
+        context,
+        `Discriminator "${discriminator}" is not required in schemas: ${discriminatorCheck.invalidSchemas.join(", ")}. Falling back to z.union() instead of z.discriminatedUnion().`
       );
       let schemaStrings3 = resolvedSchemas.map((s) => context.generatePropertySchema(s, currentSchema, false, true));
       if (options == null ? void 0 : options.passthrough) {
@@ -5234,6 +5237,7 @@ function detectConflictingProperties(schemas, context) {
   return conflicts;
 }
 function generateAllOf(schemas, isNullable2, context, currentSchema) {
+  var _a;
   if (schemas.length === 1) {
     const singleSchema = context.generatePropertySchema(schemas[0], currentSchema, false, true);
     return { schema: wrapNullable(singleSchema, isNullable2), conflicts: [] };
@@ -5242,7 +5246,7 @@ function generateAllOf(schemas, isNullable2, context, currentSchema) {
   const uniqueConflicts = [...new Set(conflicts)];
   if (uniqueConflicts.length > 0) {
     for (const conflict of uniqueConflicts) {
-      console.warn(`[openapi-to-zod] Warning: allOf composition conflict - ${conflict}`);
+      (_a = context.warn) == null ? void 0 : _a.call(context, `allOf composition conflict - ${conflict}`);
     }
   }
   const allObjects = schemas.every((s) => s.type === "object" || s.properties || s.$ref || s.allOf);
@@ -6163,7 +6167,8 @@ var _PropertyGenerator = class _PropertyGenerator {
         {
           generatePropertySchema: this.generatePropertySchema.bind(this),
           generateInlineObjectShape: this.generateInlineObjectShape.bind(this),
-          resolveSchemaRef: this.resolveSchemaRef.bind(this)
+          resolveSchemaRef: this.resolveSchemaRef.bind(this),
+          warn: this.context.warn
         },
         currentSchema
       );
@@ -6186,7 +6191,8 @@ var _PropertyGenerator = class _PropertyGenerator {
         {
           generatePropertySchema: this.generatePropertySchema.bind(this),
           resolveDiscriminatorMapping: this.resolveDiscriminatorMapping.bind(this),
-          resolveSchemaRef: this.resolveSchemaRef.bind(this)
+          resolveSchemaRef: this.resolveSchemaRef.bind(this),
+          warn: this.context.warn
         },
         {
           passthrough: needsPassthrough,
@@ -6209,7 +6215,8 @@ var _PropertyGenerator = class _PropertyGenerator {
         {
           generatePropertySchema: this.generatePropertySchema.bind(this),
           resolveDiscriminatorMapping: this.resolveDiscriminatorMapping.bind(this),
-          resolveSchemaRef: this.resolveSchemaRef.bind(this)
+          resolveSchemaRef: this.resolveSchemaRef.bind(this),
+          warn: this.context.warn
         },
         {
           passthrough: needsPassthrough,
@@ -6364,8 +6371,6 @@ var OpenApiGenerator = class {
     this.schemaUsageMap = /* @__PURE__ */ new Map();
     this.needsZodImport = true;
     this.filterStats = (0, import_openapi_core6.createFilterStatistics)();
-    /** Track total allOf conflicts detected across all schemas */
-    this.allOfConflictCount = 0;
     /** Track schemas involved in circular dependency chains */
     this.circularDependencies = /* @__PURE__ */ new Set();
     var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
@@ -6373,6 +6378,11 @@ var OpenApiGenerator = class {
       throw new import_openapi_core6.ConfigurationError("Input path is required", { providedOptions: options });
     }
     this.separateSchemasMode = Boolean(options.outputZodSchemas);
+    const showWarnings = options.showWarnings !== false;
+    this.warningCollector = new import_openapi_core6.WarningCollector({
+      packageName: "@cerios/openapi-to-zod",
+      enabled: showWarnings
+    });
     this.options = {
       mode: options.mode || "normal",
       input: options.input,
@@ -6391,13 +6401,16 @@ var OpenApiGenerator = class {
       stripPathPrefix: options.stripPathPrefix,
       useOperationId: (_f = options.useOperationId) != null ? _f : true,
       showStats: (_g = options.showStats) != null ? _g : true,
+      showWarnings,
       request: options.request,
       response: options.response,
       operationFilters: options.operationFilters,
       ignoreHeaders: options.ignoreHeaders,
       cacheSize: (_h = options.cacheSize) != null ? _h : 1e3,
       batchSize: (_i = options.batchSize) != null ? _i : 10,
-      customDateTimeFormatRegex: options.customDateTimeFormatRegex
+      customDateTimeFormatRegex: options.customDateTimeFormatRegex,
+      includeHeader: options.includeHeader,
+      fileHeader: options.fileHeader
     };
     this.patternCache = new import_openapi_core6.LRUCache((_j = this.options.cacheSize) != null ? _j : 1e3);
     this.dateTimeValidation = buildDateTimeValidation(this.options.customDateTimeFormatRegex);
@@ -6422,7 +6435,10 @@ var OpenApiGenerator = class {
       stripSchemaPrefix: this.options.stripSchemaPrefix,
       dateTimeValidation: this.dateTimeValidation,
       patternCache: this.patternCache,
-      separateTypesFile: this.separateSchemasMode
+      separateTypesFile: this.separateSchemasMode,
+      warn: (msg) => {
+        this.warningCollector.add(msg);
+      }
     });
   }
   /**
@@ -6431,7 +6447,7 @@ var OpenApiGenerator = class {
    * @returns The generated TypeScript code as a string
    */
   generateString() {
-    var _a;
+    var _a, _b, _c;
     if (!((_a = this.spec.components) == null ? void 0 : _a.schemas)) {
       throw new import_openapi_core6.SpecValidationError("No schemas found in OpenAPI spec", { filePath: this.options.input });
     }
@@ -6448,9 +6464,26 @@ var OpenApiGenerator = class {
     }
     this.generateQueryParameterSchemas();
     this.generateHeaderParameterSchemas();
-    (0, import_openapi_core6.validateFilters)(this.filterStats, this.options.operationFilters);
+    (0, import_openapi_core6.validateFilters)(this.filterStats, this.options.operationFilters, (msg) => {
+      this.warningCollector.add(msg);
+    });
     const orderedSchemaNames = this.topologicalSort();
-    const output = ["// Auto-generated by @cerios/openapi-to-zod", "// Do not edit this file manually", ""];
+    const output = [];
+    const customHeader = (0, import_openapi_core6.generateCustomFileHeader)(this.options.fileHeader);
+    if (customHeader) {
+      output.push(customHeader.trimEnd());
+      output.push("");
+    }
+    if (this.options.includeHeader !== false) {
+      output.push(
+        (0, import_openapi_core6.generateFileHeader)({
+          packageName: "@cerios/openapi-to-zod",
+          apiTitle: (_b = this.spec.info) == null ? void 0 : _b.title,
+          apiVersion: (_c = this.spec.info) == null ? void 0 : _c.version
+        }).trimEnd()
+      );
+      output.push("");
+    }
     if (this.options.showStats === true) {
       output.push(...this.generateStats());
       output.push("");
@@ -6477,6 +6510,7 @@ var OpenApiGenerator = class {
         output.push("");
       }
     }
+    this.warningCollector.flush();
     return output.join("\n");
   }
   /**
@@ -6516,6 +6550,7 @@ var OpenApiGenerator = class {
       (0, import_node_fs.writeFileSync)(normalizedOutput, output);
       console.log(`  \u2713 Generated ${normalizedOutput}`);
     }
+    this.warningCollector.flush();
   }
   /**
    * Generate Zod schemas with explicit type annotations (for outputZodSchemas mode)
@@ -6523,7 +6558,7 @@ var OpenApiGenerator = class {
    * @returns The generated Zod schemas TypeScript code
    */
   generateSeparateSchemasString() {
-    var _a;
+    var _a, _b, _c;
     const schemas = (_a = this.spec.components) == null ? void 0 : _a.schemas;
     if (!schemas) {
       return "";
@@ -6542,9 +6577,24 @@ var OpenApiGenerator = class {
     }
     this.generateQueryParameterSchemas();
     this.generateHeaderParameterSchemas();
-    (0, import_openapi_core6.validateFilters)(this.filterStats, this.options.operationFilters);
+    (0, import_openapi_core6.validateFilters)(this.filterStats, this.options.operationFilters, (msg) => {
+      this.warningCollector.add(msg);
+    });
     const orderedSchemaNames = this.topologicalSort();
-    const output = ["// Auto-generated by @cerios/openapi-to-zod", "// Do not edit this file manually", ""];
+    const output = [];
+    const customHeader = (0, import_openapi_core6.generateCustomFileHeader)(this.options.fileHeader);
+    if (customHeader) {
+      output.push(customHeader.trimEnd());
+      output.push("");
+    }
+    output.push(
+      (0, import_openapi_core6.generateFileHeader)({
+        packageName: "@cerios/openapi-to-zod",
+        apiTitle: (_b = this.spec.info) == null ? void 0 : _b.title,
+        apiVersion: (_c = this.spec.info) == null ? void 0 : _c.version
+      }).trimEnd()
+    );
+    output.push("");
     if (this.options.showStats === true) {
       output.push(...this.generateStats());
       output.push("");
@@ -6582,8 +6632,8 @@ var OpenApiGenerator = class {
    * @returns The generated TypeScript types code
    */
   generateTypesString() {
-    var _a;
-    const tsGenerator = new import_openapi_to_typescript.TypeScriptGenerator({
+    var _a, _b, _c;
+    const internalOptions = {
       input: this.options.input,
       outputTypes: this.options.outputTypes,
       includeDescriptions: this.options.includeDescriptions,
@@ -6594,9 +6644,20 @@ var OpenApiGenerator = class {
       stripPathPrefix: this.options.stripPathPrefix,
       operationFilters: this.options.operationFilters,
       showStats: this.options.showStats,
-      enumFormat: (_a = this.options.enumFormat) != null ? _a : "const-object"
+      enumFormat: (_a = this.options.enumFormat) != null ? _a : "const-object",
+      includeHeader: false,
+      // We add our own header for consistent branding
+      showWarnings: false
+      // We handle warnings ourselves
+    };
+    const tsGenerator = new import_openapi_to_typescript.TypeScriptGenerator(internalOptions);
+    const customHeader = (0, import_openapi_core6.generateCustomFileHeader)(this.options.fileHeader);
+    const header = (0, import_openapi_core6.generateFileHeader)({
+      packageName: "@cerios/openapi-to-zod",
+      apiTitle: (_b = this.spec.info) == null ? void 0 : _b.title,
+      apiVersion: (_c = this.spec.info) == null ? void 0 : _c.version
     });
-    return tsGenerator.generateString();
+    return customHeader + header + tsGenerator.generateString();
   }
   /**
    * Add explicit type annotation to a schema declaration
@@ -6915,14 +6976,16 @@ ${typeCode}`;
       stripSchemaPrefix: this.options.stripSchemaPrefix,
       dateTimeValidation: this.dateTimeValidation,
       patternCache: this.patternCache,
-      separateTypesFile: this.separateSchemasMode
+      separateTypesFile: this.separateSchemasMode,
+      warn: (msg) => {
+        this.warningCollector.add(msg);
+      }
     });
     this.propertyGenerator.setCircularDependencies(this.circularDependencies);
     this.propertyGenerator.clearAllOfConflicts();
     const zodSchema = this.propertyGenerator.generatePropertySchema(schema, name, true);
     const allOfConflicts = this.propertyGenerator.getAllOfConflicts();
     if (allOfConflicts.length > 0) {
-      this.allOfConflictCount += allOfConflicts.length;
       const conflictWarning = this.generateConflictJSDoc(allOfConflicts);
       if (jsdoc) {
         jsdoc = jsdoc.replace(/ \*\/\n$/, `
@@ -7286,8 +7349,7 @@ ${propsCode}
       `//   Total schemas: ${stats.totalSchemas}`,
       `//   Circular references: ${stats.withCircularRefs}`,
       `//   Discriminated unions: ${stats.withDiscriminators}`,
-      `//   With constraints: ${stats.withConstraints}`,
-      `//   AllOf conflicts: ${this.allOfConflictCount}`
+      `//   With constraints: ${stats.withConstraints}`
     ];
     if (this.options.operationFilters && this.filterStats.totalOperations > 0) {
       output.push("//");
@@ -7519,6 +7581,7 @@ function mergeConfigWithDefaults(config) {
       showStats: defaults.showStats,
       customDateTimeFormatRegex: defaults.customDateTimeFormatRegex,
       enumFormat: defaults.enumFormat,
+      fileHeader: defaults.fileHeader,
       // Override with spec-specific values
       ...specWithoutDeprecatedOutput,
       outputTypes: resolvedOutputTypes