@cerios/openapi-to-zod 1.5.1 → 1.6.1

package/dist/index.d.mts

@@ -234,6 +234,18 @@ interface OpenApiGeneratorOptions extends BaseGeneratorOptions {
      */
     typeAssertionThreshold?: number;
 }
+/**
+ * Internal options that extend public options with internal-only properties
+ * @internal
+ */
+interface InternalOpenApiGeneratorOptions extends OpenApiGeneratorOptions {
+    /**
+     * Whether to include the auto-generated header comment in output
+     * Used internally by downstream packages for consistent branding
+     * @internal
+     */
+    includeHeader?: boolean;
+}
 /**
  * Root configuration file structure
  */
@@ -322,6 +334,11 @@ interface PropertyGeneratorContext {
      * @default false
      */
     separateTypesFile: boolean;
+    /**
+     * Warning function for non-fatal issues during schema generation
+     * If not provided, warnings are silently ignored
+     */
+    warn?: (message: string) => void;
 }
 /**
  * Property schema generator with memoization for performance
@@ -429,13 +446,13 @@ declare class OpenApiGenerator {
     private patternCache;
     /** Instance-level date-time validation string for parallel-safe execution */
     private dateTimeValidation;
-    /** Track total allOf conflicts detected across all schemas */
-    private allOfConflictCount;
     /** Track schemas involved in circular dependency chains */
     private circularDependencies;
     /** Separate schemas mode - when outputZodSchemas is specified */
     private separateSchemasMode;
-    constructor(options: OpenApiGeneratorOptions);
+    /** Warning collector for deferred output */
+    private readonly warningCollector;
+    constructor(options: OpenApiGeneratorOptions | InternalOpenApiGeneratorOptions);
     /**
      * Generate schemas as a string (without writing to file)
      * When separateSchemasMode is active, generates Zod schemas with explicit type annotations
@@ -574,4 +591,4 @@ declare class OpenApiGenerator {
  */
 declare function buildDateTimeValidation(pattern?: string | RegExp): string;
 
-export { type CommonSchemaOptions, type ConfigFile, OpenApiGenerator, type OpenApiGeneratorOptions, PropertyGenerator, type PropertyGeneratorContext, type RequestOptions, type ResponseOptions, buildDateTimeValidation, defineConfig };
+export { type CommonSchemaOptions, type ConfigFile, type InternalOpenApiGeneratorOptions, OpenApiGenerator, type OpenApiGeneratorOptions, PropertyGenerator, type PropertyGeneratorContext, type RequestOptions, type ResponseOptions, buildDateTimeValidation, defineConfig };

package/dist/index.d.ts

@@ -234,6 +234,18 @@ interface OpenApiGeneratorOptions extends BaseGeneratorOptions {
      */
     typeAssertionThreshold?: number;
 }
+/**
+ * Internal options that extend public options with internal-only properties
+ * @internal
+ */
+interface InternalOpenApiGeneratorOptions extends OpenApiGeneratorOptions {
+    /**
+     * Whether to include the auto-generated header comment in output
+     * Used internally by downstream packages for consistent branding
+     * @internal
+     */
+    includeHeader?: boolean;
+}
 /**
  * Root configuration file structure
  */
@@ -322,6 +334,11 @@ interface PropertyGeneratorContext {
      * @default false
      */
     separateTypesFile: boolean;
+    /**
+     * Warning function for non-fatal issues during schema generation
+     * If not provided, warnings are silently ignored
+     */
+    warn?: (message: string) => void;
 }
 /**
  * Property schema generator with memoization for performance
@@ -429,13 +446,13 @@ declare class OpenApiGenerator {
     private patternCache;
     /** Instance-level date-time validation string for parallel-safe execution */
     private dateTimeValidation;
-    /** Track total allOf conflicts detected across all schemas */
-    private allOfConflictCount;
     /** Track schemas involved in circular dependency chains */
     private circularDependencies;
     /** Separate schemas mode - when outputZodSchemas is specified */
     private separateSchemasMode;
-    constructor(options: OpenApiGeneratorOptions);
+    /** Warning collector for deferred output */
+    private readonly warningCollector;
+    constructor(options: OpenApiGeneratorOptions | InternalOpenApiGeneratorOptions);
     /**
      * Generate schemas as a string (without writing to file)
      * When separateSchemasMode is active, generates Zod schemas with explicit type annotations
@@ -574,4 +591,4 @@ declare class OpenApiGenerator {
  */
 declare function buildDateTimeValidation(pattern?: string | RegExp): string;
 
-export { type CommonSchemaOptions, type ConfigFile, OpenApiGenerator, type OpenApiGeneratorOptions, PropertyGenerator, type PropertyGeneratorContext, type RequestOptions, type ResponseOptions, buildDateTimeValidation, defineConfig };
+export { type CommonSchemaOptions, type ConfigFile, type InternalOpenApiGeneratorOptions, OpenApiGenerator, type OpenApiGeneratorOptions, PropertyGenerator, type PropertyGeneratorContext, type RequestOptions, type ResponseOptions, buildDateTimeValidation, defineConfig };

package/dist/index.js

@@ -112,9 +112,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")',
@@ -135,8 +137,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) {
@@ -214,6 +217,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: [] };
@@ -222,7 +226,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);
@@ -1184,7 +1188,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
       );
@@ -1207,7 +1212,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,
@@ -1230,7 +1236,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,
@@ -1421,8 +1428,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;
@@ -1430,6 +1435,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,
@@ -1448,13 +1458,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);
@@ -1479,7 +1492,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);
+      }
     });
   }
   /**
@@ -1488,7 +1504,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 });
     }
@@ -1505,9 +1521,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("");
@@ -1534,6 +1567,7 @@ var OpenApiGenerator = class {
         output.push("");
       }
     }
+    this.warningCollector.flush();
     return output.join("\n");
   }
   /**
@@ -1573,6 +1607,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)
@@ -1580,7 +1615,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 "";
@@ -1599,9 +1634,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("");
@@ -1639,8 +1689,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,
@@ -1651,9 +1701,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
@@ -1972,14 +2033,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$/, `
@@ -2343,8 +2406,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("//");