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

package/dist/index.cjs

@@ -26,6 +26,7 @@ let node_path = require("node:path");
 node_path = __toESM(node_path, 1);
 let node_fs_promises = require("node:fs/promises");
 let _readme_openapi_parser = require("@readme/openapi-parser");
+let _scalar_openapi_upgrader = require("@scalar/openapi-upgrader");
 let yaml = require("yaml");
 let api_ref_bundler = require("api-ref-bundler");
 let _kubb_ast_macros = require("@kubb/ast/macros");
@@ -75,18 +76,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
@@ -166,15 +155,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", _kubb_core.ast.schemaTypes.any],
-	["unknown", _kubb_core.ast.schemaTypes.unknown],
-	["void", _kubb_core.ast.schemaTypes.void]
-]);
 //#endregion
 //#region ../../internals/utils/src/casing.ts
 /**
@@ -315,40 +295,6 @@ async function read(path) {
 	return (0, node_fs_promises.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.
@@ -596,128 +542,29 @@ async function bundleDocument(pathOrUrl) {
 	return await (0, api_ref_bundler.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" ? (0, yaml.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 _kubb_core.Diagnostics.Error({
-		code: _kubb_core.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 (0, _scalar_openapi_upgrader.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
@@ -727,11 +574,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" ? (0, yaml.parse)(source.data) : structuredClone(source.data));
 	if (Url.canParse(source.path)) return parseDocument(source.path);
 	const resolved = node_path.default.resolve(node_path.default.dirname(source.path), source.path);
 	await assertInputExists(resolved);
@@ -790,7 +633,7 @@ function createRefNode(node, target) {
 		deprecated: node.deprecated,
 		description: node.description,
 		default: node.default,
-		example: node.example
+		examples: node.examples
 	});
 }
 /**
@@ -931,6 +774,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();
 /**
@@ -1412,14 +1302,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,
@@ -1563,9 +1455,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);
@@ -1620,7 +1509,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);
@@ -1667,6 +1556,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,
@@ -1677,7 +1575,7 @@ function buildSchemaNode(schema, name, nullable, defaultValue) {
 		readOnly: schema.readOnly,
 		writeOnly: schema.writeOnly,
 		default: defaultValue,
-		example: schema.example,
+		examples: extractExamples(schema),
 		format: schema.format
 	};
 }
@@ -1713,13 +1611,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,
@@ -1863,7 +1755,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
 			});
@@ -2107,7 +1999,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);
@@ -2165,10 +2057,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 _kubb_core.ast.factory.createSchema({ type: typeOptionMap.get(options.unknownType) });
+			if (additionalProperties) return _kubb_core.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 ? _kubb_core.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 ? _kubb_core.ast.factory.createSchema({ type: options.unknownType }) : parseSchema({ schema: patternSchema }, rawOptions)])) : void 0;
 		const objectNode = _kubb_core.ast.factory.createSchema({
 			type: "object",
 			primitive: "object",
@@ -2444,7 +2336,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 _kubb_core.ast.factory.createSchema({
 			type: emptyType,
 			name,
@@ -2463,7 +2355,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		const schema = param["schema"] ? parseSchema({
 			schema: param["schema"],
 			name: schemaName
-		}, options) : _kubb_core.ast.factory.createSchema({ type: typeOptionMap.get(options.unknownType) });
+		}, options) : _kubb_core.ast.factory.createSchema({ type: options.unknownType });
 		return _kubb_core.ast.factory.createParameter({
 			name: paramName,
 			in: param["in"],
@@ -2551,7 +2443,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 					schema: raw && Object.keys(raw).length > 0 ? parseSchema({
 						schema: raw,
 						name: responseName
-					}, options) : _kubb_core.ast.factory.createSchema({ type: typeOptionMap.get(options.emptySchemaType) }),
+					}, options) : _kubb_core.ast.factory.createSchema({ type: options.emptySchemaType }),
 					keysToOmit: collectPropertyKeysByFlag(raw, "writeOnly")
 				};
 			};