@cerios/openapi-to-zod 0.5.3 → 1.0.0

package/dist/index.d.mts

@@ -1,3 +1,6 @@
+import { O as OpenApiGeneratorOptions } from './types-BjoP91vk.mjs';
+export { C as CommonSchemaOptions, a as ConfigFile, E as ExecutionMode, b as OpenAPISchema, c as OpenAPISpec, d as OperationFilters, R as RequestOptions, e as ResponseOptions, f as defineConfig } from './types-BjoP91vk.mjs';
+
 /**
  * Custom error classes for better error handling and debugging
  */
@@ -50,356 +53,14 @@ declare class CliOptionsError extends GeneratorError {
     constructor(message: string, context?: Record<string, unknown>);
 }
 
-/**
- * Type generation mode
- * - 'inferred': Generate Zod schemas with z.infer<typeof schema> types (default)
- * - 'native': Generate native TypeScript types without Zod schemas
- */
-type TypeMode = "inferred" | "native";
-/**
- * Native enum generation type (used when typeMode is 'native')
- * - 'union': Generate union types like 'a' | 'b' | 'c' (default)
- * - 'enum': Generate TypeScript enums like enum StatusEnum { A = 'a', B = 'b' }
- */
-type NativeEnumType = "union" | "enum";
-/**
- * Common options shared by both request and response contexts
- */
-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";
-    /**
-     * Enum generation type
-     * - 'zod': Uses z.enum() with inferred types (default)
-     * - 'typescript': Uses TypeScript enums with z.enum() referencing them
-     */
-    enumType?: "zod" | "typescript";
-    /**
-     * Whether to add .describe() calls for better error messages
-     * @default false
-     */
-    useDescribe?: boolean;
-    /**
-     * Whether to include descriptions as JSDoc comments
-     */
-    includeDescriptions?: boolean;
-}
-/**
- * Request-specific options that can override root-level options
- * Requests support native TypeScript type generation as an alternative to Zod schemas
- */
-interface RequestOptions extends CommonSchemaOptions {
-    /**
-     * Type generation mode
-     * - 'inferred': Generate Zod schemas with z.infer types (default)
-     * - 'native': Generate native TypeScript types without Zod validation
-     */
-    typeMode?: TypeMode;
-    /**
-     * Native enum generation type (when typeMode is 'native')
-     * - 'union': Generate union types (default)
-     * - 'enum': Generate TypeScript enums
-     */
-    nativeEnumType?: NativeEnumType;
-}
-/**
- * Response-specific options that can override root-level options
- * Responses always use Zod schemas for runtime validation
- */
-interface ResponseOptions extends CommonSchemaOptions {
-}
-interface OpenApiGeneratorOptions {
-    /**
-     * 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";
-    /**
-     * Input OpenAPI YAML file path
-     */
-    input: string;
-    /**
-     * Output TypeScript file path
-     * Optional when using string generation methods (generateString)
-     * Required when calling generate() to write to a file
-     */
-    output?: string;
-    /**
-     * Whether to include descriptions as JSDoc comments
-     */
-    includeDescriptions?: boolean;
-    /**
-     * Enum generation type
-     * - 'zod': Uses z.enum() with inferred types (default)
-     * - 'typescript': Uses TypeScript enums with z.enum() referencing them
-     */
-    enumType?: "zod" | "typescript";
-    /**
-     * Whether to add .describe() calls for better error messages
-     * @default false
-     */
-    useDescribe?: boolean;
-    /**
-     * 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";
-    /**
-     * Prefix to add to all generated schema names
-     * @example "api" -> "apiUserSchema"
-     */
-    prefix?: string;
-    /**
-     * Suffix to add before "Schema" in generated names
-     * @example "dto" -> "userDtoSchema"
-     */
-    suffix?: string;
-    /**
-     * Whether to include generation statistics in output file
-     * @default true
-     */
-    showStats?: boolean;
-    /**
-     * Native enum generation type (when typeMode is 'native')
-     * - 'union': Generate union types (default)
-     * - 'enum': Generate TypeScript enums with 'Enum' suffix
-     * @default 'union'
-     */
-    nativeEnumType?: NativeEnumType;
-    /**
-     * Request-specific options that override root-level options
-     * Applied when schemas are used in request contexts
-     * Supports native TypeScript type generation
-     */
-    request?: RequestOptions;
-    /**
-     * Response-specific options that override root-level options
-     * Applied when schemas are used in response contexts
-     * Always generates Zod schemas for runtime validation
-     */
-    response?: ResponseOptions;
-    /**
-     * Filter which operations to include/exclude from generation
-     * Useful for generating separate schemas for different API subsets
-     *
-     * Filtering logic:
-     * 1. If no filters specified, all operations are included
-     * 2. Empty arrays are treated as "no constraint" (not as "exclude all")
-     * 3. Include filters are applied first (allowlist)
-     * 4. Exclude filters are applied second (blocklist)
-     * 5. Exclude rules always win over include rules
-     *
-     * Supports glob patterns for paths and operationIds (e.g., "/api/v1/**", "get*")
-     *
-     * @example
-     * // Only generate schemas for user-related endpoints
-     * operationFilters: {
-     *   includeTags: ["users"]
-     * }
-     *
-     * @example
-     * // Generate only GET endpoints, excluding deprecated ones
-     * operationFilters: {
-     *   includeMethods: ["get"],
-     *   excludeDeprecated: true
-     * }
-     *
-     * @example
-     * // Generate only v1 API endpoints
-     * operationFilters: {
-     *   includePaths: ["/api/v1/**"]
-     * }
-     */
-    operationFilters?: OperationFilters;
-}
-/**
- * Operation filtering options
- * Controls which operations from the OpenAPI spec are included in generation
- */
-interface OperationFilters {
-    /**
-     * Include only operations with these tags
-     * If specified, only operations with at least one matching tag are included
-     * Empty array = no constraint
-     */
-    includeTags?: string[];
-    /**
-     * Exclude operations with these tags
-     * Operations with any matching tag are excluded
-     * Empty array = no constraint
-     */
-    excludeTags?: string[];
-    /**
-     * Include only operations matching these path patterns
-     * Supports glob patterns (e.g., "/users/**", "/api/v1/*")
-     * Empty array = no constraint
-     */
-    includePaths?: string[];
-    /**
-     * Exclude operations matching these path patterns
-     * Supports glob patterns (e.g., "/internal/**", "/admin/*")
-     * Empty array = no constraint
-     */
-    excludePaths?: string[];
-    /**
-     * Include only these HTTP methods
-     * Valid values: "get", "post", "put", "patch", "delete", "head", "options"
-     * Empty array = no constraint
-     */
-    includeMethods?: string[];
-    /**
-     * Exclude these HTTP methods
-     * Valid values: "get", "post", "put", "patch", "delete", "head", "options"
-     * Empty array = no constraint
-     */
-    excludeMethods?: string[];
-    /**
-     * Include only operations matching these operationId patterns
-     * Supports glob patterns (e.g., "getUser*", "*Admin")
-     * Empty array = no constraint
-     */
-    includeOperationIds?: string[];
-    /**
-     * Exclude operations matching these operationId patterns
-     * Supports glob patterns (e.g., "deleteUser*", "*Internal")
-     * Empty array = no constraint
-     */
-    excludeOperationIds?: string[];
-    /**
-     * Whether to exclude deprecated operations
-     * @default false
-     */
-    excludeDeprecated?: boolean;
-}
-interface OpenAPISchema {
-    type?: string | string[];
-    format?: string;
-    enum?: (string | number)[];
-    const?: string | number | boolean | null;
-    properties?: Record<string, OpenAPISchema>;
-    required?: string[];
-    items?: OpenAPISchema;
-    prefixItems?: OpenAPISchema[];
-    allOf?: OpenAPISchema[];
-    oneOf?: OpenAPISchema[];
-    anyOf?: OpenAPISchema[];
-    $ref?: string;
-    nullable?: boolean;
-    minLength?: number;
-    maxLength?: number;
-    minimum?: number;
-    maximum?: number;
-    exclusiveMinimum?: boolean | number;
-    exclusiveMaximum?: boolean | number;
-    multipleOf?: number;
-    pattern?: string;
-    description?: string;
-    title?: string;
-    example?: any;
-    examples?: any[];
-    additionalProperties?: boolean | OpenAPISchema;
-    minProperties?: number;
-    maxProperties?: number;
-    minItems?: number;
-    maxItems?: number;
-    uniqueItems?: boolean;
-    contains?: OpenAPISchema;
-    minContains?: number;
-    maxContains?: number;
-    discriminator?: {
-        propertyName: string;
-        mapping?: Record<string, string>;
-    };
-    readOnly?: boolean;
-    writeOnly?: boolean;
-    deprecated?: boolean;
-    dependentRequired?: Record<string, string[]>;
-    dependencies?: Record<string, string[] | OpenAPISchema>;
-    patternProperties?: Record<string, OpenAPISchema>;
-    propertyNames?: OpenAPISchema;
-    contentMediaType?: string;
-    contentEncoding?: string;
-    not?: OpenAPISchema;
-    if?: OpenAPISchema;
-    then?: OpenAPISchema;
-    else?: OpenAPISchema;
-    unevaluatedProperties?: boolean | OpenAPISchema;
-    unevaluatedItems?: boolean | OpenAPISchema;
-}
-interface OpenAPISpec {
-    components?: {
-        schemas?: Record<string, OpenAPISchema>;
-    };
-    paths?: Record<string, any>;
-}
-/**
- * Execution mode for batch processing
- * - 'parallel': Process all specs concurrently (default, faster)
- * - 'sequential': Process specs one at a time (safer for resource constraints)
- */
-type ExecutionMode = "parallel" | "sequential";
-/**
- * Root configuration file structure
- */
-interface ConfigFile {
-    /**
-     * Global default options applied to all specs
-     * Can be overridden by individual spec configurations
-     */
-    defaults?: Partial<Omit<OpenApiGeneratorOptions, "input" | "output">>;
-    /**
-     * Array of OpenAPI specifications to process
-     * Each spec must have input and output paths
-     */
-    specs: OpenApiGeneratorOptions[];
-    /**
-     * Execution mode for batch processing
-     * @default "parallel"
-     */
-    executionMode?: ExecutionMode;
-}
-/**
- * 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', output: 'schemas/v1.ts' },
- *     { input: 'api-v2.yaml', output: 'schemas/v2.ts', mode: 'normal' }
- *   ]
- * });
- * ```
- */
-declare function defineConfig(config: ConfigFile): ConfigFile;
-
 declare class OpenApiGenerator {
     private schemas;
     private types;
-    private enums;
-    private nativeEnums;
     private schemaDependencies;
     private options;
     private spec;
     private propertyGenerator;
     private schemaUsageMap;
-    private schemaTypeModeMap;
     private requestOptions;
     private responseOptions;
     private needsZodImport;
@@ -421,7 +82,6 @@ declare class OpenApiGenerator {
     /**
      * Resolve options for a specific context (request or response)
      * Nested options silently override root-level options
-     * Response schemas always use 'inferred' mode (Zod schemas)
      */
     private resolveOptionsForContext;
     /**
@@ -449,11 +109,6 @@ declare class OpenApiGenerator {
      * Detect circular references and mark them as "both" context for safety
      */
     private detectCircularReferences;
-    /**
-     * Determine the typeMode for each schema based on its usage context
-     * Response schemas always use 'inferred' mode
-     */
-    private determineSchemaTypeModes;
     /**
      * Validate the OpenAPI specification
      */
@@ -470,6 +125,11 @@ declare class OpenApiGenerator {
      * Generate query parameter schemas for each operation
      */
     private generateQueryParameterSchemas;
+    /**
+     * Check if a header should be ignored based on filter patterns
+     * @internal
+     */
+    private shouldIgnoreHeader;
     /**
      * Generate header parameter schemas for each operation
      * Header parameters are always string type (HTTP header semantics)
@@ -479,26 +139,6 @@ declare class OpenApiGenerator {
      * Generate Zod type for a query parameter schema
      */
     private generateQueryParamType;
-    /**
-     * Generate native TypeScript enum
-     */
-    private generateNativeEnum;
-    /**
-     * Convert string to valid enum key
-     */
-    private toEnumKey;
-    /**
-     * Add constraint annotations to JSDoc for native types
-     */
-    private addConstraintsToJSDoc;
-    /**
-     * Generate native TypeScript type definition from OpenAPI schema
-     */
-    private generateNativeTypeDefinition;
-    /**
-     * Generate TypeScript object type definition
-     */
-    private generateObjectType;
     /**
      * Topological sort for schema dependencies
      * Returns schemas in the order they should be declared
@@ -510,55 +150,4 @@ declare class OpenApiGenerator {
     private generateStats;
 }
 
-/**
- * Filter statistics to track which operations were included/excluded
- */
-interface FilterStatistics {
-    totalOperations: number;
-    includedOperations: number;
-    filteredByTags: number;
-    filteredByPaths: number;
-    filteredByMethods: number;
-    filteredByOperationIds: number;
-    filteredByDeprecated: number;
-}
-/**
- * Create a new filter statistics object with all counters initialized to zero
- */
-declare function createFilterStatistics(): FilterStatistics;
-/**
- * Determine if an operation should be included based on filter criteria
- *
- * Filter logic:
- * 1. If no filters specified, include all operations
- * 2. Empty arrays are treated as "no constraint" (not as "exclude all")
- * 3. Include filters are applied first (allowlist)
- * 4. Exclude filters are applied second (blocklist)
- * 5. Exclude rules always win over include rules
- *
- * @param operation - The OpenAPI operation object
- * @param path - The operation path (e.g., "/users/{id}")
- * @param method - The HTTP method (e.g., "get", "post")
- * @param filters - Optional filter configuration
- * @param stats - Optional statistics object to track filtering reasons
- * @returns true if the operation should be included, false otherwise
- */
-declare function shouldIncludeOperation(operation: any, path: string, method: string, filters?: OperationFilters, stats?: FilterStatistics): boolean;
-/**
- * Validate filter statistics and emit warnings for filters that matched nothing
- * Helps users debug filter configurations that might be too restrictive or contain typos
- *
- * @param stats - Filter statistics object
- * @param filters - The filter configuration to validate
- */
-declare function validateFilters(stats: FilterStatistics, filters?: OperationFilters): void;
-/**
- * Format filter statistics for display in generated output
- * Returns a formatted string suitable for inclusion in comments
- *
- * @param stats - Filter statistics object
- * @returns Formatted statistics string
- */
-declare function formatFilterStatistics(stats: FilterStatistics): string;
-
-export { CircularReferenceError, CliOptionsError, type CommonSchemaOptions, type ConfigFile, ConfigValidationError, type ExecutionMode, FileOperationError, type FilterStatistics, GeneratorError, type NativeEnumType, type OpenAPISchema, type OpenAPISpec, OpenApiGenerator, type OpenApiGeneratorOptions, type OperationFilters, type RequestOptions, type ResponseOptions, SchemaGenerationError, SpecValidationError, type TypeMode, createFilterStatistics, defineConfig, formatFilterStatistics, shouldIncludeOperation, validateFilters };
+export { CircularReferenceError, CliOptionsError, ConfigValidationError, FileOperationError, GeneratorError, OpenApiGenerator, OpenApiGeneratorOptions, SchemaGenerationError, SpecValidationError };