@cerios/openapi-to-zod 1.4.0 → 1.5.0

package/dist/index.d.ts

@@ -1,56 +1,416 @@
-import { O as OpenApiGeneratorOptions } from './types-DZ4Bw-D5.js';
-export { C as CommonSchemaOptions, a as ConfigFile, E as ExecutionMode, b as OpenAPIParameter, c as OpenAPIRequestBody, d as OpenAPIResponse, e as OpenAPISchema, f as OpenAPISpec, g as OperationFilters, R as RequestOptions, h as ResponseOptions, i as defineConfig } from './types-DZ4Bw-D5.js';
+import { BaseGeneratorOptions, ExecutionMode, OpenAPISchema, OpenAPISpec, NamingOptions, LRUCache } from '@cerios/openapi-core';
+export { CircularReferenceError, CliOptionsError, ConfigValidationError, ExecutionMode, FileOperationError, GeneratorError, OpenAPIParameter, OpenAPIRequestBody, OpenAPIResponse, OpenAPISchema, OpenAPISpec, OperationFilters, SchemaGenerationError, SpecValidationError } from '@cerios/openapi-core';
 
 /**
- * Custom error classes for better error handling and debugging
+ * Re-export core types from @cerios/openapi-core
  */
+
 /**
- * Base error class for all generator errors
+ * Common options shared by both request and response contexts
  */
-declare class GeneratorError extends Error {
-    readonly code: string;
-    readonly context?: Record<string, unknown> | undefined;
-    constructor(message: string, code: string, context?: Record<string, unknown> | undefined);
+interface CommonSchemaOptions {
+    /**
+     * Object validation mode
+     * - 'strict': Uses z.strictObject() - no additional properties allowed
+     * - 'normal': Uses z.object() - additional properties allowed
+     * - 'loose': Uses z.looseObject() - explicitly allows additional properties
+     */
+    mode?: "strict" | "normal" | "loose";
+    /**
+     * Whether to add .describe() calls for better error messages
+     * @default false
+     */
+    useDescribe?: boolean;
+    /**
+     * Whether to include descriptions as JSDoc comments
+     */
+    includeDescriptions?: boolean;
+    /**
+     * Default nullable behavior when not explicitly specified in the schema
+     *
+     * When true: Properties without explicit nullable annotation are treated as nullable.
+     * This follows the industry de facto standard for OpenAPI 3.0.x where tooling convergence
+     * made "nullable by default" the safest assumption.
+     *
+     * When false (default): Properties are only nullable when explicitly marked with `nullable: true`
+     * (OpenAPI 3.0) or `type: ["string", "null"]` (OpenAPI 3.1).
+     *
+     * @default false
+     */
+    defaultNullable?: boolean;
+    /**
+     * Behavior for empty object schemas (objects with no properties defined)
+     *
+     * - 'strict': Uses z.strictObject({}) - no additional properties allowed
+     * - 'loose': Uses z.looseObject({}) - explicitly allows additional properties (Zod v4)
+     * - 'record': Uses z.record(z.string(), z.unknown()) - treat as arbitrary key-value map
+     *
+     * Note: This option controls nested/property-level empty objects.
+     * The top-level `mode` option controls how schema definitions are wrapped.
+     *
+     * @default 'loose'
+     */
+    emptyObjectBehavior?: "strict" | "loose" | "record";
 }
 /**
- * Error thrown when OpenAPI spec validation fails
+ * Request-specific options that can override root-level options
  */
-declare class SpecValidationError extends GeneratorError {
-    constructor(message: string, context?: Record<string, unknown>);
+interface RequestOptions extends CommonSchemaOptions {
 }
 /**
- * Error thrown when file operations fail
+ * Response-specific options that can override root-level options
  */
-declare class FileOperationError extends GeneratorError {
-    readonly filePath: string;
-    constructor(message: string, filePath: string, context?: Record<string, unknown>);
+interface ResponseOptions extends CommonSchemaOptions {
 }
 /**
- * Error thrown when config file is invalid
+ * Options for Zod schema generation from OpenAPI specifications
+ *
+ * Extends BaseGeneratorOptions from @cerios/openapi-core with Zod-specific options.
  */
-declare class ConfigValidationError extends GeneratorError {
-    readonly configPath?: string | undefined;
-    constructor(message: string, configPath?: string | undefined, context?: Record<string, unknown>);
+interface OpenApiGeneratorOptions extends BaseGeneratorOptions {
+    /**
+     * Object validation mode
+     * - 'strict': Uses z.strictObject() - no additional properties allowed
+     * - 'normal': Uses z.object() - additional properties allowed
+     * - 'loose': Uses z.looseObject() - explicitly allows additional properties
+     */
+    mode?: "strict" | "normal" | "loose";
+    /**
+     * Whether to add .describe() calls for better error messages
+     * @default false
+     */
+    useDescribe?: boolean;
+    /**
+     * Behavior for empty object schemas (objects with no properties defined)
+     *
+     * - 'strict': Uses z.strictObject({}) - no additional properties allowed
+     * - 'loose': Uses z.looseObject({}) - explicitly allows additional properties (Zod v4)
+     * - 'record': Uses z.record(z.string(), z.unknown()) - treat as arbitrary key-value map
+     *
+     * Note: This option controls nested/property-level empty objects.
+     * The top-level `mode` option controls how schema definitions are wrapped.
+     *
+     * @default 'loose'
+     */
+    emptyObjectBehavior?: "strict" | "loose" | "record";
+    /**
+     * Schema filtering mode
+     * - 'all': Generate all schemas (default)
+     * - 'request': Only include schemas suitable for requests (excludes readOnly)
+     * - 'response': Only include schemas suitable for responses (excludes writeOnly)
+     */
+    schemaType?: "all" | "request" | "response";
+    /**
+     * Fallback parsing method for unknown or missing content types
+     *
+     * When a content type is not recognized, this determines how the response is parsed:
+     * - "text": Use response.text() - safest, always succeeds (default)
+     * - "json": Use response.json() - may throw if response isn't valid JSON
+     * - "body": Use response.body() - returns raw Buffer
+     *
+     * A warning will be logged during generation when an unknown content type is encountered.
+     *
+     * @default "text"
+     */
+    fallbackContentTypeParsing?: "text" | "json" | "body";
+    /**
+     * Request-specific options that override root-level options
+     * Applied when schemas are used in request contexts
+     */
+    request?: RequestOptions;
+    /**
+     * Response-specific options that override root-level options
+     * Applied when schemas are used in response contexts
+     */
+    response?: ResponseOptions;
+    /**
+     * Header parameters to ignore during schema generation
+     * Supports glob patterns for flexible matching
+     * Case-insensitive matching (HTTP header semantics)
+     *
+     * @internal Used by Playwright generator
+     */
+    ignoreHeaders?: string[];
+    /**
+     * Cache size for pattern regex compilation
+     * Higher values improve performance for large specifications with many string patterns
+     * @default 1000
+     */
+    cacheSize?: number;
+    /**
+     * Custom regex pattern for date-time format validation
+     * Overrides the default z.iso.datetime() which requires ISO 8601 format with timezone suffix (Z)
+     *
+     * **Config File Formats:**
+     * - JSON/YAML configs: Must use string pattern (requires double-escaping: `\\d`)
+     * - TypeScript configs: Can use either string pattern OR RegExp literal (`/\d/`)
+     *
+     * **Common Patterns:**
+     * ```typescript
+     * // No timezone suffix (e.g., "2026-01-07T14:30:00")
+     * customDateTimeFormatRegex: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$'
+     * // OR in TypeScript config:
+     * customDateTimeFormatRegex: /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/
+     *
+     * // With milliseconds, no Z (e.g., "2026-01-07T14:30:00.123")
+     * customDateTimeFormatRegex: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}$'
+     *
+     * // Optional Z suffix (e.g., "2026-01-07T14:30:00" or "2026-01-07T14:30:00Z")
+     * customDateTimeFormatRegex: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z?$'
+     * ```
+     *
+     * @default "z.iso.datetime()" (requires Z suffix per ISO 8601)
+     */
+    customDateTimeFormatRegex?: string | RegExp;
+    /**
+     * Output path for Zod schemas when using separate type/schema files.
+     *
+     * When specified:
+     * - TypeScript types are generated to `outputTypes` (using @cerios/openapi-to-typescript)
+     * - Zod schemas are generated to `outputZodSchemas` with explicit type annotations
+     *
+     * This approach solves "Type instantiation is excessively deep" errors that occur
+     * with very large or deeply nested schemas when using `z.infer<typeof schema>`.
+     *
+     * Instead of generating:
+     * ```typescript
+     * export const userSchema = z.object({ ... });
+     * export type User = z.infer<typeof userSchema>; // Can cause TS errors
+     * ```
+     *
+     * Generates two files:
+     * ```typescript
+     * // types.ts
+     * export type User = { ... };
+     *
+     * // schemas.ts
+     * import type { User } from './types';
+     * export const userSchema: z.ZodType<User> = z.object({ ... });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * {
+     *   input: 'openapi.yaml',
+     *   outputTypes: 'src/generated/types.ts',
+     *   outputZodSchemas: 'src/generated/schemas.ts'
+     * }
+     * ```
+     */
+    outputZodSchemas?: string;
+    /**
+     * Format for generating enums in TypeScript types (when using outputZodSchemas)
+     * - 'union': Generate union of string literals
+     * - 'const-object': Generate const object with derived type (default)
+     *
+     * This option is passed to @cerios/openapi-to-typescript when generating types.
+     *
+     * @default 'const-object'
+     */
+    enumFormat?: "union" | "const-object";
+    /**
+     * Complexity threshold for switching from type annotation (`:`) to double assertion (`as unknown as`)
+     * in generated z.ZodType<T> declarations (only applies when outputZodSchemas is used).
+     *
+     * - When not set or 0: Always use annotation syntax `: z.ZodType<T>`
+     * - When set to a positive number: Use double assertion `as unknown as z.ZodType<T>` for schemas
+     *   with complexity >= threshold, annotation syntax for simpler schemas
+     *
+     * Type annotation (`:`) provides full TypeScript type checking but can cause
+     * "Type instantiation is excessively deep" errors on very large/complex schemas.
+     * Double assertion via `unknown` completely bypasses TypeScript's structural checking,
+     * ensuring compilation even for extremely large schemas.
+     *
+     * Complexity is calculated as: properties + (nested levels * 10) + (array/union members * 2)
+     *
+     * @example
+     * // Always use annotation (default, safest)
+     * typeAssertionThreshold: 0
+     *
+     * // Use double assertion for complex schemas (when experiencing TS depth errors)
+     * typeAssertionThreshold: 100
+     *
+     * @default 0 (always use annotation)
+     */
+    typeAssertionThreshold?: number;
 }
 /**
- * Error thrown when schema generation fails
+ * Root configuration file structure
  */
-declare class SchemaGenerationError extends GeneratorError {
-    readonly schemaName: string;
-    constructor(message: string, schemaName: string, context?: Record<string, unknown>);
+interface ConfigFile {
+    /**
+     * Global default options applied to all specifications
+     * Can be overridden by individual specification configurations
+     */
+    defaults?: Partial<Omit<OpenApiGeneratorOptions, "input" | "outputTypes" | "outputZodSchemas">>;
+    /**
+     * Array of OpenAPI specifications to process
+     * Each specification must provide `input` and at least one of:
+     * - `outputTypes` (preferred) - generates combined types+schemas OR just types (when outputZodSchemas is used)
+     * - `output` (deprecated alias for outputTypes)
+     * - `outputZodSchemas` (optional) - when specified, schemas go here with z.ZodType<TypeAlias> syntax
+     */
+    specs: (Omit<OpenApiGeneratorOptions, "outputTypes"> & {
+        outputTypes?: string;
+        /**
+         * @deprecated Use `outputTypes` instead.
+         */
+        output?: string;
+    })[];
+    /**
+     * Execution mode for batch processing
+     * @default "parallel"
+     */
+    executionMode?: ExecutionMode;
 }
 /**
- * Error thrown when circular reference is detected in schema
+ * Helper function for type-safe config file creation
+ * Provides IDE autocomplete and type checking for config files
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from '@cerios/openapi-to-zod';
+ *
+ * export default defineConfig({
+ *   defaults: {
+ *     mode: 'strict',
+ *     includeDescriptions: true
+ *   },
+ *   specs: [
+ *     { input: 'api-v1.yaml', outputTypes: 'schemas/v1.ts' },
+ *     { input: 'api-v2.yaml', outputTypes: 'schemas/v2.ts', mode: 'normal' }
+ *   ]
+ * });
+ * ```
  */
-declare class CircularReferenceError extends SchemaGenerationError {
-    readonly referencePath: string[];
-    constructor(schemaName: string, referencePath: string[]);
+declare function defineConfig(config: ConfigFile): ConfigFile;
+
+type ObjectMode = "strict" | "normal" | "loose";
+
+interface PropertyGeneratorContext {
+    spec: OpenAPISpec;
+    schemaDependencies: Map<string, Set<string>>;
+    schemaType: "all" | "request" | "response";
+    mode: ObjectMode;
+    includeDescriptions: boolean;
+    useDescribe: boolean;
+    namingOptions: NamingOptions;
+    stripSchemaPrefix?: string | string[];
+    /**
+     * Default nullable behavior when not explicitly specified
+     * @default false
+     */
+    defaultNullable: boolean;
+    /**
+     * Behavior for empty object schemas (objects with no properties defined)
+     * @default 'loose'
+     */
+    emptyObjectBehavior: "strict" | "loose" | "record";
+    /**
+     * Zod validation string for date-time format fields
+     * @default "z.iso.datetime()"
+     */
+    dateTimeValidation: string;
+    /**
+     * Instance-level cache for escaped regex patterns (parallel-safe)
+     */
+    patternCache: LRUCache<string, string>;
+    /**
+     * Whether types are generated in a separate file (imported) vs inline (z.infer)
+     * When true, z.lazy uses z.ZodType<TypeName> for proper type inference
+     * When false, z.lazy uses z.ZodTypeAny to avoid circular type references
+     * @default false
+     */
+    separateTypesFile: boolean;
 }
 /**
- * Error thrown when CLI options are invalid
+ * Property schema generator with memoization for performance
  */
-declare class CliOptionsError extends GeneratorError {
-    constructor(message: string, context?: Record<string, unknown>);
+declare class PropertyGenerator {
+    private context;
+    private filteredPropsCache;
+    private schemaCache;
+    private allOfConflicts;
+    private circularDependencies;
+    static readonly INCLUSION_RULES: {
+        readonly request: (schema: OpenAPISchema) => boolean;
+        readonly response: (schema: OpenAPISchema) => boolean;
+        readonly all: () => boolean;
+    };
+    constructor(context: PropertyGeneratorContext);
+    /**
+     * Set the schemas that are involved in circular dependency chains.
+     * These schemas will use z.lazy() for forward references.
+     */
+    setCircularDependencies(deps: Set<string>): void;
+    /**
+     * Get allOf conflicts detected during the last schema generation
+     * @returns Array of conflict description strings
+     */
+    getAllOfConflicts(): string[];
+    /**
+     * Clear tracked allOf conflicts (call before generating a new schema)
+     */
+    clearAllOfConflicts(): void;
+    /**
+     * Check if a property should be included based on schemaType and readOnly/writeOnly flags
+     */
+    shouldIncludeProperty(schema: OpenAPISchema): boolean;
+    /**
+     * Recursively filter any schema type (helper for composition schemas)
+     */
+    private filterSchemaRecursive;
+    /**
+     * Recursively filter properties in nested objects based on readOnly/writeOnly
+     * Performance optimized with memoization
+     */
+    private filterNestedProperties;
+    /**
+     * Resolve discriminator mapping to actual schema references
+     */
+    private resolveDiscriminatorMapping;
+    /**
+     * Resolve a $ref string to the actual schema
+     */
+    private resolveSchemaRef;
+    /**
+     * Resolve a schema name through any aliases to get the actual schema name
+     * If the schema is an alias (allOf with single $ref), return the target name
+     */
+    private resolveSchemaAlias;
+    /**
+     * Check if this is a circular dependency through aliases
+     */
+    private isCircularThroughAlias;
+    /**
+     * Generate union for multiple types (OpenAPI 3.1)
+     */
+    private generateMultiTypeUnion;
+    /**
+     * Apply unevaluatedProperties validation to a schema
+     */
+    private applyUnevaluatedProperties;
+    /**
+     * Generate Zod schema for a property
+     * @param schema - The OpenAPI schema to generate
+     * @param currentSchema - The name of the current schema being processed (for circular ref detection)
+     * @param isTopLevel - Whether this is a top-level schema definition
+     * @param suppressDefaultNullable - When true, don't apply defaultNullable (used when outer schema has explicit nullable: false)
+     */
+    generatePropertySchema(schema: OpenAPISchema, currentSchema?: string, isTopLevel?: boolean, suppressDefaultNullable?: boolean): string;
+    /**
+     * Generate inline object shape for use with .extend()
+     * Returns just the shape object literal: { prop1: z.string(), prop2: z.number() }
+     *
+     * This method is specifically for allOf compositions where we need to pass
+     * the shape directly to .extend() instead of using z.object({...}).shape.
+     * This avoids the .nullable().shape bug when inline objects have nullable: true.
+     *
+     * According to Zod docs (https://zod.dev/api?id=extend):
+     * - .extend() accepts an object of shape definitions
+     * - e.g., baseSchema.extend({ prop: z.string() })
+     */
+    generateInlineObjectShape(schema: OpenAPISchema, currentSchema?: string): string;
 }
 
 declare class OpenApiGenerator {
@@ -69,9 +429,16 @@ 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);
     /**
      * Generate schemas as a string (without writing to file)
+     * When separateSchemasMode is active, generates Zod schemas with explicit type annotations
      * @returns The generated TypeScript code as a string
      */
     generateString(): string;
@@ -80,39 +447,59 @@ declare class OpenApiGenerator {
      */
     private ensureDirectoryExists;
     /**
-     * Generate the complete output file
+     * Generate the complete output file(s)
+     * When separateSchemasMode is active, generates both types and schemas files
      */
     generate(): void;
     /**
-     * Resolve options for a specific context (request or response)
-     * Nested options silently override root-level options
+     * Generate Zod schemas with explicit type annotations (for outputZodSchemas mode)
+     * Generates schemas like: `export const userSchema: z.ZodType<User> = z.object({...})`
+     * @returns The generated Zod schemas TypeScript code
      */
-    private resolveOptionsForContext;
+    private generateSeparateSchemasString;
+    /**
+     * Generate TypeScript types as a string (for outputZodSchemas mode)
+     * Uses @cerios/openapi-to-typescript internally
+     * @returns The generated TypeScript types code
+     */
+    generateTypesString(): string;
     /**
-     * Analyze schema usage across the OpenAPI spec to determine if schemas
-     * are used in request, response, or both contexts
+     * Add explicit type annotation to a schema declaration
+     * Transforms: `export const userSchema = z.object({...})`
+     * To: `export const userSchema: z.ZodType<User> = z.object({...})` (annotation)
+     * Or: `export const userSchema = z.object({...}) as unknown as z.ZodType<User>` (double assertion)
+     *
+     * Uses double assertion via `unknown` when typeAssertionThreshold is set and schema complexity
+     * meets or exceeds the threshold. This completely bypasses TypeScript's structural checking
+     * to avoid "Type instantiation is excessively deep" errors on very large schemas.
+     *
+     * Also removes any `export type X = z.infer<...>` lines since types
+     * are imported from the separate types file.
      */
-    private analyzeSchemaUsage;
+    private addExplicitTypeAnnotation;
     /**
-     * Expand a set of schemas to include all transitively referenced schemas
+     * Type guard to check if a value is a Record<string, unknown>
      */
-    private expandTransitiveReferences;
+    private isRecordObject;
     /**
-     * Extract schema names from $ref and nested structures
+     * Calculate the complexity of a schema for threshold comparison
+     * Complexity formula: properties + (nested levels * 10) + (array/union members * 2)
      */
-    private extractSchemaRefs;
+    private calculateSchemaComplexity;
     /**
-     * Check if schema has readOnly properties
+     * Calculate relative import path from schema file to types file
      */
-    private hasReadOnlyProperties;
+    private calculateRelativeImportPath;
     /**
-     * Check if schema has writeOnly properties
+     * Resolve options for a specific context (request or response)
+     * Nested options silently override root-level options
      */
-    private hasWriteOnlyProperties;
+    private resolveOptionsForContext;
     /**
-     * Detect circular references and mark them as "both" context for safety
+     * Initialize schema usage map using core utilities with operation filtering
+     * This is a wrapper around core's analyzeSchemaUsage that adds operation filtering
      */
-    private detectCircularReferences;
+    private initializeSchemaUsage;
     /**
      * Validate the OpenAPI specification
      */
@@ -129,17 +516,6 @@ declare class OpenApiGenerator {
      * Generate query parameter schemas for each operation
      */
     private generateQueryParameterSchemas;
-    /**
-     * Generate a PascalCase method name from HTTP method and path
-     * Used as fallback when operationId is not available
-     * @internal
-     */
-    private generateMethodNameFromPath;
-    /**
-     * Capitalizes a path segment, handling special characters like dashes, underscores, and dots
-     * @internal
-     */
-    private capitalizeSegment;
     /**
      * Check if a header should be ignored based on filter patterns
      * @internal
@@ -163,6 +539,39 @@ declare class OpenApiGenerator {
      * Generate statistics about the generated schemas
      */
     private generateStats;
+    /**
+     * Pre-analyze schemas to detect circular dependencies before code generation.
+     * This allows the property generator to use z.lazy() for forward references.
+     */
+    private analyzeCircularDependencies;
+    /**
+     * Generate JSDoc warning for allOf conflicts
+     * @param conflicts Array of conflict description strings
+     * @returns JSDoc formatted warning string
+     */
+    private generateConflictJSDoc;
 }
 
-export { CircularReferenceError, CliOptionsError, ConfigValidationError, FileOperationError, GeneratorError, OpenApiGenerator, OpenApiGeneratorOptions, SchemaGenerationError, SpecValidationError };
+/**
+ * Build the Zod validation string for date-time format
+ * Pure function that returns the validation string without side effects
+ *
+ * @param pattern - Optional regex pattern (string or RegExp) for date-time validation
+ * @returns Zod validation string (either "z.iso.datetime()" or custom regex)
+ * @throws {Error} If the provided pattern is not a valid regular expression
+ *
+ * @example
+ * // Default (no pattern)
+ * buildDateTimeValidation() // Returns "z.iso.datetime()"
+ *
+ * @example
+ * // String pattern (for JSON/YAML configs)
+ * buildDateTimeValidation('^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$')
+ *
+ * @example
+ * // RegExp literal (TypeScript configs)
+ * buildDateTimeValidation(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/)
+ */
+declare function buildDateTimeValidation(pattern?: string | RegExp): string;
+
+export { type CommonSchemaOptions, type ConfigFile, OpenApiGenerator, type OpenApiGeneratorOptions, PropertyGenerator, type PropertyGeneratorContext, type RequestOptions, type ResponseOptions, buildDateTimeValidation, defineConfig };