@cerios/openapi-to-zod 1.3.1 → 1.4.0

package/dist/internal.d.mts

@@ -1,4 +1,4 @@
-import { E as ExecutionMode, g as OperationFilters, f as OpenAPISpec, b as OpenAPIParameter, c as OpenAPIRequestBody, d as OpenAPIResponse, e as OpenAPISchema } from './types-DZ4Bw-D5.mjs';
+import { E as ExecutionMode, e as OpenAPISchema, f as OpenAPISpec, g as OperationFilters, b as OpenAPIParameter, c as OpenAPIRequestBody, d as OpenAPIResponse } from './types-DZ4Bw-D5.mjs';
 import { z } from 'zod';
 import { Loader } from 'cosmiconfig';
 
@@ -46,6 +46,149 @@ declare function executeBatch<T>(specs: T[], executionMode: ExecutionMode | unde
  */
 declare function getBatchExitCode<T>(summary: BatchExecutionSummary<T>): number;
 
+/**
+ * @shared Simple LRU Cache implementation for performance optimization
+ * @since 1.0.0
+ * Utility used by core and playwright packages
+ * Prevents memory leaks from unbounded cache growth
+ */
+declare class LRUCache<K, V> {
+    private cache;
+    private maxSize;
+    constructor(maxSize: number);
+    get capacity(): number;
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+    clear(): void;
+    size(): number;
+}
+
+/**
+ * Name conversion utilities
+ */
+interface NamingOptions {
+    prefix?: string;
+    suffix?: string;
+}
+/**
+ * Convert schema name to camelCase with optional prefix/suffix
+ * Handles dotted names like "Company.Models.User" -> "companyModelsUser"
+ */
+declare function toCamelCase(str: string, options?: NamingOptions): string;
+/**
+ * @shared Convert enum value to PascalCase and sanitize for TypeScript enum keys
+ * @since 1.0.0
+ * Utility used by core and playwright packages
+ * Handles dotted names like "Company.Models.User" -> "CompanyModelsUser"
+ */
+declare function toPascalCase(str: string | number): string;
+
+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;
+    /**
+     * 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>;
+}
+/**
+ * Property schema generator with memoization for performance
+ */
+declare class PropertyGenerator {
+    private context;
+    private filteredPropsCache;
+    private schemaCache;
+    static readonly INCLUSION_RULES: {
+        readonly request: (schema: OpenAPISchema) => boolean;
+        readonly response: (schema: OpenAPISchema) => boolean;
+        readonly all: () => boolean;
+    };
+    constructor(context: PropertyGeneratorContext);
+    /**
+     * 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;
+}
+
 /**
  * @shared Zod schema for request/response options validation
  * @since 1.0.0
@@ -141,44 +284,6 @@ type FallbackContentTypeParsing = "json" | "text" | "body";
  */
 declare function getResponseParseMethod(contentType: string | undefined, fallback?: FallbackContentTypeParsing): ContentTypeParseResult;
 
-/**
- * @shared Simple LRU Cache implementation for performance optimization
- * @since 1.0.0
- * Utility used by core and playwright packages
- * Prevents memory leaks from unbounded cache growth
- */
-declare class LRUCache<K, V> {
-    private cache;
-    private maxSize;
-    constructor(maxSize: number);
-    get capacity(): number;
-    get(key: K): V | undefined;
-    set(key: K, value: V): void;
-    has(key: K): boolean;
-    clear(): void;
-    size(): number;
-}
-
-/**
- * Name conversion utilities
- */
-interface NamingOptions {
-    prefix?: string;
-    suffix?: string;
-}
-/**
- * Convert schema name to camelCase with optional prefix/suffix
- * Handles dotted names like "Company.Models.User" -> "companyModelsUser"
- */
-declare function toCamelCase(str: string, options?: NamingOptions): string;
-/**
- * @shared Convert enum value to PascalCase and sanitize for TypeScript enum keys
- * @since 1.0.0
- * Utility used by core and playwright packages
- * Handles dotted names like "Company.Models.User" -> "CompanyModelsUser"
- */
-declare function toPascalCase(str: string | number): string;
-
 /**
  * Filter statistics to track which operations were included/excluded
  */
@@ -341,23 +446,25 @@ declare function escapeJSDoc(str: string): string;
 declare function createTypeScriptLoader(): Loader;
 
 /**
- * Configure custom date-time format validation
- * Overrides the default z.iso.datetime() with a custom regex pattern
+ * Build the Zod validation string for date-time format
+ * Pure function that returns the validation string without side effects
  *
- * @param pattern - Regex pattern (string or RegExp) for date-time validation
+ * @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
- * // String pattern (required for JSON/YAML configs)
- * configureDateTimeFormat('^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$')
+ * // Default (no pattern)
+ * buildDateTimeValidation() // Returns "z.iso.datetime()"
  *
  * @example
- * // RegExp literal (TypeScript configs only)
- * configureDateTimeFormat(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/)
- */
-declare function configureDateTimeFormat(pattern?: string | RegExp): void;
-/**
- * Reset format map to defaults (useful for testing)
+ * // 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 resetFormatMap(): void;
+declare function buildDateTimeValidation(pattern?: string | RegExp): string;
 
-export { type BaseOperationFilters, type ContentTypeParseResult, type FallbackContentTypeParsing, type FilterStatistics, type Generator, LRUCache, OperationFiltersSchema, type RequestResponseOptions, RequestResponseOptionsSchema, configureDateTimeFormat, createFilterStatistics, createTypeScriptLoader, escapeJSDoc, executeBatch, formatConfigValidationError, formatFilterStatistics, getBatchExitCode, getResponseParseMethod, mergeParameters, resetFormatMap, resolveParameterRef, resolveRef, resolveRequestBodyRef, resolveResponseRef, shouldIncludeOperation, stripPathPrefix, stripPrefix, toCamelCase, toPascalCase, validateFilters };
+export { type BaseOperationFilters, type ContentTypeParseResult, type FallbackContentTypeParsing, type FilterStatistics, type Generator, LRUCache, OperationFiltersSchema, PropertyGenerator, type PropertyGeneratorContext, type RequestResponseOptions, RequestResponseOptionsSchema, buildDateTimeValidation, createFilterStatistics, createTypeScriptLoader, escapeJSDoc, executeBatch, formatConfigValidationError, formatFilterStatistics, getBatchExitCode, getResponseParseMethod, mergeParameters, resolveParameterRef, resolveRef, resolveRequestBodyRef, resolveResponseRef, shouldIncludeOperation, stripPathPrefix, stripPrefix, toCamelCase, toPascalCase, validateFilters };

package/dist/internal.d.ts

@@ -1,4 +1,4 @@
-import { E as ExecutionMode, g as OperationFilters, f as OpenAPISpec, b as OpenAPIParameter, c as OpenAPIRequestBody, d as OpenAPIResponse, e as OpenAPISchema } from './types-DZ4Bw-D5.js';
+import { E as ExecutionMode, e as OpenAPISchema, f as OpenAPISpec, g as OperationFilters, b as OpenAPIParameter, c as OpenAPIRequestBody, d as OpenAPIResponse } from './types-DZ4Bw-D5.js';
 import { z } from 'zod';
 import { Loader } from 'cosmiconfig';
 
@@ -46,6 +46,149 @@ declare function executeBatch<T>(specs: T[], executionMode: ExecutionMode | unde
  */
 declare function getBatchExitCode<T>(summary: BatchExecutionSummary<T>): number;
 
+/**
+ * @shared Simple LRU Cache implementation for performance optimization
+ * @since 1.0.0
+ * Utility used by core and playwright packages
+ * Prevents memory leaks from unbounded cache growth
+ */
+declare class LRUCache<K, V> {
+    private cache;
+    private maxSize;
+    constructor(maxSize: number);
+    get capacity(): number;
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+    clear(): void;
+    size(): number;
+}
+
+/**
+ * Name conversion utilities
+ */
+interface NamingOptions {
+    prefix?: string;
+    suffix?: string;
+}
+/**
+ * Convert schema name to camelCase with optional prefix/suffix
+ * Handles dotted names like "Company.Models.User" -> "companyModelsUser"
+ */
+declare function toCamelCase(str: string, options?: NamingOptions): string;
+/**
+ * @shared Convert enum value to PascalCase and sanitize for TypeScript enum keys
+ * @since 1.0.0
+ * Utility used by core and playwright packages
+ * Handles dotted names like "Company.Models.User" -> "CompanyModelsUser"
+ */
+declare function toPascalCase(str: string | number): string;
+
+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;
+    /**
+     * 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>;
+}
+/**
+ * Property schema generator with memoization for performance
+ */
+declare class PropertyGenerator {
+    private context;
+    private filteredPropsCache;
+    private schemaCache;
+    static readonly INCLUSION_RULES: {
+        readonly request: (schema: OpenAPISchema) => boolean;
+        readonly response: (schema: OpenAPISchema) => boolean;
+        readonly all: () => boolean;
+    };
+    constructor(context: PropertyGeneratorContext);
+    /**
+     * 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;
+}
+
 /**
  * @shared Zod schema for request/response options validation
  * @since 1.0.0
@@ -141,44 +284,6 @@ type FallbackContentTypeParsing = "json" | "text" | "body";
  */
 declare function getResponseParseMethod(contentType: string | undefined, fallback?: FallbackContentTypeParsing): ContentTypeParseResult;
 
-/**
- * @shared Simple LRU Cache implementation for performance optimization
- * @since 1.0.0
- * Utility used by core and playwright packages
- * Prevents memory leaks from unbounded cache growth
- */
-declare class LRUCache<K, V> {
-    private cache;
-    private maxSize;
-    constructor(maxSize: number);
-    get capacity(): number;
-    get(key: K): V | undefined;
-    set(key: K, value: V): void;
-    has(key: K): boolean;
-    clear(): void;
-    size(): number;
-}
-
-/**
- * Name conversion utilities
- */
-interface NamingOptions {
-    prefix?: string;
-    suffix?: string;
-}
-/**
- * Convert schema name to camelCase with optional prefix/suffix
- * Handles dotted names like "Company.Models.User" -> "companyModelsUser"
- */
-declare function toCamelCase(str: string, options?: NamingOptions): string;
-/**
- * @shared Convert enum value to PascalCase and sanitize for TypeScript enum keys
- * @since 1.0.0
- * Utility used by core and playwright packages
- * Handles dotted names like "Company.Models.User" -> "CompanyModelsUser"
- */
-declare function toPascalCase(str: string | number): string;
-
 /**
  * Filter statistics to track which operations were included/excluded
  */
@@ -341,23 +446,25 @@ declare function escapeJSDoc(str: string): string;
 declare function createTypeScriptLoader(): Loader;
 
 /**
- * Configure custom date-time format validation
- * Overrides the default z.iso.datetime() with a custom regex pattern
+ * Build the Zod validation string for date-time format
+ * Pure function that returns the validation string without side effects
  *
- * @param pattern - Regex pattern (string or RegExp) for date-time validation
+ * @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
- * // String pattern (required for JSON/YAML configs)
- * configureDateTimeFormat('^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$')
+ * // Default (no pattern)
+ * buildDateTimeValidation() // Returns "z.iso.datetime()"
  *
  * @example
- * // RegExp literal (TypeScript configs only)
- * configureDateTimeFormat(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/)
- */
-declare function configureDateTimeFormat(pattern?: string | RegExp): void;
-/**
- * Reset format map to defaults (useful for testing)
+ * // 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 resetFormatMap(): void;
+declare function buildDateTimeValidation(pattern?: string | RegExp): string;
 
-export { type BaseOperationFilters, type ContentTypeParseResult, type FallbackContentTypeParsing, type FilterStatistics, type Generator, LRUCache, OperationFiltersSchema, type RequestResponseOptions, RequestResponseOptionsSchema, configureDateTimeFormat, createFilterStatistics, createTypeScriptLoader, escapeJSDoc, executeBatch, formatConfigValidationError, formatFilterStatistics, getBatchExitCode, getResponseParseMethod, mergeParameters, resetFormatMap, resolveParameterRef, resolveRef, resolveRequestBodyRef, resolveResponseRef, shouldIncludeOperation, stripPathPrefix, stripPrefix, toCamelCase, toPascalCase, validateFilters };
+export { type BaseOperationFilters, type ContentTypeParseResult, type FallbackContentTypeParsing, type FilterStatistics, type Generator, LRUCache, OperationFiltersSchema, PropertyGenerator, type PropertyGeneratorContext, type RequestResponseOptions, RequestResponseOptionsSchema, buildDateTimeValidation, createFilterStatistics, createTypeScriptLoader, escapeJSDoc, executeBatch, formatConfigValidationError, formatFilterStatistics, getBatchExitCode, getResponseParseMethod, mergeParameters, resolveParameterRef, resolveRef, resolveRequestBodyRef, resolveResponseRef, shouldIncludeOperation, stripPathPrefix, stripPrefix, toCamelCase, toPascalCase, validateFilters };