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

package/dist/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

@@ -53,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
@@ -144,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
 /**
@@ -293,27 +272,6 @@ async function read(path) {
 	return readFile(path, { encoding: "utf8" });
 }
 //#endregion
-//#region ../../internals/utils/src/object.ts
-/**
-* 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.
@@ -565,58 +523,25 @@ async function bundleDocument(pathOrUrl) {
 /**
 * 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 `@scalar/openapi-upgrader`.
+* 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 });
-	return upgrade(typeof pathOrApi === "string" ? parse(pathOrApi) : pathOrApi, "3.0");
-}
-/**
-* 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
@@ -626,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);
@@ -689,7 +610,7 @@ function createRefNode(node, target) {
 		deprecated: node.deprecated,
 		description: node.description,
 		default: node.default,
-		example: node.example
+		examples: node.examples
 	});
 }
 /**
@@ -1358,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,
@@ -1509,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);
@@ -1566,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);
@@ -1613,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,
@@ -1623,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
 	};
 }
@@ -1659,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,
@@ -1809,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
 			});
@@ -2053,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);
@@ -2111,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",
@@ -2390,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,
@@ -2409,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"],
@@ -2497,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")
 				};
 			};