		The MIT License (MIT)
		Copyright © 2025 Cerios

		Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

		The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

		THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

+163

README.md

		# @cerios/openapi-core

		Core utilities for parsing and processing OpenAPI specifications. This package provides the shared foundation for OpenAPI code generators.

		## Installation

		```bash
		npm install @cerios/openapi-core
		```

		## Features

		- 🔍 OpenAPI Parsing - Parse OpenAPI 3.0/3.1 YAML and JSON specifications
		- 🔗 Reference Resolution - Resolve `$ref` references throughout the spec
		- 🏷️ Operation Filtering - Filter operations by tags, paths, and methods
		- 🛠️ Utility Functions - Common utilities for schema processing
		- 📦 Batch Execution - Parallel and sequential execution of generators
		- 🧪 Test Fixtures - Shared OpenAPI fixtures for testing

		## Usage

		```typescript
		import {
		shouldIncludeOperation,
		toPascalCase,
		toCamelCase,
		resolveRefName,
		LRUCache,
		loadOpenAPISpec,
		} from "@cerios/openapi-core";

		// Load and parse an OpenAPI spec
		const spec = await loadOpenAPISpec("openapi.yaml");

		// Extract schema name from $ref
		const schemaName = resolveRefName("#/components/schemas/User"); // "User"

		// Filter operations
		const include = shouldIncludeOperation(operation, path, method, {
		includeTags: ["users"],
		excludePaths: ["/internal/*"],
		});

		// Name utilities
		const className = toPascalCase("user-profile"); // "UserProfile"
		const methodName = toCamelCase("get-user-by-id"); // "getUserById"
		```

		## API Reference

		### Types

		- `OpenAPISpec` - OpenAPI specification structure
		- `OpenAPISchema` - Schema definition structure
		- `OpenAPIParameter` - Parameter definition
		- `OpenAPIRequestBody` - Request body definition
		- `OpenAPIResponse` - Response definition
		- `OperationFilters` - Operation filtering options
		- `ExecutionMode` - Parallel/sequential execution mode
		- `BaseGeneratorOptions` - Base options for all generators

		### Spec Parsing

		- `loadOpenAPISpec()` - Load and parse an OpenAPI spec file
		- `loadOpenAPISpecCached()` - Load spec with LRU caching

		### Reference Resolution

		- `resolveRefName()` - Extract name from `$ref` path
		- `resolveRequestBodyRef()` - Resolve request body references
		- `resolveResponseRef()` - Resolve response references
		- `mergeParameters()` - Merge path and operation parameters

		### Operation Filtering

		- `shouldIncludeOperation()` - Check if operation matches filters
		- `validateFilters()` - Validate filter configuration
		- `createFilterStatistics()` - Create filter statistics tracker
		- `formatFilterStatistics()` - Format statistics for display

		### Name Utilities

		- `toPascalCase()` - Convert string to PascalCase
		- `toCamelCase()` - Convert string to camelCase
		- `resolveRefName()` - Extract name from $ref path
		- `getOperationName()` - Get operation name from operationId or path
		- `generateMethodNameFromPath()` - Generate method name from path
		- `capitalize()` - Capitalize first letter

		### Method Naming

		- `pathToPascalCase()` - Convert path to PascalCase (e.g., `/users/{userId}` → `UsersByUserId`)
		- `generateHttpMethodName()` - Generate method name from HTTP method + path
		- `extractPathParams()` - Extract parameter names from path template
		- `sanitizeOperationId()` - Sanitize operationId for TypeScript
		- `sanitizeParamName()` - Sanitize parameter name for TypeScript

		### Schema Traversal

		- `extractSchemaRefs()` - Extract all `$ref` names from schema tree
		- `expandTransitiveReferences()` - Expand to include transitively referenced schemas
		- `detectCircularReferences()` - Detect circular reference chains
		- `topologicalSortSchemas()` - Sort schemas by dependencies
		- `analyzeSchemaUsage()` - Analyze request/response context usage
		- `classifyEnumType()` - Classify enum values as string/number/boolean/mixed

		### Header Filters

		- `shouldIgnoreHeader()` - Check if header matches ignore patterns
		- `filterHeaders()` - Filter headers excluding ignored ones
		- `validateIgnorePatterns()` - Validate and warn about unmatched patterns

		### Pattern Utilities

		- `stripPrefix()` - Strip prefix from schema names
		- `stripSuffix()` - Strip suffix from strings
		- `stripAffixes()` - Strip both prefix and suffix
		- `stripPathPrefix()` - Strip prefix from paths (supports glob)
		- `isGlobPattern()` - Check if string is a glob pattern

		### String Utilities

		- `escapeJSDoc()` - Escape JSDoc content
		- `escapeDescription()` - Escape description text
		- `escapePattern()` - Escape regex pattern
		- `getPrimaryType()` - Get primary type from schema
		- `hasMultipleTypes()` - Check if schema has multiple types
		- `isNullable()` - Check if schema is nullable

		### Content Type Utilities

		- `getResponseParseMethod()` - Determine response parsing method (json, text, blob, etc.)

		### Config Loader

		- `createConfigLoader()` - Factory for type-safe config loaders with cosmiconfig + Zod validation
		- `mergeCliWithConfig()` - Merge CLI options with config values (CLI takes precedence)

		### CLI Utilities

		- `findSpecFiles()` - Find OpenAPI spec files in directory
		- `getRandomCeriosMessage()` - Get random CLI greeting message

		### Classes

		- `LRUCache` - Least Recently Used cache implementation
		- `GeneratorError` - Base error class for generators
		- `SpecValidationError` - OpenAPI spec validation errors
		- `FileOperationError` - File I/O errors
		- `ConfigValidationError` - Configuration errors
		- `CircularReferenceError` - Circular reference detection errors
		- `CliOptionsError` - CLI options validation errors
		- `SchemaGenerationError` - Schema generation errors

		### Batch Execution

		- `executeBatch()` - Execute multiple generators
		- `getBatchExitCode()` - Calculate exit code from results
		- `Generator` - Interface for generator implementations

		## License

		MIT

+72

-72

package.json

		{
		"name": "@cerios/openapi-core",
		"version": "0.0.1",
		"description": "Core utilities for parsing and processing OpenAPI specifications. Shared foundation for OpenAPI code generators.",
		"keywords": [
		"api",
		"cerios",
		"core",
		"openapi",
		"parser",
		"schema",
		"typescript",
		"yaml"
		],
		"homepage": "https://github.com/CeriosTesting/openapi-to-zod#readme",
		"bugs": {
		"url": "https://github.com/CeriosTesting/openapi-to-zod/issues"
		},
		"license": "MIT",
		"author": "Ronald Veth - Cerios",
		"repository": {
		"type": "git",
		"url": "git+https://github.com/CeriosTesting/openapi-to-zod.git",
		"directory": "packages/openapi-core"
		},
		"files": [
		"dist"
		],
		"type": "commonjs",
		"sideEffects": false,
		"main": "./dist/index.js",
		"module": "./dist/index.mjs",
		"types": "./dist/index.d.ts",
		"exports": {
		".": {
		"import": {
		"types": "./dist/index.d.mts",
		"default": "./dist/index.mjs"
		},
		"require": {
		"types": "./dist/index.d.ts",
		"default": "./dist/index.js"
		}
		},
		"./package.json": "./package.json"
		},
		"publishConfig": {
		"access": "public",
		"provenance": false
		},
		"scripts": {
		"build": "tsup",
		"check-exports": "attw --pack .",
		"compile": "tsc --noEmit",
		"dev": "tsup --watch",
		"pack": "pnpm pack --pack-destination=../..",
		"test": "vitest run"
		},
		"dependencies": {
		"cosmiconfig": "catalog:",
		"esbuild": "catalog:",
		"minimatch": "catalog:",
		"yaml": "catalog:",
		"zod": "catalog:"
		},
		"devDependencies": {
		"@arethetypeswrong/cli": "catalog:",
		"@types/node": "catalog:",
		"tsup": "catalog:",
		"typescript": "catalog:",
		"vitest": "catalog:"
		}
		}
		"name": "@cerios/openapi-core",
		"version": "1.0.0",
		"description": "Core utilities for parsing and processing OpenAPI specifications. Shared foundation for OpenAPI code generators.",
		"keywords": [
		"api",
		"cerios",
		"core",
		"openapi",
		"parser",
		"schema",
		"typescript",
		"yaml"
		],
		"homepage": "https://github.com/CeriosTesting/openapi-codegen#readme",
		"bugs": {
		"url": "https://github.com/CeriosTesting/openapi-codegen/issues"
		},
		"license": "MIT",
		"author": "Ronald Veth - Cerios",
		"repository": {
		"type": "git",
		"url": "git+https://github.com/CeriosTesting/openapi-codegen.git",
		"directory": "packages/openapi-core"
		},
		"files": [
		"dist"
		],
		"type": "commonjs",
		"sideEffects": false,
		"main": "./dist/index.js",
		"module": "./dist/index.mjs",
		"types": "./dist/index.d.ts",
		"exports": {
		".": {
		"import": {
		"types": "./dist/index.d.mts",
		"default": "./dist/index.mjs"
		},
		"require": {
		"types": "./dist/index.d.ts",
		"default": "./dist/index.js"
		}
		},
		"./package.json": "./package.json"
		},
		"publishConfig": {
		"access": "public",
		"provenance": true
		},
		"dependencies": {
		"cosmiconfig": "^9.0.0",
		"esbuild": "^0.27.3",
		"minimatch": "^10.2.0",
		"yaml": "^2.8.2",
		"zod": "^4.3.6"
		},
		"devDependencies": {
		"@arethetypeswrong/cli": "^0.18.2",
		"@types/node": "^25.2.3",
		"tsup": "^8.5.1",
		"typescript": "^5.9.3",
		"vitest": "^4.0.18"
		},
		"scripts": {
		"build": "tsup",
		"check-exports": "attw --pack .",
		"compile": "tsc --noEmit",
		"dev": "tsup --watch",
		"pack": "pnpm pack --pack-destination=../..",
		"test": "vitest run"
		}
		}

@cerios/openapi-core - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics

Worsened metrics

Dependency changes