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

package/dist/index.js

@@ -5,7 +5,8 @@ import { access, readFile } from "node:fs/promises";
 import { compileErrors, validate } from "@readme/openapi-parser";
 import { parse } from "yaml";
 import { bundle } from "api-ref-bundler";
-import { childName, containsCircularRef, enumPropName, extractRefName, findCircularSchemas } from "@kubb/ast/utils";
+import { macroDiscriminatorEnum, macroEnumName, macroSimplifyUnion } from "@kubb/ast/macros";
+import { childName, containsCircularRef, enumPropName, extractRefName, findCircularSchemas, mergeAdjacentObjectsLazy } from "@kubb/ast/utils";
 import { collect, narrowSchema } from "@kubb/ast";
 //#region src/constants.ts
 /**
@@ -813,6 +814,23 @@ 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
@@ -831,13 +849,16 @@ function dereferenceWithRef(document, schema) {
 * const parser = createSchemaParser(context, oasDialect) // explicit
 * ```
 */
-const oasDialect = ast.defineSchemaDialect({
+const oasDialect = ast.defineDialect({
 	name: "oas",
-	isNullable,
-	isReference,
-	isDiscriminator,
-	isBinary: (schema) => schema.type === "string" && schema.contentMediaType === "application/octet-stream",
-	resolveRef
+	schema: {
+		isNullable,
+		isReference,
+		isDiscriminator,
+		isBinary: (schema) => schema.type === "string" && schema.contentMediaType === "application/octet-stream",
+		resolveRef,
+		optionality
+	}
 });
 //#endregion
 //#region src/discriminator.ts
@@ -1560,6 +1581,38 @@ function normalizeArrayEnum(schema) {
 	};
 }
 /**
+* Builds a `null` scalar node carrying the schema's documentation. Shared by the `const: null`
+* and the drf-spectacular `NullEnum` (`{ enum: [null] }`) branches, which render identically.
+*/
+function createNullSchema(schema, name) {
+	return ast.factory.createSchema({
+		type: "null",
+		primitive: "null",
+		name,
+		title: schema.title,
+		description: schema.description,
+		deprecated: schema.deprecated,
+		format: schema.format
+	});
+}
+/**
+* Names the inline enums on a property's schema, and on each item when the property is a tuple, from
+* the parent and property name. Wraps `macroEnumName` at the property construction site.
+*/
+function nameEnums(node, options) {
+	const macro = macroEnumName(options);
+	const named = ast.applyMacros(node, [macro], { depth: "shallow" });
+	const tupleNode = ast.narrowSchema(named, "tuple");
+	if (tupleNode?.items) {
+		const namedItems = tupleNode.items.map((item) => ast.applyMacros(item, [macro], { depth: "shallow" }));
+		if (namedItems.some((item, i) => item !== tupleNode.items[i])) return {
+			...tupleNode,
+			items: namedItems
+		};
+	}
+	return named;
+}
+/**
 * Factory function that creates schema and operation converters for a given OpenAPI context.
 *
 * Returns closures that share mutable state (`resolvingRefs` set for cycle detection).
@@ -1598,7 +1651,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		if (refPath && !resolvingRefs.has(refPath)) {
 			if (!resolvedRefCache.has(refPath)) {
 				try {
-					const referenced = dialect.resolveRef(document, refPath);
+					const referenced = dialect.schema.resolveRef(document, refPath);
 					if (referenced) {
 						resolvingRefs.add(refPath);
 						resolvedSchema = parseSchema({ schema: referenced }, rawOptions);
@@ -1647,13 +1700,13 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		}
 		const filteredDiscriminantValues = [];
 		const allOfMembers = schema.allOf.filter((item) => {
-			if (!dialect.isReference(item) || !name) return true;
-			const deref = dialect.resolveRef(document, item.$ref);
-			if (!deref || !dialect.isDiscriminator(deref)) return true;
+			if (!dialect.schema.isReference(item) || !name) return true;
+			const deref = dialect.schema.resolveRef(document, item.$ref);
+			if (!deref || !dialect.schema.isDiscriminator(deref)) return true;
 			const parentUnion = deref.oneOf ?? deref.anyOf;
 			if (!parentUnion) return true;
 			const childRef = `${SCHEMA_REF_PREFIX}${name}`;
-			const inOneOf = parentUnion.some((oneOfItem) => dialect.isReference(oneOfItem) && oneOfItem.$ref === childRef);
+			const inOneOf = parentUnion.some((oneOfItem) => dialect.schema.isReference(oneOfItem) && oneOfItem.$ref === childRef);
 			const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef);
 			if (inOneOf || inMapping) {
 				const discriminatorValue = findDiscriminator(deref.discriminator.mapping, childRef);
@@ -1674,9 +1727,9 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 			const missingRequired = schema.required.filter((key) => !outerKeys.has(key));
 			if (missingRequired.length) {
 				const resolvedMembers = schema.allOf.flatMap((item) => {
-					if (!dialect.isReference(item)) return [item];
-					const deref = dialect.resolveRef(document, item.$ref);
-					return deref && !dialect.isReference(deref) ? [deref] : [];
+					if (!dialect.schema.isReference(item)) return [item];
+					const deref = dialect.schema.resolveRef(document, item.$ref);
+					return deref && !dialect.schema.isReference(deref) ? [deref] : [];
 				});
 				for (const key of missingRequired) for (const resolved of resolvedMembers) if (resolved.properties?.[key]) {
 					allOfMembers.push(parseSchema({
@@ -1700,7 +1753,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		}));
 		return ast.factory.createSchema({
 			type: "intersection",
-			members: [...ast.mergeAdjacentObjectsLazy(allOfMembers.slice(0, syntheticStart)), ...ast.mergeAdjacentObjectsLazy(allOfMembers.slice(syntheticStart))],
+			members: [...mergeAdjacentObjectsLazy(allOfMembers.slice(0, syntheticStart)), ...mergeAdjacentObjectsLazy(allOfMembers.slice(syntheticStart))],
 			...buildSchemaNode(schema, name, nullable, defaultValue)
 		});
 	}
@@ -1721,10 +1774,10 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		const strategy = schema.oneOf ? "one" : "any";
 		const unionBase = {
 			...buildSchemaNode(schema, name, nullable, defaultValue),
-			discriminatorPropertyName: dialect.isDiscriminator(schema) ? schema.discriminator.propertyName : void 0,
+			discriminatorPropertyName: dialect.schema.isDiscriminator(schema) ? schema.discriminator.propertyName : void 0,
 			strategy
 		};
-		const discriminator = dialect.isDiscriminator(schema) ? schema.discriminator : void 0;
+		const discriminator = dialect.schema.isDiscriminator(schema) ? schema.discriminator : void 0;
 		const sharedPropertiesNode = schema.properties ? (() => {
 			const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema;
 			return parseSchema({
@@ -1734,18 +1787,17 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		})() : void 0;
 		if (sharedPropertiesNode || discriminator?.mapping) {
 			const members = unionMembers.map((s) => {
-				const ref = dialect.isReference(s) ? s.$ref : void 0;
+				const ref = dialect.schema.isReference(s) ? s.$ref : void 0;
 				const discriminatorValue = findDiscriminator(discriminator?.mapping, ref);
 				const memberNode = parseSchema({
 					schema: s,
 					name
 				}, rawOptions);
 				if (!discriminatorValue || !discriminator) return memberNode;
-				const narrowedDiscriminatorNode = sharedPropertiesNode ? pickDiscriminatorPropertyNode(ast.setDiscriminatorEnum({
-					node: sharedPropertiesNode,
+				const narrowedDiscriminatorNode = sharedPropertiesNode ? pickDiscriminatorPropertyNode(ast.applyMacros(sharedPropertiesNode, [macroDiscriminatorEnum({
 					propertyName: discriminator.propertyName,
 					values: [discriminatorValue]
-				}), discriminator.propertyName) : void 0;
+				})], { depth: "shallow" }), discriminator.propertyName) : void 0;
 				return ast.factory.createSchema({
 					type: "intersection",
 					members: [memberNode, narrowedDiscriminatorNode ?? createDiscriminantNode({
@@ -1766,29 +1818,22 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 				members: [unionNode, sharedPropertiesNode]
 			});
 		}
-		return ast.factory.createSchema({
+		const unionNode = ast.factory.createSchema({
 			type: "union",
 			...unionBase,
-			members: ast.simplifyUnion(unionMembers.map((s) => parseSchema({
+			members: unionMembers.map((s) => parseSchema({
 				schema: s,
 				name
-			}, rawOptions)))
+			}, rawOptions))
 		});
+		return ast.applyMacros(unionNode, [macroSimplifyUnion], { depth: "shallow" });
 	}
 	/**
 	* Converts an OAS 3.1 `const` schema into a null scalar or a single-value `EnumSchemaNode`.
 	*/
 	function convertConst({ schema, name, nullable, defaultValue }) {
 		const constValue = schema.const;
-		if (constValue === null) return ast.factory.createSchema({
-			type: "null",
-			primitive: "null",
-			name,
-			title: schema.title,
-			description: schema.description,
-			deprecated: schema.deprecated,
-			format: schema.format
-		});
+		if (constValue === null) return createNullSchema(schema, name);
 		const constPrimitive = getPrimitiveType(typeof constValue === "number" ? "number" : typeof constValue === "boolean" ? "boolean" : "string");
 		return ast.factory.createSchema({
 			type: "enum",
@@ -1877,15 +1922,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		}, rawOptions);
 		const nullInEnum = schema.enum.includes(null);
 		const filteredValues = nullInEnum ? schema.enum.filter((v) => v !== null) : schema.enum;
-		if (nullInEnum && filteredValues.length === 0) return ast.factory.createSchema({
-			type: "null",
-			primitive: "null",
-			name,
-			title: schema.title,
-			description: schema.description,
-			deprecated: schema.deprecated,
-			format: schema.format
-		});
+		if (nullInEnum && filteredValues.length === 0) return createNullSchema(schema, name);
 		const enumNullable = nullable || nullInEnum || void 0;
 		const enumDefault = schema.default === null && enumNullable ? void 0 : schema.default;
 		const enumPrimitive = getPrimitiveType(type);
@@ -1935,23 +1972,15 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		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 = dialect.isNullable(resolvedPropSchema);
-			const propNode = parseSchema({
+			const propNullable = dialect.schema.isNullable(resolvedPropSchema);
+			const schemaNode = nameEnums(parseSchema({
 				schema: resolvedPropSchema,
 				name: childName(name, propName)
-			}, rawOptions);
-			const schemaNode = (() => {
-				const node = ast.setEnumName(propNode, name, propName, options.enumSuffix);
-				const tupleNode = ast.narrowSchema(node, "tuple");
-				if (tupleNode?.items) {
-					const namedItems = tupleNode.items.map((item) => ast.setEnumName(item, name, propName, options.enumSuffix));
-					if (namedItems.some((item, i) => item !== tupleNode.items[i])) return {
-						...tupleNode,
-						items: namedItems
-					};
-				}
-				return node;
-			})();
+			}, rawOptions), {
+				parentName: name,
+				propName,
+				enumSuffix: options.enumSuffix
+			});
 			return ast.factory.createProperty({
 				name: propName,
 				schema: {
@@ -1959,7 +1988,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 					nullable: schemaNode.type === "null" ? void 0 : propNullable || void 0
 				},
 				required
-			});
+			}, dialect);
 		}) : [];
 		const additionalProperties = schema.additionalProperties;
 		const additionalPropertiesNode = (() => {
@@ -1980,16 +2009,15 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 			maxProperties: schema.maxProperties,
 			...buildSchemaNode(schema, name, nullable, defaultValue)
 		});
-		if (dialect.isDiscriminator(schema) && schema.discriminator.mapping) {
+		if (dialect.schema.isDiscriminator(schema) && schema.discriminator.mapping) {
 			const discPropName = schema.discriminator.propertyName;
 			const values = Object.keys(schema.discriminator.mapping);
 			const enumName = name ? enumPropName(name, discPropName, options.enumSuffix) : void 0;
-			return ast.setDiscriminatorEnum({
-				node: objectNode,
+			return ast.applyMacros(objectNode, [macroDiscriminatorEnum({
 				propertyName: discPropName,
 				values,
 				enumName
-			});
+			})], { depth: "shallow" });
 		}
 		return objectNode;
 	}
@@ -2125,7 +2153,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 	const schemaRules = [
 		{
 			name: "ref",
-			match: ({ schema }) => dialect.isReference(schema),
+			match: ({ schema }) => dialect.schema.isReference(schema),
 			convert: convertRef
 		},
 		{
@@ -2150,7 +2178,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		},
 		{
 			name: "blob",
-			match: ({ schema }) => dialect.isBinary(schema),
+			match: ({ schema }) => dialect.schema.isBinary(schema),
 			convert: convertBlob
 		},
 		{
@@ -2231,7 +2259,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 			schema: flattenedSchema,
 			name
 		}, rawOptions);
-		const nullable = dialect.isNullable(schema) || void 0;
+		const nullable = dialect.schema.isNullable(schema) || void 0;
 		const schemaCtx = {
 			schema,
 			name,
@@ -2274,7 +2302,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 				description: param["description"] ?? schema.description
 			},
 			required
-		});
+		}, dialect);
 	}
 	/**
 	* Reads the inline `requestBody` metadata (description / required) that OAS exposes
@@ -2308,7 +2336,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		const keys = [];
 		for (const key in schema.properties) {
 			const prop = schema.properties[key];
-			if (prop && !dialect.isReference(prop) && prop[flag]) keys.push(key);
+			if (prop && !dialect.schema.isReference(prop) && prop[flag]) keys.push(key);
 		}
 		return keys.length ? keys : null;
 	}
@@ -2325,14 +2353,14 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		const content = allContentTypes.flatMap((ct) => {
 			const schema = getRequestSchema(document, operation, { contentType: ct });
 			if (!schema) return [];
-			return [{
+			return [ast.factory.createContent({
 				contentType: ct,
-				schema: ast.syncOptionality(parseSchema({
+				schema: dialect.schema.optionality(parseSchema({
 					schema,
 					name: requestBodyName
 				}, options), requestBodyMeta.required),
 				keysToOmit: collectPropertyKeysByFlag(schema, "readOnly")
-			}];
+			})];
 		});
 		const requestBody = content.length > 0 || requestBodyMeta.description ? {
 			description: requestBodyMeta.description,
@@ -2357,17 +2385,17 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 					keysToOmit: collectPropertyKeysByFlag(raw, "writeOnly")
 				};
 			};
-			const content = (ctx.contentType ? [ctx.contentType] : getResponseBodyContentTypes(document, operation, statusCode)).map((contentType) => ({
+			const content = (ctx.contentType ? [ctx.contentType] : getResponseBodyContentTypes(document, operation, statusCode)).map((contentType) => ast.factory.createContent({
 				contentType,
 				...parseEntrySchema(contentType)
 			}));
-			if (content.length === 0) content.push({
+			if (content.length === 0) content.push(ast.factory.createContent({
 				contentType: getRequestContentType({
 					document,
 					operation
 				}) || "application/json",
 				...parseEntrySchema(ctx.contentType)
-			});
+			}));
 			return ast.factory.createResponse({
 				statusCode,
 				description,
@@ -2375,7 +2403,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 			});
 		});
 		const pathItem = document.paths?.[operation.path];
-		const pathItemDoc = pathItem && !dialect.isReference(pathItem) ? pathItem : void 0;
+		const pathItemDoc = pathItem && !dialect.schema.isReference(pathItem) ? pathItem : void 0;
 		const pickDoc = (key) => {
 			const own = operation.schema[key];
 			if (typeof own === "string") return own;
@@ -2460,36 +2488,6 @@ function visit(node, pointer) {
 //#endregion
 //#region src/stream.ts
 /**
-* Builds the deduplication plan from the already-parsed top-level schema nodes plus a
-* single extra parse pass over operations (so duplicates in request/response bodies are seen).
-*
-* Only enums and objects are candidates, and object shapes that reference a circular schema are
-* rejected to avoid hoisting recursive structures. Inline shapes reuse their context-derived
-* name (collision-resolved against existing component names). Shapes without a name stay inline.
-*/
-function createDedupePlan({ schemaNodes, operationNodes, schemaNames, circularNames }) {
-	const circularSchemas = new Set(circularNames);
-	const usedNames = new Set(schemaNames);
-	return ast.buildDedupePlan([...schemaNodes, ...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}`
-	});
-}
-/**
 * Reads the server URL from the document's `servers` array at `serverIndex`,
 * interpolating any `serverVariables` into the URL template.
 *
@@ -2558,11 +2556,25 @@ function preScan({ schemas, parseSchema, parseOperation, document, parserOptions
 			const operationNode = parseOperation(parserOptions, operation);
 			if (operationNode) operationNodes.push(operationNode);
 		}
-		dedupePlan = createDedupePlan({
-			schemaNodes: allNodes,
-			operationNodes,
-			schemaNames: Object.keys(schemas),
-			circularNames
+		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}`
 		});
 		for (const definition of dedupePlan.hoisted) if (definition.type === "enum" && definition.name) enumNames.push(definition.name);
 	}