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

package/dist/index.cjs

@@ -837,6 +837,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
@@ -855,13 +872,16 @@ function dereferenceWithRef(document, schema) {
 * const parser = createSchemaParser(context, oasDialect) // explicit
 * ```
 */
-const oasDialect = _kubb_core.ast.defineSchemaDialect({
+const oasDialect = _kubb_core.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
@@ -1584,6 +1604,21 @@ 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 _kubb_core.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.
 */
@@ -1639,7 +1674,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);
@@ -1688,13 +1723,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);
@@ -1715,9 +1750,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({
@@ -1762,10 +1797,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({
@@ -1775,7 +1810,7 @@ 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,
@@ -1821,15 +1856,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 	*/
 	function convertConst({ schema, name, nullable, defaultValue }) {
 		const constValue = schema.const;
-		if (constValue === null) return _kubb_core.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 _kubb_core.ast.factory.createSchema({
 			type: "enum",
@@ -1918,15 +1945,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 _kubb_core.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);
@@ -1976,7 +1995,7 @@ 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 propNullable = dialect.schema.isNullable(resolvedPropSchema);
 			const schemaNode = nameEnums(parseSchema({
 				schema: resolvedPropSchema,
 				name: (0, _kubb_ast_utils.childName)(name, propName)
@@ -1992,7 +2011,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 					nullable: schemaNode.type === "null" ? void 0 : propNullable || void 0
 				},
 				required
-			});
+			}, dialect);
 		}) : [];
 		const additionalProperties = schema.additionalProperties;
 		const additionalPropertiesNode = (() => {
@@ -2013,7 +2032,7 @@ 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 ? (0, _kubb_ast_utils.enumPropName)(name, discPropName, options.enumSuffix) : void 0;
@@ -2157,7 +2176,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 	const schemaRules = [
 		{
 			name: "ref",
-			match: ({ schema }) => dialect.isReference(schema),
+			match: ({ schema }) => dialect.schema.isReference(schema),
 			convert: convertRef
 		},
 		{
@@ -2182,7 +2201,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		},
 		{
 			name: "blob",
-			match: ({ schema }) => dialect.isBinary(schema),
+			match: ({ schema }) => dialect.schema.isBinary(schema),
 			convert: convertBlob
 		},
 		{
@@ -2263,7 +2282,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,
@@ -2306,7 +2325,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 				description: param["description"] ?? schema.description
 			},
 			required
-		});
+		}, dialect);
 	}
 	/**
 	* Reads the inline `requestBody` metadata (description / required) that OAS exposes
@@ -2340,7 +2359,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;
 	}
@@ -2357,14 +2376,14 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		const content = allContentTypes.flatMap((ct) => {
 			const schema = getRequestSchema(document, operation, { contentType: ct });
 			if (!schema) return [];
-			return [{
+			return [_kubb_core.ast.factory.createContent({
 				contentType: ct,
-				schema: _kubb_core.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,
@@ -2389,17 +2408,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) => _kubb_core.ast.factory.createContent({
 				contentType,
 				...parseEntrySchema(contentType)
 			}));
-			if (content.length === 0) content.push({
+			if (content.length === 0) content.push(_kubb_core.ast.factory.createContent({
 				contentType: getRequestContentType({
 					document,
 					operation
 				}) || "application/json",
 				...parseEntrySchema(ctx.contentType)
-			});
+			}));
 			return _kubb_core.ast.factory.createResponse({
 				statusCode,
 				description,
@@ -2407,7 +2426,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;
@@ -2492,36 +2511,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 _kubb_core.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 !(0, _kubb_ast_utils.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.
 *
@@ -2590,11 +2579,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 = _kubb_core.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 !(0, _kubb_ast_utils.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);
 	}