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

package/dist/index.cjs

@@ -790,10 +790,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
@@ -816,17 +815,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;
@@ -834,18 +831,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(_kubb_core.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
@@ -912,7 +906,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
@@ -1175,9 +1169,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 = {
@@ -1191,10 +1188,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;
@@ -1852,16 +1852,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 = {}) {
@@ -1988,7 +1992,7 @@ const adapterOas = (0, _kubb_core.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