@cerios/openapi-to-zod 0.3.0 → 0.5.0

package/dist/index.d.mts

@@ -113,7 +113,7 @@ interface RequestOptions extends CommonSchemaOptions {
  */
 interface ResponseOptions extends CommonSchemaOptions {
 }
-interface GeneratorOptions {
+interface OpenApiGeneratorOptions {
     /**
      * Object validation mode
      * - 'strict': Uses z.strictObject() - no additional properties allowed
@@ -187,6 +187,98 @@ interface GeneratorOptions {
      * 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[];
@@ -263,12 +355,12 @@ interface ConfigFile {
      * Global default options applied to all specs
      * Can be overridden by individual spec configurations
      */
-    defaults?: Partial<Omit<GeneratorOptions, "input" | "output">>;
+    defaults?: Partial<Omit<OpenApiGeneratorOptions, "input" | "output">>;
     /**
      * Array of OpenAPI specifications to process
      * Each spec must have input and output paths
      */
-    specs: GeneratorOptions[];
+    specs: OpenApiGeneratorOptions[];
     /**
      * Execution mode for batch processing
      * @default "parallel"
@@ -297,7 +389,7 @@ interface ConfigFile {
  */
 declare function defineConfig(config: ConfigFile): ConfigFile;
 
-declare class ZodSchemaGenerator {
+declare class OpenApiGenerator {
     private schemas;
     private types;
     private enums;
@@ -311,7 +403,8 @@ declare class ZodSchemaGenerator {
     private requestOptions;
     private responseOptions;
     private needsZodImport;
-    constructor(options: GeneratorOptions);
+    private filterStats;
+    constructor(options: OpenApiGeneratorOptions);
     /**
      * Generate schemas as a string (without writing to file)
      * @returns The generated TypeScript code as a string
@@ -377,6 +470,11 @@ declare class ZodSchemaGenerator {
      * Generate query parameter schemas for each operation
      */
     private generateQueryParameterSchemas;
+    /**
+     * Generate header parameter schemas for each operation
+     * Header parameters are always string type (HTTP header semantics)
+     */
+    private generateHeaderParameterSchemas;
     /**
      * Generate Zod type for a query parameter schema
      */
@@ -412,4 +510,55 @@ declare class ZodSchemaGenerator {
     private generateStats;
 }
 
-export { CircularReferenceError, CliOptionsError, type ConfigFile, ConfigValidationError, type ExecutionMode, FileOperationError, GeneratorError, type GeneratorOptions, type OpenAPISpec, SchemaGenerationError, SpecValidationError, ZodSchemaGenerator, defineConfig };
+/**
+ * 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 ConfigFile, ConfigValidationError, type ExecutionMode, FileOperationError, type FilterStatistics, GeneratorError, type OpenAPISpec, OpenApiGenerator, type OpenApiGeneratorOptions, type OperationFilters, SchemaGenerationError, SpecValidationError, createFilterStatistics, defineConfig, formatFilterStatistics, shouldIncludeOperation, validateFilters };

package/dist/index.d.ts

@@ -113,7 +113,7 @@ interface RequestOptions extends CommonSchemaOptions {
  */
 interface ResponseOptions extends CommonSchemaOptions {
 }
-interface GeneratorOptions {
+interface OpenApiGeneratorOptions {
     /**
      * Object validation mode
      * - 'strict': Uses z.strictObject() - no additional properties allowed
@@ -187,6 +187,98 @@ interface GeneratorOptions {
      * 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[];
@@ -263,12 +355,12 @@ interface ConfigFile {
      * Global default options applied to all specs
      * Can be overridden by individual spec configurations
      */
-    defaults?: Partial<Omit<GeneratorOptions, "input" | "output">>;
+    defaults?: Partial<Omit<OpenApiGeneratorOptions, "input" | "output">>;
     /**
      * Array of OpenAPI specifications to process
      * Each spec must have input and output paths
      */
-    specs: GeneratorOptions[];
+    specs: OpenApiGeneratorOptions[];
     /**
      * Execution mode for batch processing
      * @default "parallel"
@@ -297,7 +389,7 @@ interface ConfigFile {
  */
 declare function defineConfig(config: ConfigFile): ConfigFile;
 
-declare class ZodSchemaGenerator {
+declare class OpenApiGenerator {
     private schemas;
     private types;
     private enums;
@@ -311,7 +403,8 @@ declare class ZodSchemaGenerator {
     private requestOptions;
     private responseOptions;
     private needsZodImport;
-    constructor(options: GeneratorOptions);
+    private filterStats;
+    constructor(options: OpenApiGeneratorOptions);
     /**
      * Generate schemas as a string (without writing to file)
      * @returns The generated TypeScript code as a string
@@ -377,6 +470,11 @@ declare class ZodSchemaGenerator {
      * Generate query parameter schemas for each operation
      */
     private generateQueryParameterSchemas;
+    /**
+     * Generate header parameter schemas for each operation
+     * Header parameters are always string type (HTTP header semantics)
+     */
+    private generateHeaderParameterSchemas;
     /**
      * Generate Zod type for a query parameter schema
      */
@@ -412,4 +510,55 @@ declare class ZodSchemaGenerator {
     private generateStats;
 }
 
-export { CircularReferenceError, CliOptionsError, type ConfigFile, ConfigValidationError, type ExecutionMode, FileOperationError, GeneratorError, type GeneratorOptions, type OpenAPISpec, SchemaGenerationError, SpecValidationError, ZodSchemaGenerator, defineConfig };
+/**
+ * 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 ConfigFile, ConfigValidationError, type ExecutionMode, FileOperationError, type FilterStatistics, GeneratorError, type OpenAPISpec, OpenApiGenerator, type OpenApiGeneratorOptions, type OperationFilters, SchemaGenerationError, SpecValidationError, createFilterStatistics, defineConfig, formatFilterStatistics, shouldIncludeOperation, validateFilters };