@kubb/adapter-oas 5.0.0-alpha.16 → 5.0.0-alpha.18

package/src/types.ts

@@ -1,52 +1,158 @@
+// external packages
+
+import { httpMethods } from '@kubb/ast'
+import type { HttpMethod as AstHttpMethod, ParserOptions } from '@kubb/ast/types'
 import type { AdapterFactoryOptions } from '@kubb/core'
-import type { Oas as OasClass } from './oas/Oas.ts'
-import type { contentType } from './oas/types.ts'
+import type { Operation as OASOperation } from 'oas/operation'
+import type {
+  DiscriminatorObject as OASDiscriminatorObject,
+  OASDocument,
+  MediaTypeObject as OASMediaTypeObject,
+  ResponseObject as OASResponseObject,
+  SchemaObject as OASSchemaObject,
+} from 'oas/types'
+import type { OpenAPIV3 } from 'openapi-types'
+
+/**
+ * Re-exports of `openapi-types` for use by adapter consumers.
+ */
+export type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types'
+
+/**
+ * Content-type string used when selecting request/response schemas from a spec.
+ *
+ * Accepts `'application/json'` or any arbitrary media type string.
+ *
+ * @example
+ * ```ts
+ * const ct: contentType = 'application/vnd.api+json'
+ * ```
+ */
+export type contentType = 'application/json' | (string & {})
 
 /**
- * Controls how various OAS constructs are mapped to Kubb AST nodes.
+ * Augments `oas`'s `SchemaObject` with OAS 3.1 / JSON Schema fields the parser needs.
+ *
+ * @example
+ * ```ts
+ * const schema: SchemaObject = {
+ *   type: 'string',
+ *   const: 'dog',
+ *   contentMediaType: 'application/octet-stream',
+ * }
+ * ```
  */
-export type ParserOptions = {
+export type SchemaObject = OASSchemaObject & {
+  /**
+   * OAS 3.0 vendor extension: marks a schema as nullable without using `type: ['null', ...]`.
+   */
+  'x-nullable'?: boolean
   /**
-   * How `format: 'date-time'` schemas are represented. `false` falls through to a plain string.
+   * OAS 3.1: constrains the schema to a single fixed value (equivalent to a one-item `enum`).
    */
-  dateType: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
+  const?: string | number | boolean | null
   /**
-   * Whether `type: 'integer'` and `format: 'int64'` produce `number` or `bigint` nodes.
+   * OAS 3.1: media type of the schema content. `'application/octet-stream'` on a `string` schema maps to `blob`.
    */
-  integerType?: 'number' | 'bigint'
+  contentMediaType?: string
+  $ref?: string
   /**
-   * AST type used when no schema type can be inferred.
+   * OAS 3.1: positional tuple items, replacing the multi-item `items` array from OAS 3.0.
    */
-  unknownType: 'any' | 'unknown' | 'void'
+  prefixItems?: Array<SchemaObject | ReferenceObject>
   /**
-   * AST type used for completely empty schemas (`{}`).
+   * JSON Schema: maps regex patterns to sub-schemas for validating additional properties.
    */
-  emptySchemaType: 'any' | 'unknown' | 'void'
+  patternProperties?: Record<string, SchemaObject | boolean>
   /**
-   * Suffix appended to derived enum names when building property schema names.
+   * Single-schema form of `items`. Narrowed from the base type to take precedence over the tuple overload.
    */
-  enumSuffix: 'enum' | (string & {})
+  items?: SchemaObject | ReferenceObject
+  /**
+   * Enum values for this schema (narrowed from `unknown[]`).
+   */
+  enum?: Array<string | number | boolean | null>
 }
 
-export type OasAdapterOptions = {
+/**
+ * Uppercase → lowercase HTTP method map, re-exported for backwards compatibility.
+ *
+ * @example
+ * ```ts
+ * HttpMethods['GET'] // 'get'
+ * HttpMethods['POST'] // 'post'
+ * ```
+ */
+export const HttpMethods = Object.fromEntries(Object.entries(httpMethods).map(([lower, upper]) => [upper, lower])) as Record<
+  Uppercase<AstHttpMethod>,
+  Lowercase<AstHttpMethod>
+>
+
+/**
+ * Lowercase HTTP method string as used by the `oas` package (`'get' | 'post' | ...`).
+ */
+export type HttpMethod = Lowercase<AstHttpMethod>
+
+/**
+ * Normalized OpenAPI document type used throughout the adapter.
+ */
+export type Document = OASDocument
+
+/**
+ * Operation wrapper type returned by the `oas` package.
+ */
+export type Operation = OASOperation
+
+/**
+ * OpenAPI `discriminator` object attached to a `oneOf`/`anyOf` schema.
+ */
+export type DiscriminatorObject = OASDiscriminatorObject
+
+/**
+ * OpenAPI `$ref` pointer object (`{ $ref: string }`).
+ */
+export type ReferenceObject = OpenAPIV3.ReferenceObject
+
+/**
+ * OpenAPI response object type (may contain `content`, `description`, `headers`).
+ */
+export type ResponseObject = OASResponseObject
+
+/**
+ * OpenAPI media type object that maps a content-type to a schema.
+ */
+export type MediaTypeObject = OASMediaTypeObject
+
+/**
+ * User-facing options for `adapterOas(...)`.
+ *
+ * Extends `ParserOptions` from `@kubb/ast` with adapter-specific controls
+ * like spec validation and server URL selection.
+ *
+ * @example
+ * ```ts
+ * adapterOas({
+ *   validate: false,
+ *   dateType: 'date',
+ *   serverIndex: 0,
+ *   serverVariables: { env: 'prod' },
+ * })
+ * ```
+ */
+export type AdapterOasOptions = {
   /**
    * Validate the OpenAPI spec before parsing.
    * @default true
    */
   validate?: boolean
   /**
-   * Override the `Oas` class (e.g. for custom subclass behavior).
-   */
-  oasClass?: typeof OasClass
-  /**
-   * Restrict which content-type is used when extracting request/response schemas.
-   * By default, the first valid JSON media type is used.
+   * Preferred content-type used when extracting request/response schemas.
+   * Defaults to the first valid JSON media type found in the spec.
    */
   contentType?: contentType
   /**
-   * Which server to use from `oas.api.servers` when computing `baseURL`.
-   * - `0` → first server, `1` → second server, etc.
-   * - When omitted, `baseURL` in the resulting `RootNode.meta` is `undefined`.
+   * Index into `oas.api.servers` for computing `baseURL`.
+   * `0` → first server, `1` → second server. Omit to leave `baseURL` undefined.
    */
   serverIndex?: number
   /**
@@ -54,45 +160,50 @@ export type OasAdapterOptions = {
    * Only used when `serverIndex` is set.
    *
    * @example
+   * ```ts
    * // spec server: "https://api.{env}.example.com"
    * serverVariables: { env: 'prod' }
    * // → baseURL: "https://api.prod.example.com"
+   * ```
    */
   serverVariables?: Record<string, string>
   /**
-   * How the discriminator field should be interpreted.
-   * - `'strict'`  — uses `oneOf` schemas as defined.
-   * - `'inherit'` — replaces `oneOf` with the schema from `discriminator.mapping`.
+   * How the discriminator field is interpreted.
+   * - `'strict'`  — uses `oneOf` schemas as written in the spec.
+   * - `'inherit'` — propagates discriminator values into child schemas from `discriminator.mapping`.
    * @default 'strict'
    */
   discriminator?: 'strict' | 'inherit'
-  /**
-   * How `format: 'date-time'` schemas are represented in the AST.
-   * - `'string'` maps to a `datetime` string node.
-   * - `'date'` maps to a JavaScript `Date` node.
-   * - `false` falls through to a plain `string` node.
-   * @default 'string'
-   */
 } & Partial<ParserOptions>
 
-export type OasAdapterResolvedOptions = {
+/**
+ * Resolved adapter options available at runtime after defaults have been applied.
+ */
+export type AdapterOasResolvedOptions = {
   validate: boolean
-  oasClass: OasAdapterOptions['oasClass']
-  contentType: OasAdapterOptions['contentType']
-  serverIndex: OasAdapterOptions['serverIndex']
-  serverVariables: OasAdapterOptions['serverVariables']
-  discriminator: NonNullable<OasAdapterOptions['discriminator']>
-  dateType: NonNullable<OasAdapterOptions['dateType']>
-  integerType: NonNullable<OasAdapterOptions['integerType']>
-  unknownType: NonNullable<OasAdapterOptions['unknownType']>
-  emptySchemaType: NonNullable<OasAdapterOptions['emptySchemaType']>
-  enumSuffix: OasAdapterOptions['enumSuffix']
+  contentType: AdapterOasOptions['contentType']
+  serverIndex: AdapterOasOptions['serverIndex']
+  serverVariables: AdapterOasOptions['serverVariables']
+  discriminator: NonNullable<AdapterOasOptions['discriminator']>
+  dateType: NonNullable<AdapterOasOptions['dateType']>
+  integerType: NonNullable<AdapterOasOptions['integerType']>
+  unknownType: NonNullable<AdapterOasOptions['unknownType']>
+  emptySchemaType: NonNullable<AdapterOasOptions['emptySchemaType']>
+  enumSuffix: AdapterOasOptions['enumSuffix']
   /**
    * Map from original `$ref` paths to their collision-resolved schema names.
-   * Populated by the adapter after each `parse()` call.
-   * e.g. `'#/components/schemas/Order'` → `'OrderSchema'`
+   * Populated after each `parse()` call.
+   *
+   * @example
+   * ```ts
+   * nameMapping.get('#/components/schemas/Order') // 'Order'
+   * nameMapping.get('#/components/responses/Order') // 'OrderResponse'
+   * ```
    */
   nameMapping: Map<string, string>
 }
 
-export type OasAdapter = AdapterFactoryOptions<'oas', OasAdapterOptions, OasAdapterResolvedOptions>
+/**
+ * `@kubb/core` adapter factory type for the OpenAPI adapter.
+ */
+export type AdapterOas = AdapterFactoryOptions<'oas', AdapterOasOptions, AdapterOasResolvedOptions>

package/src/infer.ts

@@ -1,85 +0,0 @@
-import type {
-  ArraySchemaNode,
-  DateSchemaNode,
-  DatetimeSchemaNode,
-  EnumSchemaNode,
-  IntersectionSchemaNode,
-  NumberSchemaNode,
-  ObjectSchemaNode,
-  RefSchemaNode,
-  ScalarSchemaNode,
-  SchemaNode,
-  StringSchemaNode,
-  TimeSchemaNode,
-  UnionSchemaNode,
-} from '@kubb/ast/types'
-import type { SchemaObject } from './oas/types.ts'
-import type { ParserOptions } from './types.ts'
-
-/**
- * Maps each `dateType` option value to the AST node produced by `format: 'date-time'`.
- */
-type DateTimeNodeByDateType = {
-  date: DateSchemaNode
-  string: DatetimeSchemaNode
-  stringOffset: DatetimeSchemaNode
-  stringLocal: DatetimeSchemaNode
-  false: StringSchemaNode
-}
-
-/**
- * Resolves the AST node produced by `format: 'date-time'` based on the `dateType` option.
- */
-type ResolveDateTimeNode<TDateType extends ParserOptions['dateType']> = DateTimeNodeByDateType[TDateType extends keyof DateTimeNodeByDateType
-  ? TDateType
-  : 'string']
-
-/**
- * Single source of truth: ordered list of `[shape, SchemaNode]` pairs.
- * `InferSchemaNode` walks this tuple in order and returns the node type of the first matching entry.
- * Parameterized over `TDateType` so `format: 'date-time'` resolves to the correct node based on the option.
- */
-type SchemaNodeMap<TDateType extends ParserOptions['dateType'] = 'string'> = [
-  [{ $ref: string }, RefSchemaNode],
-  [{ allOf: ReadonlyArray<unknown>; properties: object }, IntersectionSchemaNode],
-  [{ allOf: readonly [unknown, unknown, ...unknown[]] }, IntersectionSchemaNode],
-  [{ allOf: ReadonlyArray<unknown> }, SchemaNode],
-  [{ oneOf: ReadonlyArray<unknown> }, UnionSchemaNode],
-  [{ anyOf: ReadonlyArray<unknown> }, UnionSchemaNode],
-  [{ const: null }, ScalarSchemaNode],
-  [{ const: string | number | boolean }, EnumSchemaNode],
-  [{ type: ReadonlyArray<string> }, UnionSchemaNode],
-  [{ type: 'array'; enum: ReadonlyArray<unknown> }, ArraySchemaNode],
-  [{ enum: ReadonlyArray<unknown> }, EnumSchemaNode],
-  [{ type: 'object' }, ObjectSchemaNode],
-  [{ additionalProperties: boolean | {} }, ObjectSchemaNode],
-  [{ type: 'array' }, ArraySchemaNode],
-  [{ items: object }, ArraySchemaNode],
-  [{ prefixItems: ReadonlyArray<unknown> }, ArraySchemaNode],
-  [{ type: string; format: 'date-time' }, ResolveDateTimeNode<TDateType>],
-  [{ type: string; format: 'date' }, DateSchemaNode],
-  [{ type: string; format: 'time' }, TimeSchemaNode],
-  [{ format: 'date-time' }, ResolveDateTimeNode<TDateType>],
-  [{ format: 'date' }, DateSchemaNode],
-  [{ format: 'time' }, TimeSchemaNode],
-  [{ type: 'string' }, StringSchemaNode],
-  [{ type: 'number' }, NumberSchemaNode],
-  [{ type: 'integer' }, NumberSchemaNode],
-  [{ type: 'bigint' }, NumberSchemaNode],
-  [{ type: string }, ScalarSchemaNode],
-  [{ minLength: number }, StringSchemaNode],
-  [{ maxLength: number }, StringSchemaNode],
-  [{ pattern: string }, StringSchemaNode],
-  [{ minimum: number }, NumberSchemaNode],
-  [{ maximum: number }, NumberSchemaNode],
-]
-
-export type InferSchemaNode<
-  TSchema extends SchemaObject,
-  TDateType extends ParserOptions['dateType'] = 'string',
-  TEntries extends ReadonlyArray<[object, SchemaNode]> = SchemaNodeMap<TDateType>,
-> = TEntries extends [infer TEntry extends [object, SchemaNode], ...infer TRest extends ReadonlyArray<[object, SchemaNode]>]
-  ? TSchema extends TEntry[0]
-    ? TEntry[1]
-    : InferSchemaNode<TSchema, TDateType, TRest>
-  : SchemaNode

package/src/naming.ts

@@ -1,25 +0,0 @@
-import { pascalCase } from '@internals/utils'
-import { narrowSchema } from '@kubb/ast'
-import type { SchemaNode } from '@kubb/ast/types'
-
-export function resolveChildName(parentName: string | undefined, propName: string): string | undefined {
-  return parentName ? pascalCase([parentName, propName].join(' ')) : undefined
-}
-
-export function resolveEnumPropName(parentName: string | undefined, propName: string, enumSuffix: string): string {
-  return pascalCase([parentName, propName, enumSuffix].filter(Boolean).join(' '))
-}
-
-export function applyEnumName(propNode: SchemaNode, parentName: string | undefined, propName: string, enumSuffix: string): SchemaNode {
-  const enumNode = narrowSchema(propNode, 'enum')
-
-  if (enumNode?.primitive === 'boolean') {
-    return { ...propNode, name: undefined }
-  }
-
-  if (enumNode) {
-    return { ...propNode, name: resolveEnumPropName(parentName, propName, enumSuffix) }
-  }
-
-  return propNode
-}