@kubb/ast 5.0.0-alpha.73 → 5.0.0-alpha.74

package/dist/index.cjs

@@ -49,15 +49,11 @@ const nodeKinds = {
 	break: "Break"
 };
 /**
-* Canonical schema type strings used by AST schema nodes.
+* Schema type discriminators used by all AST schema nodes.
 *
-* These values are used across the AST as stable discriminators
-* (for example `schema.type === schemaTypes.object`).
-*
-* The map is grouped by intent:
-* - primitives (`string`, `number`, `boolean`, ...)
-* - structural/composite (`object`, `array`, `union`, ...)
-* - special OpenAPI-oriented types (`ref`, `datetime`, `uuid`, ...)
+* These values serve as stable discriminators across the AST (e.g., `schema.type === schemaTypes.object`).
+* Grouped by category: primitives (`string`, `number`, `boolean`), structural types (`object`, `array`, `union`),
+* and format-specific types (`date`, `uuid`, `email`). Use `isScalarPrimitive()` to check for scalar types.
 */
 const schemaTypes = {
 	/**
@@ -166,7 +162,9 @@ const schemaTypes = {
 	never: "never"
 };
 /**
-* Primitive scalar schema types used when simplifying union members.
+* Scalar primitive schema types used for union simplification and type narrowing.
+*
+* Use `isScalarPrimitive()` to safely check whether a type is a scalar primitive.
 */
 const SCALAR_PRIMITIVE_TYPES = new Set([
 	"string",
@@ -176,11 +174,18 @@ const SCALAR_PRIMITIVE_TYPES = new Set([
 	"boolean"
 ]);
 /**
-* Returns `true` when `type` is a scalar primitive schema type.
+* Type guard that returns `true` when `type` is a scalar primitive schema type.
+*
+* Use this to check if a schema type can be directly assigned without wrapping (e.g., `string | number | boolean`).
 */
 function isScalarPrimitive(type) {
 	return SCALAR_PRIMITIVE_TYPES.has(type);
 }
+/**
+* HTTP method identifiers used by operation nodes.
+*
+* Includes all standard HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE).
+*/
 const httpMethods = {
 	get: "GET",
 	post: "POST",
@@ -191,6 +196,12 @@ const httpMethods = {
 	options: "OPTIONS",
 	trace: "TRACE"
 };
+/**
+* Common MIME types used in request/response content negotiation.
+*
+* Covers JSON, XML, form data, PDFs, images, audio, and video formats.
+* Use these as keys when serializing request/response bodies.
+*/
 const mediaTypes = {
 	applicationJson: "application/json",
 	applicationXml: "application/xml",
@@ -788,13 +799,17 @@ const plainStringTypes = new Set([
 	"datetime"
 ]);
 /**
-* Returns a merged schema view for a ref node, combining the resolved `node.schema`
-* (base from the referenced definition) with any usage-site sibling fields set directly
-* on the ref node (description, readOnly, nullable, deprecated, etc.).
+* Merges a ref node with its resolved schema, giving usage-site fields precedence.
 *
-* Usage-site fields take precedence over the resolved schema's own fields when both are defined.
+* Usage-site fields (`description`, `readOnly`, `nullable`, `deprecated`) on the ref node
+* override the same fields in the resolved `node.schema`. Non-ref nodes are returned unchanged.
 *
-* For non-ref nodes the node itself is returned unchanged.
+* @example
+* ```ts
+* // Ref with description override
+* const ref = createSchema({ type: 'ref', ref: '#/components/schemas/Pet', description: 'A cute pet' })
+* const merged = syncSchemaRef(ref)  // merges with resolved Pet schema
+* ```
 */
 function syncSchemaRef(node) {
 	const ref = narrowSchema(node, "ref");
@@ -808,16 +823,10 @@ function syncSchemaRef(node) {
 	});
 }
 /**
-* Returns `true` when a schema is emitted as a plain `string` type.
-*
-* - `string`, `uuid`, `email`, `url`, `datetime` are always plain strings.
-* - `date` and `time` are plain strings when their `representation` is `'string'` rather than `'date'`.
+* Type guard that returns `true` when a schema emits as a plain `string` type.
 *
-* @example
-* ```ts
-* isStringType(createSchema({ type: 'uuid' }))                          // true
-* isStringType(createSchema({ type: 'date', representation: 'date' }))  // false
-* ```
+* Covers `string`, `uuid`, `email`, `url`, and `datetime` types. For `date` and `time`
+* types, returns `true` only when `representation` is `'string'` rather than `'date'`.
 */
 function isStringType(node) {
 	if (plainStringTypes.has(node.type)) return true;
@@ -828,19 +837,9 @@ function isStringType(node) {
 /**
 * Applies casing rules to parameter names and returns a new parameter array.
 *
-* The input array is not mutated.
-* If `casing` is not set, the original array is returned unchanged.
-*
-* Use this before passing parameters to schema builders so that property keys
-* in generated output match the desired casing while preserving
-* `OperationNode.parameters` for other consumers.
-*
-* @example
-* ```ts
-* const params = [createParameter({ name: 'pet_id', in: 'query', schema: createSchema({ type: 'string' }) })]
-* const cased = caseParams(params, 'camelcase')
-* // cased[0].name === 'petId'
-* ```
+* Use this before passing parameters to schema builders so output property keys match
+* the desired casing while preserving `OperationNode.parameters` for other consumers.
+* The input array is not mutated. When `casing` is not set, the original array is returned unchanged.
 */
 function caseParams(params, casing) {
 	if (!casing) return params;
@@ -900,20 +899,12 @@ function resolveParamsType({ node, param, resolver }) {
 	});
 }
 /**
-* Converts an {@link OperationNode} into a {@link FunctionParametersNode}.
-*
-* Centralizes the per-plugin `getParams()` pattern. Provide a `resolver` for
-* type resolution and `extraParams` for plugin-specific trailing parameters.
+* Converts an `OperationNode` into function parameters for code generation.
 *
-* @example
-* ```ts
-* const params = createOperationParams(node, {
-*   paramsType: 'inline',
-*   pathParamsType: 'inline',
-*   resolver: tsResolver,
-*   extraParams: [createFunctionParameter({ name: 'options', type: createParamsType({ variant: 'reference', name: 'Partial<RequestOptions>' }), default: '{}' })],
-* })
-* ```
+* Centralizes parameter grouping logic for all plugins. Provide a `resolver` for type name resolution
+* and `extraParams` for plugin-specific trailing parameters (e.g., `options` objects).
+* Supports three grouping modes: `object` (single destructured param), `inline` (separate params),
+* and `inlineSpread` (rest parameter). Use `CreateOperationParamsOptions` to fine-tune output.
 */
 function createOperationParams(node, options) {
 	const { paramsType, pathParamsType, paramsCasing, resolver, pathParamsDefault, extraParams = [], paramNames, typeWrapper } = options;
@@ -1123,9 +1114,9 @@ function sortKey(node) {
 	return `${isArray}:${typeOnly}:${node.path}:${hasName}:${name}`;
 }
 /**
-* Deduplicates an array of `SourceNode` objects.
-* Named sources are deduplicated by `name + isExportable + isTypeOnly`.
-* Unnamed sources are deduplicated by object reference.
+* Deduplicates and merges `SourceNode` objects by `name + isExportable + isTypeOnly`.
+*
+* Unnamed sources are deduplicated by object reference. Returns a deduplicated array in original order.
 */
 function combineSources(sources) {
 	const seen = /* @__PURE__ */ new Map();
@@ -1136,8 +1127,10 @@ function combineSources(sources) {
 	return [...seen.values()];
 }
 /**
-* Deduplicates and merges an array of `ExportNode` objects.
-* Exports with the same path and `isTypeOnly` flag have their names 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.
+* Non-array exports are deduplicated by exact identity. Returns a sorted, deduplicated array.
 */
 function combineExports(exports) {
 	const result = [];
@@ -1177,9 +1170,12 @@ function combineExports(exports) {
 	return result;
 }
 /**
-* Deduplicates and merges an array of `ImportNode` objects.
-* Filters out unused imports (names not referenced in `source` or re-exported).
-* Imports with the same path and `isTypeOnly` flag have their names merged.
+* Deduplicates and merges `ImportNode` objects, filtering out unused imports.
+*
+* Retains imports that are referenced in `source` or re-exported. Imports with the same path and
+* `isTypeOnly` flag have their names merged. Returns a sorted, deduplicated, filtered array.
+*
+* @note Use this when combining imports from multiple files to avoid duplicate declarations.
 */
 function combineImports(imports, exports, source) {
 	const exportedNames = new Set(exports.flatMap((e) => Array.isArray(e.name) ? e.name : e.name ? [e.name] : []));
@@ -1225,11 +1221,10 @@ function combineImports(imports, exports, source) {
 	return result;
 }
 /**
-* Recursively extracts all string content embedded in a {@link CodeNode} tree.
+* Extracts all string content from a `CodeNode` tree recursively.
 *
-* Includes text node values, and string attribute fields (`params`, `generics`,
-* `returnType`, `type`) that may reference identifiers needing imports.
-* Used by `createFile` to build the full source string for import filtering.
+* Collects text node values, identifier references in string fields (`params`, `generics`, `returnType`, `type`),
+* and nested node content. Used internally to build the full source string for import filtering.
 */
 function extractStringsFromNodes(nodes) {
 	if (!nodes?.length) return "";
@@ -1249,9 +1244,10 @@ function extractStringsFromNodes(nodes) {
 	}).filter(Boolean).join("\n");
 }
 /**
-* Resolves the referenced schema name of a `ref` node, falling back through
-* `ref` → `name` → nested `schema.name`. Returns `undefined` for non-ref
-* nodes or when no name can be resolved.
+* Resolves the schema name of a ref node, falling back through `ref` → `name` → nested `schema.name`.
+*
+* Returns `undefined` for non-ref nodes or when no name can be resolved. Use this to get a schema's
+* identifier for type definitions or error messages.
 *
 * @example
 * ```ts
@@ -1265,15 +1261,12 @@ function resolveRefName(node) {
 	return node.name ?? node.schema?.name ?? void 0;
 }
 /**
-* Recursively collects every named schema referenced (transitively) from
-* `node` via `ref` edges. Refs are followed by name only — the resolved
-* `node.schema` of a ref is not traversed inline.
+* Collects every named schema referenced (transitively) from a node via ref edges.
 *
-* @example
-* ```ts
-* const refs = collectReferencedSchemaNames(petSchema)
-* // => Set { 'Cat', 'Dog' }
-* ```
+* Refs are followed by name only — the resolved `node.schema` is not traversed inline.
+* Use this to determine schema dependencies, build reference graphs, or detect what schemas need to be emitted.
+*
+* @note Returns a Set of schema names for efficient membership testing.
 */
 function collectReferencedSchemaNames(node, out = /* @__PURE__ */ new Set()) {
 	if (!node) return out;
@@ -1286,26 +1279,13 @@ function collectReferencedSchemaNames(node, out = /* @__PURE__ */ new Set()) {
 	return out;
 }
 /**
-* Identifies every named schema that participates in a circular dependency
-* chain — including direct self-loops (e.g. `TreeNode → TreeNode`) and indirect
-* cycles spanning multiple schemas (e.g. `Pet → Cat → Pet`).
-*
-* The returned set contains schema names. Plugins that translate schemas into
-* a host language can use this to wrap recursive positions in a deferred
-* construct (lazy getter, `z.lazy(() => …)`, etc.) and avoid runtime stack
-* overflows when the generated code is executed.
+* Identifies all schemas that participate in circular dependency chains, including direct self-loops.
 *
-* Refs are followed by name only — `node.schema` (the resolved referent) is
-* not traversed inline, which keeps the algorithm linear in the size of the
-* schema graph.
+* Returns a Set of schema names with circular dependencies. Use this to wrap recursive schema positions
+* in deferred constructs (lazy getter, `z.lazy(() => …)`) to prevent infinite recursion when generated code runs.
+* Refs are followed by name only, keeping the algorithm linear in the schema graph size.
 *
-* @example
-* ```ts
-* const circular = findCircularSchemas(inputNode.schemas)
-* if (circular.has('Pet')) {
-*   // emit lazy wrapper for any property whose schema references Pet
-* }
-* ```
+* @note Call this once on the full schema graph, then use `containsCircularRef()` to check individual schemas.
 */
 function findCircularSchemas(schemas) {
 	const graph = /* @__PURE__ */ new Map();
@@ -1332,21 +1312,12 @@ function findCircularSchemas(schemas) {
 	return circular;
 }
 /**
-* Returns true when `node` (or anything nested within it) carries a `ref`
-* whose resolved name belongs to `circularSchemas`.
+* Type guard returning `true` when a schema or anything nested within it contains a ref to a circular schema.
 *
-* When `excludeName` is provided, refs to that name are ignored — useful
-* when self-references are already handled separately from cross-schema
-* cycles (e.g. the faker plugin emits `undefined as any` for direct
-* self-recursion but a lazy getter for indirect cycles).
+* Use `excludeName` to ignore refs to specific schemas (useful when self-references are handled separately).
+* Commonly used with `findCircularSchemas()` to detect where lazy wrappers are needed in code generation.
 *
-* @example
-* ```ts
-* const circular = findCircularSchemas(schemas)
-* if (containsCircularRef(property.schema, { circularSchemas: circular, excludeName: 'Pet' })) {
-*   // emit `get foo() { return fakeCat() }` instead of eager call
-* }
-* ```
+* @note Returns `true` for the first matching circular ref found; use for fast dependency checks.
 */
 function containsCircularRef(node, { circularSchemas, excludeName }) {
 	if (!node || circularSchemas.size === 0) return false;