@kubb/adapter-oas 5.0.0-alpha.73 → 5.0.0-alpha.74

package/dist/index.d.ts

@@ -326,18 +326,18 @@ declare namespace OpenAPIV3 {
 //#endregion
 //#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.
+ * Content-type string for selecting request/response schemas from an OpenAPI spec.
+ * Supports `'application/json'` or any other media type.
  *
  * @example
  * ```ts
- * const ct: contentType = 'application/vnd.api+json'
+ * 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.
+ * Extended OpenAPI 3.0 schema object that includes OpenAPI 3.1 and JSON Schema fields.
+ * The parser uses these additional fields to handle newer spec versions.
  *
  * @example
  * ```ts
@@ -380,7 +380,7 @@ type SchemaObject$1 = SchemaObject$2 & {
   enum?: Array<string | number | boolean | null>;
 };
 /**
- * Uppercase → lowercase HTTP method map, re-exported for backwards compatibility.
+ * Maps uppercase HTTP method names to lowercase for backwards compatibility.
  *
  * @example
  * ```ts
@@ -390,38 +390,36 @@ type SchemaObject$1 = SchemaObject$2 & {
  */
 declare const HttpMethods$1: Record<Uppercase<ast.HttpMethod>, Lowercase<ast.HttpMethod>>;
 /**
- * Lowercase HTTP method string as used by the `oas` package (`'get' | 'post' | ...`).
+ * HTTP method as a lowercase string (`'get' | 'post' | ...`).
  */
 type HttpMethod = Lowercase<ast.HttpMethod>;
 /**
- * Normalized OpenAPI document type used throughout the adapter.
+ * Normalized OpenAPI document after parsing.
  */
 type Document = OASDocument;
 /**
- * Operation wrapper type returned by the `oas` package.
+ * API operation extracted from an OpenAPI document.
  */
 type Operation = Operation$1;
 /**
- * OpenAPI `discriminator` object attached to a `oneOf`/`anyOf` schema.
+ * Discriminator object for `oneOf`/`anyOf` schemas in OpenAPI.
  */
 type DiscriminatorObject$1 = DiscriminatorObject$2;
 /**
- * OpenAPI `$ref` pointer object (`{ $ref: string }`).
+ * OpenAPI reference object pointing to a schema definition via `$ref`.
  */
 type ReferenceObject$1 = OpenAPIV3.ReferenceObject;
 /**
- * OpenAPI response object type (may contain `content`, `description`, `headers`).
+ * OpenAPI response object from a spec that contains schema, status code, and headers.
  */
 type ResponseObject$1 = ResponseObject$2;
 /**
- * OpenAPI media type object that maps a content-type to a schema.
+ * OpenAPI media type object that maps a content-type string to its schema.
  */
 type MediaTypeObject$1 = MediaTypeObject$2;
 /**
- * User-facing options for `adapterOas(...)`.
- *
- * Extends `ParserOptions` from `@kubb/ast` with adapter-specific controls
- * like spec validation and server URL selection.
+ * Configuration options for the OpenAPI adapter.
+ * Controls spec validation, content-type selection, and server URL resolution.
  *
  * @example
  * ```ts
@@ -470,7 +468,7 @@ type AdapterOasOptions = {
   discriminator?: 'strict' | 'inherit';
 } & Partial<ast.ParserOptions>;
 /**
- * Resolved adapter options available at runtime after defaults have been applied.
+ * Adapter options after defaults have been applied and schema name collisions resolved.
  */
 type AdapterOasResolvedOptions = {
   validate: boolean;

package/dist/index.js

@@ -764,10 +764,9 @@ function dereferenceWithRef(document, schema) {
 //#endregion
 //#region src/resolvers.ts
 /**
-* Resolves `{variable}` placeholders in an OpenAPI server URL.
-*
-* Resolution order per variable: `overrides[key]` → `variable.default` → left unreplaced.
-* Throws when an override value is not in the variable's allowed `enum` list.
+* Replaces `{variable}` placeholders in an OpenAPI server URL with provided values.
+* Resolution order: `overrides[key]` → `variable.default` → left unreplaced.
+* Throws if an override value is not in the variable's `enum` list.
 *
 * @example
 * ```ts
@@ -790,17 +789,15 @@ function resolveServerUrl(server, overrides) {
 	return url;
 }
 /**
-* Looks up the Kubb `SchemaType` for a given OAS `format` string.
-* Returns `undefined` for formats not in `formatMap` (e.g. `int64`, `date-time`),
-* which are handled separately because their output depends on parser options.
+* Returns the Kubb `SchemaType` for a given OAS `format` string, or `null` if not found.
+* Formats not in `formatMap` (e.g., `int64`, `date-time`) are handled separately by parser options.
 */
 function getSchemaType(format) {
 	return formatMap[format] ?? null;
 }
 /**
-* Maps an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
-* Numeric types (`number`, `integer`, `bigint`) are returned unchanged;
-* `boolean` maps to `'boolean'`; everything else defaults to `'string'`.
+* Converts an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
+* Numeric types (`number`, `integer`, `bigint`) pass through unchanged. `boolean` maps to `'boolean'`. Everything else becomes `'string'`.
 */
 function getPrimitiveType(type) {
 	if (type === "number" || type === "integer" || type === "bigint") return type;
@@ -808,18 +805,15 @@ function getPrimitiveType(type) {
 	return "string";
 }
 /**
-* Narrows a raw content-type string to the `MediaType` union recognized by Kubb.
-* Returns `undefined` for content types not present in `KNOWN_MEDIA_TYPES`.
+* Narrows a content-type string to the `MediaType` union Kubb recognizes, or returns `null`.
 */
 function getMediaType(contentType) {
 	return Object.values(ast.mediaTypes).includes(contentType) ? contentType : null;
 }
 /**
-* Returns all resolved parameters for an operation, merging path-level and operation-level entries.
-*
-* Operation-level parameters take precedence over path-level ones with the same `in:name` key.
-* `$ref` parameters are resolved via `dereferenceWithRef` to restore backward compatibility
-* with `oas` v31+ which otherwise filters them out.
+* Returns all parameters for an operation, merging path-level and operation-level entries.
+* Operation-level parameters override path-level ones with the same `in:name` key.
+* `$ref` parameters resolve via `dereferenceWithRef` for backward compatibility.
 *
 * @example
 * ```ts
@@ -886,7 +880,7 @@ function getResponseSchema(document, operation, statusCode, options = {}) {
 	return dereferenceWithRef(document, schema);
 }
 /**
-* Returns the request body schema for an operation, or `undefined` when absent.
+* Returns the request body schema for an operation, or `null` when absent.
 *
 * @example
 * ```ts
@@ -1149,9 +1143,12 @@ function getRequestBodyContentTypes(document, operation) {
 //#endregion
 //#region src/parser.ts
 /**
-* Normalize a malformed `{ type: 'array', enum: [...] }` schema by moving the
-* enum values into the items sub-schema. This pattern is technically invalid OAS
-* but appears in the wild and must be handled gracefully.
+* Normalizes malformed `{ type: 'array', enum: [...] }` schemas by moving enum values into items.
+*
+* This pattern violates the OpenAPI spec but appears in real specs. The fix moves enum values
+* from the array to its items sub-schema, making them valid for downstream processing.
+*
+* @note This is a defensive measure for robustness with non-compliant specs.
 */
 function normalizeArrayEnum(schema) {
 	const normalizedItems = {
@@ -1165,10 +1162,13 @@ function normalizeArrayEnum(schema) {
 	};
 }
 /**
-* Builds the internal converter functions for a given `OasParserContext`.
+* Factory function that creates schema and operation converters for a given OpenAPI context.
 *
-* All `convert*` functions are defined as function declarations so they can freely
-* reference each other and `parseSchema` via JS hoisting (mutual recursion).
+* Returns closures that share mutable state (`resolvingRefs` set for cycle detection).
+* Each converter branch (`convertRef`, `convertAllOf`, etc.) mutually recursively calls `parseSchema`,
+* made possible by hoisting of function declarations.
+*
+* @note Not exported; called internally by `parseOas()` and `parseSchema()`.
 */
 function createSchemaParser(ctx) {
 	const document = ctx.document;
@@ -1826,16 +1826,20 @@ function createSchemaParser(ctx) {
 	};
 }
 /**
-* Converts the entire OpenAPI spec into an `InputNode` (the top-level `@kubb/ast` tree).
+* Parses an OpenAPI specification into Kubb's universal `InputNode` AST.
+*
+* This is the main entry point for `@kubb/adapter-oas`. It converts OpenAPI/Swagger specs into a spec-agnostic tree
+* that downstream plugins (`plugin-ts`, `plugin-zod`, etc.) consume for code generation. No code is generated here —
+* the tree is a pure data structure representing all schemas and operations.
 *
-* This is the main entry point: `OpenAPI / Swagger → Kubb AST`.
-* No code is generated here — the resulting tree is spec-agnostic and consumed by
-* downstream plugins (`plugin-ts`, `plugin-zod`, …).
+* Returns the AST root and a `nameMapping` for resolving schema references.
 *
 * @example
 * ```ts
+* import { parseOas } from '@kubb/adapter-oas'
+*
 * const document = await parseFromConfig(config)
-* const root = parseOas(document, { dateType: 'date', contentType: 'application/json' })
+* const { root, nameMapping } = parseOas(document, { dateType: 'date', contentType: 'application/json' })
 * ```
 */
 function parseOas(document, options = {}) {
@@ -1962,7 +1966,7 @@ const adapterOas = createAdapter((options) => {
 //#endregion
 //#region src/types.ts
 /**
-* Uppercase → lowercase HTTP method map, re-exported for backwards compatibility.
+* Maps uppercase HTTP method names to lowercase for backwards compatibility.
 *
 * @example
 * ```ts