@cerios/openapi-to-zod 0.6.0 → 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,298 +53,6 @@ declare class CliOptionsError extends GeneratorError {
     constructor(message: string, context?: Record<string, unknown>);
 }
 
-/**
- * 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";
-    /**
-     * 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
- */
-interface RequestOptions extends CommonSchemaOptions {
-}
-/**
- * Response-specific options that can override root-level options
- */
-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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
@@ -414,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)
@@ -434,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 OpenAPISchema, type OpenAPISpec, OpenApiGenerator, type OpenApiGeneratorOptions, type OperationFilters, type RequestOptions, type ResponseOptions, SchemaGenerationError, SpecValidationError, createFilterStatistics, defineConfig, formatFilterStatistics, shouldIncludeOperation, validateFilters };
+export { CircularReferenceError, CliOptionsError, ConfigValidationError, FileOperationError, GeneratorError, OpenApiGenerator, OpenApiGeneratorOptions, SchemaGenerationError, SpecValidationError };