@kubb/ast 5.0.0-beta.29 → 5.0.0-beta.30

package/dist/index.cjs

@@ -224,6 +224,60 @@ const mediaTypes = {
 	videoMp4: "video/mp4"
 };
 //#endregion
+//#region src/dialect.ts
+/**
+* Identity helper that types a {@link SchemaDialect} for an adapter. Like
+* `defineParser`, it adds no runtime behavior — it pins the dialect's type for
+* inference and gives adapter authors a discoverable anchor.
+*
+* @example
+* ```ts
+* export const oasDialect = defineSchemaDialect({
+*   name: 'oas',
+*   isNullable,
+*   isReference,
+*   isDiscriminator,
+*   isBinary: (schema) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
+*   resolveRef,
+* })
+* ```
+*/
+function defineSchemaDialect(dialect) {
+	return dialect;
+}
+//#endregion
+//#region src/dispatch.ts
+/**
+* Walks an ordered list of {@link DispatchRule}s and returns the first node produced.
+*
+* This is the shared backbone for spec adapters (OpenAPI today, AsyncAPI and others later).
+* The contract an adapter follows is intentionally minimal:
+*
+*     context → [rule.match → rule.convert] → node
+*
+* An adapter derives a context from a source spec node, then declares an ordered table of
+* rules mapping spec shapes onto Kubb AST nodes. To add support for a new spec, write a new
+* context type and a new rules table — the traversal here is reused unchanged.
+*
+* Order is significant: earlier rules win, so list higher-precedence or more specific shapes
+* first (e.g. composition keywords before plain `type`). A rule whose `match` returns `true`
+* may still `convert` to `null` to defer to later rules. When no rule produces a node this
+* returns `null`, leaving the caller to apply its own fallback.
+*
+* @example
+* ```ts
+* const node = dispatch(schemaRules, schemaContext) ?? createSchema({ type: fallbackType })
+* ```
+*/
+function dispatch(rules, context) {
+	for (const rule of rules) {
+		if (!rule.match(context)) continue;
+		const node = rule.convert(context);
+		if (node !== null && node !== void 0) return node;
+	}
+	return null;
+}
+//#endregion
 //#region ../../internals/utils/src/casing.ts
 /**
 * Shared implementation for camelCase and PascalCase conversion.
@@ -498,6 +552,19 @@ const isOutputNode = isKind("Output");
 */
 const isOperationNode = isKind("Operation");
 /**
+* Narrows an `OperationNode` to an `HttpOperationNode`, guaranteeing `method` and `path`.
+*
+* @example
+* ```ts
+* if (isHttpOperationNode(node)) {
+*   console.log(node.method, node.path)
+* }
+* ```
+*/
+function isHttpOperationNode(node) {
+	return node.protocol === "http" || node.method !== void 0 && node.path !== void 0;
+}
+/**
 * Returns `true` when the input is a `SchemaNode`.
 *
 * @example
@@ -560,58 +627,84 @@ function createLimit(concurrency) {
 		});
 	};
 }
+const visitorKeysByKind = {
+	Input: ["schemas", "operations"],
+	Operation: [
+		"parameters",
+		"requestBody",
+		"responses"
+	],
+	RequestBody: ["content"],
+	Content: ["schema"],
+	Response: ["content"],
+	Schema: [
+		"properties",
+		"items",
+		"members",
+		"additionalProperties"
+	],
+	Property: ["schema"],
+	Parameter: ["schema"]
+};
 /**
-* Returns the immediate traversable children of `node`.
+* Returns `true` when `value` is an AST node (an object carrying a `kind`).
+*/
+function isNode(value) {
+	return typeof value === "object" && value !== null && "kind" in value;
+}
+/**
+* Returns the immediate traversable children of `node` based on {@link VISITOR_KEYS}.
 *
-* For `Schema` nodes, children (`properties`, `items`, `members`, and non-boolean
-* `additionalProperties`) are only included
-* when `recurse` is `true`; shallow mode skips them.
+* `Schema` children are only included when `recurse` is `true`; shallow mode skips them.
 *
 * @example
 * ```ts
 * const children = getChildren(operationNode, true)
-* // returns parameters, requestBody schema (if present), and responses
+* // returns parameters, the request body, and responses
 * ```
 */
 function* getChildren(node, recurse) {
-	if (node.kind === "Input") {
-		yield* node.schemas;
-		yield* node.operations;
-		return;
-	}
-	if (node.kind === "Output") return;
-	if (node.kind === "Operation") {
-		yield* node.parameters;
-		if (node.requestBody?.content) {
-			for (const c of node.requestBody.content) if (c.schema) yield c.schema;
-		}
-		yield* node.responses;
-		return;
-	}
-	if (node.kind === "Schema") {
-		if (!recurse) return;
-		if ("properties" in node && node.properties.length > 0) yield* node.properties;
-		if ("items" in node && node.items) yield* node.items;
-		if ("members" in node && node.members) yield* node.members;
-		if ("additionalProperties" in node && node.additionalProperties && node.additionalProperties !== true) yield node.additionalProperties;
-		return;
-	}
-	if (node.kind === "Property") {
-		yield node.schema;
-		return;
-	}
-	if (node.kind === "Parameter") {
-		yield node.schema;
-		return;
-	}
-	if (node.kind === "Response") {
-		if (node.content) {
-			for (const c of node.content) if (c.schema) yield c.schema;
-		}
-		return;
+	if (node.kind === "Schema" && !recurse) return;
+	const keys = visitorKeysByKind[node.kind];
+	if (!keys) return;
+	const record = node;
+	for (const key of keys) {
+		const value = record[key];
+		if (Array.isArray(value)) {
+			for (const item of value) if (isNode(item)) yield item;
+		} else if (isNode(value)) yield value;
 	}
 }
 /**
+* Maps a node `kind` to the matching visitor callback name. Only the seven
+* traversable node kinds have an entry; every other kind resolves to
+* `undefined` and is skipped.
+*/
+const VISITOR_KEY_BY_KIND = {
+	Input: "input",
+	Output: "output",
+	Operation: "operation",
+	Schema: "schema",
+	Property: "property",
+	Parameter: "parameter",
+	Response: "response"
+};
+/**
+* Invokes the visitor callback that matches `node.kind`, passing the traversal
+* context. Returns the callback's result (a replacement node, a collected
+* value, or `undefined` when no callback is registered for the kind).
+*
+* Shared by `walk`, `transform`, and `collectLazy` so node-kind dispatch lives
+* in one place. `TResult` is the caller's expected return: the same node type
+* for `transform`, the collected value type for `collectLazy`, ignored for `walk`.
+*/
+function applyVisitor(node, visitor, parent) {
+	const key = VISITOR_KEY_BY_KIND[node.kind];
+	if (!key) return void 0;
+	const fn = visitor[key];
+	return fn?.(node, { parent });
+}
+/**
 * Async depth-first traversal for side effects. Visitor return values are
 * ignored. Use `transform` when you want to rewrite nodes.
 *
@@ -637,122 +730,63 @@ async function walk(node, options) {
 	return _walk(node, options, (options.depth ?? visitorDepths.deep) === visitorDepths.deep, createLimit(options.concurrency ?? 30), void 0);
 }
 async function _walk(node, visitor, recurse, limit, parent) {
-	switch (node.kind) {
-		case "Input":
-			await limit(() => visitor.input?.(node, { parent }));
-			break;
-		case "Output":
-			await limit(() => visitor.output?.(node, { parent }));
-			break;
-		case "Operation":
-			await limit(() => visitor.operation?.(node, { parent }));
-			break;
-		case "Schema":
-			await limit(() => visitor.schema?.(node, { parent }));
-			break;
-		case "Property":
-			await limit(() => visitor.property?.(node, { parent }));
-			break;
-		case "Parameter":
-			await limit(() => visitor.parameter?.(node, { parent }));
-			break;
-		case "Response":
-			await limit(() => visitor.response?.(node, { parent }));
-			break;
-	}
+	await limit(() => applyVisitor(node, visitor, parent));
 	const children = getChildren(node, recurse);
 	for (const child of children) await _walk(child, visitor, recurse, limit, node);
 }
 function transform(node, options) {
 	const { depth, parent, ...visitor } = options;
 	const recurse = (depth ?? visitorDepths.deep) === visitorDepths.deep;
-	if (node.kind === "Input") {
-		const input = visitor.input?.(node, { parent }) ?? node;
-		return {
-			...input,
-			schemas: input.schemas.map((s) => transform(s, {
-				...options,
-				parent: input
-			})),
-			operations: input.operations.map((op) => transform(op, {
-				...options,
-				parent: input
-			}))
-		};
-	}
-	if (node.kind === "Output") return visitor.output?.(node, { parent }) ?? node;
-	if (node.kind === "Operation") {
-		const op = visitor.operation?.(node, { parent }) ?? node;
-		return {
-			...op,
-			parameters: op.parameters.map((p) => transform(p, {
-				...options,
-				parent: op
-			})),
-			requestBody: op.requestBody ? {
-				...op.requestBody,
-				content: op.requestBody.content?.map((c) => ({
-					...c,
-					schema: c.schema ? transform(c.schema, {
-						...options,
-						parent: op
-					}) : void 0
-				}))
-			} : void 0,
-			responses: op.responses.map((r) => transform(r, {
-				...options,
-				parent: op
-			}))
-		};
-	}
-	if (node.kind === "Schema") {
-		const schema = visitor.schema?.(node, { parent }) ?? node;
-		const childOptions = {
-			...options,
-			parent: schema
-		};
-		return {
-			...schema,
-			..."properties" in schema && recurse ? { properties: schema.properties.map((p) => transform(p, childOptions)) } : {},
-			..."items" in schema && recurse ? { items: schema.items?.map((i) => transform(i, childOptions)) } : {},
-			..."members" in schema && recurse ? { members: schema.members?.map((m) => transform(m, childOptions)) } : {},
-			..."additionalProperties" in schema && recurse && schema.additionalProperties && schema.additionalProperties !== true ? { additionalProperties: transform(schema.additionalProperties, childOptions) } : {}
-		};
-	}
-	if (node.kind === "Property") {
-		const prop = visitor.property?.(node, { parent }) ?? node;
-		return createProperty({
-			...prop,
-			schema: transform(prop.schema, {
-				...options,
-				parent: prop
-			})
-		});
-	}
-	if (node.kind === "Parameter") {
-		const param = visitor.parameter?.(node, { parent }) ?? node;
-		return createParameter({
-			...param,
-			schema: transform(param.schema, {
-				...options,
-				parent: param
-			})
-		});
-	}
-	if (node.kind === "Response") {
-		const response = visitor.response?.(node, { parent }) ?? node;
-		return {
-			...response,
-			content: response.content?.map((entry) => ({
-				...entry,
-				schema: entry.schema ? transform(entry.schema, {
-					...options,
-					parent: response
-				}) : entry.schema
-			}))
-		};
+	const rebuilt = transformChildren(applyVisitor(node, visitor, parent) ?? node, options, recurse);
+	if (rebuilt === node) return node;
+	const finalize = nodeFinalizers[rebuilt.kind];
+	return finalize ? finalize(rebuilt) : rebuilt;
+}
+/**
+* Per-kind builders rerun after children are rebuilt. `Property`/`Parameter`
+* resync schema optionality against their `required` flag once the schema may
+* have changed.
+*/
+const nodeFinalizers = {
+	Property: (node) => createProperty(node),
+	Parameter: (node) => createParameter(node)
+};
+/**
+* Immutably rebuilds a node's children using {@link VISITOR_KEYS}, transforming
+* each child node and leaving non-node values (e.g. `additionalProperties: true`) intact.
+* `Schema` children are skipped in shallow mode.
+*/
+function transformChildren(node, options, recurse) {
+	if (node.kind === "Schema" && !recurse) return node;
+	const keys = visitorKeysByKind[node.kind];
+	if (!keys) return node;
+	const record = node;
+	const childOptions = {
+		...options,
+		parent: node
+	};
+	let updates;
+	for (const key of keys) {
+		if (!(key in record)) continue;
+		const value = record[key];
+		if (Array.isArray(value)) {
+			let changed = false;
+			const mapped = value.map((item) => {
+				if (!isNode(item)) return item;
+				const next = transform(item, childOptions);
+				if (next !== item) changed = true;
+				return next;
+			});
+			if (changed) (updates ??= {})[key] = mapped;
+		} else if (isNode(value)) {
+			const next = transform(value, childOptions);
+			if (next !== value) (updates ??= {})[key] = next;
+		}
 	}
-	return node;
+	return updates ? {
+		...node,
+		...updates
+	} : node;
 }
 /**
 * Lazy depth-first collection pass. Yields every non-null value returned by
@@ -773,30 +807,7 @@ function transform(node, options) {
 function* collectLazy(node, options) {
 	const { depth, parent, ...visitor } = options;
 	const recurse = (depth ?? visitorDepths.deep) === visitorDepths.deep;
-	let v;
-	switch (node.kind) {
-		case "Input":
-			v = visitor.input?.(node, { parent });
-			break;
-		case "Output":
-			v = visitor.output?.(node, { parent });
-			break;
-		case "Operation":
-			v = visitor.operation?.(node, { parent });
-			break;
-		case "Schema":
-			v = visitor.schema?.(node, { parent });
-			break;
-		case "Property":
-			v = visitor.property?.(node, { parent });
-			break;
-		case "Parameter":
-			v = visitor.parameter?.(node, { parent });
-			break;
-		case "Response":
-			v = visitor.response?.(node, { parent });
-			break;
-	}
+	const v = applyVisitor(node, visitor, parent);
 	if (v != null) yield v;
 	for (const child of getChildren(node, recurse)) yield* collectLazy(child, {
 		...options,
@@ -1158,6 +1169,16 @@ function combineSources(sources) {
 	return [...seen.values()];
 }
 /**
+* Merges `incoming` names into `existing`, preserving order and dropping duplicates.
+*
+* Shared by `combineExports` and `combineImports` for the same-path name-merge case.
+*/
+function mergeNameArrays(existing, incoming) {
+	const merged = new Set(existing);
+	for (const name of incoming) merged.add(name);
+	return [...merged];
+}
+/**
 * Deduplicates and merges `ExportNode` objects by path and type.
 *
 * Named exports with the same path and `isTypeOnly` flag have their names merged into a single export.
@@ -1178,11 +1199,8 @@ function combineExports(exports) {
 			if (!name.length) continue;
 			const key = pathTypeKey(path, isTypeOnly);
 			const existing = namedByPath.get(key);
-			if (existing && Array.isArray(existing.name)) {
-				const merged = new Set(existing.name);
-				for (const n of name) merged.add(n);
-				existing.name = [...merged];
-			} else {
+			if (existing && Array.isArray(existing.name)) existing.name = mergeNameArrays(existing.name, name);
+			else {
 				const newItem = {
 					...curr,
 					name: [...new Set(name)]
@@ -1240,11 +1258,8 @@ function combineImports(imports, exports, source) {
 			if (!name.length) continue;
 			const key = pathTypeKey(path, isTypeOnly);
 			const existing = namedByPath.get(key);
-			if (existing && Array.isArray(existing.name)) {
-				const merged = new Set(existing.name);
-				for (const n of name) merged.add(n);
-				existing.name = [...merged];
-			} else {
+			if (existing && Array.isArray(existing.name)) existing.name = mergeNameArrays(existing.name, name);
+			else {
 				const newItem = {
 					...curr,
 					name
@@ -1463,6 +1478,29 @@ function syncOptionality(schema, required) {
 	};
 }
 /**
+* Identity-preserving node update: returns `node` unchanged when every field in
+* `changes` already equals (by reference) the current value, otherwise a new node
+* with the changes applied.
+*
+* Mirrors the TypeScript compiler's `factory.updateX` contract — pair it with the
+* structural sharing in {@link transform} so a no-op rewrite doesn't allocate and
+* downstream passes can detect "nothing changed" by identity. Comparison is
+* shallow: a structurally-equal but newly-allocated array/object counts as a change.
+*
+* @example
+* ```ts
+* update(node, { name: node.name })        // -> same `node` reference
+* update(node, { name: 'renamed' })        // -> new node, `name` replaced
+* ```
+*/
+function update(node, changes) {
+	for (const key in changes) if (changes[key] !== node[key]) return {
+		...node,
+		...changes
+	};
+	return node;
+}
+/**
 * Creates an `InputNode` with stable defaults for `schemas` and `operations`.
 *
 * @example
@@ -1527,35 +1565,35 @@ function createOutput(overrides = {}) {
 	};
 }
 /**
-* Creates an `OperationNode` with default empty arrays for `tags`, `parameters`, and `responses`.
-*
-* @example
-* ```ts
-* const operation = createOperation({
-*   operationId: 'getPetById',
-*   method: 'GET',
-*   path: '/pet/{petId}',
-* })
-* // tags, parameters, and responses are []
-* ```
-*
-* @example
-* ```ts
-* const operation = createOperation({
-*   operationId: 'findPets',
-*   method: 'GET',
-*   path: '/pet/findByStatus',
-*   tags: ['pet'],
-* })
-* ```
+* Creates a `ContentNode` for a single request-body or response content type.
+*/
+function createContent(props) {
+	return {
+		...props,
+		kind: "Content"
+	};
+}
+/**
+* Creates a `RequestBodyNode`, normalizing each content entry into a `ContentNode`.
 */
+function createRequestBody(props) {
+	return {
+		...props,
+		kind: "RequestBody",
+		content: props.content?.map(createContent)
+	};
+}
 function createOperation(props) {
+	const { requestBody, ...rest } = props;
+	const isHttp = rest.method !== void 0 && rest.path !== void 0;
 	return {
 		tags: [],
 		parameters: [],
 		responses: [],
-		...props,
-		kind: "Operation"
+		...rest,
+		...isHttp ? { protocol: "http" } : {},
+		kind: "Operation",
+		requestBody: requestBody ? createRequestBody(requestBody) : void 0
 	};
 }
 /**
@@ -1683,14 +1721,15 @@ function createParameter(props) {
 */
 function createResponse(props) {
 	const { schema, mediaType, keysToOmit, content, ...rest } = props;
+	const entries = content ?? (schema ? [{
+		contentType: mediaType ?? "application/json",
+		schema,
+		keysToOmit: keysToOmit ?? null
+	}] : void 0);
 	return {
 		...rest,
 		kind: "Response",
-		content: content ?? (schema ? [{
-			contentType: mediaType ?? "application/json",
-			schema,
-			keysToOmit: keysToOmit ?? null
-		}] : void 0)
+		content: entries?.map(createContent)
 	};
 }
 /**
@@ -2326,6 +2365,7 @@ exports.containsCircularRef = containsCircularRef;
 exports.createArrowFunction = createArrowFunction;
 exports.createBreak = createBreak;
 exports.createConst = createConst;
+exports.createContent = createContent;
 exports.createDiscriminantNode = createDiscriminantNode;
 exports.createExport = createExport;
 exports.createFile = createFile;
@@ -2343,6 +2383,7 @@ exports.createParameterGroup = createParameterGroup;
 exports.createParamsType = createParamsType;
 exports.createPrinterFactory = createPrinterFactory;
 exports.createProperty = createProperty;
+exports.createRequestBody = createRequestBody;
 exports.createResponse = createResponse;
 exports.createSchema = createSchema;
 exports.createSource = createSource;
@@ -2350,12 +2391,15 @@ exports.createStreamInput = createStreamInput;
 exports.createText = createText;
 exports.createType = createType;
 exports.definePrinter = definePrinter;
+exports.defineSchemaDialect = defineSchemaDialect;
+exports.dispatch = dispatch;
 exports.enumPropName = enumPropName;
 exports.extractRefName = extractRefName;
 exports.extractStringsFromNodes = extractStringsFromNodes;
 exports.findCircularSchemas = findCircularSchemas;
 exports.findDiscriminator = findDiscriminator;
 exports.httpMethods = httpMethods;
+exports.isHttpOperationNode = isHttpOperationNode;
 exports.isInputNode = isInputNode;
 exports.isOperationNode = isOperationNode;
 exports.isOutputNode = isOutputNode;
@@ -2375,6 +2419,7 @@ exports.simplifyUnion = simplifyUnion;
 exports.syncOptionality = syncOptionality;
 exports.syncSchemaRef = syncSchemaRef;
 exports.transform = transform;
+exports.update = update;
 exports.walk = walk;
 
 //# sourceMappingURL=index.cjs.map