@kubb/ast 5.0.0-beta.4 → 5.0.0-beta.41

package/src/utils.ts

@@ -1,4 +1,4 @@
-import { camelCase, isValidVarName } from '@internals/utils'
+import { camelCase, isValidVarName, memoize } from '@internals/utils'
 
 import { createFunctionParameter, createFunctionParameters, createParameterGroup, createParamsType, createProperty, createSchema } from './factory.ts'
 import { narrowSchema } from './guards.ts'
@@ -17,7 +17,7 @@ import type {
 } from './nodes/index.ts'
 import type { SchemaType } from './nodes/schema.ts'
 import { extractRefName } from './refs.ts'
-import { collect } from './visitor.ts'
+import { collect, collectLazy } from './visitor.ts'
 
 const plainStringTypes = new Set<SchemaType>(['string', 'uuid', 'email', 'url', 'datetime'] as const)
 
@@ -74,16 +74,18 @@ export function isStringType(node: SchemaNode): boolean {
  * 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.
  */
-export function caseParams(params: Array<ParameterNode>, casing: 'camelcase' | undefined): Array<ParameterNode> {
-  if (!casing) {
-    return params
-  }
+const caseParamsMemo = memoize(new WeakMap<Array<ParameterNode>, (casing: string) => Array<ParameterNode>>(), (params) =>
+  memoize(new Map<string, Array<ParameterNode>>(), (casing: string) =>
+    params.map((param) => {
+      const transformed = casing === 'camelcase' || !isValidVarName(param.name) ? camelCase(param.name) : param.name
+      return { ...param, name: transformed }
+    }),
+  ),
+)
 
-  return params.map((param) => {
-    const transformed = casing === 'camelcase' || !isValidVarName(param.name) ? camelCase(param.name) : param.name
-
-    return { ...param, name: transformed }
-  })
+export function caseParams(params: Array<ParameterNode>, casing: 'camelcase' | undefined): Array<ParameterNode> {
+  if (!casing) return params
+  return caseParamsMemo(params)(casing)
 }
 
 /**
@@ -247,7 +249,7 @@ export type CreateOperationParamsOptions = {
    * Applies a uniform transformation to every resolved type name before it is used
    * in a parameter node. Use this for framework-level type wrappers.
    *
-   * @example Vue Query — wrap every parameter type with `MaybeRefOrGetter`
+   * @example Vue Query, wrap every parameter type with `MaybeRefOrGetter`
    * `typeWrapper: (t) => \`MaybeRefOrGetter<${t}>\``
    */
   typeWrapper?: (type: string) => string
@@ -313,7 +315,7 @@ export function createOperationParams(node: OperationNode, options: CreateOperat
       variant: 'reference',
       name: typeWrapper ? typeWrapper(type) : type,
     })
-  // Only reference-variant TypeNodes are wrapped — they hold a plain type name string that needs casing applied.
+  // Only reference-variant TypeNodes are wrapped, they hold a plain type name string that needs casing applied.
   // Member and struct TypeNodes are pre-resolved structured expressions and are passed through unchanged.
   const wrapTypeNode = (type: ParamsTypeNode): ParamsTypeNode => (type.kind === 'ParamsType' && type.variant === 'reference' ? wrapType(type.name) : type)
 
@@ -392,7 +394,7 @@ export function createOperationParams(node: OperationNode, options: CreateOperat
   } else {
     if (pathParams.length) {
       if (pathParamsType === 'inlineSpread') {
-        const spreadType = resolver?.resolvePathParamsName(node, pathParams[0]!) ?? undefined
+        const spreadType = resolver?.resolvePathParamsName(node, pathParams[0]!)
         params.push(
           createFunctionParameter({
             name: pathName,
@@ -474,7 +476,7 @@ function buildGroupParam({
   name: string
   node: OperationNode
   params: Array<ParameterNode>
-  groupType: ParamGroupType | undefined
+  groupType: ParamGroupType | null | undefined
   resolver: OperationParamsResolver | undefined
   wrapType: (type: string) => ParamsTypeNode
 }): Array<FunctionParameterNode> {
@@ -496,7 +498,7 @@ function buildGroupParam({
 
 /**
  * Derives a {@link ParamGroupType} from the resolver's group method.
- * Returns `undefined` when the group name equals the individual param name (no real group).
+ * Returns `null` when the group name equals the individual param name (no real group).
  */
 function resolveGroupType({
   node,
@@ -508,14 +510,14 @@ function resolveGroupType({
   params: Array<ParameterNode>
   groupMethod: (_node: OperationNode, _param: ParameterNode) => string
   resolver: OperationParamsResolver
-}): ParamGroupType | undefined {
+}): ParamGroupType | null {
   if (!params.length) {
-    return undefined
+    return null
   }
   const firstParam = params[0]!
   const groupName = groupMethod.call(resolver, node, firstParam)
   if (groupName === resolver.resolveParamName(node, firstParam)) {
-    return undefined
+    return null
   }
   const allOptional = params.every((p) => !p.required)
   return {
@@ -554,23 +556,23 @@ function sourceKey(source: SourceNode): string {
   return `${nameKey}:${source.isExportable ?? false}:${source.isTypeOnly ?? false}`
 }
 
-function pathTypeKey(path: string, isTypeOnly: boolean | undefined): string {
+function pathTypeKey(path: string, isTypeOnly: boolean | null | undefined): string {
   return `${path}:${isTypeOnly ?? false}`
 }
 
-function exportKey(path: string, name: string | undefined, isTypeOnly: boolean | undefined, asAlias: boolean | undefined): string {
+function exportKey(path: string, name: string | null | undefined, isTypeOnly: boolean | null | undefined, asAlias: boolean | null | undefined): string {
   return `${path}:${name ?? ''}:${isTypeOnly ?? false}:${asAlias ?? ''}`
 }
 
-function importKey(path: string, name: string | undefined, isTypeOnly: boolean | undefined): string {
+function importKey(path: string, name: string | null | undefined, isTypeOnly: boolean | null | undefined): string {
   return `${path}:${name ?? ''}:${isTypeOnly ?? false}`
 }
 
 /**
  * Computes a multi-level sort key for exports and imports:
- * non-array names first (wildcards/namespace aliases); type-only before value; alphabetical path; unnamed before named.
+ * non-array names first (wildcards/namespace aliases). Type-only before value. Alphabetical path. Unnamed before named.
  */
-function sortKey(node: { name?: string | Array<unknown>; isTypeOnly?: boolean; path: string }): string {
+function sortKey(node: { name?: string | Array<unknown> | null; isTypeOnly?: boolean | null; path: string }): string {
   const isArray = Array.isArray(node.name) ? '1' : '0'
   const typeOnly = node.isTypeOnly ? '0' : '1'
   const hasName = node.name != null ? '1' : '0'
@@ -592,6 +594,17 @@ export function combineSources(sources: Array<SourceNode>): Array<SourceNode> {
   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<TName>(existing: Array<TName>, incoming: Array<TName>): Array<TName> {
+  const merged = new Set(existing)
+  for (const name of incoming) merged.add(name)
+  return [...merged]
+}
+
 /**
  * Deduplicates and merges `ExportNode` objects by path and type.
  *
@@ -605,7 +618,7 @@ export function combineExports(exports: Array<ExportNode>): Array<ExportNode> {
   // Deduplicates non-array exports by their exact identity
   const seen = new Set<string>()
 
-  // Precompute sort keys once — avoids recomputing per comparison.
+  // Precompute sort keys once, avoids recomputing per comparison.
   const keyed = exports.map((node) => ({ node, key: sortKey(node) }))
   keyed.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
 
@@ -619,9 +632,7 @@ export function combineExports(exports: Array<ExportNode>): Array<ExportNode> {
       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]
+        existing.name = mergeNameArrays(existing.name, name)
       } else {
         const newItem: ExportNode = { ...curr, name: [...new Set(name)] }
         result.push(newItem)
@@ -653,7 +664,7 @@ export function combineImports(imports: Array<ImportNode>, exports: Array<Export
   const isUsed = (importName: string): boolean => !source || source.includes(importName) || exportedNames.has(importName)
 
   // Memoize object import names so the same logical (propertyName, name) pair always
-  // reuses the same object reference — Set-based deduplication then works correctly.
+  // reuses the same object reference. Set-based deduplication then works correctly.
   const importNameMemo = new Map<string, { propertyName: string; name?: string }>()
   const canonicalizeName = (n: string | { propertyName: string; name?: string }): string | { propertyName: string; name?: string } => {
     if (typeof n === 'string') return n
@@ -662,13 +673,24 @@ export function combineImports(imports: Array<ImportNode>, exports: Array<Export
     return importNameMemo.get(key)!
   }
 
+  // Paths that keep at least one used named import. A default import from such a path is retained
+  // even when its binding can't be found in `source` e.g. a generated `client` default import
+  // alongside `import type { Client } from <same path>`, where merged grouped output omits the body.
+  const pathsWithUsedNamedImport = new Set<string>()
+  for (const node of imports) {
+    if (!Array.isArray(node.name)) continue
+    if (node.name.some((item) => (typeof item === 'string' ? isUsed(item) : isUsed(item.name ?? item.propertyName)))) {
+      pathsWithUsedNamedImport.add(node.path)
+    }
+  }
+
   const result: Array<ImportNode> = []
   // Accumulates array-named imports keyed by `path:isTypeOnly` for name-merging
   const namedByPath = new Map<string, ImportNode>()
   // Deduplicates non-array imports by their exact identity
   const seen = new Set<string>()
 
-  // Precompute sort keys once — avoids recomputing per comparison.
+  // Precompute sort keys once, avoids recomputing per comparison.
   const keyed = imports.map((node) => ({ node, key: sortKey(node) }))
   keyed.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
 
@@ -686,16 +708,14 @@ export function combineImports(imports: Array<ImportNode>, exports: Array<Export
       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]
+        existing.name = mergeNameArrays(existing.name, name)
       } else {
         const newItem: ImportNode = { ...curr, name }
         result.push(newItem)
         namedByPath.set(key, newItem)
       }
     } else {
-      if (name && !isUsed(name)) continue
+      if (name && !isUsed(name) && !pathsWithUsedNamedImport.has(path)) continue
 
       const key = importKey(path, name, isTypeOnly)
       if (!seen.has(key)) {
@@ -723,13 +743,18 @@ export function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): str
       if (node.kind === 'Text') return node.value
       if (node.kind === 'Break') return ''
       if (node.kind === 'Jsx') return node.value
-      const parts: string[] = []
+
+      const parts: Array<string> = []
+
       if ('params' in node && node.params) parts.push(node.params)
       if ('generics' in node && node.generics) parts.push(Array.isArray(node.generics) ? node.generics.join(', ') : node.generics)
       if ('returnType' in node && node.returnType) parts.push(node.returnType)
       if ('type' in node && typeof node.type === 'string') parts.push(node.type)
+
       const nested = extractStringsFromNodes(node.nodes)
+
       if (nested) parts.push(nested)
+
       return parts.join('\n')
     })
     .filter(Boolean)
@@ -739,7 +764,7 @@ export function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): str
 /**
  * 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
+ * Returns `null` 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
@@ -748,17 +773,17 @@ export function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): str
  * // => 'Pet'
  * ```
  */
-export function resolveRefName(node: SchemaNode | undefined): string | undefined {
-  if (!node || node.type !== 'ref') return undefined
-  if (node.ref) return extractRefName(node.ref) ?? node.name ?? node.schema?.name ?? undefined
+export function resolveRefName(node: SchemaNode | undefined): string | null {
+  if (!node || node.type !== 'ref') return null
+  if (node.ref) return extractRefName(node.ref) ?? node.name ?? node.schema?.name ?? null
 
-  return node.name ?? node.schema?.name ?? undefined
+  return node.name ?? node.schema?.name ?? null
 }
 
 /**
  * Collects every named schema referenced (transitively) from a node via ref edges.
  *
- * Refs are followed by name only — the resolved `node.schema` is not traversed inline.
+ * 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.
  *
  * @example Collect refs from a single schema
@@ -775,18 +800,22 @@ export function resolveRefName(node: SchemaNode | undefined): string | undefined
  * }
  * ```
  */
-export function collectReferencedSchemaNames(node: SchemaNode | undefined, out: Set<string> = new Set()): Set<string> {
-  if (!node) return out
+const collectSchemaRefs = memoize(new WeakMap<SchemaNode, ReadonlySet<string>>(), (node: SchemaNode): ReadonlySet<string> => {
+  const refs = new Set<string>()
   collect<void>(node, {
     schema(child) {
       if (child.type === 'ref') {
         const name = resolveRefName(child)
-
-        if (name) out.add(name)
+        if (name) refs.add(name)
       }
-      return undefined
     },
   })
+  return refs
+})
+
+export function collectReferencedSchemaNames(node: SchemaNode | undefined, out: Set<string> = new Set()): Set<string> {
+  if (!node) return out
+  for (const name of collectSchemaRefs(node)) out.add(name)
   return out
 }
 
@@ -794,7 +823,7 @@ export function collectReferencedSchemaNames(node: SchemaNode | undefined, out:
  * Collects the names of all top-level schemas transitively used by a set of operations.
  *
  * An operation uses a schema when any of its parameters, request body content, or responses
- * reference it — directly or indirectly through other named schemas.
+ * reference it, directly or indirectly through other named schemas.
  * The walk is iterative and safe against reference cycles.
  *
  * Use this together with `include` filters to determine which schemas from `components/schemas`
@@ -803,10 +832,10 @@ export function collectReferencedSchemaNames(node: SchemaNode | undefined, out:
  *
  * @example Only generate schemas referenced by included operations
  * ```ts
- * const includedOps = inputNode.operations.filter(op => resolver.resolveOptions(op, { options, include }) !== null)
- * const allowed = collectUsedSchemaNames(includedOps, inputNode.schemas)
+ * const includedOps = operations.filter(op => resolver.resolveOptions(op, { options, include }) !== null)
+ * const allowed = collectUsedSchemaNames(includedOps, schemas)
  *
- * for (const schema of inputNode.schemas) {
+ * for (const schema of schemas) {
  *   if (schema.name && !allowed.has(schema.name)) continue
  *   // … generate schema
  * }
@@ -814,16 +843,18 @@ export function collectReferencedSchemaNames(node: SchemaNode | undefined, out:
  *
  * @example Check whether a specific schema is needed
  * ```ts
- * const allowed = collectUsedSchemaNames(includedOps, inputNode.schemas)
+ * const allowed = collectUsedSchemaNames(includedOps, schemas)
  * allowed.has('OrderStatus') // false when no included operation references OrderStatus
  * ```
  */
-export function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string> {
+const collectUsedSchemaNamesMemo = memoize(new WeakMap<ReadonlyArray<OperationNode>, (schemas: ReadonlyArray<SchemaNode>) => Set<string>>(), (ops) =>
+  memoize(new WeakMap<ReadonlyArray<SchemaNode>, Set<string>>(), (schemas) => computeUsedSchemaNames(ops, schemas)),
+)
+
+function computeUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string> {
   const schemaMap = new Map<string, SchemaNode>()
   for (const schema of schemas) {
-    if (schema.name) {
-      schemaMap.set(schema.name, schema)
-    }
+    if (schema.name) schemaMap.set(schema.name, schema)
   }
 
   const result = new Set<string>()
@@ -834,15 +865,13 @@ export function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>,
       if (!result.has(name)) {
         result.add(name)
         const namedSchema = schemaMap.get(name)
-        if (namedSchema) {
-          visitSchema(namedSchema)
-        }
+        if (namedSchema) visitSchema(namedSchema)
       }
     }
   }
 
   for (const op of operations) {
-    for (const schema of collect<SchemaNode>(op, { depth: 'shallow', schema: (node) => node })) {
+    for (const schema of collectLazy<SchemaNode>(op, { depth: 'shallow', schema: (node) => node })) {
       visitSchema(schema)
     }
   }
@@ -850,16 +879,13 @@ export function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>,
   return result
 }
 
-/**
- * Identifies all schemas that participate in circular dependency chains, including direct self-loops.
- *
- * 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.
- *
- * @note Call this once on the full schema graph, then use `containsCircularRef()` to check individual schemas.
- */
-export function findCircularSchemas(schemas: ReadonlyArray<SchemaNode>): Set<string> {
+export function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string> {
+  return collectUsedSchemaNamesMemo(operations)(schemas)
+}
+
+const EMPTY_CIRCULAR_SET = new Set<string>()
+
+const findCircularSchemasMemo = memoize(new WeakMap<ReadonlyArray<SchemaNode>, Set<string>>(), (schemas: ReadonlyArray<SchemaNode>): Set<string> => {
   const graph = new Map<string, Set<string>>()
 
   for (const schema of schemas) {
@@ -870,7 +896,7 @@ export function findCircularSchemas(schemas: ReadonlyArray<SchemaNode>): Set<str
   const circular = new Set<string>()
   for (const start of graph.keys()) {
     const visited = new Set<string>()
-    const stack: string[] = [...(graph.get(start) ?? [])]
+    const stack: Array<string> = [...(graph.get(start) ?? [])]
     while (stack.length > 0) {
       const node = stack.pop()!
       if (node === start) {
@@ -886,6 +912,20 @@ export function findCircularSchemas(schemas: ReadonlyArray<SchemaNode>): Set<str
   }
 
   return circular
+})
+
+/**
+ * Identifies all schemas that participate in circular dependency chains, including direct self-loops.
+ *
+ * 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.
+ *
+ * @note Call this once on the full schema graph, then use `containsCircularRef()` to check individual schemas.
+ */
+export function findCircularSchemas(schemas: ReadonlyArray<SchemaNode>): Set<string> {
+  if (schemas.length === 0) return EMPTY_CIRCULAR_SET
+  return findCircularSchemasMemo(schemas)
 }
 
 /**
@@ -894,7 +934,7 @@ export function findCircularSchemas(schemas: ReadonlyArray<SchemaNode>): Set<str
  * 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.
  *
- * @note Returns `true` for the first matching circular ref found; use for fast dependency checks.
+ * @note Returns `true` for the first matching circular ref found. Use for fast dependency checks.
  */
 export function containsCircularRef(
   node: SchemaNode | undefined,
@@ -902,14 +942,15 @@ export function containsCircularRef(
 ): boolean {
   if (!node || circularSchemas.size === 0) return false
 
-  const matches = collect<true>(node, {
+  for (const _ of collectLazy<true>(node, {
     schema(child) {
-      if (child.type !== 'ref') return undefined
+      if (child.type !== 'ref') return null
       const name = resolveRefName(child)
-
-      return name && name !== excludeName && circularSchemas.has(name) ? true : undefined
+      return name && name !== excludeName && circularSchemas.has(name) ? true : null
     },
-  })
+  })) {
+    return true
+  }
 
-  return matches.length > 0
+  return false
 }