@kubb/adapter-oas 5.0.0-alpha.2 → 5.0.0-alpha.3

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { DiscriminatorObject, OASDocument, SchemaObject } from "oas/types";
 import BaseOas from "oas";
 import * as oas_normalize_lib_types0 from "oas-normalize/lib/types";
 import { Operation } from "oas/operation";
+import { OpenAPIV3 } from "openapi-types";
 
 //#region src/oas/types.d.ts
 type contentType = 'application/json' | (string & {});
@@ -24,10 +25,30 @@ type SchemaObject$1 = SchemaObject & {
    */
   contentMediaType?: string;
   $ref?: string;
+  /**
+   * OAS 3.1 / JSON Schema: positional items in a tuple schema.
+   * Replaces the OAS 3.0 multi-item `items` array syntax.
+   */
+  prefixItems?: Array<SchemaObject$1 | ReferenceObject>;
+  /**
+   * JSON Schema: maps regex patterns to sub-schemas for additional property validation.
+   */
+  patternProperties?: Record<string, SchemaObject$1 | boolean>;
+  /**
+   * OAS 3.0 / JSON Schema: single-schema form.
+   * The OAS base type already includes this, but we re-declare it here to ensure
+   * the single-schema overload takes precedence over the multi-schema tuple form.
+   */
+  items?: SchemaObject$1 | ReferenceObject;
+  /**
+   * Enum values for this schema (narrowed from `unknown[]` in the base type).
+   */
+  enum?: Array<string | number | boolean | null>;
 };
 type Document = OASDocument;
 type Operation$1 = Operation;
 type DiscriminatorObject$1 = DiscriminatorObject;
+type ReferenceObject = OpenAPIV3.ReferenceObject;
 //#endregion
 //#region src/oas/Oas.d.ts
 type OasOptions = {
@@ -149,6 +170,12 @@ type OasAdapterResolvedOptions = {
   integerType: NonNullable<OasAdapterOptions['integerType']>;
   unknownType: NonNullable<OasAdapterOptions['unknownType']>;
   emptySchemaType: NonNullable<OasAdapterOptions['emptySchemaType']>;
+  /**
+   * Map from original `$ref` paths to their collision-resolved schema names.
+   * Populated by the adapter after each `parse()` call.
+   * e.g. `'#/components/schemas/Order'` → `'OrderSchema'`
+   */
+  nameMapping: Map<string, string>;
 };
 type OasAdapter = AdapterFactoryOptions<'oas', OasAdapterOptions, OasAdapterResolvedOptions>;
 //#endregion

package/dist/index.js

@@ -900,6 +900,137 @@ function resolveCollisions(schemasWithMeta) {
 	};
 }
 //#endregion
+//#region src/utils.ts
+/**
+* Extracts the schema name from a `$ref` string.
+* For `#/components/schemas/Order` this returns `'Order'`.
+* Falls back to the full ref string when no slash is present.
+*/
+function extractRefName($ref) {
+	return $ref.split("/").at(-1) ?? $ref;
+}
+/**
+* Replaces the discriminator property's schema inside an `ObjectSchemaNode`
+* with an enum of the given `values`.
+*
+* - When `enumName` is provided the enum is named, which lets printers emit a
+*   standalone enum declaration + type reference (e.g. `PetTypeEnum`).
+* - When `enumName` is omitted the enum stays anonymous, so printers inline it
+*   as a literal union (e.g. `'dog'`).
+*
+* Returns the node unchanged when it is not an object or lacks the target property.
+*/
+function applyDiscriminatorEnum({ node, propertyName, values, enumName }) {
+	if (node.type !== "object" || !node.properties?.length) return node;
+	if (!node.properties.some((prop) => prop.name === propertyName)) return node;
+	return createSchema({
+		...node,
+		properties: node.properties.map((prop) => {
+			if (prop.name !== propertyName) return prop;
+			const enumSchema = createSchema({
+				type: "enum",
+				primitive: "string",
+				enumValues: values,
+				name: enumName,
+				readOnly: prop.schema.readOnly,
+				writeOnly: prop.schema.writeOnly
+			});
+			return createProperty({
+				...prop,
+				schema: enumSchema
+			});
+		})
+	});
+}
+/**
+* Merges consecutive anonymous (`name`-less) `ObjectSchemaNode`s in `members` into a
+* single object by combining their `properties` arrays.
+*
+* Only adjacent pairs are merged — non-object or named nodes act as boundaries.
+* This collapses patterns like `Address & { streetNumber } & { streetName }` into
+* `Address & { streetNumber; streetName }`.
+*/
+function mergeAdjacentAnonymousObjects(members) {
+	return members.reduce((acc, member) => {
+		const obj = narrowSchema(member, "object");
+		if (obj && !obj.name) {
+			const prev = acc[acc.length - 1];
+			const prevObj = prev ? narrowSchema(prev, "object") : null;
+			if (prevObj && !prevObj.name) {
+				acc[acc.length - 1] = createSchema({
+					...prevObj,
+					properties: [...prevObj.properties ?? [], ...obj.properties ?? []]
+				});
+				return acc;
+			}
+		}
+		acc.push(member);
+		return acc;
+	}, []);
+}
+/**
+* Simplifies a union member list by removing `enum` nodes whose `primitive` type is
+* already represented by a broader scalar node in the same union.
+*
+* For example `['placed', 'approved'] | string` collapses to `string` because
+* `string` subsumes all string literals.  `'' | string` similarly becomes `string`.
+*
+* Only scalar primitives (`string`, `number`, `integer`, `bigint`, `boolean`) are
+* considered — object, array, and ref members are left untouched.
+*/
+function simplifyUnionMembers(members) {
+	const scalarPrimitives = new Set(members.filter((m) => [
+		"string",
+		"number",
+		"integer",
+		"bigint",
+		"boolean"
+	].includes(m.type)).map((m) => m.type));
+	if (!scalarPrimitives.size) return members;
+	return members.filter((m) => {
+		if (m.type !== "enum") return true;
+		const prim = m.primitive;
+		if (!prim) return true;
+		if (scalarPrimitives.has(prim)) return false;
+		if ((prim === "integer" || prim === "number") && (scalarPrimitives.has("integer") || scalarPrimitives.has("number"))) return false;
+		return true;
+	});
+}
+/**
+* `nameMapping`, and calls `resolve` to obtain the `{ name, path }` pair for
+* each import. When `oas` is supplied, only `$ref`s that are resolvable in the
+* spec are included; omit it to skip the existence check.
+*
+* This function is the pure, state-free alternative to `OasParser.getImports`.
+* Because it receives `nameMapping` explicitly it can be called without holding
+* a reference to the parser or the OAS instance.
+*
+* @example
+* ```ts
+* // Use adapter state directly — no parser reference needed
+* const imports = getImports({
+*   node: schemaNode,
+*   nameMapping: adapter.options.nameMapping,
+*   resolve: (schemaName) => ({
+*     name: schemaManager.getName(schemaName, { type: 'type' }),
+*     path: schemaManager.getFile(schemaName).path,
+*   }),
+* })
+* ```
+*/
+function getImports({ node, nameMapping, resolve }) {
+	return collect(node, { schema(schemaNode) {
+		if (schemaNode.type !== "ref" || !schemaNode.ref) return;
+		const rawName = extractRefName(schemaNode.ref);
+		const result = resolve(nameMapping.get(rawName) ?? rawName);
+		if (!result) return;
+		return {
+			name: [result.name],
+			path: result.path
+		};
+	} });
+}
+//#endregion
 //#region src/parser.ts
 /**
 * Default values for all `Options` fields.
@@ -920,14 +1051,6 @@ function formatToSchemaType(format) {
 	return formatMap[format];
 }
 /**
-* Extracts the final path segment of a JSON Pointer `$ref` string.
-* For `#/components/schemas/Order` this returns `'Order'`.
-* Falls back to the full ref string when no slash is present.
-*/
-function extractRefName($ref) {
-	return $ref.split("/").at(-1) ?? $ref;
-}
-/**
 * Maps an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
 * Numeric types (`number`, `integer`, `bigint`) are returned unchanged;
 * `boolean` maps to `'boolean'`; everything else defaults to `'string'`.
@@ -945,26 +1068,6 @@ function toMediaType(contentType) {
 	return knownMediaTypes.includes(contentType) ? contentType : void 0;
 }
 /**
-* When a discriminator is present, replaces the discriminator property's schema with
-* an enum of the mapping keys so downstream code emits a precise literal-union type.
-* Returns the original schema unchanged when there is no discriminator or no mapping.
-*/
-function applyDiscriminatorEnum(schema) {
-	if (!isDiscriminator(schema)) return schema;
-	const propName = schema.discriminator.propertyName;
-	if (!schema.properties?.[propName]) return schema;
-	return {
-		...schema,
-		properties: {
-			...schema.properties,
-			[propName]: {
-				...schema.properties[propName],
-				enum: schema.discriminator.mapping ? Object.keys(schema.discriminator.mapping) : void 0
-			}
-		}
-	};
-}
-/**
 * Creates an OAS parser that converts an OpenAPI/Swagger spec into
 * the `@kubb/ast` tree.
 *
@@ -1055,18 +1158,17 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	* reflected in generated JSDoc and type modifiers.
 	*/
 	function convertRef({ schema, nullable, defaultValue }) {
-		const schemaObject = schema;
 		return createSchema({
 			type: "ref",
-			name: extractRefName(schemaObject.$ref),
-			ref: schemaObject.$ref,
+			name: extractRefName(schema.$ref),
+			ref: schema.$ref,
 			nullable,
-			description: schemaObject.description,
-			deprecated: schemaObject.deprecated,
-			readOnly: schemaObject.readOnly,
-			writeOnly: schemaObject.writeOnly,
-			pattern: schemaObject.type === "string" ? schemaObject.pattern : void 0,
-			example: schemaObject.example,
+			description: schema.description,
+			deprecated: schema.deprecated,
+			readOnly: schema.readOnly,
+			writeOnly: schema.writeOnly,
+			pattern: schema.type === "string" ? schema.pattern : void 0,
+			example: schema.example,
 			default: defaultValue
 		});
 	}
@@ -1117,6 +1219,7 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 			const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef);
 			return !inOneOf && !inMapping;
 		}).map((s) => convertSchema({ schema: s }, options));
+		const syntheticStart = allOfMembers.length;
 		if (Array.isArray(schema.required) && schema.required.length) {
 			const outerKeys = schema.properties ? new Set(Object.keys(schema.properties)) : /* @__PURE__ */ new Set();
 			const missingRequired = schema.required.filter((key) => !outerKeys.has(key));
@@ -1141,7 +1244,7 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 		}
 		return createSchema({
 			type: "intersection",
-			members: allOfMembers,
+			members: [...allOfMembers.slice(0, syntheticStart), ...mergeAdjacentAnonymousObjects(allOfMembers.slice(syntheticStart))],
 			...buildSchemaBase(schema, name, nullable, defaultValue)
 		});
 	}
@@ -1161,20 +1264,34 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 		};
 		if (schema.properties) {
 			const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema;
-			const propertiesNode = convertSchema({ schema: schemaWithoutUnion }, options);
+			const discriminator = isDiscriminator(schema) ? schema.discriminator : void 0;
+			const memberBaseSchema = discriminator ? Object.fromEntries(Object.entries(schemaWithoutUnion).filter(([key]) => key !== "discriminator")) : schemaWithoutUnion;
 			return createSchema({
 				type: "union",
 				...unionBase,
-				members: unionMembers.map((s) => createSchema({
-					type: "intersection",
-					members: [convertSchema({ schema: s }, options), propertiesNode]
-				}))
+				members: unionMembers.map((s) => {
+					const ref = isReference(s) ? s.$ref : void 0;
+					const discriminatorValue = discriminator?.mapping && ref ? Object.entries(discriminator.mapping).find(([, v]) => v === ref)?.[0] : void 0;
+					let propertiesNode = convertSchema({
+						schema: memberBaseSchema,
+						name
+					}, options);
+					if (discriminatorValue && discriminator) propertiesNode = applyDiscriminatorEnum({
+						node: propertiesNode,
+						propertyName: discriminator.propertyName,
+						values: [discriminatorValue]
+					});
+					return createSchema({
+						type: "intersection",
+						members: [convertSchema({ schema: s }, options), propertiesNode]
+					});
+				})
 			});
 		}
 		return createSchema({
 			type: "union",
 			...unionBase,
-			members: unionMembers.map((s) => convertSchema({ schema: s }, options))
+			members: simplifyUnionMembers(unionMembers.map((s) => convertSchema({ schema: s }, options)))
 		});
 	}
 	/**
@@ -1259,9 +1376,8 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	*/
 	function convertEnum({ schema, name, nullable, type, options }) {
 		if (type === "array") {
-			const rawSchema = schema;
 			const normalizedItems = {
-				...typeof rawSchema.items === "object" && !Array.isArray(rawSchema.items) ? rawSchema.items : {},
+				...typeof schema.items === "object" && !Array.isArray(schema.items) ? schema.items : {},
 				enum: schema.enum
 			};
 			const { enum: _enum, ...schemaWithoutEnum } = schema;
@@ -1341,22 +1457,28 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	* - not required + nullable → `nullish: true`
 	*/
 	function convertObject({ schema, name, nullable, defaultValue, options, mergedOptions }) {
-		const resolvedSchema = applyDiscriminatorEnum(schema);
-		const properties = resolvedSchema.properties ? Object.entries(resolvedSchema.properties).map(([propName, propSchema]) => {
-			const required = Array.isArray(resolvedSchema.required) ? resolvedSchema.required.includes(propName) : !!resolvedSchema.required;
+		const properties = schema.properties ? Object.entries(schema.properties).map(([propName, propSchema]) => {
+			const required = Array.isArray(schema.required) ? schema.required.includes(propName) : !!schema.required;
 			const resolvedPropSchema = propSchema;
 			const propNullable = isNullable(resolvedPropSchema);
+			const basePropName = name ? pascalCase([name, propName].join(" ")) : void 0;
+			const propNode = convertSchema({
+				schema: resolvedPropSchema,
+				name: basePropName
+			}, options);
+			const isEnumNode = !!narrowSchema(propNode, "enum");
+			const derivedPropName = isEnumNode && name ? pascalCase([
+				name,
+				propName,
+				mergedOptions.enumSuffix
+			].filter(Boolean).join(" ")) : basePropName;
 			return createProperty({
 				name: propName,
 				schema: {
-					...convertSchema({
-						schema: resolvedPropSchema,
-						name: name ? pascalCase([
-							name,
-							propName,
-							mergedOptions.enumSuffix
-						].filter(Boolean).join(" ")) : void 0
-					}, options),
+					...isEnumNode && derivedPropName !== basePropName ? {
+						...propNode,
+						name: derivedPropName
+					} : propNode,
 					nullable: propNullable || void 0,
 					optional: !required && !propNullable ? true : void 0,
 					nullish: !required && propNullable ? true : void 0
@@ -1364,15 +1486,15 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 				required
 			});
 		}) : [];
-		const additionalProperties = resolvedSchema.additionalProperties;
+		const additionalProperties = schema.additionalProperties;
 		let additionalPropertiesNode;
 		if (additionalProperties === true) additionalPropertiesNode = true;
 		else if (additionalProperties && Object.keys(additionalProperties).length > 0) additionalPropertiesNode = convertSchema({ schema: additionalProperties }, options);
 		else if (additionalProperties === false) additionalPropertiesNode = void 0;
 		else if (additionalProperties) additionalPropertiesNode = createSchema({ type: resolveTypeOption(mergedOptions.unknownType) });
-		const rawPatternProperties = "patternProperties" in resolvedSchema ? resolvedSchema.patternProperties : void 0;
-		const patternProperties = rawPatternProperties ? Object.fromEntries(Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [pattern, patternSchema === true || Object.keys(patternSchema).length === 0 ? createSchema({ type: resolveTypeOption(mergedOptions.unknownType) }) : convertSchema({ schema: patternSchema }, options)])) : void 0;
-		return createSchema({
+		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 ? createSchema({ type: resolveTypeOption(mergedOptions.unknownType) }) : convertSchema({ schema: patternSchema }, options)])) : void 0;
+		const objectNode = createSchema({
 			type: "object",
 			primitive: "object",
 			properties,
@@ -1380,6 +1502,20 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 			patternProperties,
 			...buildSchemaBase(schema, name, nullable, defaultValue)
 		});
+		if (isDiscriminator(schema) && schema.discriminator.mapping) {
+			const discPropName = schema.discriminator.propertyName;
+			return applyDiscriminatorEnum({
+				node: objectNode,
+				propertyName: discPropName,
+				values: Object.keys(schema.discriminator.mapping),
+				enumName: name ? pascalCase([
+					name,
+					discPropName,
+					mergedOptions.enumSuffix
+				].filter(Boolean).join(" ")) : void 0
+			});
+		}
+		return objectNode;
 	}
 	/**
 	* Converts an OAS 3.1 `prefixItems` tuple into a `TupleSchemaNode`.
@@ -1388,12 +1524,11 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	* after the prefix items is mapped to the rest parameter of the tuple.
 	*/
 	function convertTuple({ schema, name, nullable, defaultValue, options }) {
-		const rawSchema = schema;
 		return createSchema({
 			type: "tuple",
 			primitive: "array",
-			items: rawSchema.prefixItems.map((item) => convertSchema({ schema: item }, options)),
-			rest: rawSchema.items ? convertSchema({ schema: rawSchema.items }, options) : void 0,
+			items: (schema.prefixItems ?? []).map((item) => convertSchema({ schema: item }, options)),
+			rest: schema.items ? convertSchema({ schema: schema.items }, options) : void 0,
 			min: schema.minItems,
 			max: schema.maxItems,
 			...buildSchemaBase(schema, name, nullable, defaultValue)
@@ -1406,13 +1541,13 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	* `enumSuffix` is forwarded so generators can emit a named enum declaration.
 	*/
 	function convertArray({ schema, name, nullable, defaultValue, options, mergedOptions }) {
-		const rawSchema = schema;
-		const itemName = rawSchema.items?.enum?.length && name ? pascalCase([name, mergedOptions.enumSuffix].join(" ")) : void 0;
+		const rawItems = schema.items;
+		const itemName = rawItems?.enum?.length && name ? pascalCase([name, mergedOptions.enumSuffix].join(" ")) : void 0;
 		return createSchema({
 			type: "array",
 			primitive: "array",
-			items: rawSchema.items ? [convertSchema({
-				schema: rawSchema.items,
+			items: rawItems ? [convertSchema({
+				schema: rawItems,
 				name: itemName
 			}, options)] : [],
 			min: schema.minItems,
@@ -1528,10 +1663,13 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 			const arrayNullable = schema.type.includes("null") || nullable || void 0;
 			if (nonNullTypes.length > 1) return createSchema({
 				type: "union",
-				members: nonNullTypes.map((t) => convertSchema({ schema: {
-					...schema,
-					type: t
-				} }, options)),
+				members: nonNullTypes.map((t) => convertSchema({
+					schema: {
+						...schema,
+						type: t
+					},
+					name
+				}, options)),
 				...buildSchemaBase(schema, name, arrayNullable, defaultValue)
 			});
 		}
@@ -1560,12 +1698,16 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	* When the parameter has no `schema` or its schema is a `$ref`, falls back to `unknownType`.
 	*/
 	function parseParameter(options, param) {
+		const required = param["required"] ?? false;
 		const schema = param["schema"] && !isReference(param["schema"]) ? convertSchema({ schema: param["schema"] }, options) : createSchema({ type: resolveTypeOption(options.unknownType) });
 		return createParameter({
 			name: param["name"],
 			in: param["in"],
-			schema,
-			required: param["required"] ?? false
+			schema: {
+				...schema,
+				optional: !required || !!schema.optional ? true : void 0
+			},
+			required
 		});
 	}
 	/**
@@ -1594,7 +1736,7 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 		return createOperation({
 			operationId: operation.getOperationId(),
 			method: operation.method.toUpperCase(),
-			path: operation.path,
+			path: new URLPath(operation.path).URL,
 			tags: operation.getTags().map((tag) => tag.name),
 			summary: operation.getSummary() || void 0,
 			description: operation.getDescription() || void 0,
@@ -1651,31 +1793,11 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 			}
 		} });
 	}
-	/**
-	* Collects all `KubbFile.Import` descriptors needed by a `SchemaNode` tree.
-	*
-	* Walks the tree looking for `ref` nodes, verifies each `$ref` is resolvable in the spec,
-	* applies collision-resolved names from `nameMapping`, and calls `resolve` to obtain the
-	* import path and name. Returns an empty array for refs that cannot be resolved.
-	*/
-	function getImports(node, resolve) {
-		return collect(node, { schema(schemaNode) {
-			if (schemaNode.type !== "ref" || !schemaNode.ref) return;
-			if (!oas.get(schemaNode.ref)) return;
-			const rawName = extractRefName(schemaNode.ref);
-			const result = resolve(nameMapping.get(rawName) ?? rawName);
-			if (!result) return;
-			return {
-				name: [result.name],
-				path: result.path
-			};
-		} });
-	}
 	return {
 		parse,
 		convertSchema,
 		resolveRefs,
-		getImports
+		nameMapping
 	};
 }
 //#endregion
@@ -1701,6 +1823,7 @@ const adapterOasName = "oas";
 */
 const adapterOas = defineAdapter((options) => {
 	const { validate = true, oasClass, contentType, serverIndex, serverVariables, discriminator = "strict", collisionDetection = false, dateType = "string", integerType = "number", unknownType = "any", emptySchemaType = unknownType } = options;
+	const nameMapping = /* @__PURE__ */ new Map();
 	return {
 		name: "oas",
 		options: {
@@ -1714,7 +1837,15 @@ const adapterOas = defineAdapter((options) => {
 			dateType,
 			integerType,
 			unknownType,
-			emptySchemaType
+			emptySchemaType,
+			nameMapping
+		},
+		getImports(node, resolve) {
+			return getImports({
+				node,
+				nameMapping,
+				resolve
+			});
 		},
 		async parse(source) {
 			const oas = await parseFromConfig(sourceToFakeConfig(source), oasClass);
@@ -1728,11 +1859,14 @@ const adapterOas = defineAdapter((options) => {
 			} catch (_err) {}
 			const server = serverIndex !== void 0 ? oas.api.servers?.at(serverIndex) : void 0;
 			const baseURL = server?.url ? resolveServerUrl(server, serverVariables) : void 0;
+			const parser = createOasParser(oas, {
+				contentType,
+				collisionDetection
+			});
+			nameMapping.clear();
+			for (const [key, value] of parser.nameMapping) nameMapping.set(key, value);
 			return createRoot({
-				...createOasParser(oas, {
-					contentType,
-					collisionDetection
-				}).parse({
+				...parser.parse({
 					dateType,
 					integerType,
 					unknownType,