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

package/dist/index.d.ts

@@ -1250,7 +1250,7 @@ type AdapterOasResolvedOptions = {
   enumSuffix: AdapterOasOptions['enumSuffix'];
   /**
    * Map from original `$ref` paths to their collision-resolved schema names.
-   * Populated after each `parse()` call.
+   * Populated once the adapter resolves a spec's schemas, on the first `stream()` or `parse()`.
    *
    * @example
    * ```ts
@@ -1267,7 +1267,7 @@ type AdapterOas = AdapterFactoryOptions<'oas', AdapterOasOptions, AdapterOasReso
 //#endregion
 //#region src/adapter.d.ts
 /**
- * Canonical adapter name for `@kubb/adapter-oas`. Used for driver lookups.
+ * The `name` of `@kubb/adapter-oas`, used to identify this adapter in a Kubb config.
  */
 declare const adapterOasName = "oas";
 /**

package/dist/index.js

@@ -14,10 +14,9 @@ import { collect, narrowSchema } from "@kubb/ast";
 *
 * @example
 * ```ts
-* import { DEFAULT_PARSER_OPTIONS } from '@kubb/adapter-oas'
+* import { DEFAULT_PARSER_OPTIONS, parseOas } from '@kubb/adapter-oas'
 *
-* const parser = createOasParser(oas)
-* const root = parser.parse({ ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
+* const { root } = parseOas(document, { ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
 * ```
 */
 const DEFAULT_PARSER_OPTIONS = {
@@ -88,12 +87,24 @@ const structuralKeys = new Set([
 	"not"
 ]);
 /**
+* Formats `convertFormat` maps to a dedicated type without going through `formatMap`:
+* `int64` and the date/time family. Keep this in sync with the `convertFormat`
+* special-cases in `parser.ts`. `isHandledFormat` reads it so the
+* `KUBB_UNSUPPORTED_FORMAT` diagnostic and the parser agree on what is handled.
+*/
+const specialCasedFormats = new Set([
+	"int64",
+	"date-time",
+	"date",
+	"time"
+]);
+/**
 * Static map from OAS `format` strings to Kubb `SchemaType` values.
 *
 * Only formats whose AST type differs from the OAS `type` field appear here.
-* Formats that depend on runtime options (`int64`, `date-time`, `date`, `time`) are handled separately
-* in the parser. `ipv4` and `ipv6` map to their own dedicated schema types. `hostname` and
-* `idn-hostname` map to `'url'` as the closest generic string-format type.
+* Formats that depend on runtime options (`int64`, `date-time`, `date`, `time`) are handled
+* separately in the parser. `ipv4` and `ipv6` map to their own dedicated schema types. `hostname`
+* and `idn-hostname` map to `'url'` as the closest generic string-format type.
 *
 * @example
 * ```ts
@@ -104,18 +115,6 @@ const structuralKeys = new Set([
 * formatMap['float']  // 'number'
 * ```
 */
-/**
-* Formats `convertFormat` maps to a dedicated type without going through `formatMap`:
-* `int64` and the date/time family. Keep this in sync with the `convertFormat`
-* special-cases in `parser.ts`. `isHandledFormat` reads it so the
-* `KUBB_UNSUPPORTED_FORMAT` diagnostic and the parser agree on what is handled.
-*/
-const specialCasedFormats = new Set([
-	"int64",
-	"date-time",
-	"date",
-	"time"
-]);
 const formatMap = {
 	uuid: "uuid",
 	email: "email",
@@ -636,7 +635,7 @@ function isDiscriminator(obj) {
 //#endregion
 //#region src/factory.ts
 /**
-* Loads and dereferences an OpenAPI document, returning the raw `Document`.
+* 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`
@@ -747,17 +746,180 @@ async function validateDocument(document, { throwOnError = false } = {}) {
 	}
 }
 //#endregion
+//#region src/dedupe.ts
+/**
+* Minimum occurrences before a shape is deduplicated.
+*/
+const MIN_OCCURRENCES = 2;
+/**
+* Builds the shared `ref` replacement for a duplicate occurrence, carrying the
+* usage-slot and documentation fields that are not part of the shared type.
+*/
+function createRefNode(node, target) {
+	return ast.factory.createSchema({
+		type: "ref",
+		name: target.name,
+		ref: target.ref,
+		optional: node.optional,
+		nullish: node.nullish,
+		readOnly: node.readOnly,
+		writeOnly: node.writeOnly,
+		deprecated: node.deprecated,
+		description: node.description,
+		default: node.default,
+		example: node.example
+	});
+}
+/**
+* Strips usage-slot flags from an extracted definition and applies its name.
+* A standalone definition is never optional, so `optional`/`nullish` are cleared.
+*/
+function cleanDefinition(node, name) {
+	return {
+		...node,
+		name,
+		optional: void 0,
+		nullish: void 0
+	};
+}
+/**
+* Returns `true` when a node is eligible for deduplication. Only enums and objects qualify, and
+* object shapes that take part in a circular chain are rejected so recursive structures are not
+* extracted (which would break the cycle).
+*/
+function isCandidate(node, circularSchemas) {
+	if (node.type === "enum") return true;
+	if (node.type !== "object") return false;
+	if (node.name && circularSchemas.has(node.name)) return false;
+	return !containsCircularRef(node, { circularSchemas });
+}
+/**
+* Produces the name for an inline shape with no existing named component, resolving
+* collisions against `usedNames`. Returns `null` for an unnamed shape, which stays inline.
+*/
+function nameFor(node, usedNames) {
+	const base = node.name;
+	if (!base) return null;
+	let name = base;
+	let counter = 2;
+	while (usedNames.has(name)) name = `${base}${counter++}`;
+	usedNames.add(name);
+	return name;
+}
+/**
+* Scans a forest of schema and operation nodes and produces a {@link Plan}.
+*
+* A shape that occurs at least {@link MIN_OCCURRENCES} times is deduplicated: if any occurrence is
+* a named top-level schema, the first one becomes the target (so other top-level duplicates and
+* inline copies turn into references to it). Other top-level names with the same content are
+* recorded as aliases. Otherwise a new definition is extracted using {@link nameFor}. The returned
+* plan rewrites nodes against those decisions.
+*
+* @example
+* ```ts
+* const dedupePlan = plan([...schemaNodes, ...operationNodes], { circularSchemas, usedNames })
+* ```
+*/
+function plan(roots, context) {
+	const { circularSchemas, usedNames } = context;
+	const topLevelNodes = /* @__PURE__ */ new Set();
+	const groups = /* @__PURE__ */ new Map();
+	for (const root of roots) {
+		if (root.kind === "Schema") topLevelNodes.add(root);
+		for (const schemaNode of ast.collect(root, { schema: (node) => node })) {
+			if (!isCandidate(schemaNode, circularSchemas)) continue;
+			const signature = ast.signatureOf(schemaNode);
+			const isTopLevel = topLevelNodes.has(schemaNode) && !!schemaNode.name;
+			const group = groups.get(signature);
+			if (group) {
+				group.count++;
+				if (isTopLevel) group.topLevelNames.push(schemaNode.name);
+			} else groups.set(signature, {
+				count: 1,
+				representative: schemaNode,
+				topLevelNames: isTopLevel ? [schemaNode.name] : []
+			});
+		}
+	}
+	const bySignature = /* @__PURE__ */ new Map();
+	const byName = /* @__PURE__ */ new Map();
+	const pendingExtractions = [];
+	for (const [signature, group] of groups) {
+		if (group.count < MIN_OCCURRENCES) continue;
+		const [firstName, ...duplicateNames] = group.topLevelNames;
+		if (firstName) {
+			const target = {
+				name: firstName,
+				ref: `${SCHEMA_REF_PREFIX}${firstName}`
+			};
+			bySignature.set(signature, target);
+			for (const duplicate of duplicateNames) byName.set(duplicate, target);
+			continue;
+		}
+		const name = nameFor(group.representative, usedNames);
+		if (!name) continue;
+		bySignature.set(signature, {
+			name,
+			ref: `${SCHEMA_REF_PREFIX}${name}`
+		});
+		pendingExtractions.push({
+			name,
+			representative: group.representative
+		});
+	}
+	function rewrite(node, skipRootMatch) {
+		if (bySignature.size === 0 && byName.size === 0) return node;
+		const root = node;
+		return ast.transform(node, { schema(schemaNode) {
+			if (schemaNode.type === "ref") {
+				const refName = schemaNode.ref ? extractRefName(schemaNode.ref) : schemaNode.name;
+				const target = refName ? byName.get(refName) : void 0;
+				return target ? {
+					...schemaNode,
+					name: target.name,
+					ref: target.ref
+				} : void 0;
+			}
+			if (skipRootMatch && schemaNode === root) return void 0;
+			const target = bySignature.get(ast.signatureOf(schemaNode));
+			if (!target) return void 0;
+			return createRefNode(schemaNode, target);
+		} });
+	}
+	return {
+		extracted: pendingExtractions.map(({ name, representative }) => cleanDefinition(rewrite(representative, true), name)),
+		apply(node) {
+			return rewrite(node, false);
+		},
+		applyTopLevel(node) {
+			const target = bySignature.get(ast.signatureOf(node));
+			if (target && target.name !== node.name) return ast.factory.createSchema({
+				type: "ref",
+				name: node.name ?? null,
+				ref: target.ref,
+				description: node.description,
+				deprecated: node.deprecated
+			});
+			return rewrite(node, true);
+		},
+		isAlias(name) {
+			return byName.has(name);
+		}
+	};
+}
+//#endregion
 //#region src/refs.ts
 const _refCache = /* @__PURE__ */ new WeakMap();
 /**
 * Resolves a local JSON pointer reference from a document.
 *
-* Accepts `#/...` refs. Returns `null` for empty or non-local refs.
-* Throws when the pointer cannot be resolved.
+* Accepts `#/...` refs. Returns `null` for an empty or non-local ref. When the pointer cannot be
+* resolved, reports a `refNotFound` diagnostic into the active build and returns `null`. Outside a
+* build there is no sink to collect it, so it throws instead.
 *
 * @example
 * ```ts
-* resolveRef<SchemaObject>(document, '#/components/schemas/Pet') // SchemaObject | null
+* resolveRef<SchemaObject>(document, '#/components/schemas/Pet')
 * ```
 */
 function resolveRef(document, $ref) {
@@ -814,23 +976,6 @@ function dereferenceWithRef(document, schema) {
 //#endregion
 //#region src/dialect.ts
 /**
-* Derives a schema's `optional`/`nullish` flags from a parent's `required` value and the
-* schema's own `nullable`. How "required" and "nullable" combine is OpenAPI-specific, so it
-* lives in the dialect.
-*
-* - Non-required + non-nullable → `optional: true`.
-* - Non-required + nullable → `nullish: true`.
-* - Required → both flags cleared.
-*/
-function optionality(schema, required) {
-	const nullable = schema.nullable ?? false;
-	return {
-		...schema,
-		optional: !required && !nullable ? true : void 0,
-		nullish: !required && nullable ? true : void 0
-	};
-}
-/**
 * The OpenAPI / Swagger dialect, the default used by `@kubb/adapter-oas`.
 *
 * Implements the spec-agnostic {@link ast.SchemaDialect} contract: it isolates the
@@ -856,14 +1001,14 @@ const oasDialect = ast.defineDialect({
 		isReference,
 		isDiscriminator,
 		isBinary: (schema) => schema.type === "string" && schema.contentMediaType === "application/octet-stream",
-		resolveRef,
-		optionality
-	}
+		resolveRef
+	},
+	dedupe: { plan }
 });
 //#endregion
 //#region src/discriminator.ts
 /**
-* Builds a map of child schema names → discriminator patch data by scanning the given
+* Maps each child schema name to its discriminator patch data by scanning the given
 * top-level AST schema nodes for union schemas that carry a `discriminatorPropertyName`.
 *
 * The streaming path calls this on a small pre-parsed subset of schemas (only the
@@ -979,9 +1124,8 @@ function findDiscriminator(mapping, ref) {
 /**
 * MIME type fragments that mark a media type as JSON-like.
 *
-* Matches the substrings used by the `oas` library's `matchesMimeType.json`, so a content type is
-* JSON when it contains any of these. The `+json` entry catches structured-syntax suffixes such as
-* `application/vnd.api+json`.
+* A content type is JSON when it contains any of these substrings. The `+json` entry catches
+* structured-syntax suffixes such as `application/vnd.api+json`.
 */
 const jsonMimeFragments = [
 	"application/json",
@@ -1077,8 +1221,8 @@ function getRequestContent({ document, operation, mediaType }) {
 	return available ? [available, content[available]] : false;
 }
 /**
-* Returns the primary request content type. Prefers a JSON-like media type (the last one wins,
-* matching the previous behavior), then the first declared one, defaulting to `'application/json'`.
+* Returns the primary request content type. Prefers a JSON-like media type (the last one wins
+* when several are declared), then the first declared one, defaulting to `'application/json'`.
 */
 function getRequestContentType({ document, operation }) {
 	const content = getRequestBodyContent({
@@ -1173,9 +1317,9 @@ function getSchemaType(format) {
 	return formatMap[format] ?? null;
 }
 /**
-* Whether the parser maps `format` to a dedicated type. True for any `formatMap` entry and the
-* `specialCasedFormats` `convertFormat` handles directly. False means the format falls back to the
-* base type, which is what `KUBB_UNSUPPORTED_FORMAT` flags. Reading both sources keeps the
+* Whether the parser maps `format` to a dedicated type. True for any `formatMap` entry, plus the
+* `specialCasedFormats` that `convertFormat` handles directly. False means the format falls back to
+* the base type, which is what `KUBB_UNSUPPORTED_FORMAT` flags. Reading both sources keeps the
 * diagnostic in step with the parser as `formatMap` grows.
 */
 function isHandledFormat(format) {
@@ -1193,7 +1337,7 @@ function getPrimitiveType(type) {
 /**
 * 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.
+* Each `$ref` parameter is dereferenced via `dereferenceWithRef` before merging.
 *
 * @example
 * ```ts
@@ -1294,7 +1438,10 @@ function getRequestSchema(document, operation, options = {}) {
 * ```ts
 * flattenSchema({ allOf: [{ description: 'A pet' }], type: 'object', properties: {} })
 * // { type: 'object', properties: {}, description: 'A pet' }
+* ```
 *
+* @example
+* ```ts
 * flattenSchema({ allOf: [{ $ref: '#/components/schemas/Pet' }] })
 * // returned unchanged, contains a $ref
 * ```
@@ -1988,7 +2135,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 					nullable: schemaNode.type === "null" ? void 0 : propNullable || void 0
 				},
 				required
-			}, dialect);
+			});
 		}) : [];
 		const additionalProperties = schema.additionalProperties;
 		const additionalPropertiesNode = (() => {
@@ -2302,7 +2449,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 				description: param["description"] ?? schema.description
 			},
 			required
-		}, dialect);
+		});
 	}
 	/**
 	* Reads the inline `requestBody` metadata (description / required) that OAS exposes
@@ -2355,7 +2502,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 			if (!schema) return [];
 			return [ast.factory.createContent({
 				contentType: ct,
-				schema: dialect.schema.optionality(parseSchema({
+				schema: ast.optionality(parseSchema({
 					schema,
 					name: requestBodyName
 				}, options), requestBodyMeta.required),
@@ -2558,30 +2705,15 @@ function preScan({ schemas, parseSchema, parseOperation, document, parserOptions
 		}
 		const circularSchemas = new Set(circularNames);
 		const usedNames = new Set(Object.keys(schemas));
-		dedupePlan = ast.buildDedupePlan([...allNodes, ...operationNodes], {
-			isCandidate: (node) => {
-				if (node.type === "enum") return true;
-				if (node.type !== "object") return false;
-				if (node.name && circularSchemas.has(node.name)) return false;
-				return !containsCircularRef(node, { circularSchemas });
-			},
-			nameFor: (node) => {
-				const base = node.name;
-				if (!base) return null;
-				let name = base;
-				let counter = 2;
-				while (usedNames.has(name)) name = `${base}${counter++}`;
-				usedNames.add(name);
-				return name;
-			},
-			refFor: (name) => `${SCHEMA_REF_PREFIX}${name}`
+		dedupePlan = oasDialect.dedupe.plan([...allNodes, ...operationNodes], {
+			circularSchemas,
+			usedNames
 		});
-		for (const definition of dedupePlan.hoisted) if (definition.type === "enum" && definition.name) enumNames.push(definition.name);
+		for (const definition of dedupePlan.extracted) if (definition.type === "enum" && definition.name) enumNames.push(definition.name);
 	}
-	const aliasNames = dedupePlan?.aliasNames;
 	return {
 		refAliasMap,
-		enumNames: aliasNames && aliasNames.size > 0 ? enumNames.filter((name) => !aliasNames.has(name)) : enumNames,
+		enumNames: dedupePlan ? enumNames.filter((name) => !dedupePlan.isAlias(name)) : enumNames,
 		circularNames,
 		discriminatorChildMap,
 		dedupePlan
@@ -2606,39 +2738,29 @@ function preScan({ schemas, parseSchema, parseOperation, document, parserOptions
 * ```
 */
 function createInputStream({ schemas, parseSchema, parseOperation, document, parserOptions, refAliasMap, discriminatorChildMap, dedupePlan, meta }) {
-	const rewriteTopLevelSchema = (node) => {
-		if (!dedupePlan) return node;
-		const canonical = dedupePlan.canonicalBySignature.get(ast.signatureOf(node));
-		if (canonical && canonical.name !== node.name) return ast.factory.createSchema({
-			type: "ref",
-			name: node.name ?? null,
-			ref: canonical.ref,
-			description: node.description,
-			deprecated: node.deprecated
-		});
-		return ast.applyDedupe(node, dedupePlan, true);
-	};
 	const schemasIterable = { [Symbol.asyncIterator]() {
 		return (async function* () {
-			if (dedupePlan) for (const definition of dedupePlan.hoisted) yield definition;
+			if (dedupePlan) for (const definition of dedupePlan.extracted) yield definition;
 			for (const [name, schema] of Object.entries(schemas)) {
-				if (dedupePlan?.aliasNames.has(name)) continue;
+				if (dedupePlan?.isAlias(name)) continue;
 				const alias = refAliasMap.get(name);
 				if (alias?.name && schemas[alias.name]) {
-					yield rewriteTopLevelSchema({
+					const aliasNode = {
 						...parseSchema({
 							schema: schemas[alias.name],
 							name: alias.name
 						}, parserOptions),
 						name
-					});
+					};
+					yield dedupePlan ? dedupePlan.applyTopLevel(aliasNode) : aliasNode;
 					continue;
 				}
 				const parsed = parseSchema({
 					schema,
 					name
 				}, parserOptions);
-				yield rewriteTopLevelSchema(discriminatorChildMap?.get(name) ? patchDiscriminatorNode(parsed, discriminatorChildMap.get(name)) : parsed);
+				const node = discriminatorChildMap?.get(name) ? patchDiscriminatorNode(parsed, discriminatorChildMap.get(name)) : parsed;
+				yield dedupePlan ? dedupePlan.applyTopLevel(node) : node;
 			}
 		})();
 	} };
@@ -2646,7 +2768,7 @@ function createInputStream({ schemas, parseSchema, parseOperation, document, par
 		return (async function* () {
 			for (const operation of getOperations(document)) {
 				const node = parseOperation(parserOptions, operation);
-				if (node) yield dedupePlan ? ast.applyDedupe(node, dedupePlan) : node;
+				if (node) yield dedupePlan ? dedupePlan.apply(node) : node;
 			}
 		})();
 	} };
@@ -2660,7 +2782,7 @@ function createInputStream({ schemas, parseSchema, parseOperation, document, par
 //#endregion
 //#region src/adapter.ts
 /**
-* Canonical adapter name for `@kubb/adapter-oas`. Used for driver lookups.
+* The `name` of `@kubb/adapter-oas`, used to identify this adapter in a Kubb config.
 */
 const adapterOasName = "oas";
 /**