@kubb/oas/dist/index.d.ts

OpenAPI Specification (OAS) utilities and helpers for Kubb, providing parsing, normalization, and manipulation of OpenAPI/Swagger schemas.

import { t as __name } from "./chunk--u3MIqq1.js";
import BaseOas from "oas";
import * as OasTypes from "oas/types";
import { DiscriminatorObject as DiscriminatorObject$1, HttpMethods, MediaTypeObject as MediaTypeObject$1, OASDocument, ParameterObject, ResponseObject as ResponseObject$1, SchemaObject as SchemaObject$1 } from "oas/types";
import * as oas_normalize_lib_types0 from "oas-normalize/lib/types";
import { Operation as Operation$1 } from "oas/operation";
import { OpenAPIV3, OpenAPIV3 as OpenAPIV3$1, OpenAPIV3_1, OpenAPIV3_1 as OpenAPIV3_1$1 } from "openapi-types";
import { Config } from "@kubb/core";

//#region src/constants.d.ts
/**
 * 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).
 */
declare const STRUCTURAL_KEYS: Set<string>;
/**
 * 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.
 */
declare const FORMAT_MAP: {
  readonly uuid: "uuid";
  readonly email: "email";
  readonly 'idn-email': "email";
  readonly uri: "url";
  readonly 'uri-reference': "url";
  readonly url: "url";
  readonly ipv4: "url";
  readonly ipv6: "url";
  readonly hostname: "url";
  readonly 'idn-hostname': "url";
  readonly binary: "blob";
  readonly byte: "blob";
  readonly int32: "integer";
  readonly float: "number";
  readonly double: "number";
};
/**
 * Exhaustive list of media types that Kubb recognizes.
 * Kept as a module-level constant to avoid re-allocating the array on every call.
 */
declare const KNOWN_MEDIA_TYPES: readonly ["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"];
/**
 * 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.
 */
declare const ENUM_EXTENSION_KEYS: readonly ["x-enumNames", "x-enum-varnames"];
/**
 * 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
 */
declare const httpMethods: {
  readonly GET: "get";
  readonly POST: "post";
  readonly PUT: "put";
  readonly PATCH: "patch";
  readonly DELETE: "delete";
  readonly HEAD: "head";
  readonly OPTIONS: "options";
  readonly TRACE: "trace";
};
//#endregion
//#region src/types.d.ts
type contentType = 'application/json' | (string & {});
type SchemaObject = SchemaObject$1 & {
  /**
   * 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;
};
type HttpMethod = HttpMethods;
type Document = OASDocument;
type Operation = Operation$1;
type DiscriminatorObject = DiscriminatorObject$1;
type ReferenceObject = OpenAPIV3$1.ReferenceObject;
type ResponseObject = ResponseObject$1;
type MediaTypeObject = MediaTypeObject$1;
//#endregion
//#region src/Oas.d.ts
/**
 * Prefix used to create synthetic `$ref` values for anonymous (inline) discriminator schemas.
 * The suffix is the schema index within the discriminator's `oneOf`/`anyOf` array.
 * @example `#kubb-inline-0`
 */
declare const KUBB_INLINE_REF_PREFIX = "#kubb-inline-";
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 | null): DiscriminatorObject | null;
  dereferenceWithRef<T = unknown>(schema?: T): T;
  getResponseSchema(operation: Operation, statusCode: string | number): SchemaObject;
  getRequestSchema(operation: Operation): SchemaObject | undefined;
  getParametersSchema(operation: Operation, inKey: 'path' | 'query' | 'header'): SchemaObject | null;
  validate(): Promise<oas_normalize_lib_types0.ValidationResult>;
  flattenSchema(schema: SchemaObject | null): SchemaObject | 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>;
    nameMapping: Map<string, string>;
  };
}
//#endregion
//#region src/resolveServerUrl.d.ts
type ServerVariable = {
  default?: string | number;
  enum?: (string | number)[];
};
type ServerObject = {
  url: string;
  variables?: Record<string, ServerVariable>;
};
/**
 * Resolves an OpenAPI server URL by substituting `{variable}` placeholders
 * with values from `overrides` (user-provided) or the spec-defined defaults.
 *
 * Throws if an override value is not in the variable's `enum` list.
 */
declare function resolveServerUrl(server: ServerObject, overrides?: Record<string, string>): string;
//#endregion
//#region src/utils.d.ts
/**
 * Returns `true` when `doc` is an OpenAPI 3.1 document.
 */
declare function isOpenApiV3_1Document(doc: unknown): doc is OpenAPIV3_1$1.Document;
/**
 * Returns `true` when `obj` is a parameter object (has an `in` field distinguishing it from a schema).
 */
declare function isParameterObject(obj: ParameterObject | SchemaObject): obj is ParameterObject;
/**
 * Determines if a schema is nullable, considering:
 * - OpenAPI 3.0 `nullable` / `x-nullable`
 * - OpenAPI 3.1 JSON Schema `type: ['null', ...]` or `type: 'null'`
 */
declare function isNullable(schema?: SchemaObject & {
  'x-nullable'?: boolean;
}): boolean;
/**
 * Returns `true` when `obj` is an OpenAPI `$ref` pointer object.
 */
declare function isReference(obj?: unknown): obj is OpenAPIV3$1.ReferenceObject | OpenAPIV3_1$1.ReferenceObject;
/**
 * Returns `true` when `obj` is a schema that carries a structured `discriminator` object
 * (as opposed to a plain string discriminator used in some older specs).
 */
declare function isDiscriminator(obj?: unknown): obj is SchemaObject & {
  discriminator: OpenAPIV3$1.DiscriminatorObject;
};
/**
 * Determines whether a schema is required.
 *
 * Returns true if the schema has a non-empty {@link SchemaObject.required} array or a truthy {@link SchemaObject.required} property.
 */
declare function isRequired(schema?: SchemaObject): boolean;
declare function isAllOptional(schema: unknown): boolean;
declare function isOptional(schema?: SchemaObject): boolean;
/**
 * Determines the appropriate default value for a schema parameter.
 * - For array types: returns '[]'
 * - For union types (anyOf/oneOf):
 *   - If at least one variant has all-optional fields: returns '{}'
 *   - Otherwise: returns undefined (no default)
 * - For object types with optional fields: returns '{}'
 * - For primitive types (string, number, boolean): returns undefined (no default)
 * - For required types: returns undefined (no default)
 */
declare function getDefaultValue(schema?: SchemaObject): string | undefined;
declare function parse(pathOrApi: string | Document, {
  oasClass,
  canBundle,
  enablePaths
}?: {
  oasClass?: typeof Oas;
  canBundle?: boolean;
  enablePaths?: boolean;
}): Promise<Oas>;
declare function merge(pathOrApi: Array<string | Document>, {
  oasClass
}?: {
  oasClass?: typeof Oas;
}): Promise<Oas>;
declare function parseFromConfig(config: Config, oasClass?: typeof Oas): Promise<Oas>;
/**
 * Flatten allOf schemas by merging keyword-only fragments.
 * Only flattens schemas where allOf items don't contain structural keys or $refs.
 */
declare function flattenSchema(schema: SchemaObject | null): SchemaObject | null;
/**
 * Validate an OpenAPI document using oas-normalize.
 */
declare function validate(document: Document): Promise<oas_normalize_lib_types0.ValidationResult>;
//#endregion
export { DiscriminatorObject, Document, ENUM_EXTENSION_KEYS, FORMAT_MAP, HttpMethod, httpMethods as HttpMethods, httpMethods, KNOWN_MEDIA_TYPES, KUBB_INLINE_REF_PREFIX, MediaTypeObject, Oas, type OasTypes, type OpenAPIV3, type OpenAPIV3_1, Operation, ReferenceObject, ResponseObject, STRUCTURAL_KEYS, SchemaObject, contentType, flattenSchema, getDefaultValue, isAllOptional, isDiscriminator, isNullable, isOpenApiV3_1Document, isOptional, isParameterObject, isReference, isRequired, merge, parse, parseFromConfig, resolveServerUrl, validate };
//# sourceMappingURL=index.d.ts.map