@kubb/adapter-oas 5.0.0-beta.58 → 5.0.0-beta.59

package/dist/index.d.ts

@@ -1071,8 +1071,7 @@ type Operation = {
 //#endregion
 //#region src/types.d.ts
 /**
- * Content-type string for selecting request/response schemas from an OpenAPI spec.
- * Supports `'application/json'` or any other media type.
+ * Media type used to pick a schema from an operation's request or response.
  *
  * @example
  * ```ts
@@ -1131,12 +1130,12 @@ type SchemaObject$1 = {
    */
   items?: SchemaObject$1 | ReferenceObject$1;
   /**
-   * Enum values for this schema (narrowed from `unknown[]`).
+   * Allowed values for this schema.
    */
   enum?: Array<string | number | boolean | null>;
 } & (OpenAPIV3.SchemaObject | OpenAPIV3_1.SchemaObject | JSONSchema4 | JSONSchema6 | JSONSchema7);
 /**
- * HTTP method as a lowercase string (`'get' | 'post' | ...`).
+ * HTTP method in the lowercase form an OpenAPI path item uses for its keys.
  */
 type HttpMethod = Lowercase<ast.HttpMethod>;
 /**
@@ -1156,7 +1155,7 @@ type DiscriminatorObject$1 = OpenAPIV3.DiscriminatorObject | OpenAPIV3_1.Discrim
  */
 type ReferenceObject$1 = OpenAPIV3.ReferenceObject;
 /**
- * OpenAPI response object from a spec that contains schema, status code, and headers.
+ * OpenAPI response object holding the content and headers for one status code.
  */
 type ResponseObject$1 = OpenAPIV3.ResponseObject | OpenAPIV3_1.ResponseObject;
 /**
@@ -1164,9 +1163,8 @@ type ResponseObject$1 = OpenAPIV3.ResponseObject | OpenAPIV3_1.ResponseObject;
  */
 type MediaTypeObject$1 = OpenAPIV3.MediaTypeObject | OpenAPIV3_1.MediaTypeObject;
 /**
- * Configuration options for the OpenAPI adapter. Controls spec validation,
- * content-type selection, server URL resolution, and how types are derived
- * from the spec.
+ * Configuration for the OpenAPI adapter: spec validation, content-type selection,
+ * server URL resolution, and how schema types are derived.
  *
  * @example
  * ```ts
@@ -1227,9 +1225,9 @@ type AdapterOasOptions = {
    *
    * 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: documentation such as
-   * `description` and `example` is ignored. Enabled by default. Set to `false` to keep every
-   * occurrence inline and produce byte-for-byte identical output to earlier versions.
+   * 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.
    *
    * @default true
    */

package/dist/index.js

@@ -5,7 +5,7 @@ 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, findDiscriminator } from "@kubb/ast/utils";
+import { childName, containsCircularRef, enumPropName, extractRefName, findCircularSchemas } from "@kubb/ast/utils";
 import { collect, narrowSchema } from "@kubb/ast";
 //#region src/constants.ts
 /**
@@ -91,7 +91,7 @@ const structuralKeys = new Set([
 *
 * Only formats whose AST type differs from the OAS `type` field appear here.
 * Formats that depend on runtime options (`int64`, `date-time`, `date`, `time`) are handled separately
-* in the parser. `ipv4` and `ipv6` map to their own dedicated schema types; `hostname` and
+* in the parser. `ipv4` and `ipv6` map to their own dedicated schema types. `hostname` and
 * `idn-hostname` map to `'url'` as the closest generic string-format type.
 *
 * @example
@@ -144,8 +144,8 @@ const formatMap = {
 */
 const enumExtensionKeys = ["x-enumNames", "x-enum-varnames"];
 /**
-* Maps `'any' | 'unknown' | 'void'` option strings to their `ScalarSchemaType` constant.
-* Replaces a plain object lookup with a `Map` for explicit key membership testing via `.has()`.
+* Maps the `unknownType`/`emptySchemaType` option string to its `ScalarSchemaType` constant.
+* A `Map` (over a plain object) lets callers test key membership with `.has()`.
 */
 const typeOptionMap = new Map([
 	["any", ast.schemaTypes.any],
@@ -840,6 +840,120 @@ const oasDialect = ast.defineSchemaDialect({
 	resolveRef
 });
 //#endregion
+//#region src/discriminator.ts
+/**
+* Builds a map of child schema names → discriminator patch data by scanning the given
+* top-level AST schema nodes for union schemas that carry a `discriminatorPropertyName`.
+*
+* The streaming path calls this on a small pre-parsed subset of schemas (only the
+* discriminator parents) rather than on all schemas at once.
+*/
+function buildDiscriminatorChildMap(schemas) {
+	const childMap = /* @__PURE__ */ new Map();
+	for (const schema of schemas) {
+		let unionNode = ast.narrowSchema(schema, "union");
+		if (!unionNode) {
+			const intersectionMembers = ast.narrowSchema(schema, "intersection")?.members;
+			if (intersectionMembers) for (const m of intersectionMembers) {
+				const u = ast.narrowSchema(m, "union");
+				if (u) {
+					unionNode = u;
+					break;
+				}
+			}
+		}
+		if (!unionNode?.discriminatorPropertyName || !unionNode.members) continue;
+		const { discriminatorPropertyName, members } = unionNode;
+		for (const member of members) {
+			const intersectionNode = ast.narrowSchema(member, "intersection");
+			if (!intersectionNode?.members) continue;
+			let refNode = null;
+			let objNode = null;
+			for (const m of intersectionNode.members) {
+				refNode ??= ast.narrowSchema(m, "ref");
+				objNode ??= ast.narrowSchema(m, "object");
+			}
+			if (!refNode?.name || !objNode) continue;
+			const prop = objNode.properties.find((p) => p.name === discriminatorPropertyName);
+			const enumNode = prop ? ast.narrowSchema(prop.schema, "enum") : null;
+			if (!enumNode?.enumValues?.length) continue;
+			const enumValues = enumNode.enumValues.filter((v) => v !== null);
+			if (!enumValues.length) continue;
+			const existing = childMap.get(refNode.name);
+			if (!existing) {
+				childMap.set(refNode.name, {
+					propertyName: discriminatorPropertyName,
+					enumValues: [...enumValues]
+				});
+				continue;
+			}
+			existing.enumValues.push(...enumValues);
+		}
+	}
+	return childMap;
+}
+/**
+* Patches a single top-level `SchemaNode` with its discriminator entry (adds or replaces
+* the discriminant property). Used by the streaming path to apply patches inline per yield
+* without buffering all schemas.
+*/
+function patchDiscriminatorNode(node, entry) {
+	const objectNode = ast.narrowSchema(node, "object");
+	if (!objectNode) return node;
+	const { propertyName, enumValues } = entry;
+	const enumSchema = ast.factory.createSchema({
+		type: "enum",
+		enumValues
+	});
+	const newProp = ast.factory.createProperty({
+		name: propertyName,
+		required: true,
+		schema: enumSchema
+	});
+	const existingIdx = objectNode.properties.findIndex((p) => p.name === propertyName);
+	const newProperties = existingIdx >= 0 ? objectNode.properties.map((p, i) => i === existingIdx ? newProp : p) : [...objectNode.properties, newProp];
+	return {
+		...objectNode,
+		properties: newProperties
+	};
+}
+/**
+* Creates a single-property object schema used as a discriminator literal.
+*
+* @example
+* ```ts
+* createDiscriminantNode({ propertyName: 'type', value: 'dog' })
+* // -> { type: 'object', properties: [{ name: 'type', required: true, schema: enum('dog') }] }
+* ```
+*/
+function createDiscriminantNode({ propertyName, value }) {
+	return ast.factory.createSchema({
+		type: "object",
+		primitive: "object",
+		properties: [ast.factory.createProperty({
+			name: propertyName,
+			schema: ast.factory.createSchema({
+				type: "enum",
+				primitive: "string",
+				enumValues: [value]
+			}),
+			required: true
+		})]
+	});
+}
+/**
+* Returns the discriminator key whose mapping value matches `ref`, or `null` when there is no match.
+*
+* @example
+* ```ts
+* findDiscriminator({ dog: '#/components/schemas/Dog' }, '#/components/schemas/Dog') // 'dog'
+* ```
+*/
+function findDiscriminator(mapping, ref) {
+	if (!mapping || !ref) return null;
+	return Object.entries(mapping).find(([, value]) => value === ref)?.[0] ?? null;
+}
+//#endregion
 //#region src/mime.ts
 /**
 * MIME type fragments that mark a media type as JSON-like.
@@ -1328,7 +1442,7 @@ function getSchemas(document, { contentType }) {
 }
 /**
 * Resolves the AST type descriptor for a date/time format, honoring the `dateType` option.
-* Returns `null` when `dateType: false`, signalling the format should fall through to `string`.
+* Returns `null` when `dateType: false`, so the format falls through to `string`.
 */
 function getDateType(options, format) {
 	if (!options.dateType) return null;
@@ -1430,9 +1544,9 @@ function getResponseBodyContentTypes(document, operation, statusCode) {
 * Normalizes malformed `{ type: 'array', enum: [...] }` schemas by moving enum values into items.
 *
 * This pattern violates the OpenAPI spec but appears in real specs. The fix moves enum values
-* from the array to its items sub-schema, making them valid for downstream processing.
+* from the array to its items sub-schema, so they are valid for downstream processing.
 *
-* @note This is a defensive measure for robustness with non-compliant specs.
+* @note A defensive measure for non-compliant specs.
 */
 function normalizeArrayEnum(schema) {
 	const normalizedItems = {
@@ -1450,7 +1564,7 @@ function normalizeArrayEnum(schema) {
 *
 * Returns closures that share mutable state (`resolvingRefs` set for cycle detection).
 * Each converter branch (`convertRef`, `convertAllOf`, etc.) mutually recursively calls `parseSchema`,
-* made possible by hoisting of function declarations.
+* which works because function declarations hoist.
 *
 * @internal
 */
@@ -1580,7 +1694,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 			const { allOf: _allOf, ...schemaWithoutAllOf } = schema;
 			allOfMembers.push(parseSchema({ schema: schemaWithoutAllOf }, rawOptions));
 		}
-		for (const { propertyName, value } of filteredDiscriminantValues) allOfMembers.push(ast.factory.createDiscriminantNode({
+		for (const { propertyName, value } of filteredDiscriminantValues) allOfMembers.push(createDiscriminantNode({
 			propertyName,
 			value
 		}));
@@ -1634,7 +1748,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 				}), discriminator.propertyName) : void 0;
 				return ast.factory.createSchema({
 					type: "intersection",
-					members: [memberNode, narrowedDiscriminatorNode ?? ast.factory.createDiscriminantNode({
+					members: [memberNode, narrowedDiscriminatorNode ?? createDiscriminantNode({
 						propertyName: discriminator.propertyName,
 						value: discriminatorValue
 					})]
@@ -2289,84 +2403,6 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 	};
 }
 //#endregion
-//#region src/discriminator.ts
-/**
-* Builds a map of child schema names → discriminator patch data by scanning the given
-* top-level AST schema nodes for union schemas that carry a `discriminatorPropertyName`.
-*
-* The streaming path calls this on a small pre-parsed subset of schemas (only the
-* discriminator parents) rather than on all schemas at once.
-*/
-function buildDiscriminatorChildMap(schemas) {
-	const childMap = /* @__PURE__ */ new Map();
-	for (const schema of schemas) {
-		let unionNode = ast.narrowSchema(schema, "union");
-		if (!unionNode) {
-			const intersectionMembers = ast.narrowSchema(schema, "intersection")?.members;
-			if (intersectionMembers) for (const m of intersectionMembers) {
-				const u = ast.narrowSchema(m, "union");
-				if (u) {
-					unionNode = u;
-					break;
-				}
-			}
-		}
-		if (!unionNode?.discriminatorPropertyName || !unionNode.members) continue;
-		const { discriminatorPropertyName, members } = unionNode;
-		for (const member of members) {
-			const intersectionNode = ast.narrowSchema(member, "intersection");
-			if (!intersectionNode?.members) continue;
-			let refNode = null;
-			let objNode = null;
-			for (const m of intersectionNode.members) {
-				refNode ??= ast.narrowSchema(m, "ref");
-				objNode ??= ast.narrowSchema(m, "object");
-			}
-			if (!refNode?.name || !objNode) continue;
-			const prop = objNode.properties.find((p) => p.name === discriminatorPropertyName);
-			const enumNode = prop ? ast.narrowSchema(prop.schema, "enum") : null;
-			if (!enumNode?.enumValues?.length) continue;
-			const enumValues = enumNode.enumValues.filter((v) => v !== null);
-			if (!enumValues.length) continue;
-			const existing = childMap.get(refNode.name);
-			if (!existing) {
-				childMap.set(refNode.name, {
-					propertyName: discriminatorPropertyName,
-					enumValues: [...enumValues]
-				});
-				continue;
-			}
-			existing.enumValues.push(...enumValues);
-		}
-	}
-	return childMap;
-}
-/**
-* Patches a single top-level `SchemaNode` with its discriminator entry (adds or replaces
-* the discriminant property). Used by the streaming path to apply patches inline per yield
-* without buffering all schemas.
-*/
-function patchDiscriminatorNode(node, entry) {
-	const objectNode = ast.narrowSchema(node, "object");
-	if (!objectNode) return node;
-	const { propertyName, enumValues } = entry;
-	const enumSchema = ast.factory.createSchema({
-		type: "enum",
-		enumValues
-	});
-	const newProp = ast.factory.createProperty({
-		name: propertyName,
-		required: true,
-		schema: enumSchema
-	});
-	const existingIdx = objectNode.properties.findIndex((p) => p.name === propertyName);
-	const newProperties = existingIdx >= 0 ? objectNode.properties.map((p, i) => i === existingIdx ? newProp : p) : [...objectNode.properties, newProp];
-	return {
-		...objectNode,
-		properties: newProperties
-	};
-}
-//#endregion
 //#region src/schemaDiagnostics.ts
 /**
 * Reports the advisory diagnostics (`KUBB_UNSUPPORTED_FORMAT`, `KUBB_DEPRECATED`) for one
@@ -2429,7 +2465,7 @@ function visit(node, pointer) {
 *
 * 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.
+* name (collision-resolved against existing component names). Shapes without a name stay inline.
 */
 function createDedupePlan({ schemaNodes, operationNodes, schemaNames, circularNames }) {
 	const circularSchemas = new Set(circularNames);