@kubb/oas
Version:
OpenAPI Specification (OAS) utilities and helpers for Kubb, providing parsing, normalization, and manipulation of OpenAPI/Swagger schemas.
89 lines (83 loc) • 2.86 kB
text/typescript
import type { MediaType, SchemaType } from '@kubb/ast/types'
import type { HttpMethods as OASHttpMethods } from 'oas/types'
/**
* JSON Schema keywords that indicate structural composition.
* Used when deciding whether an inline `allOf` fragment can be safely flattened
* into its parent (fragments containing any of these keys must not be inlined).
*/
export const STRUCTURAL_KEYS = new Set<string>(['properties', 'items', 'additionalProperties', 'oneOf', 'anyOf', 'allOf', 'not'])
/**
* Maps OAS/JSON Schema `format` strings to their Kubb `SchemaType` equivalents.
*
* Only formats that require a type different from the raw OAS `type` are listed here.
* `int64`, `date-time`, `date`, and `time` are handled separately because their
* output depends on runtime parser options and cannot live in a static map.
*
* Note: `ipv4`, `ipv6`, and `hostname` map to `'url'` — not semantically accurate,
* but `'url'` is the closest supported scalar type in the Kubb AST.
*/
export const FORMAT_MAP = {
uuid: 'uuid',
email: 'email',
'idn-email': 'email',
uri: 'url',
'uri-reference': 'url',
url: 'url',
ipv4: 'url',
ipv6: 'url',
hostname: 'url',
'idn-hostname': 'url',
binary: 'blob',
byte: 'blob',
// Numeric formats — format is more specific than type, so these override type.
// see https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.7
int32: 'integer',
float: 'number',
double: 'number',
} as const satisfies Record<string, SchemaType>
/**
* Exhaustive list of media types that Kubb recognizes.
* Kept as a module-level constant to avoid re-allocating the array on every call.
*/
export const KNOWN_MEDIA_TYPES = [
'application/json',
'application/xml',
'application/x-www-form-urlencoded',
'application/octet-stream',
'application/pdf',
'application/zip',
'application/graphql',
'multipart/form-data',
'text/plain',
'text/html',
'text/csv',
'text/xml',
'image/png',
'image/jpeg',
'image/gif',
'image/webp',
'image/svg+xml',
'audio/mpeg',
'video/mp4',
] as const satisfies ReadonlyArray<MediaType>
/**
* Vendor extension keys used by various spec generators to attach human-readable
* labels to enum values. Checked in priority order: the first key found wins.
*/
export const ENUM_EXTENSION_KEYS = ['x-enumNames', 'x-enum-varnames'] as const
/**
* Canonical HTTP method names used throughout the Kubb OAS layer.
* Keys are uppercase (as used in generated code); values are the lowercase
* strings that the `oas` library uses internally.
* @deprecated use httpMethods from @kubb/ast
*/
export const httpMethods = {
GET: 'get',
POST: 'post',
PUT: 'put',
PATCH: 'patch',
DELETE: 'delete',
HEAD: 'head',
OPTIONS: 'options',
TRACE: 'trace',
} as const satisfies Record<Uppercase<OASHttpMethods>, OASHttpMethods>