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

package/dist/index.d.ts

@@ -1,143 +1,50 @@
 import { t as __name } from "./chunk--u3MIqq1.js";
 import * as _kubb_core0 from "@kubb/core";
 import { AdapterFactoryOptions } from "@kubb/core";
-import { DiscriminatorObject, OASDocument, ParameterObject, 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 { OpenAPIV3 } from "openapi-types";
+import { ParserOptions } from "@kubb/ast/types";
 
-//#region src/oas/types.d.ts
-type contentType = 'application/json' | (string & {});
-type SchemaObject$1 = SchemaObject & {
-  /**
-   * OAS 3.1 extension: allows marking a schema as nullable even when `type` does not include `'null'`.
-   */
-  'x-nullable'?: boolean;
-  /**
-   * OAS 3.1: constrains the schema to a single fixed value.
-   * Semantically 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`).
-   */
-  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.
-   */
-  prefixItems?: Array<SchemaObject$1 | ReferenceObject>;
-  /**
-   * JSON Schema: maps regex patterns to sub-schemas for additional property validation.
-   */
-  patternProperties?: Record<string, SchemaObject$1 | 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.
-   */
-  items?: SchemaObject$1 | ReferenceObject;
-  /**
-   * Enum values for this schema (narrowed from `unknown[]` in the base type).
-   */
-  enum?: Array<string | number | boolean | null>;
-};
-type Document = OASDocument;
-type Operation$1 = Operation;
-type DiscriminatorObject$1 = DiscriminatorObject;
-type ReferenceObject = OpenAPIV3.ReferenceObject;
-//#endregion
-//#region src/oas/Oas.d.ts
-type OasOptions = {
-  contentType?: contentType;
-  discriminator?: 'strict' | 'inherit';
-};
-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;
-  /**
-   * Returns all resolved parameters for an operation, merging path-level and operation-level
-   * parameters and deduplicating by `in:name` (operation-level takes precedence).
-   *
-   * oas v31+ filters out `$ref` parameters in `getParameters()`, so this method accesses the
-   * raw `operation.schema.parameters` and path-item parameters directly and resolves `$ref`
-   * pointers via `dereferenceWithRef` to preserve backward compatibility.
-   */
-  getParameters(operation: Operation$1): Array<ParameterObject>;
-  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'>;
-  }): {
-    schemas: Record<string, SchemaObject$1>;
-    nameMapping: Map<string, string>;
-  };
-}
-//#endregion
 //#region src/types.d.ts
 /**
- * Controls how various OAS constructs are mapped to Kubb AST nodes.
+ * 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 ParserOptions = {
-  /**
-   * How `format: 'date-time'` schemas are represented. `false` falls through to a plain string.
-   */
-  dateType: false | 'string' | 'stringOffset' | 'stringLocal' | 'date';
-  /**
-   * Whether `type: 'integer'` and `format: 'int64'` produce `number` or `bigint` nodes.
-   */
-  integerType?: 'number' | 'bigint';
-  /**
-   * AST type used when no schema type can be inferred.
-   */
-  unknownType: 'any' | 'unknown' | 'void';
-  /**
-   * AST type used for completely empty schemas (`{}`).
-   */
-  emptySchemaType: 'any' | 'unknown' | 'void';
-  /**
-   * Suffix appended to derived enum names when building property schema names.
-   */
-  enumSuffix: 'enum' | (string & {});
-};
-type OasAdapterOptions = {
+type contentType = 'application/json' | (string & {});
+/**
+ * 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).
-   */
-  oasClass?: typeof Oas;
-  /**
-   * 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;
   /**
@@ -145,61 +52,77 @@ 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';
 } & Partial<ParserOptions>;
-type OasAdapterResolvedOptions = {
+/**
+ * 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']>;
-  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>;
 };
-type OasAdapter = AdapterFactoryOptions<'oas', OasAdapterOptions, OasAdapterResolvedOptions>;
+/**
+ * `@kubb/core` adapter factory type for the OpenAPI adapter.
+ */
+type AdapterOas = AdapterFactoryOptions<'oas', AdapterOasOptions, AdapterOasResolvedOptions>;
 //#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 a `RootNode` 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
 export { adapterOas, adapterOasName };
 //# sourceMappingURL=index.d.ts.map