@kubb/ast 5.9.3 → 5.9.5

package/README.md

@@ -32,15 +32,14 @@ Defines the node tree, visitor pattern, factory functions, and type guards used
 | ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
 | `@kubb/ast`                     | Runtime: node definitions, guards, visitor, macro engine, constants                                               |
 | `ast.factory` (via `@kubb/ast`) | Node constructors (`createSchema`, `createFile`, and friends), the `ts.factory` analogue                          |
-| `@kubb/ast/types`               | Types only: all node interfaces, type aliases, visitor types                                                      |
 | `kubb/kit`                      | Re-exports the `ast` and `factory` namespaces, the way most Kubb code reaches the AST without a direct dependency |
 
-`@kubb/ast` is an internal library. Inside the Kubb ecosystem the whole surface travels on the `ast` namespace from `kubb/kit`, so plugins and generators reach it there instead of depending on this package directly. The examples below import from `@kubb/ast` for clarity; through `kubb/kit` the same calls read as `ast.walk`, `ast.factory.createSchema`, and so on.
+`@kubb/ast` is an internal library. Inside the Kubb ecosystem the whole surface travels on the `ast` namespace from `kubb/kit`, so plugins and generators reach it there instead of depending on this package directly. The examples below import from `@kubb/ast` for clarity; through `kubb/kit` the same calls read as `ast.transform`, `ast.factory.createSchema`, and so on.
 
 ## Node tree
 
 ```
-RootNode
+InputNode
 ├── schemas: SchemaNode[]
 └── operations: OperationNode[]
     ├── parameters: ParameterNode[]   → SchemaNode
@@ -113,7 +112,7 @@ const types = collectSync<string>(root, {
 
 ```ts
 import { narrowSchema } from '@kubb/ast'
-import type { Node } from '@kubb/ast/types'
+import type { Node } from '@kubb/ast'
 
 function process(node: Node) {
   if (node.kind === 'Schema') {
@@ -133,12 +132,11 @@ resolveRefName({ kind: 'Schema', type: 'ref', ref: '#/components/schemas/Pet' })
 
 ## Adding a node
 
-Adding a node touches four files.
+Adding a node touches three files.
 
 1. Define the node type and its `createFoo` function in its own `src/nodes/*.ts` file, and add the kind to `NodeKind` in `src/nodes/base.ts`.
-2. Add the type to the `Node` union in `src/nodes/index.ts` and export it from `src/types.ts`.
-3. Re-export `createFoo` from `src/factory.ts`.
-4. When the node has children or a visitor callback, add it to `VISITOR_KEYS` and `VISITOR_KEY_BY_KIND` in `src/visitor.ts`.
+2. Add the type to the `Node` union and re-export `createFoo` in `src/nodes/index.ts`, and export the type from `src/types.ts`.
+3. When the node has children or a visitor callback, add it to `VISITOR_KEYS` and `VISITOR_KEY_BY_KIND` in `src/visitor.ts`.
 
 ## Supporting Kubb
 

package/dist/index.cjs

@@ -34,10 +34,6 @@ let node_path = require("node:path");
 node_path = __toESM(node_path, 1);
 let node_crypto = require("node:crypto");
 //#region src/constants.ts
-const visitorDepths = {
-	shallow: "shallow",
-	deep: "deep"
-};
 /**
 * Schema type discriminators used by all AST schema nodes.
 *
@@ -205,7 +201,6 @@ const VISITOR_KEYS = {
 /** Visitor callback names in traversal order, the keys of {@link Visitor}. */
 const visitorKeys = [
 	"input",
-	"output",
 	"operation",
 	"schema",
 	"property",
@@ -217,14 +212,12 @@ const visitorKeys = [
 */
 const VISITOR_KEY_BY_KIND = {
 	Input: "input",
-	Output: "output",
 	Operation: "operation",
 	Schema: "schema",
 	Property: "property",
 	Parameter: "parameter",
 	Response: "response"
 };
-const visitorKeysByKind = VISITOR_KEYS;
 /**
 * Returns `true` when `value` is an AST node (an object carrying a `kind`).
 */
@@ -238,14 +231,6 @@ function isNodeRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
-* Returns the child fields of `node` to walk, from {@link VISITOR_KEYS}, or `undefined` when there
-* is nothing to walk. `Schema` children are only walked when `recurse` is `true`.
-*/
-function childKeys(node, recurse) {
-	if (node.kind === "Schema" && !recurse) return void 0;
-	return visitorKeysByKind[node.kind];
-}
-/**
 * Returns the immediate traversable children of `node`.
 *
 * @example
@@ -255,7 +240,7 @@ function childKeys(node, recurse) {
 * ```
 */
 function* getChildren(node, recurse) {
-	const keys = childKeys(node, recurse);
+	const keys = node.kind === "Schema" && !recurse ? void 0 : VISITOR_KEYS[node.kind];
 	if (!keys) return;
 	const record = node;
 	for (const key of keys) {
@@ -314,7 +299,7 @@ function applyVisitor(node, visitor, parent) {
 */
 function transform(node, options) {
 	const { depth, parent, ...visitor } = options;
-	return transformNode(node, visitor, (depth ?? visitorDepths.deep) === visitorDepths.deep, parent);
+	return transformNode(node, visitor, (depth ?? "deep") === "deep", parent);
 }
 /**
 * Visits a single node, then immutably rebuilds its children. Returns the original
@@ -329,7 +314,7 @@ function transformNode(node, visitor, recurse, parent) {
 * (e.g. `additionalProperties: true`) intact.
 */
 function transformChildren(node, visitor, recurse) {
-	const keys = childKeys(node, recurse);
+	const keys = node.kind === "Schema" && !recurse ? void 0 : VISITOR_KEYS[node.kind];
 	if (!keys) return node;
 	const record = node;
 	let updates;
@@ -387,7 +372,7 @@ function transformChildren(node, visitor, recurse) {
 */
 function* collect(node, options) {
 	const { depth, parent, ...visitor } = options;
-	yield* collectNode(node, visitor, (depth ?? visitorDepths.deep) === visitorDepths.deep, parent);
+	yield* collectNode(node, visitor, (depth ?? "deep") === "deep", parent);
 }
 function* collectNode(node, visitor, recurse, parent) {
 	const v = applyVisitor(node, visitor, parent);
@@ -517,18 +502,6 @@ function optionality(schema, required) {
 		nullish: !required && nullable ? true : void 0
 	};
 }
-/**
-* Defaults `required` to `false` and derives the schema's `optional`/`nullish` flags from it.
-* Shared build step of `createProperty` and `createParameter`.
-*/
-function withRequired(props) {
-	const required = props.required ?? false;
-	return {
-		...props,
-		required,
-		schema: optionality(props.schema, required)
-	};
-}
 //#endregion
 //#region src/createPrinter.ts
 /**
@@ -636,6 +609,10 @@ function extractStringsFromNodes(nodes) {
 }
 //#endregion
 //#region src/utils/refs.ts
+/** Returns the last segment of a `$ref` pointer, for example `'Pet'` for `#/components/schemas/Pet`. */
+function refName(ref) {
+	return ref.split("/").at(-1) ?? ref;
+}
 /**
 * Resolves the emitted name of the schema a ref node points at. Prefers `targetName` (set when
 * the referenced schema was renamed, e.g. to break a collision), then the last segment of `ref`,
@@ -652,7 +629,7 @@ function extractStringsFromNodes(nodes) {
 function resolveRefName(node) {
 	if (!node || node.type !== "ref") return null;
 	if (node.targetName) return node.targetName;
-	if (node.ref) return node.ref.split("/").at(-1) ?? node.ref;
+	if (node.ref) return refName(node.ref);
 	return node.name ?? node.schema?.name ?? null;
 }
 /**
@@ -987,6 +964,17 @@ function inferDiscriminatorPropertyName(members) {
 	}
 }
 //#endregion
+//#region src/nodes/base.ts
+/** Builds a `createX` factory for a node whose only computed field is `kind`. */
+function nodeFactory(kind) {
+	return (input) => {
+		return {
+			...input,
+			kind
+		};
+	};
+}
+//#endregion
 //#region src/nodes/code.ts
 /**
 * Creates a `ConstNode` representing a TypeScript `const` declaration.
@@ -997,12 +985,7 @@ function inferDiscriminatorPropertyName(members) {
 * // export const pets: Pet[] = ... as const
 * ```
 */
-function createConst(input) {
-	return {
-		...input,
-		kind: "Const"
-	};
-}
+const createConst = nodeFactory("Const");
 /**
 * Creates a `TypeNode` representing a TypeScript `type` alias declaration.
 *
@@ -1012,12 +995,7 @@ function createConst(input) {
 * // export type Pet = ...
 * ```
 */
-function createType(input) {
-	return {
-		...input,
-		kind: "Type"
-	};
-}
+const createType = nodeFactory("Type");
 /**
 * Creates a `FunctionNode` representing a TypeScript `function` declaration.
 *
@@ -1027,12 +1005,7 @@ function createType(input) {
 * // export async function fetchPet(): Promise<Pet> { ... }
 * ```
 */
-function createFunction(input) {
-	return {
-		...input,
-		kind: "Function"
-	};
-}
+const createFunction = nodeFactory("Function");
 /**
 * Creates an `ArrowFunctionNode` representing a TypeScript arrow function.
 *
@@ -1042,12 +1015,7 @@ function createFunction(input) {
 * // export const double = (n: number) => ...
 * ```
 */
-function createArrowFunction(input) {
-	return {
-		...input,
-		kind: "ArrowFunction"
-	};
-}
+const createArrowFunction = nodeFactory("ArrowFunction");
 /**
 * Creates a {@link TextNode} representing a raw string fragment in the source output.
 *
@@ -1095,12 +1063,7 @@ function createJsx(value) {
 /**
 * Creates a `ContentNode` for a single request-body or response content type.
 */
-function createContent(input) {
-	return {
-		...input,
-		kind: "Content"
-	};
-}
+const createContent = nodeFactory("Content");
 //#endregion
 //#region src/utils/combineFileMembers.ts
 const IDENTIFIER_RUN = /[\w$]+/g;
@@ -1249,12 +1212,7 @@ function combineImports(imports, exports, source) {
 * // import { useState } from 'react'
 * ```
 */
-function createImport(input) {
-	return {
-		...input,
-		kind: "Import"
-	};
-}
+const createImport = nodeFactory("Import");
 /**
 * Creates an `ExportNode` representing a language-agnostic export/public API declaration.
 *
@@ -1264,12 +1222,7 @@ function createImport(input) {
 * // export { Pet } from './Pet'
 * ```
 */
-function createExport(input) {
-	return {
-		...input,
-		kind: "Export"
-	};
-}
+const createExport = nodeFactory("Export");
 /**
 * Creates a `SourceNode` representing a fragment of source code within a file.
 *
@@ -1278,12 +1231,7 @@ function createExport(input) {
 * createSource({ name: 'Pet', nodes: [createText('export type Pet = { id: number }')], isExportable: true })
 * ```
 */
-function createSource(input) {
-	return {
-		...input,
-		kind: "Source"
-	};
-}
+const createSource = nodeFactory("Source");
 /**
 * Creates a fully resolved `FileNode` from a file input descriptor.
 *
@@ -1389,12 +1337,7 @@ function createInput(overrides = {}) {
 /**
 * Creates a `RequestBodyNode`.
 */
-function createRequestBody(input) {
-	return {
-		...input,
-		kind: "RequestBody"
-	};
-}
+const createRequestBody = nodeFactory("RequestBody");
 //#endregion
 //#region src/nodes/operation.ts
 function createOperation(props) {
@@ -1411,28 +1354,10 @@ function createOperation(props) {
 	};
 }
 //#endregion
-//#region src/nodes/output.ts
-/**
-* Creates an `OutputNode` with a stable default for `files`.
-*
-* @example
-* ```ts
-* const output = createOutput()
-* // { kind: 'Output', files: [] }
-* ```
-*/
-function createOutput(overrides = {}) {
-	return {
-		files: [],
-		...overrides,
-		kind: "Output"
-	};
-}
-//#endregion
 //#region src/nodes/parameter.ts
 /**
 * Creates a `ParameterNode`. `required` defaults to `false`, and the schema's
-* `optional`/`nullish` flags are derived from it through {@link withRequired}.
+* `optional`/`nullish` flags are derived from it.
 *
 * @example
 * ```ts
@@ -1445,8 +1370,11 @@ function createOutput(overrides = {}) {
 * ```
 */
 function createParameter(input) {
+	const required = input.required ?? false;
 	return {
-		...withRequired(input),
+		...input,
+		required,
+		schema: optionality(input.schema, required),
 		kind: "Parameter"
 	};
 }
@@ -1454,7 +1382,7 @@ function createParameter(input) {
 //#region src/nodes/property.ts
 /**
 * Creates a `PropertyNode`. `required` defaults to `false`, and the schema's
-* `optional`/`nullish` flags are derived from it through {@link withRequired}.
+* `optional`/`nullish` flags are derived from it.
 *
 * @example
 * ```ts
@@ -1467,8 +1395,11 @@ function createParameter(input) {
 * ```
 */
 function createProperty(input) {
+	const required = input.required ?? false;
 	return {
-		...withRequired(input),
+		...input,
+		required,
+		schema: optionality(input.schema, required),
 		kind: "Property"
 	};
 }
@@ -1540,8 +1471,8 @@ function createSchema(props) {
 	};
 }
 //#endregion
-//#region src/factory.ts
-var factory_exports = /* @__PURE__ */ __exportAll({
+//#region src/nodes/index.ts
+var nodes_exports = /* @__PURE__ */ __exportAll({
 	createArrowFunction: () => createArrowFunction,
 	createBreak: () => createBreak,
 	createConst: () => createConst,
@@ -1553,7 +1484,6 @@ var factory_exports = /* @__PURE__ */ __exportAll({
 	createInput: () => createInput,
 	createJsx: () => createJsx,
 	createOperation: () => createOperation,
-	createOutput: () => createOutput,
 	createParameter: () => createParameter,
 	createProperty: () => createProperty,
 	createRequestBody: () => createRequestBody,
@@ -1561,32 +1491,8 @@ var factory_exports = /* @__PURE__ */ __exportAll({
 	createSchema: () => createSchema,
 	createSource: () => createSource,
 	createText: () => createText,
-	createType: () => createType,
-	update: () => update
+	createType: () => createType
 });
-/**
-* 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 does not allocate and
-* downstream passes can detect "nothing changed" by identity. Comparison is shallow,
-* so a structurally equal but newly allocated array or 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;
-}
 //#endregion
 //#region src/index.ts
 var src_exports = /* @__PURE__ */ __exportAll({
@@ -1601,7 +1507,7 @@ var src_exports = /* @__PURE__ */ __exportAll({
 	createPrinter: () => createPrinter,
 	defineMacro: () => defineMacro,
 	extractStringsFromNodes: () => extractStringsFromNodes,
-	factory: () => factory_exports,
+	factory: () => nodes_exports,
 	findCircularSchemas: () => findCircularSchemas,
 	findCircularSchemasFromGraph: () => findCircularSchemasFromGraph,
 	getSchemaLiteralValues: () => getSchemaLiteralValues,
@@ -1611,6 +1517,7 @@ var src_exports = /* @__PURE__ */ __exportAll({
 	mergeRefWithSchema: () => mergeRefWithSchema,
 	narrowSchema: () => narrowSchema,
 	optionality: () => optionality,
+	refName: () => refName,
 	resolveRefName: () => resolveRefName,
 	resolveSchemaProperties: () => resolveSchemaProperties,
 	schemaTypes: () => schemaTypes,
@@ -1636,7 +1543,7 @@ exports.extractStringsFromNodes = extractStringsFromNodes;
 Object.defineProperty(exports, "factory", {
 	enumerable: true,
 	get: function() {
-		return factory_exports;
+		return nodes_exports;
 	}
 });
 exports.findCircularSchemas = findCircularSchemas;
@@ -1648,6 +1555,7 @@ exports.isHttpOperationNode = isHttpOperationNode;
 exports.mergeRefWithSchema = mergeRefWithSchema;
 exports.narrowSchema = narrowSchema;
 exports.optionality = optionality;
+exports.refName = refName;
 exports.resolveRefName = resolveRefName;
 exports.resolveSchemaProperties = resolveSchemaProperties;
 exports.schemaTypes = schemaTypes;