@kubb/adapter-oas 5.0.0-beta.74 → 5.0.0-beta.76

package/dist/index.js

@@ -132,6 +132,17 @@ const formatMap = {
 * ```
 */
 const enumExtensionKeys = ["x-enumNames", "x-enum-varnames"];
+/**
+* Vendor extension keys that attach human-readable descriptions to enum values, checked in priority order.
+*
+* @example
+* ```ts
+* import { enumDescriptionKeys } from '@kubb/adapter-oas'
+*
+* const key = enumDescriptionKeys.find((k) => k in schema) // 'x-enumDescriptions' | 'x-enum-descriptions' | undefined
+* ```
+*/
+const enumDescriptionKeys = ["x-enumDescriptions", "x-enum-descriptions"];
 //#endregion
 //#region ../../internals/utils/src/casing.ts
 /**
@@ -148,18 +159,6 @@ function toCamelOrPascal(text, pascal) {
 	}).join("").replace(/[^a-zA-Z0-9]/g, "");
 }
 /**
-* Converts `text` to camelCase.
-*
-* @example Word boundaries
-* `camelCase('hello-world') // 'helloWorld'`
-*
-* @example With a prefix
-* `camelCase('tag', { prefix: 'create' }) // 'createTag'`
-*/
-function camelCase(text, { prefix = "", suffix = "" } = {}) {
-	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, false);
-}
-/**
 * Converts `text` to PascalCase.
 *
 * @example Word boundaries
@@ -272,209 +271,6 @@ async function read(path) {
 	return readFile(path, { encoding: "utf8" });
 }
 //#endregion
-//#region ../../internals/utils/src/reserved.ts
-/**
-* JavaScript and Java reserved words.
-* @link https://github.com/jonschlinkert/reserved/blob/master/index.js
-*/
-const reservedWords = new Set([
-	"abstract",
-	"arguments",
-	"boolean",
-	"break",
-	"byte",
-	"case",
-	"catch",
-	"char",
-	"class",
-	"const",
-	"continue",
-	"debugger",
-	"default",
-	"delete",
-	"do",
-	"double",
-	"else",
-	"enum",
-	"eval",
-	"export",
-	"extends",
-	"false",
-	"final",
-	"finally",
-	"float",
-	"for",
-	"function",
-	"goto",
-	"if",
-	"implements",
-	"import",
-	"in",
-	"instanceof",
-	"int",
-	"interface",
-	"let",
-	"long",
-	"native",
-	"new",
-	"null",
-	"package",
-	"private",
-	"protected",
-	"public",
-	"return",
-	"short",
-	"static",
-	"super",
-	"switch",
-	"synchronized",
-	"this",
-	"throw",
-	"throws",
-	"transient",
-	"true",
-	"try",
-	"typeof",
-	"var",
-	"void",
-	"volatile",
-	"while",
-	"with",
-	"yield",
-	"Array",
-	"Date",
-	"hasOwnProperty",
-	"Infinity",
-	"isFinite",
-	"isNaN",
-	"isPrototypeOf",
-	"length",
-	"Math",
-	"name",
-	"NaN",
-	"Number",
-	"Object",
-	"prototype",
-	"String",
-	"toString",
-	"undefined",
-	"valueOf"
-]);
-/**
-* Returns `true` when `name` is a syntactically valid JavaScript variable name.
-*
-* @example
-* ```ts
-* isValidVarName('status')  // true
-* isValidVarName('class')   // false (reserved word)
-* isValidVarName('42foo')   // false (starts with digit)
-* ```
-*/
-function isValidVarName(name) {
-	if (!name || reservedWords.has(name)) return false;
-	return isIdentifier(name);
-}
-/**
-* Returns `true` when `name` is syntactically a valid identifier, ignoring reserved words.
-*
-* Reserved words and globals (`class`, `name`, `Date`, …) are valid as bare object-literal keys
-* even though they are not valid variable names, so use this (not {@link isValidVarName}) when
-* deciding whether an object key needs quoting.
-*
-* @example
-* ```ts
-* isIdentifier('name')   // true
-* isIdentifier('x-total')// false
-* ```
-*/
-function isIdentifier(name) {
-	return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name);
-}
-//#endregion
-//#region ../../internals/utils/src/url.ts
-function transformParam(raw, casing) {
-	const param = isValidVarName(raw) ? raw : camelCase(raw);
-	return casing === "camelcase" ? camelCase(param) : param;
-}
-function toParamsObject(path, { replacer, casing } = {}) {
-	const params = {};
-	for (const match of path.matchAll(/\{([^}]+)\}/g)) {
-		const param = transformParam(match[1], casing);
-		const key = replacer ? replacer(param) : param;
-		params[key] = key;
-	}
-	return Object.keys(params).length > 0 ? params : null;
-}
-/**
-* Helpers for OpenAPI/Swagger paths, plus a thin wrapper over the native `URL`.
-*/
-var Url = class Url {
-	/**
-	* Reports whether `url` is a parseable absolute URL. Delegates to the native `URL.canParse`.
-	*
-	* @example
-	* Url.canParse('https://petstore.swagger.io/v2') // true
-	* Url.canParse('/pet/{petId}')                   // false
-	*/
-	static canParse(url, base) {
-		return URL.canParse(url, base);
-	}
-	/**
-	* Converts an OpenAPI/Swagger path to Express-style colon syntax.
-	*
-	* @example
-	* Url.toPath('/pet/{petId}') // '/pet/:petId'
-	*/
-	static toPath(path) {
-		return path.replace(/\{([^}]+)\}/g, ":$1");
-	}
-	/**
-	* Converts an OpenAPI/Swagger path to a TypeScript template literal string.
-	* `prefix` is prepended inside the literal, `replacer` transforms each parameter name,
-	* and `casing` controls parameter identifier casing.
-	*
-	* @example
-	* Url.toTemplateString('/pet/{petId}') // '`/pet/${petId}`'
-	*
-	* @example
-	* Url.toTemplateString('/pet/{petId}', { prefix: 'https://api' }) // '`https://api/pet/${petId}`'
-	*/
-	static toTemplateString(path, { prefix, replacer, casing } = {}) {
-		const result = path.split(/\{([^}]+)\}/).map((part, i) => {
-			if (i % 2 === 0) return part;
-			const param = transformParam(part, casing);
-			return `\${${replacer ? replacer(param) : param}}`;
-		}).join("");
-		return `\`${prefix ?? ""}${result}\``;
-	}
-	/**
-	* Returns the path and its extracted params as a structured `URLObject`, or as a stringified
-	* expression when `stringify` is set.
-	*
-	* @example
-	* Url.toObject('/pet/{petId}')
-	* // { url: '/pet/:petId', params: { petId: 'petId' } }
-	*/
-	static toObject(path, { type = "path", replacer, stringify, casing } = {}) {
-		const object = {
-			url: type === "path" ? Url.toPath(path) : Url.toTemplateString(path, {
-				replacer,
-				casing
-			}),
-			params: toParamsObject(path, {
-				replacer,
-				casing
-			})
-		};
-		if (stringify) {
-			if (type === "template") return JSON.stringify(object).replaceAll("'", "").replaceAll(`"`, "");
-			if (object.params) return `{ url: '${object.url}', params: ${JSON.stringify(object.params).replaceAll("'", "").replaceAll(`"`, "")} }`;
-			return `{ url: '${object.url}' }`;
-		}
-		return object;
-	}
-};
-//#endregion
 //#region src/bundler.ts
 const urlRegExp = /^https?:\/+/i;
 async function readSource(sourcePath) {
@@ -552,7 +348,7 @@ async function parseDocument(pathOrApi) {
 */
 async function parseFromConfig(source) {
 	if (source.type === "data") return parseDocument(typeof source.data === "string" ? parse(source.data) : structuredClone(source.data));
-	if (Url.canParse(source.path)) return parseDocument(source.path);
+	if (URL.canParse(source.path)) return parseDocument(source.path);
 	const resolved = path.resolve(path.dirname(source.path), source.path);
 	await assertInputExists(resolved);
 	return parseDocument(resolved);
@@ -563,7 +359,7 @@ async function parseFromConfig(source) {
 * its parse error instead.
 */
 async function assertInputExists(input) {
-	if (Url.canParse(input)) return;
+	if (URL.canParse(input)) return;
 	if (!await exists(input)) throw new Diagnostics.Error({
 		code: Diagnostics.code.inputNotFound,
 		severity: "error",
@@ -1465,7 +1261,7 @@ 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) {
+function createNullSchema(schema, name, nullable) {
 	return ast.factory.createSchema({
 		type: "null",
 		primitive: "null",
@@ -1473,6 +1269,7 @@ function createNullSchema(schema, name) {
 		title: schema.title,
 		description: schema.description,
 		deprecated: schema.deprecated,
+		nullable,
 		format: schema.format
 	});
 }
@@ -1651,6 +1448,34 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 				properties: [discriminatorProperty]
 			});
 		}
+		function resolveRefSilent($ref) {
+			if (!$ref.startsWith("#")) return null;
+			return decodeURIComponent($ref.substring(1)).split("/").filter(Boolean).reduce((obj, key) => obj?.[key], document) ?? null;
+		}
+		function implicitDiscriminantValue(member) {
+			if (!discriminator || discriminator.mapping || !dialect.schema.isReference(member)) return null;
+			const value = extractRefName(member.$ref);
+			if (!value) return null;
+			const variant = resolveRefSilent(member.$ref);
+			if (!variant) return null;
+			const propertyName = discriminator.propertyName;
+			const seen = new Set([member.$ref]);
+			function constrains(v) {
+				const prop = v.properties?.[propertyName];
+				const resolved = prop && dialect.schema.isReference(prop) ? resolveRefSilent(prop.$ref) : prop;
+				if (resolved && (Array.isArray(resolved.enum) || resolved.const !== void 0)) return true;
+				const composition = v.allOf ?? v.oneOf ?? v.anyOf;
+				if (!composition) return false;
+				return composition.some((m) => {
+					if (!dialect.schema.isReference(m)) return constrains(m);
+					if (seen.has(m.$ref)) return false;
+					seen.add(m.$ref);
+					const r = resolveRefSilent(m.$ref);
+					return r ? constrains(r) : false;
+				});
+			}
+			return constrains(variant) ? null : value;
+		}
 		const unionMembers = [...schema.oneOf ?? [], ...schema.anyOf ?? []];
 		const strategy = schema.oneOf ? "one" : "any";
 		const unionBase = {
@@ -1659,17 +1484,15 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 			strategy
 		};
 		const discriminator = dialect.schema.isDiscriminator(schema) ? schema.discriminator : void 0;
-		const sharedPropertiesNode = schema.properties ? (() => {
-			const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema;
-			return parseSchema({
-				schema: discriminator ? Object.fromEntries(Object.entries(schemaWithoutUnion).filter(([key]) => key !== "discriminator")) : schemaWithoutUnion,
-				name
-			}, rawOptions);
-		})() : void 0;
-		if (sharedPropertiesNode || discriminator?.mapping) {
+		const { oneOf: _o, anyOf: _a, discriminator: _d, ...memberBaseSchema } = schema;
+		const sharedPropertiesNode = schema.properties ? parseSchema({
+			schema: memberBaseSchema,
+			name
+		}, rawOptions) : void 0;
+		if (sharedPropertiesNode || discriminator) {
 			const members = unionMembers.map((s) => {
 				const ref = dialect.schema.isReference(s) ? s.$ref : void 0;
-				const discriminatorValue = findDiscriminator(discriminator?.mapping, ref);
+				const discriminatorValue = findDiscriminator(discriminator?.mapping, ref) ?? implicitDiscriminantValue(s);
 				const memberNode = parseSchema({
 					schema: s,
 					name
@@ -1822,9 +1645,11 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 			format: schema.format
 		};
 		const extensionKey = enumExtensionKeys.find((key) => key in schema);
-		if (extensionKey || enumPrimitive === "number" || enumPrimitive === "integer" || enumPrimitive === "boolean") {
+		const descriptionKey = enumDescriptionKeys.find((key) => key in schema);
+		if (extensionKey || descriptionKey || enumPrimitive === "number" || enumPrimitive === "integer" || enumPrimitive === "boolean") {
 			const enumPrimitiveType = enumPrimitive === "number" || enumPrimitive === "integer" ? "number" : enumPrimitive === "boolean" ? "boolean" : "string";
 			const rawEnumNames = extensionKey ? schema[extensionKey] : void 0;
+			const rawEnumDescriptions = descriptionKey ? schema[descriptionKey] : void 0;
 			const uniqueValues = [...new Set(filteredValues)];
 			const seenNames = /* @__PURE__ */ new Set();
 			return ast.factory.createSchema({
@@ -1833,7 +1658,8 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 				namedEnumValues: uniqueValues.map((value, index) => ({
 					name: String(rawEnumNames?.[index] ?? value),
 					value,
-					primitive: enumPrimitiveType
+					primitive: enumPrimitiveType,
+					description: rawEnumDescriptions?.[index]
 				})).filter((entry) => {
 					if (seenNames.has(entry.name)) return false;
 					seenNames.add(entry.name);
@@ -1903,22 +1729,11 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		return objectNode;
 	}
 	/**
-	* Resolves a tuple's rest-element schema from the `items` keyword that sits alongside `prefixItems`.
-	*
-	* `items: false` closes the tuple, so no rest element is emitted. An absent `items` widens the tail
-	* to `any`, and a schema object (or `items: true`) becomes the homogeneous rest type.
-	*/
-	function resolveTupleRest(items, rawOptions) {
-		if (items === false) return void 0;
-		if (!items || items === true) return ast.factory.createSchema({ type: "any" });
-		return parseSchema({ schema: items }, rawOptions);
-	}
-	/**
 	* Converts an OAS 3.1 `prefixItems` tuple into a `TupleSchemaNode`.
 	*/
 	function convertTuple({ schema, name, nullable, defaultValue, rawOptions }) {
 		const tupleItems = (schema.prefixItems ?? []).map((item) => parseSchema({ schema: item }, rawOptions));
-		const rest = resolveTupleRest(schema.items, rawOptions);
+		const rest = schema.items === false ? void 0 : !schema.items || schema.items === true ? ast.factory.createSchema({ type: "any" }) : parseSchema({ schema: schema.items }, rawOptions);
 		return ast.factory.createSchema({
 			type: "tuple",
 			primitive: "array",
@@ -1988,21 +1803,6 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		});
 	}
 	/**
-	* Converts an explicit `type: 'null'` schema.
-	*/
-	function convertNull({ schema, name, nullable }) {
-		return ast.factory.createSchema({
-			type: "null",
-			primitive: "null",
-			name,
-			title: schema.title,
-			description: schema.description,
-			deprecated: schema.deprecated,
-			nullable,
-			format: schema.format
-		});
-	}
-	/**
 	* Converts a binary string schema (`type: 'string'`, `contentMediaType: 'application/octet-stream'`)
 	* into a `blob` node.
 	*/
@@ -2044,94 +1844,76 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 	*/
 	const schemaRules = [
 		{
-			name: "ref",
 			match: ({ schema }) => dialect.schema.isReference(schema),
 			convert: convertRef
 		},
 		{
-			name: "allOf",
 			match: ({ schema }) => !!schema.allOf?.length,
 			convert: convertAllOf
 		},
 		{
-			name: "union",
 			match: ({ schema }) => !!(schema.oneOf?.length || schema.anyOf?.length),
 			convert: convertUnion
 		},
 		{
-			name: "const",
 			match: ({ schema }) => "const" in schema && schema.const !== void 0,
 			convert: convertConst
 		},
 		{
-			name: "format",
 			match: ({ schema }) => !!schema.format,
 			convert: convertFormat
 		},
 		{
-			name: "blob",
 			match: ({ schema }) => dialect.schema.isBinary(schema),
 			convert: convertBlob
 		},
 		{
-			name: "multi-type",
 			match: ({ schema }) => Array.isArray(schema.type) && schema.type.length > 1,
 			convert: convertMultiType
 		},
 		{
-			name: "constrained-string",
 			match: ({ schema, type }) => !type && (schema.minLength !== void 0 || schema.maxLength !== void 0 || schema.pattern !== void 0),
 			convert: convertString
 		},
 		{
-			name: "constrained-number",
 			match: ({ schema, type }) => !type && (schema.minimum !== void 0 || schema.maximum !== void 0),
 			convert: (ctx) => convertNumeric(ctx, "number")
 		},
 		{
-			name: "enum",
 			match: ({ schema }) => !!schema.enum?.length,
 			convert: convertEnum
 		},
 		{
-			name: "object",
 			match: ({ schema, type }) => type === "object" || !!schema.properties || !!schema.additionalProperties || "patternProperties" in schema,
 			convert: convertObject
 		},
 		{
-			name: "tuple",
 			match: ({ schema }) => "prefixItems" in schema,
 			convert: convertTuple
 		},
 		{
-			name: "array",
 			match: ({ schema, type }) => type === "array" || "items" in schema,
 			convert: convertArray
 		},
 		{
-			name: "string",
 			match: ({ type }) => type === "string",
 			convert: convertString
 		},
 		{
-			name: "number",
 			match: ({ type }) => type === "number",
 			convert: (ctx) => convertNumeric(ctx, "number")
 		},
 		{
-			name: "integer",
 			match: ({ type }) => type === "integer",
 			convert: (ctx) => convertNumeric(ctx, "integer")
 		},
 		{
-			name: "boolean",
 			match: ({ type }) => type === "boolean",
 			convert: convertBoolean
 		},
 		{
-			name: "null",
 			match: ({ type }) => type === "null",
-			convert: convertNull
+			convert: ({ schema, name, nullable }) => createNullSchema(schema, name, nullable)
 		}
 	];
 	/**
@@ -2186,6 +1968,8 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 			schema: param["schema"],
 			name: schemaName
 		}, options) : ast.factory.createSchema({ type: options.unknownType });
+		const style = param["style"];
+		const explode = param["explode"];
 		return ast.factory.createParameter({
 			name: paramName,
 			in: param["in"],
@@ -2193,7 +1977,9 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 				...schema,
 				description: param["description"] ?? schema.description
 			},
-			required
+			required,
+			...style !== void 0 ? { style } : {},
+			...explode !== void 0 ? { explode } : {}
 		});
 	}
 	/**
@@ -2209,17 +1995,6 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		};
 	}
 	/**
-	* Reads the inline response object (not a `$ref`) and returns its description plus its `content` map.
-	*/
-	function getResponseMeta(responseObj) {
-		if (typeof responseObj !== "object" || responseObj === null || Array.isArray(responseObj)) return {};
-		const inline = responseObj;
-		return {
-			description: inline.description,
-			content: inline.content
-		};
-	}
-	/**
 	* Collects property names whose schema has a truthy boolean flag (`readOnly` or `writeOnly`).
 	* `$ref` entries are skipped since their flags live on the dereferenced target.
 	*/
@@ -2266,7 +2041,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 				statusCode
 			});
 			const responseName = operationName ? `${operationName}Status${statusCode}` : void 0;
-			const { description } = getResponseMeta(responseObj);
+			const description = typeof responseObj === "object" && responseObj !== null ? responseObj.description : void 0;
 			const parseEntrySchema = (contentType) => {
 				const raw = getResponseSchema(document, operation, statusCode, { contentType });
 				return {
@@ -2335,6 +2110,7 @@ function collectInlineEnums(roots, topLevelNames) {
 		const isSchemaRoot = root.kind === "Schema";
 		for (const node of ast.collect(root, { schema: (schemaNode) => schemaNode })) {
 			if (node.type !== "enum" || !node.name) continue;
+			if ((node.namedEnumValues ?? node.enumValues ?? []).length === 1) continue;
 			if (isSchemaRoot && node === root) continue;
 			if (topLevelNames.has(node.name)) continue;
 			if (!promoted.has(node.name)) promoted.set(node.name, {
@@ -2484,7 +2260,9 @@ function preScan({ schemas, parseSchema, parseOperation, document, parserOptions
 			name
 		});
 		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);
+		const enumNode = ast.narrowSchema(node, ast.schemaTypes.enum);
+		const isConstEnum = (enumNode?.namedEnumValues ?? enumNode?.enumValues ?? []).length === 1;
+		if (enumNode && node.name && !isConstEnum) enumNames.push(node.name);
 		if (discriminator === "propagate" && (schema.oneOf ?? schema.anyOf) && schema.discriminator?.propertyName) discriminatorParentNodes.push(node);
 	}
 	const circularNames = [...findCircularSchemas(allNodes)];