@kubb/ast 5.0.0-beta.3 → 5.0.0-beta.31

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)
 }
 
 /**
@@ -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,15 +556,15 @@ 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}`
 }
 
@@ -570,7 +572,7 @@ function importKey(path: string, name: string | undefined, isTypeOnly: boolean |
  * 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.
  */
-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.
  *
@@ -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)
@@ -662,6 +673,17 @@ 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>()
@@ -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,11 +773,11 @@ 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
 }
 
 /**
@@ -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
 }
 
@@ -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)
 }
 
 /**
@@ -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
 }