@kubb/adapter-oas 5.0.0-alpha.4 → 5.0.0-alpha.40

package/dist/index.d.ts

@@ -1,115 +1,133 @@
 import { t as __name } from "./chunk--u3MIqq1.js";
-import * as _kubb_core0 from "@kubb/core";
-import { AdapterFactoryOptions } from "@kubb/core";
-import { DiscriminatorObject, OASDocument, SchemaObject } from "oas/types";
-import BaseOas from "oas";
-import * as oas_normalize_lib_types0 from "oas-normalize/lib/types";
-import { Operation } from "oas/operation";
+import * as _$_kubb_core0 from "@kubb/core";
+import { AdapterFactoryOptions, AdapterSource, ast } from "@kubb/core";
+import { DiscriminatorObject as DiscriminatorObject$1, MediaTypeObject as MediaTypeObject$1, OASDocument, ResponseObject as ResponseObject$1, SchemaObject as SchemaObject$1 } from "oas/types";
+import { Operation as Operation$1 } from "oas/operation";
 import { OpenAPIV3 } from "openapi-types";
 
-//#region src/oas/types.d.ts
-type contentType = 'application/json' | (string & {});
-type SchemaObject$1 = SchemaObject & {
+//#region src/types.d.ts
+/**
+ * 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'
+ * ```
+ */
+type ContentType = 'application/json' | (string & {});
+/**
+ * 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',
+ * }
+ * ```
+ */
+type SchemaObject = SchemaObject$1 & {
   /**
-   * OAS 3.1 extension: allows marking a schema as nullable even when `type` does not include `'null'`.
+   * OAS 3.0 vendor extension: marks a schema as nullable without using `type: ['null', ...]`.
    */
   'x-nullable'?: boolean;
   /**
-   * OAS 3.1: constrains the schema to a single fixed value.
-   * Semantically equivalent to a one-item `enum`.
+   * OAS 3.1: constrains the schema to a single fixed value (equivalent to a one-item `enum`).
    */
   const?: string | number | boolean | null;
   /**
-   * OAS 3.1: specifies the media type of the schema content.
-   * When set to `'application/octet-stream'` on a `string` schema, the schema is treated as binary (`blob`).
+   * OAS 3.1: media type of the schema content. `'application/octet-stream'` on a `string` schema maps to `blob`.
    */
   contentMediaType?: string;
   $ref?: string;
   /**
-   * OAS 3.1 / JSON Schema: positional items in a tuple schema.
-   * Replaces the OAS 3.0 multi-item `items` array syntax.
+   * OAS 3.1: positional tuple items, replacing the multi-item `items` array from OAS 3.0.
    */
-  prefixItems?: Array<SchemaObject$1 | ReferenceObject>;
+  prefixItems?: Array<SchemaObject | ReferenceObject>;
   /**
-   * JSON Schema: maps regex patterns to sub-schemas for additional property validation.
+   * JSON Schema: maps regex patterns to sub-schemas for validating additional properties.
    */
-  patternProperties?: Record<string, SchemaObject$1 | boolean>;
+  patternProperties?: Record<string, SchemaObject | boolean>;
   /**
-   * OAS 3.0 / JSON Schema: single-schema form.
-   * The OAS base type already includes this, but we re-declare it here to ensure
-   * the single-schema overload takes precedence over the multi-schema tuple form.
+   * Single-schema form of `items`. Narrowed from the base type to take precedence over the tuple overload.
    */
-  items?: SchemaObject$1 | ReferenceObject;
+  items?: SchemaObject | ReferenceObject;
   /**
-   * Enum values for this schema (narrowed from `unknown[]` in the base type).
+   * Enum values for this schema (narrowed from `unknown[]`).
    */
   enum?: Array<string | number | boolean | null>;
 };
+/**
+ * Uppercase → lowercase HTTP method map, re-exported for backwards compatibility.
+ *
+ * @example
+ * ```ts
+ * HttpMethods['GET'] // 'get'
+ * HttpMethods['POST'] // 'post'
+ * ```
+ */
+declare const HttpMethods: Record<Uppercase<ast.HttpMethod>, Lowercase<ast.HttpMethod>>;
+/**
+ * Lowercase HTTP method string as used by the `oas` package (`'get' | 'post' | ...`).
+ */
+type HttpMethod = Lowercase<ast.HttpMethod>;
+/**
+ * Normalized OpenAPI document type used throughout the adapter.
+ */
 type Document = OASDocument;
-type Operation$1 = Operation;
-type DiscriminatorObject$1 = DiscriminatorObject;
+/**
+ * Operation wrapper type returned by the `oas` package.
+ */
+type Operation = Operation$1;
+/**
+ * OpenAPI `discriminator` object attached to a `oneOf`/`anyOf` schema.
+ */
+type DiscriminatorObject = DiscriminatorObject$1;
+/**
+ * OpenAPI `$ref` pointer object (`{ $ref: string }`).
+ */
 type ReferenceObject = OpenAPIV3.ReferenceObject;
-//#endregion
-//#region src/oas/Oas.d.ts
-type OasOptions = {
-  contentType?: contentType;
-  discriminator?: 'strict' | 'inherit';
-  /**
-   * Resolve name collisions when schemas from different components share the same name (case-insensitive).
-   * @default false
-   */
-  collisionDetection?: boolean;
-};
-declare class Oas extends BaseOas {
-  #private;
-  document: Document;
-  constructor(document: Document);
-  setOptions(options: OasOptions): void;
-  get options(): OasOptions;
-  get<T = unknown>($ref: string): T | null;
-  getKey($ref: string): string | undefined;
-  set($ref: string, value: unknown): false | undefined;
-  getDiscriminator(schema: SchemaObject$1 | null): DiscriminatorObject$1 | null;
-  dereferenceWithRef<T = unknown>(schema?: T): T;
-  getResponseSchema(operation: Operation$1, statusCode: string | number): SchemaObject$1;
-  getRequestSchema(operation: Operation$1): SchemaObject$1 | undefined;
-  getParametersSchema(operation: Operation$1, inKey: 'path' | 'query' | 'header'): SchemaObject$1 | null;
-  validate(): Promise<oas_normalize_lib_types0.ValidationResult>;
-  flattenSchema(schema: SchemaObject$1 | null): SchemaObject$1 | null;
-  /**
-   * Get schemas from OpenAPI components (schemas, responses, requestBodies).
-   * Returns schemas in dependency order along with name mapping for collision resolution.
-   */
-  getSchemas(options?: {
-    contentType?: contentType;
-    includes?: Array<'schemas' | 'responses' | 'requestBodies'>;
-    collisionDetection?: boolean;
-  }): {
-    schemas: Record<string, SchemaObject$1>;
-    nameMapping: Map<string, string>;
-  };
-}
-//#endregion
-//#region src/types.d.ts
-type OasAdapterOptions = {
+/**
+ * OpenAPI response object type (may contain `content`, `description`, `headers`).
+ */
+type ResponseObject = ResponseObject$1;
+/**
+ * OpenAPI media type object that maps a content-type to a schema.
+ */
+type MediaTypeObject = MediaTypeObject$1;
+/**
+ * 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' },
+ * })
+ * ```
+ */
+type AdapterOasOptions = {
   /**
    * Validate the OpenAPI spec before parsing.
    * @default true
    */
   validate?: boolean;
   /**
-   * Override the `Oas` class (e.g. for custom subclass behavior).
+   * Preferred content-type used when extracting request/response schemas.
+   * Defaults to the first valid JSON media type found in the spec.
    */
-  oasClass?: typeof Oas;
+  contentType?: ContentType;
   /**
-   * Restrict which content-type is used when extracting request/response schemas.
-   * By default, the first valid JSON media type is used.
-   */
-  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;
   /**
@@ -117,89 +135,141 @@ 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';
-  /**
-   * Automatically resolve name collisions across schema components.
-   * @default false
-   */
-  collisionDetection?: boolean;
-  /**
-   * 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'
-   */
-  dateType?: false | 'string' | 'stringOffset' | 'stringLocal' | 'date';
-  /**
-   * Whether `type: 'integer'` / `format: 'int64'` produces `number` or `bigint` nodes.
-   * @default 'number'
-   */
-  integerType?: 'number' | 'bigint';
-  /**
-   * AST type used when no schema type can be inferred.
-   * @default 'any'
-   */
-  unknownType?: 'any' | 'unknown' | 'void';
-  /**
-   * AST type used for completely empty schemas (`{}`).
-   * @default `unknownType`
-   */
-  emptySchemaType?: 'any' | 'unknown' | 'void';
-};
-type OasAdapterResolvedOptions = {
+} & Partial<ast.ParserOptions>;
+/**
+ * Resolved adapter options available at runtime after defaults have been applied.
+ */
+type AdapterOasResolvedOptions = {
   validate: boolean;
-  oasClass: OasAdapterOptions['oasClass'];
-  contentType: OasAdapterOptions['contentType'];
-  serverIndex: OasAdapterOptions['serverIndex'];
-  serverVariables: OasAdapterOptions['serverVariables'];
-  discriminator: NonNullable<OasAdapterOptions['discriminator']>;
-  collisionDetection: boolean;
-  dateType: NonNullable<OasAdapterOptions['dateType']>;
-  integerType: NonNullable<OasAdapterOptions['integerType']>;
-  unknownType: NonNullable<OasAdapterOptions['unknownType']>;
-  emptySchemaType: NonNullable<OasAdapterOptions['emptySchemaType']>;
+  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>;
 };
-type OasAdapter = AdapterFactoryOptions<'oas', OasAdapterOptions, OasAdapterResolvedOptions>;
+/**
+ * `@kubb/core` adapter factory type for the OpenAPI adapter.
+ */
+type AdapterOas = AdapterFactoryOptions<'oas', AdapterOasOptions, AdapterOasResolvedOptions, Document>;
 //#endregion
 //#region src/adapter.d.ts
+/**
+ * Stable string identifier for the OAS adapter used in Kubb's adapter registry.
+ */
 declare const adapterOasName = "oas";
 /**
- * Creates an OpenAPI / Swagger adapter for Kubb.
+ * Creates the default OpenAPI / Swagger adapter for Kubb.
  *
- * This is the default adapter — you can omit it from your config when using
- * an OpenAPI spec, but supplying it explicitly lets you pass options.
+ * Parses the spec, optionally validates it, resolves the base URL, and converts
+ * everything into an `InputNode` that downstream plugins consume.
  *
  * @example
  * ```ts
  * import { defineConfig } from '@kubb/core'
  * import { adapterOas } from '@kubb/adapter-oas'
+ * import { pluginTs } from '@kubb/plugin-ts'
  *
  * export default defineConfig({
- *   adapter: adapterOas({ validate: true, dateType: 'date' }),
- *   input:   { path: './openapi.yaml' },
- *   plugins: [pluginTs(), pluginZod()],
+ *   adapter: adapterOas({ dateType: 'date', serverIndex: 0 }),
+ *   input: { path: './openapi.yaml' },
+ *   plugins: [pluginTs()],
  * })
  * ```
  */
-declare const adapterOas: (options?: OasAdapterOptions | undefined) => _kubb_core0.Adapter<OasAdapter>;
+declare const adapterOas: (options?: AdapterOasOptions | undefined) => _$_kubb_core0.Adapter<AdapterOas>;
+//#endregion
+//#region src/factory.d.ts
+type ParseOptions = {
+  canBundle?: boolean;
+  enablePaths?: boolean;
+};
+type ValidateDocumentOptions = {
+  throwOnError?: boolean;
+};
+/**
+ * Loads and dereferences an OpenAPI document, returning the raw `Document`.
+ *
+ * Accepts a file path string or an already-parsed document object. File paths are bundled via
+ * Redocly to resolve external `$ref`s. Swagger 2.0 documents are automatically up-converted
+ * to OpenAPI 3.0 via `swagger2openapi`.
+ *
+ * @example
+ * ```ts
+ * const document = await parseDocument('./openapi.yaml')
+ * const document = await parse(rawDocumentObject, { canBundle: false })
+ * ```
+ */
+declare function parseDocument(pathOrApi: string | Document, {
+  canBundle,
+  enablePaths
+}?: ParseOptions): Promise<Document>;
+/**
+ * Deep-merges multiple OpenAPI documents into a single `Document`.
+ *
+ * Each document is parsed independently then recursively merged with `remeda`'s `mergeDeep`.
+ * Throws when the input array is empty.
+ *
+ * @example
+ * ```ts
+ * const document = await mergeDocuments(['./pets.yaml', './orders.yaml'])
+ * ```
+ */
+declare function mergeDocuments(pathOrApi: Array<string | Document>): Promise<Document>;
+/**
+ * Creates a `Document` from an `AdapterSource`.
+ *
+ * Handles all three source types:
+ * - `{ type: 'path' }` — resolves and bundles a local file path or remote URL.
+ * - `{ type: 'paths' }` — merges multiple file paths into a single document.
+ * - `{ type: 'data' }` — parses an inline string (YAML/JSON) or raw object.
+ *
+ * @example
+ * ```ts
+ * const document = await parseFromConfig({ type: 'path', path: './openapi.yaml' })
+ * const document = await parseFromConfig({ type: 'data', data: '{"openapi":"3.0.0",...}' })
+ * ```
+ */
+declare function parseFromConfig(source: AdapterSource): Promise<Document>;
+/**
+ * Validates an OpenAPI document using `oas-normalize` with colorized error output.
+ *
+ * @example
+ * ```ts
+ * await validateDocument(document)
+ * ```
+ */
+declare function validateDocument(document: Document, {
+  throwOnError
+}?: ValidateDocumentOptions): Promise<void>;
 //#endregion
-export { adapterOas, adapterOasName };
+export { type AdapterOas, type AdapterOasOptions, type AdapterOasResolvedOptions, type ContentType, type DiscriminatorObject, type Document, type HttpMethod, HttpMethods, type MediaTypeObject, type Operation, type ParseOptions, type ReferenceObject, type ResponseObject, type SchemaObject, type ValidateDocumentOptions, adapterOas, adapterOasName, mergeDocuments, parseDocument, parseFromConfig, validateDocument };
 //# sourceMappingURL=index.d.ts.map