@kubb/adapter-oas 5.0.0-beta.63 → 5.0.0-beta.65

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { t as __name } from "./chunk-C0LytTxp.js";
+import { t as __name } from "./rolldown-runtime-C0LytTxp.js";
 import { AdapterFactoryOptions, ast } from "@kubb/core";
 
 //#region ../../node_modules/.pnpm/@types+json-schema@7.0.15/node_modules/@types/json-schema/index.d.ts
@@ -1133,7 +1133,7 @@ type SchemaObject$1 = {
    * Allowed values for this schema.
    */
   enum?: Array<string | number | boolean | null>;
-} & (OpenAPIV3.SchemaObject | OpenAPIV3_1.SchemaObject | JSONSchema4 | JSONSchema6 | JSONSchema7);
+} & (OpenAPIV3_1.SchemaObject | JSONSchema4 | JSONSchema6 | JSONSchema7);
 /**
  * HTTP method in the lowercase form an OpenAPI path item uses for its keys.
  */
@@ -1141,27 +1141,27 @@ type HttpMethod = Lowercase<ast.HttpMethod>;
 /**
  * Normalized OpenAPI document after parsing.
  */
-type Document = (OpenAPIV3.Document | OpenAPIV3_1.Document) & Record<string, unknown>;
+type Document = OpenAPIV3_1.Document & Record<string, unknown>;
 /**
  * Single operation object (the `get`/`post`/… entry on a path item) plus any vendor extensions.
  */
-type OperationObject$1 = (OpenAPIV3.OperationObject | OpenAPIV3_1.OperationObject) & Record<string, unknown>;
+type OperationObject$1 = OpenAPIV3_1.OperationObject & Record<string, unknown>;
 /**
  * Discriminator object for `oneOf`/`anyOf` schemas in OpenAPI.
  */
-type DiscriminatorObject$1 = OpenAPIV3.DiscriminatorObject | OpenAPIV3_1.DiscriminatorObject;
+type DiscriminatorObject$1 = OpenAPIV3_1.DiscriminatorObject;
 /**
  * OpenAPI reference object pointing to a schema definition via `$ref`.
  */
-type ReferenceObject$1 = OpenAPIV3.ReferenceObject;
+type ReferenceObject$1 = OpenAPIV3_1.ReferenceObject;
 /**
  * OpenAPI response object holding the content and headers for one status code.
  */
-type ResponseObject$1 = OpenAPIV3.ResponseObject | OpenAPIV3_1.ResponseObject;
+type ResponseObject$1 = OpenAPIV3_1.ResponseObject;
 /**
  * OpenAPI media type object that maps a content-type string to its schema.
  */
-type MediaTypeObject$1 = OpenAPIV3.MediaTypeObject | OpenAPIV3_1.MediaTypeObject;
+type MediaTypeObject$1 = OpenAPIV3_1.MediaTypeObject;
 /**
  * Configuration for the OpenAPI adapter: spec validation, content-type selection,
  * server URL resolution, and how schema types are derived.

package/dist/index.js

@@ -1,8 +1,9 @@
-import "./chunk-C0LytTxp.js";
+import "./rolldown-runtime-C0LytTxp.js";
 import { Diagnostics, ast, createAdapter } from "@kubb/core";
 import path from "node:path";
 import { access, readFile } from "node:fs/promises";
 import { compileErrors, validate } from "@readme/openapi-parser";
+import { upgrade } from "@scalar/openapi-upgrader";
 import { parse } from "yaml";
 import { bundle } from "api-ref-bundler";
 import { macroDiscriminatorEnum, macroEnumName, macroSimplifyUnion } from "@kubb/ast/macros";
@@ -52,18 +53,6 @@ const SUPPORTED_METHODS = new Set([
 	"trace"
 ]);
 /**
-* OpenAPI version string written into the stub document created during multi-spec merges.
-*/
-const MERGE_OPENAPI_VERSION = "3.0.0";
-/**
-* Fallback `info.title` placed in the stub document when merging multiple API files.
-*/
-const MERGE_DEFAULT_TITLE = "Merged API";
-/**
-* Fallback `info.version` placed in the stub document when merging multiple API files.
-*/
-const MERGE_DEFAULT_VERSION = "1.0.0";
-/**
 * Set of JSON Schema keywords that prevent a schema fragment from being inlined during `allOf` flattening.
 *
 * A fragment that contains any of these keys carries structural meaning of its own and must stay as a separate
@@ -143,15 +132,6 @@ const formatMap = {
 * ```
 */
 const enumExtensionKeys = ["x-enumNames", "x-enum-varnames"];
-/**
-* Maps the `unknownType`/`emptySchemaType` option string to its `ScalarSchemaType` constant.
-* A `Map` (over a plain object) lets callers test key membership with `.has()`.
-*/
-const typeOptionMap = new Map([
-	["any", ast.schemaTypes.any],
-	["unknown", ast.schemaTypes.unknown],
-	["void", ast.schemaTypes.void]
-]);
 //#endregion
 //#region ../../internals/utils/src/casing.ts
 /**
@@ -292,40 +272,6 @@ async function read(path) {
 	return readFile(path, { encoding: "utf8" });
 }
 //#endregion
-//#region ../../internals/utils/src/object.ts
-/**
-* Returns `true` when `value` is a plain (non-null, non-array) object.
-*
-* @example
-* ```ts
-* isPlainObject({})          // true
-* isPlainObject([])          // false
-* isPlainObject(null)        // false
-* ```
-*/
-function isPlainObject(value) {
-	return typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype;
-}
-/**
-* Recursively merges `source` into `target`, combining nested plain objects.
-* Arrays and non-object values from `source` override the corresponding values in `target`.
-*
-* @example
-* ```ts
-* mergeDeep({ a: { x: 1 } }, { a: { y: 2 } })
-* // { a: { x: 1, y: 2 } }
-* ```
-*/
-function mergeDeep(target, source) {
-	const result = { ...target };
-	for (const key of Object.keys(source)) {
-		const sv = source[key];
-		const tv = result[key];
-		result[key] = sv !== null && typeof sv === "object" && !Array.isArray(sv) && tv !== null && typeof tv === "object" && !Array.isArray(tv) ? mergeDeep(tv, sv) : sv;
-	}
-	return result;
-}
-//#endregion
 //#region ../../internals/utils/src/reserved.ts
 /**
 * JavaScript and Java reserved words.
@@ -573,128 +519,29 @@ async function bundleDocument(pathOrUrl) {
 	return await bundle(pathOrUrl, resolver);
 }
 //#endregion
-//#region src/guards.ts
-/**
-* Returns `true` when `doc` is a Swagger 2.0 document (no `openapi` key).
-*
-* @example
-* ```ts
-* if (isOpenApiV2Document(doc)) {
-*   // doc is OpenAPIV2.Document
-* }
-* ```
-*/
-function isOpenApiV2Document(doc) {
-	return !!doc && isPlainObject(doc) && !("openapi" in doc);
-}
-/**
-* Returns `true` when a schema should be treated as nullable.
-*
-* Recognizes all nullable signals across OAS versions: `nullable: true` (OAS 3.0),
-* `x-nullable: true` (vendor extension), `type: 'null'`, and `type: ['null', ...]` (OAS 3.1).
-*
-* @example
-* ```ts
-* isNullable({ type: 'string', nullable: true }) // true
-* isNullable({ type: ['string', 'null'] })       // true
-* isNullable({ type: 'string' })                 // false
-* ```
-*/
-function isNullable(schema) {
-	if ((schema?.nullable ?? schema?.["x-nullable"]) === true) return true;
-	const schemaType = schema?.type;
-	if (schemaType === "null") return true;
-	if (Array.isArray(schemaType)) return schemaType.includes("null");
-	return false;
-}
-/**
-* Returns `true` when `obj` is an OpenAPI `$ref` pointer object.
-*
-* @example
-* ```ts
-* isReference({ $ref: '#/components/schemas/Pet' }) // true
-* isReference({ type: 'string' })                   // false
-* ```
-*/
-function isReference(obj) {
-	return !!obj && typeof obj === "object" && "$ref" in obj;
-}
-/**
-* Returns `true` when `obj` is a schema with a structured OAS 3.x `discriminator` object.
-*
-* @example
-* ```ts
-* isDiscriminator({ discriminator: { propertyName: 'type', mapping: {} } }) // true
-* isDiscriminator({ discriminator: 'type' })                                 // false (Swagger 2 string form)
-* ```
-*/
-function isDiscriminator(obj) {
-	const record = obj;
-	return !!obj && !!record["discriminator"] && typeof record["discriminator"] !== "string";
-}
-//#endregion
 //#region src/factory.ts
 /**
 * Loads and bundles an OpenAPI document, returning the raw `Document`.
 *
-* Accepts a file path string or an already-parsed document object. File paths and URLs are
-* bundled via `api-ref-bundler`, hoisting external file schemas into named `components.schemas`
-* entries so generators can emit named types and imports. Swagger 2.0 documents are
-* automatically up-converted to OpenAPI 3.0 via `swagger2openapi`.
+* A string is a file path or URL: it is bundled via `api-ref-bundler`, hoisting external file
+* schemas into named `components.schemas` entries so generators can emit named types and imports.
+* An object is treated as an already-parsed document. Swagger 2.0 and OpenAPI 3.0 documents are
+* up-converted to OpenAPI 3.1 via `@scalar/openapi-upgrader`.
 *
 * @example
 * ```ts
 * const document = await parseDocument('./openapi.yaml')
-* const document = await parse(rawDocumentObject, { canBundle: false })
-* ```
-*/
-async function parseDocument(pathOrApi, { canBundle = true } = {}) {
-	if (typeof pathOrApi === "string" && canBundle) return parseDocument(await bundleDocument(pathOrApi), { canBundle: false });
-	const document = typeof pathOrApi === "string" ? parse(pathOrApi) : pathOrApi;
-	if (isOpenApiV2Document(document)) {
-		const { default: swagger2openapi } = await import("swagger2openapi");
-		const { openapi } = await swagger2openapi.convertObj(document, { anchors: true });
-		return openapi;
-	}
-	return document;
-}
-/**
-* Deep-merges multiple OpenAPI documents into a single `Document`.
-*
-* Each document is parsed independently, then deep-merged into one in array order.
-* Throws when the input array is empty.
-*
-* @example
-* ```ts
-* const document = await mergeDocuments(['./pets.yaml', './orders.yaml'])
+* const document = await parseDocument(rawDocumentObject)
 * ```
 */
-async function mergeDocuments(pathOrApi) {
-	const documents = await Promise.all(pathOrApi.map((p) => parseDocument(p, { canBundle: false })));
-	if (documents.length === 0) throw new Diagnostics.Error({
-		code: Diagnostics.code.inputRequired,
-		severity: "error",
-		message: "No OAS documents were provided for merging.",
-		help: "Pass at least one path or document to `input.path`.",
-		location: { kind: "config" }
-	});
-	const seed = {
-		openapi: MERGE_OPENAPI_VERSION,
-		info: {
-			title: MERGE_DEFAULT_TITLE,
-			version: MERGE_DEFAULT_VERSION
-		},
-		paths: {},
-		components: { schemas: {} }
-	};
-	return parseDocument(documents.reduce((acc, current) => mergeDeep(acc, current), seed));
+async function parseDocument(pathOrApi) {
+	if (typeof pathOrApi === "string") return parseDocument(await bundleDocument(pathOrApi));
+	return upgrade(pathOrApi, "3.1");
 }
 /**
 * 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
@@ -704,11 +551,7 @@ async function mergeDocuments(pathOrApi) {
 * ```
 */
 async function parseFromConfig(source) {
-	if (source.type === "data") {
-		if (typeof source.data === "object") return parseDocument(structuredClone(source.data));
-		return parseDocument(source.data, { canBundle: false });
-	}
-	if (source.type === "paths") return mergeDocuments(source.paths);
+	if (source.type === "data") return parseDocument(typeof source.data === "string" ? parse(source.data) : structuredClone(source.data));
 	if (Url.canParse(source.path)) return parseDocument(source.path);
 	const resolved = path.resolve(path.dirname(source.path), source.path);
 	await assertInputExists(resolved);
@@ -767,7 +610,7 @@ function createRefNode(node, target) {
 		deprecated: node.deprecated,
 		description: node.description,
 		default: node.default,
-		example: node.example
+		examples: node.examples
 	});
 }
 /**
@@ -908,6 +751,53 @@ function plan(roots, context) {
 	};
 }
 //#endregion
+//#region src/guards.ts
+/**
+* Returns `true` when a schema should be treated as nullable.
+*
+* Recognizes all nullable signals across OAS versions: `nullable: true` (OAS 3.0),
+* `x-nullable: true` (vendor extension), `type: 'null'`, and `type: ['null', ...]` (OAS 3.1).
+*
+* @example
+* ```ts
+* isNullable({ type: 'string', nullable: true }) // true
+* isNullable({ type: ['string', 'null'] })       // true
+* isNullable({ type: 'string' })                 // false
+* ```
+*/
+function isNullable(schema) {
+	if ((schema?.nullable ?? schema?.["x-nullable"]) === true) return true;
+	const schemaType = schema?.type;
+	if (schemaType === "null") return true;
+	if (Array.isArray(schemaType)) return schemaType.includes("null");
+	return false;
+}
+/**
+* Returns `true` when `obj` is an OpenAPI `$ref` pointer object.
+*
+* @example
+* ```ts
+* isReference({ $ref: '#/components/schemas/Pet' }) // true
+* isReference({ type: 'string' })                   // false
+* ```
+*/
+function isReference(obj) {
+	return !!obj && typeof obj === "object" && "$ref" in obj;
+}
+/**
+* Returns `true` when `obj` is a schema with a structured OAS 3.x `discriminator` object.
+*
+* @example
+* ```ts
+* isDiscriminator({ discriminator: { propertyName: 'type', mapping: {} } }) // true
+* isDiscriminator({ discriminator: 'type' })                                 // false (Swagger 2 string form)
+* ```
+*/
+function isDiscriminator(obj) {
+	const record = obj;
+	return !!obj && !!record["discriminator"] && typeof record["discriminator"] !== "string";
+}
+//#endregion
 //#region src/refs.ts
 const _refCache = /* @__PURE__ */ new WeakMap();
 /**
@@ -1389,14 +1279,16 @@ function getResponseBody(responseBody, contentType) {
 * getResponseSchema(document, operation, '4XX')       // {}
 * ```
 */
-function getResponseSchema(document, operation, statusCode, options = {}) {
-	if (operation.schema.responses) {
-		const responses = operation.schema.responses;
-		for (const key in responses) {
-			const schema = responses[key];
-			if (schema && isReference(schema)) responses[key] = resolveRef(document, schema.$ref);
-		}
+function resolveResponseRefs(document, operation) {
+	const responses = operation.schema.responses;
+	if (!responses) return;
+	for (const key in responses) {
+		const schema = responses[key];
+		if (schema && isReference(schema)) responses[key] = resolveRef(document, schema.$ref);
 	}
+}
+function getResponseSchema(document, operation, statusCode, options = {}) {
+	resolveResponseRefs(document, operation);
 	const responseBody = getResponseBody(getResponseByStatusCode({
 		document,
 		operation,
@@ -1540,9 +1432,6 @@ const semanticSuffixes = {
 	responses: "Response",
 	requestBodies: "Request"
 };
-function getSemanticSuffix(source) {
-	return semanticSuffixes[source];
-}
 function resolveSchemaRef(document, schema) {
 	if (!isReference(schema)) return schema;
 	const resolved = resolveRef(document, schema.$ref);
@@ -1597,7 +1486,7 @@ function getSchemas(document, { contentType }) {
 			}
 		}
 		items.forEach((item, index) => {
-			const suffix = isSingle ? "" : hasMultipleSources ? getSemanticSuffix(item.source) : index === 0 ? "" : String(index + 1);
+			const suffix = isSingle ? "" : hasMultipleSources ? semanticSuffixes[item.source] : index === 0 ? "" : String(index + 1);
 			const uniqueName = item.originalName + suffix;
 			schemas[uniqueName] = item.schema;
 			nameMapping.set(`#/components/${item.source}/${item.originalName}`, uniqueName);
@@ -1644,6 +1533,15 @@ function getDateType(options, format) {
 /**
 * Collects the shared metadata fields passed to every `createSchema` call.
 */
+/**
+* Reads schema examples as an array. OAS 3.1 uses an `examples` array, but specs (including ones
+* labeled 3.1) still use the singular OAS 3.0 `example`, which the upgrader only converts on the
+* 3.0 -> 3.1 hop. Normalize both into one array so the AST node exposes only `examples`.
+*/
+function extractExamples(schema) {
+	if (Array.isArray(schema.examples)) return schema.examples;
+	return schema.example !== void 0 ? [schema.example] : void 0;
+}
 function buildSchemaNode(schema, name, nullable, defaultValue) {
 	return {
 		name,
@@ -1654,7 +1552,7 @@ function buildSchemaNode(schema, name, nullable, defaultValue) {
 		readOnly: schema.readOnly,
 		writeOnly: schema.writeOnly,
 		default: defaultValue,
-		example: schema.example,
+		examples: extractExamples(schema),
 		format: schema.format
 	};
 }
@@ -1690,13 +1588,7 @@ function getRequestBodyContentTypes(document, operation) {
 * ```
 */
 function getResponseBodyContentTypes(document, operation, statusCode) {
-	if (operation.schema.responses) {
-		const responses = operation.schema.responses;
-		for (const key in responses) {
-			const schema = responses[key];
-			if (schema && isReference(schema)) responses[key] = resolveRef(document, schema.$ref);
-		}
-	}
+	resolveResponseRefs(document, operation);
 	const responseObj = getResponseByStatusCode({
 		document,
 		operation,
@@ -1840,7 +1732,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 				readOnly: schema.readOnly ?? memberNode.readOnly,
 				writeOnly: schema.writeOnly ?? memberNode.writeOnly,
 				default: mergedDefault,
-				example: schema.example ?? memberNode.example,
+				examples: extractExamples(schema) ?? memberNode.examples,
 				pattern: schema.pattern ?? ("pattern" in memberNode ? memberNode.pattern : void 0),
 				format: schema.format ?? memberNode.format
 			});
@@ -2084,7 +1976,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 			readOnly: schema.readOnly,
 			writeOnly: schema.writeOnly,
 			default: enumDefault,
-			example: schema.example,
+			examples: extractExamples(schema),
 			format: schema.format
 		};
 		const extensionKey = enumExtensionKeys.find((key) => key in schema);
@@ -2142,10 +2034,10 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 			if (additionalProperties === true) return true;
 			if (additionalProperties === false) return false;
 			if (additionalProperties && Object.keys(additionalProperties).length > 0) return parseSchema({ schema: additionalProperties }, rawOptions);
-			if (additionalProperties) return ast.factory.createSchema({ type: typeOptionMap.get(options.unknownType) });
+			if (additionalProperties) return ast.factory.createSchema({ type: options.unknownType });
 		})();
 		const rawPatternProperties = "patternProperties" in schema ? schema.patternProperties : void 0;
-		const patternProperties = rawPatternProperties ? Object.fromEntries(Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [pattern, patternSchema === true || typeof patternSchema === "object" && Object.keys(patternSchema).length === 0 ? ast.factory.createSchema({ type: typeOptionMap.get(options.unknownType) }) : parseSchema({ schema: patternSchema }, rawOptions)])) : void 0;
+		const patternProperties = rawPatternProperties ? Object.fromEntries(Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [pattern, patternSchema === true || typeof patternSchema === "object" && Object.keys(patternSchema).length === 0 ? ast.factory.createSchema({ type: options.unknownType }) : parseSchema({ schema: patternSchema }, rawOptions)])) : void 0;
 		const objectNode = ast.factory.createSchema({
 			type: "object",
 			primitive: "object",
@@ -2421,7 +2313,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 			const node = rule.convert(schemaCtx);
 			if (node) return node;
 		}
-		const emptyType = typeOptionMap.get(options.emptySchemaType);
+		const emptyType = options.emptySchemaType;
 		return ast.factory.createSchema({
 			type: emptyType,
 			name,
@@ -2440,7 +2332,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		const schema = param["schema"] ? parseSchema({
 			schema: param["schema"],
 			name: schemaName
-		}, options) : ast.factory.createSchema({ type: typeOptionMap.get(options.unknownType) });
+		}, options) : ast.factory.createSchema({ type: options.unknownType });
 		return ast.factory.createParameter({
 			name: paramName,
 			in: param["in"],
@@ -2528,7 +2420,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 					schema: raw && Object.keys(raw).length > 0 ? parseSchema({
 						schema: raw,
 						name: responseName
-					}, options) : ast.factory.createSchema({ type: typeOptionMap.get(options.emptySchemaType) }),
+					}, options) : ast.factory.createSchema({ type: options.emptySchemaType }),
 					keysToOmit: collectPropertyKeysByFlag(raw, "writeOnly")
 				};
 			};