@kubb/adapter-oas 5.0.0-beta.67 → 5.0.0-beta.69

package/dist/index.d.ts

@@ -1162,6 +1162,22 @@ type ResponseObject$1 = OpenAPIV3_1.ResponseObject;
  * OpenAPI media type object that maps a content-type string to its schema.
  */
 type MediaTypeObject$1 = OpenAPIV3_1.MediaTypeObject;
+/**
+ * Selects which entry in the spec's `servers` array becomes the base URL and
+ * supplies values for its `{variable}` placeholders.
+ */
+type ServerOptions = {
+  /**
+   * Index into the `servers` array from your OpenAPI spec. Most projects pick
+   * `0` for the primary server. Omit to leave `baseURL` undefined.
+   */
+  index?: number;
+  /**
+   * Override values for `{variable}` placeholders in the selected server URL.
+   * Variables you do not provide use their `default` value from the spec.
+   */
+  variables?: Record<string, string>;
+};
 /**
  * Configuration for the OpenAPI adapter: spec validation, content-type selection,
  * server URL resolution, and how schema types are derived.
@@ -1171,8 +1187,7 @@ type MediaTypeObject$1 = OpenAPIV3_1.MediaTypeObject;
  * adapterOas({
  *   validate: false,
  *   dateType: 'date',
- *   serverIndex: 0,
- *   serverVariables: { env: 'prod' },
+ *   server: { index: 0, variables: { env: 'prod' } },
  * })
  * ```
  */
@@ -1191,47 +1206,38 @@ type AdapterOasOptions = {
    */
   contentType?: ContentType;
   /**
-   * Index into the `servers` array from your OpenAPI spec. Used to compute the
-   * base URL for plugins that need it. Most projects pick `0` for the primary
-   * server. Omit to leave `baseURL` undefined.
-   */
-  serverIndex?: number;
-  /**
-   * Override values for `{variable}` placeholders in the selected server URL.
-   * Only used when `serverIndex` is set. Variables you do not provide use
-   * their `default` value from the spec.
+   * Selects the server entry used to compute the base URL for plugins that need
+   * it, and overrides its `{variable}` placeholders. Omit to leave `baseURL`
+   * undefined.
    *
    * @example
    * ```ts
    * // spec server: "https://api.{env}.example.com"
-   * serverVariables: { env: 'prod' }
+   * server: { index: 0, variables: { env: 'prod' } }
    * // → baseURL: "https://api.prod.example.com"
    * ```
    */
-  serverVariables?: Record<string, string>;
+  server?: ServerOptions;
   /**
    * How the `discriminator` field on `oneOf`/`anyOf` schemas is interpreted.
-   * - `'strict'` child schemas stay exactly as written. The discriminator
+   * - `'preserve'` child schemas stay exactly as written. The discriminator
    *   narrows types at the call site but child shapes are not modified.
-   * - `'inherit'` Kubb propagates the discriminator property as a literal
-   *   value into each child schema, so each branch's discriminator field is
-   *   precisely typed.
+   * - `'propagate'` Kubb pushes the discriminator property as a literal value
+   *   into each child schema, so each branch's discriminator field is precisely
+   *   typed.
    *
-   * @default 'strict'
+   * @default 'preserve'
    */
-  discriminator?: 'strict' | 'inherit';
+  discriminator?: 'preserve' | 'propagate';
   /**
-   * Collapse structurally identical schemas and enums into a single shared definition.
-   *
-   * Duplicated inline shapes (especially enums repeated across many properties) are hoisted
-   * into one named schema. Every other occurrence, and any structurally identical top-level
-   * component, becomes a `ref` to it. Equality is shape-only, so documentation such as
-   * `description` and `example` is ignored. Set to `false` to keep every occurrence inline
-   * and produce byte-for-byte identical output to earlier versions.
+   * Where inline enums live.
+   * - `'inline'` keeps each enum inline on the property that declares it.
+   * - `'root'` lifts every inline enum to a reusable top-level schema named after its context
+   *   (e.g. `PetStatusEnum`) and references it everywhere it appears.
    *
-   * @default true
+   * @default 'inline'
    */
-  dedupe?: boolean;
+  enums?: 'inline' | 'root';
 } & Partial<ast.ParserOptions>;
 /**
  * Adapter options after defaults have been applied and schema name collisions resolved.
@@ -1239,10 +1245,9 @@ type AdapterOasOptions = {
 type AdapterOasResolvedOptions = {
   validate: boolean;
   contentType: AdapterOasOptions['contentType'];
-  serverIndex: AdapterOasOptions['serverIndex'];
-  serverVariables: AdapterOasOptions['serverVariables'];
+  server: AdapterOasOptions['server'];
   discriminator: NonNullable<AdapterOasOptions['discriminator']>;
-  dedupe: NonNullable<AdapterOasOptions['dedupe']>;
+  enums: NonNullable<AdapterOasOptions['enums']>;
   dateType: NonNullable<AdapterOasOptions['dateType']>;
   integerType: NonNullable<AdapterOasOptions['integerType']>;
   unknownType: NonNullable<AdapterOasOptions['unknownType']>;
@@ -1289,8 +1294,8 @@ declare const adapterOasName = "oas";
  *   input: { path: './petStore.yaml' },
  *   output: { path: './src/gen' },
  *   adapter: adapterOas({
- *     serverIndex: 0,
- *     discriminator: 'inherit',
+ *     server: { index: 0 },
+ *     discriminator: 'propagate',
  *     dateType: 'date',
  *   }),
  *   plugins: [pluginTs()],

package/dist/index.js

@@ -7,7 +7,7 @@ import { upgrade } from "@scalar/openapi-upgrader";
 import { parse } from "yaml";
 import { bundle } from "api-ref-bundler";
 import { macroDiscriminatorEnum, macroEnumName, macroSimplifyUnion } from "@kubb/ast/macros";
-import { childName, containsCircularRef, enumPropName, extractRefName, findCircularSchemas, mergeAdjacentObjectsLazy } from "@kubb/ast/utils";
+import { childName, enumPropName, extractRefName, findCircularSchemas, mergeAdjacentObjectsLazy } from "@kubb/ast/utils";
 import { collect, narrowSchema } from "@kubb/ast";
 //#region src/constants.ts
 /**
@@ -589,168 +589,6 @@ 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,
-		examples: node.examples
-	});
-}
-/**
-* 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/guards.ts
 /**
 * Returns `true` when a schema should be treated as nullable.
@@ -892,8 +730,7 @@ const oasDialect = ast.defineDialect({
 		isDiscriminator,
 		isBinary: (schema) => schema.type === "string" && schema.contentMediaType === "application/octet-stream",
 		resolveRef
-	},
-	dedupe: { plan }
+	}
 });
 //#endregion
 //#region src/discriminator.ts
@@ -2475,6 +2312,53 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 	};
 }
 //#endregion
+//#region src/promoteEnums.ts
+/**
+* Collects inline enums to lift to the top level, keyed by the name the parser derived for them
+* (e.g. `PetStatusEnum`). An enum already defined as a top-level component is left as-is, and a
+* name that recurs maps to the first definition so each name yields one shared type.
+*/
+function collectInlineEnums(roots, topLevelNames) {
+	const promoted = /* @__PURE__ */ new Map();
+	for (const root of roots) {
+		const isSchemaRoot = root.kind === "Schema";
+		for (const node of ast.collect(root, { schema: (schemaNode) => schemaNode })) {
+			if (node.type !== "enum" || !node.name) continue;
+			if (isSchemaRoot && node === root) continue;
+			if (topLevelNames.has(node.name)) continue;
+			if (!promoted.has(node.name)) promoted.set(node.name, {
+				...node,
+				optional: void 0,
+				nullish: void 0
+			});
+		}
+	}
+	return promoted;
+}
+/**
+* Replaces every promoted inline enum in `node` with a `ref` to its lifted definition, keeping the
+* occurrence's usage-slot and documentation fields.
+*/
+function refPromotedEnums(node, promoted) {
+	if (promoted.size === 0) return node;
+	return ast.transform(node, { schema(schemaNode) {
+		if (schemaNode.type !== "enum" || !schemaNode.name || !promoted.has(schemaNode.name)) return void 0;
+		return ast.factory.createSchema({
+			type: "ref",
+			name: schemaNode.name,
+			ref: `${SCHEMA_REF_PREFIX}${schemaNode.name}`,
+			optional: schemaNode.optional,
+			nullish: schemaNode.nullish,
+			readOnly: schemaNode.readOnly,
+			writeOnly: schemaNode.writeOnly,
+			deprecated: schemaNode.deprecated,
+			description: schemaNode.description,
+			default: schemaNode.default,
+			examples: schemaNode.examples
+		});
+	} });
+}
+//#endregion
 //#region src/schemaDiagnostics.ts
 /**
 * Reports the advisory diagnostics (`KUBB_UNSUPPORTED_FORMAT`, `KUBB_DEPRECATED`) for one
@@ -2532,20 +2416,21 @@ function visit(node, pointer) {
 //#endregion
 //#region src/stream.ts
 /**
-* Reads the server URL from the document's `servers` array at `serverIndex`,
-* interpolating any `serverVariables` into the URL template.
+* Reads the server URL from the document's `servers` array at `server.index`,
+* interpolating any `server.variables` into the URL template.
 *
-* Returns `null` when `serverIndex` is omitted or out of range.
+* Returns `null` when `server.index` is omitted or out of range.
 *
 * @example Resolve the first server
-* `resolveBaseUrl({ document, serverIndex: 0 })`
+* `resolveBaseUrl({ document, server: { index: 0 } })`
 *
 * @example Override a path variable
-* `resolveBaseUrl({ document, serverIndex: 0, serverVariables: { version: 'v2' } })`
+* `resolveBaseUrl({ document, server: { index: 0, variables: { version: 'v2' } } })`
 */
-function resolveBaseUrl({ document, serverIndex, serverVariables }) {
-	const server = serverIndex !== void 0 ? document.servers?.at(serverIndex) : void 0;
-	return server?.url ? resolveServerUrl(server, serverVariables) : null;
+function resolveBaseUrl({ document, server }) {
+	const index = server?.index;
+	const entry = index !== void 0 ? document.servers?.at(index) : void 0;
+	return entry?.url ? resolveServerUrl(entry, server?.variables) : null;
 }
 /**
 * Parses every schema once to build the lookup structures that streaming needs upfront.
@@ -2568,11 +2453,11 @@ function resolveBaseUrl({ document, serverIndex, serverVariables }) {
 *   schemas,
 *   parseSchema,
 *   parserOptions,
-*   discriminator: 'strict',
+*   discriminator: 'preserve',
 * })
 * ```
 */
-function preScan({ schemas, parseSchema, parseOperation, document, parserOptions, discriminator, dedupe }) {
+function preScan({ schemas, parseSchema, parseOperation, document, parserOptions, discriminator, enums = "inline" }) {
 	const allNodes = [];
 	const refAliasMap = /* @__PURE__ */ new Map();
 	const enumNames = [];
@@ -2589,31 +2474,26 @@ function preScan({ schemas, parseSchema, parseOperation, document, parserOptions
 		});
 		if (node.type === "ref" && node.name && node.name !== name) refAliasMap.set(name, node);
 		if (ast.narrowSchema(node, ast.schemaTypes.enum) && node.name) enumNames.push(node.name);
-		if (discriminator === "inherit" && (schema.oneOf ?? schema.anyOf) && schema.discriminator?.propertyName) discriminatorParentNodes.push(node);
+		if (discriminator === "propagate" && (schema.oneOf ?? schema.anyOf) && schema.discriminator?.propertyName) discriminatorParentNodes.push(node);
 	}
 	const circularNames = [...findCircularSchemas(allNodes)];
 	const discriminatorChildMap = discriminatorParentNodes.length > 0 ? buildDiscriminatorChildMap(discriminatorParentNodes) : null;
-	let dedupePlan = null;
-	if (dedupe) {
+	let promotedEnums = null;
+	if (enums === "root" && document && parseOperation) {
 		const operationNodes = [];
 		for (const operation of getOperations(document)) {
 			const operationNode = parseOperation(parserOptions, operation);
 			if (operationNode) operationNodes.push(operationNode);
 		}
-		const circularSchemas = new Set(circularNames);
-		const usedNames = new Set(Object.keys(schemas));
-		dedupePlan = oasDialect.dedupe.plan([...allNodes, ...operationNodes], {
-			circularSchemas,
-			usedNames
-		});
-		for (const definition of dedupePlan.extracted) if (definition.type === "enum" && definition.name) enumNames.push(definition.name);
+		promotedEnums = collectInlineEnums([...allNodes, ...operationNodes], new Set(Object.keys(schemas)));
+		for (const name of promotedEnums.keys()) enumNames.push(name);
 	}
 	return {
 		refAliasMap,
-		enumNames: dedupePlan ? enumNames.filter((name) => !dedupePlan.isAlias(name)) : enumNames,
+		enumNames,
 		circularNames,
 		discriminatorChildMap,
-		dedupePlan
+		promotedEnums
 	};
 }
 /**
@@ -2634,12 +2514,11 @@ function preScan({ schemas, parseSchema, parseOperation, document, parserOptions
 * }
 * ```
 */
-function createInputStream({ schemas, parseSchema, parseOperation, document, parserOptions, refAliasMap, discriminatorChildMap, dedupePlan, meta }) {
+function createInputStream({ schemas, parseSchema, parseOperation, document, parserOptions, refAliasMap, discriminatorChildMap, promotedEnums, meta }) {
 	const schemasIterable = { [Symbol.asyncIterator]() {
 		return (async function* () {
-			if (dedupePlan) for (const definition of dedupePlan.extracted) yield definition;
+			if (promotedEnums) for (const definition of promotedEnums.values()) yield definition;
 			for (const [name, schema] of Object.entries(schemas)) {
-				if (dedupePlan?.isAlias(name)) continue;
 				const alias = refAliasMap.get(name);
 				if (alias?.name && schemas[alias.name]) {
 					const aliasNode = {
@@ -2649,7 +2528,7 @@ function createInputStream({ schemas, parseSchema, parseOperation, document, par
 						}, parserOptions),
 						name
 					};
-					yield dedupePlan ? dedupePlan.applyTopLevel(aliasNode) : aliasNode;
+					yield promotedEnums ? refPromotedEnums(aliasNode, promotedEnums) : aliasNode;
 					continue;
 				}
 				const parsed = parseSchema({
@@ -2657,7 +2536,7 @@ function createInputStream({ schemas, parseSchema, parseOperation, document, par
 					name
 				}, parserOptions);
 				const node = discriminatorChildMap?.get(name) ? patchDiscriminatorNode(parsed, discriminatorChildMap.get(name)) : parsed;
-				yield dedupePlan ? dedupePlan.applyTopLevel(node) : node;
+				yield promotedEnums ? refPromotedEnums(node, promotedEnums) : node;
 			}
 		})();
 	} };
@@ -2665,7 +2544,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 ? dedupePlan.apply(node) : node;
+				if (node) yield promotedEnums ? refPromotedEnums(node, promotedEnums) : node;
 			}
 		})();
 	} };
@@ -2701,8 +2580,8 @@ const adapterOasName = "oas";
 *   input: { path: './petStore.yaml' },
 *   output: { path: './src/gen' },
 *   adapter: adapterOas({
-*     serverIndex: 0,
-*     discriminator: 'inherit',
+*     server: { index: 0 },
+*     discriminator: 'propagate',
 *     dateType: 'date',
 *   }),
 *   plugins: [pluginTs()],
@@ -2710,7 +2589,7 @@ const adapterOasName = "oas";
 * ```
 */
 const adapterOas = createAdapter((options) => {
-	const { validate = true, contentType, serverIndex, serverVariables, discriminator = "strict", dedupe = true, dateType = DEFAULT_PARSER_OPTIONS.dateType, integerType = DEFAULT_PARSER_OPTIONS.integerType, unknownType = DEFAULT_PARSER_OPTIONS.unknownType, enumSuffix = DEFAULT_PARSER_OPTIONS.enumSuffix, emptySchemaType = unknownType || DEFAULT_PARSER_OPTIONS.emptySchemaType } = options;
+	const { validate = true, contentType, server, discriminator = "preserve", enums = "inline", dateType = DEFAULT_PARSER_OPTIONS.dateType, integerType = DEFAULT_PARSER_OPTIONS.integerType, unknownType = DEFAULT_PARSER_OPTIONS.unknownType, enumSuffix = DEFAULT_PARSER_OPTIONS.enumSuffix, emptySchemaType = unknownType || DEFAULT_PARSER_OPTIONS.emptySchemaType } = options;
 	const parserOptions = {
 		...DEFAULT_PARSER_OPTIONS,
 		dateType,
@@ -2768,7 +2647,7 @@ const adapterOas = createAdapter((options) => {
 			document,
 			parserOptions,
 			discriminator,
-			dedupe
+			enums
 		});
 		preScanCache.set(document, result);
 		return result;
@@ -2777,7 +2656,7 @@ const adapterOas = createAdapter((options) => {
 		const document = await ensureDocument(source);
 		const schemas = await ensureSchemas(document);
 		const { parseSchema, parseOperation } = ensureSchemaParser(document);
-		const { refAliasMap, enumNames, circularNames, discriminatorChildMap, dedupePlan } = ensurePreScan(document, schemas, parseSchema, parseOperation);
+		const { refAliasMap, enumNames, circularNames, discriminatorChildMap, promotedEnums } = ensurePreScan(document, schemas, parseSchema, parseOperation);
 		return createInputStream({
 			schemas,
 			parseSchema,
@@ -2786,15 +2665,14 @@ const adapterOas = createAdapter((options) => {
 			parserOptions,
 			refAliasMap,
 			discriminatorChildMap,
-			dedupePlan,
+			promotedEnums,
 			meta: {
 				title: document.info?.title,
 				description: document.info?.description,
 				version: document.info?.version,
 				baseURL: resolveBaseUrl({
 					document,
-					serverIndex,
-					serverVariables
+					server
 				}),
 				circularNames,
 				enumNames
@@ -2807,10 +2685,9 @@ const adapterOas = createAdapter((options) => {
 			return {
 				validate,
 				contentType,
-				serverIndex,
-				serverVariables,
+				server,
 				discriminator,
-				dedupe,
+				enums,
 				dateType,
 				integerType,
 				unknownType,