chore: wip

Author: glennmichael123

bun.lock

@@ -1,6 +1,6 @@
 # API Documentation
 
-> Generated on 2026-02-10T03:49:37.841Z
+> Generated on 2026-02-10T12:25:12.486Z
 
 ## Table of Contents
 

packages/dtsx/.test-cli/docs-test/api-docs/API.md

@@ -24,16 +24,15 @@ export function extractDeclarations(
   const contentHash = hashContent(sourceCode)
   const cacheKey = `${filePath}:${keepComments ? 1 : 0}:${isolatedDeclarations ? 1 : 0}`
   const cached = declarationCache.get(cacheKey)
-  const now = Date.now()
 
   if (cached && cached.contentHash === contentHash) {
-    cached.lastAccess = now
+    cached.lastAccess = Date.now()
     return cached.declarations
   }
 
   const declarations = scanDeclarations(sourceCode, filePath, keepComments, isolatedDeclarations)
 
-  declarationCache.set(cacheKey, { declarations, contentHash, lastAccess: now })
+  declarationCache.set(cacheKey, { declarations, contentHash, lastAccess: Date.now() })
 
   if (declarationCache.size > MAX_DECLARATION_CACHE_SIZE) {
     let oldestKey: string | null = null

packages/dtsx/src/extractor/extract.ts

@@ -888,6 +888,43 @@ export function scanDeclarations(source: string, filename: string, keepComments:
     if (!inner)
       return '()'
 
+    // Fast path: if params are already in DTS-safe form, return as-is
+    // Requirements: no newlines in raw string, all params typed (have ':'), no destructuring/defaults/decorators/rest/modifiers
+    if (rawParams.indexOf('\n') === -1 && inner.indexOf(':') !== -1
+      && inner.indexOf('{') === -1 && inner.indexOf('[') === -1 && inner.indexOf('=') === -1
+      && inner.indexOf('@') === -1 && inner.indexOf('...') === -1) {
+      // Verify every param has a type annotation: count colons at depth 0 vs commas at depth 0
+      let colons = 0
+      let commas = 0
+      let depth = 0
+      for (let fi = 0; fi < inner.length; fi++) {
+        const fc = inner.charCodeAt(fi)
+        if (fc === CH_LPAREN || fc === CH_LANGLE || fc === CH_LBRACE) depth++
+        else if (fc === CH_RPAREN || fc === CH_RANGLE || fc === CH_RBRACE) depth--
+        else if (depth === 0) {
+          if (fc === CH_COLON) colons++
+          else if (fc === CH_COMMA) commas++
+        }
+      }
+      // Every param needs at least one colon (commas + 1 params)
+      if (colons >= commas + 1) {
+        let hasModifier = false
+        for (let m = 0; m < PARAM_MODIFIERS.length; m++) {
+          const mod = PARAM_MODIFIERS[m]
+          const modIdx = inner.indexOf(mod)
+          if (modIdx !== -1) {
+            const afterIdx = modIdx + mod.length
+            if ((modIdx === 0 || !isIdentChar(inner.charCodeAt(modIdx - 1)))
+              && (afterIdx >= inner.length || !isIdentChar(inner.charCodeAt(afterIdx)))) {
+              hasModifier = true
+              break
+            }
+          }
+        }
+        if (!hasModifier) return rawParams
+      }
+    }
+
     // Split parameters by comma at depth 0
     const params: string[] = []
     let paramStart = 0
@@ -1313,7 +1350,7 @@ export function scanDeclarations(source: string, filename: string, keepComments:
 
     // Build DTS text
     const dtsParams = buildDtsParams(rawParams)
-    const text = (isExported ? 'export ' : '') + 'declare function ' + (name || 'default') + generics + dtsParams + ': ' + returnType + ';'
+    const text = `${isExported ? 'export ' : ''}declare function ${name || 'default'}${generics}${dtsParams}: ${returnType};`
     const comments = extractLeadingComments(declStart)
 
     // Record index if this function had a body (implementation signature for overloads)
@@ -1510,7 +1547,7 @@ export function scanDeclarations(source: string, filename: string, keepComments:
     const body = cleanBraceBlock(rawBody)
 
     // Build DTS text
-    const text = (isExported ? 'export ' : '') + 'declare interface ' + name + generics + (extendsClause ? ' extends ' + extendsClause : '') + ' ' + body
+    const text = `${isExported ? 'export ' : ''}declare interface ${name}${generics}${extendsClause ? ` extends ${extendsClause}` : ''} ${body}`
     const comments = extractLeadingComments(declStart)
 
     return {
@@ -1567,7 +1604,7 @@ export function scanDeclarations(source: string, filename: string, keepComments:
       pos++
 
     // Build DTS text
-    const text = (isExported ? 'export ' : '') + 'type ' + name + generics + ' = ' + typeBody
+    const text = `${isExported ? 'export ' : ''}type ${name}${generics} = ${typeBody}`
     const comments = extractLeadingComments(declStart)
 
     return {
@@ -1681,7 +1718,7 @@ export function scanDeclarations(source: string, filename: string, keepComments:
     const classBody = buildClassBodyDts()
 
     // Build DTS text
-    const text = (isExported ? 'export ' : '') + 'declare ' + (isAbstract ? 'abstract ' : '') + 'class ' + name + generics + (extendsClause ? ' extends ' + extendsClause : '') + (implementsList && implementsList.length > 0 ? ' implements ' + implementsList.join(', ') : '') + ' ' + classBody
+    const text = `${isExported ? 'export ' : ''}declare ${isAbstract ? 'abstract ' : ''}class ${name}${generics}${extendsClause ? ` extends ${extendsClause}` : ''}${implementsList && implementsList.length > 0 ? ` implements ${implementsList.join(', ')}` : ''} ${classBody}`
     const comments = extractLeadingComments(declStart)
 
     return {
@@ -2484,7 +2521,7 @@ export function scanDeclarations(source: string, filename: string, keepComments:
     const body = pos < len && source.charCodeAt(pos) === CH_LBRACE ? buildNamespaceBodyDts() : '{}'
 
     // Build DTS text
-    const text = (isExported ? 'export ' : '') + 'declare ' + keyword + ' ' + name + ' ' + body
+    const text = `${isExported ? 'export ' : ''}declare ${keyword} ${name} ${body}`
     const comments = extractLeadingComments(declStart)
     const isAmbient = name.startsWith('\'') || name.startsWith('"')
 
@@ -3066,24 +3103,29 @@ function resolveReferencedTypes(declarations: Declaration[], nonExportedTypes: M
   const declNames = new Set<string>()
   for (const d of declarations) declNames.add(d.name)
 
-  // Build initial combined text once (excluding imports)
-  const combinedParts: string[] = []
+  // Keep declaration texts as an array — search each part individually (avoids giant join allocation)
+  const textParts: string[] = []
   for (let i = 0; i < declarations.length; i++) {
     if (declarations[i].kind !== 'import') {
-      combinedParts.push(declarations[i].text)
+      textParts.push(declarations[i].text)
     }
   }
-  let combinedText = combinedParts.length > 1
-    ? combinedParts.join('\n')
-    : (combinedParts[0] || '')
 
   for (;;) {
     // Collect referenced non-exported types not yet resolved
     const toInsert: Declaration[] = []
     for (const [name, decl] of nonExportedTypes) {
       if (resolved.has(name))
         continue
-      if (combinedText && isWordInText(name, combinedText)) {
+      // Search each text part individually with early break
+      let found = false
+      for (let p = 0; p < textParts.length; p++) {
+        if (isWordInText(name, textParts[p])) {
+          found = true
+          break
+        }
+      }
+      if (found) {
         if (!declNames.has(name)) {
           toInsert.push(decl)
           declNames.add(name)
@@ -3095,31 +3137,25 @@ function resolveReferencedTypes(declarations: Declaration[], nonExportedTypes: M
     if (toInsert.length === 0)
       break
 
-    // Insert at correct source positions to preserve declaration order
-    for (const decl of toInsert) {
-      const declStart = decl.start ?? Number.POSITIVE_INFINITY
-      let insertIdx = declarations.length
-      for (let i = 0; i < declarations.length; i++) {
-        const candidateStart = declarations[i].start ?? Number.POSITIVE_INFINITY
-        if (candidateStart > declStart) {
-          insertIdx = i
-          break
-        }
+    // Merge at correct source positions in a single O(n+k) pass (avoids O(k*n) splice)
+    toInsert.sort((a, b) => (a.start ?? Infinity) - (b.start ?? Infinity))
+    const merged: Declaration[] = []
+    let ti = 0
+    for (let i = 0; i < declarations.length; i++) {
+      const candidateStart = declarations[i].start ?? Infinity
+      while (ti < toInsert.length && (toInsert[ti].start ?? Infinity) <= candidateStart) {
+        merged.push(toInsert[ti++])
       }
-      declarations.splice(insertIdx, 0, decl)
+      merged.push(declarations[i])
     }
+    while (ti < toInsert.length) merged.push(toInsert[ti++])
+    declarations.length = 0
+    for (let i = 0; i < merged.length; i++) declarations.push(merged[i])
 
-    // Append newly inserted declaration text for next iteration checks
-    if (toInsert.length > 0) {
-      const appendedParts: string[] = []
-      for (const decl of toInsert) {
-        if (decl.kind !== 'import') {
-          appendedParts.push(decl.text)
-        }
-      }
-      if (appendedParts.length > 0) {
-        const appendedText = appendedParts.length > 1 ? appendedParts.join('\n') : appendedParts[0]
-        combinedText = combinedText ? `${combinedText}\n${appendedText}` : appendedText
+    // Append new texts to parts array for next iteration
+    for (const decl of toInsert) {
+      if (decl.kind !== 'import') {
+        textParts.push(decl.text)
       }
     }
   }

packages/dtsx/src/extractor/scanner.ts

@@ -80,7 +80,8 @@ export function processDeclarations(
   keepComments: boolean = true,
   importOrder: string[] = ['bun'],
 ): string {
-  const output: string[] = []
+  // Build result string directly instead of output array (avoids array + join allocation)
+  let result = ''
 
   // Extract and add triple-slash directives at the top of the file
   // Fast check: skip whitespace with charCodeAt to avoid trimStart() allocation
@@ -90,8 +91,10 @@ export function processDeclarations(
   if (_si < src.length - 2 && src.charCodeAt(_si) === 47 && src.charCodeAt(_si + 1) === 47 && src.charCodeAt(_si + 2) === 47) {
     const tripleSlashDirectives = extractTripleSlashDirectives(src)
     if (tripleSlashDirectives.length > 0) {
-      output.push(...tripleSlashDirectives)
-      output.push('') // Blank line after directives
+      for (let i = 0; i < tripleSlashDirectives.length; i++) {
+        if (result) result += '\n'
+        result += tripleSlashDirectives[i]
+      }
     }
   }
 
@@ -183,29 +186,27 @@ export function processDeclarations(
     }
   }
 
-  // Build reference check sets for interfaces (optimized: single pass over text sources)
+  // Build reference check sets for interfaces (search each declaration directly, no join)
   const interfaceReferences = new Set<string>()
   if (interfaces.length > 0) {
-    // Build combined text from functions/classes/types for interface reference check
-    const refCheckParts: string[] = []
-    for (const func of functions) {
-      if (func.isExported)
-        refCheckParts.push(func.text)
-    }
-    for (const cls of classes) {
-      refCheckParts.push(cls.text)
-    }
-    for (const type of types) {
-      refCheckParts.push(type.text)
-    }
-    const refCheckText = refCheckParts.length > 0 ? refCheckParts.join('\n') : ''
-
-    if (refCheckText) {
-      for (const iface of interfaces) {
-        if (refCheckText.includes(iface.name)) {
-          interfaceReferences.add(iface.name)
+    for (const iface of interfaces) {
+      let found = false
+      if (!found) {
+        for (const func of functions) {
+          if (func.isExported && func.text.includes(iface.name)) { found = true; break }
+        }
+      }
+      if (!found) {
+        for (const cls of classes) {
+          if (cls.text.includes(iface.name)) { found = true; break }
         }
       }
+      if (!found) {
+        for (const type of types) {
+          if (type.text.includes(iface.name)) { found = true; break }
+        }
+      }
+      if (found) interfaceReferences.add(iface.name)
     }
   }
 
@@ -261,14 +262,14 @@ export function processDeclarations(
       combinedTextParts.push(exp.text)
     }
 
-    // Import detection: scan combined declaration text once per import item
-    const combinedText = combinedTextParts.length > 0
-      ? (combinedTextParts.length > 1 ? combinedTextParts.join('\n') : combinedTextParts[0])
-      : ''
-    if (combinedText) {
+    // Import detection: scan each declaration text individually (avoids giant join allocation)
+    if (combinedTextParts.length > 0) {
       for (const item of allImportedItemsMap.keys()) {
-        if (isWordInText(item, combinedText)) {
-          usedImportItems.add(item)
+        for (let p = 0; p < combinedTextParts.length; p++) {
+          if (isWordInText(item, combinedTextParts[p])) {
+            usedImportItems.add(item)
+            break
+          }
         }
       }
     }
@@ -344,14 +345,17 @@ export function processDeclarations(
     })
   }
 
-  output.push(...processedImports)
-
-  // Always add blank line after imports if there are any imports
-  if (processedImports.length > 0)
-    output.push('')
+  // Append imports to result
+  for (let i = 0; i < processedImports.length; i++) {
+    if (result) result += '\n'
+    result += processedImports[i]
+  }
 
   // Process type exports first
-  for (let i = 0; i < typeExportStatements.length; i++) output.push(typeExportStatements[i])
+  for (let i = 0; i < typeExportStatements.length; i++) {
+    if (result) result += '\n'
+    result += typeExportStatements[i]
+  }
 
   // Process other declarations — iterate each group directly (no spread allocation)
   const declGroups = [functions, variables, interfaces, types, classes, enums, modules]
@@ -391,23 +395,24 @@ export function processDeclarations(
         default:
           assertNever(kind, `Unhandled declaration kind in processor: ${kind}`)
       }
-      if (processed) output.push(processed)
+      if (processed) {
+        if (result) result += '\n'
+        result += processed
+      }
     }
   }
 
   // Process value exports
-  for (let i = 0; i < valueExportStatements.length; i++) output.push(valueExportStatements[i])
+  for (let i = 0; i < valueExportStatements.length; i++) {
+    if (result) result += '\n'
+    result += valueExportStatements[i]
+  }
 
   // Process default export last
-  for (let i = 0; i < defaultExport.length; i++) output.push(defaultExport[i])
-
-  // Build final output — skip empty strings inline instead of filter()
-  let result = ''
-  for (let i = 0; i < output.length; i++) {
-    if (output[i] !== '') {
-      if (result) result += '\n'
-      result += output[i]
-    }
+  for (let i = 0; i < defaultExport.length; i++) {
+    if (result) result += '\n'
+    result += defaultExport[i]
   }
+
   return result
 }