refactor(memoization): remove misnamed memoizeDebounced

The function was fundamentally broken: it returned synchronously via
`return memoized(...args)` on every call, which is just `memoize` with
extra allocated `setTimeout` timers. The scheduled callback's return
value was discarded, so no debouncing occurred — fn fired on every
call, the cache-hit behavior was a consequence of `memoize`, not the
debounce machinery. The `wait` parameter was effectively dead.

A correct debounce cannot return synchronously — the whole point is to
defer work past a quiet window. Changing the signature to
`Promise<Result>` would be a breaking change with no existing callers
(zero in-repo use sites, zero in the fleet), so the simplest fix is
to remove the export. Callers that actually need debouncing should use
a real debouncer that returns a promise.

Author: jdalton

src/memoization.ts

@@ -374,46 +374,6 @@ export function memoizeAsync<Args extends unknown[], Result>(
   }
 }
 
-/**
- * Create a debounced memoized function.
- * Combines memoization with debouncing for expensive operations.
- *
- * @param fn - Function to memoize and debounce
- * @param wait - Debounce wait time in milliseconds
- * @param options - Memoization options
- * @returns Debounced memoized function
- *
- * @example
- * import { memoizeDebounced } from '@socketsecurity/lib/memoization'
- *
- * const search = memoizeDebounced(
- *   (query: string) => performSearch(query),
- *   300,
- *   { name: 'search' }
- * )
- */
-export function memoizeDebounced<Args extends unknown[], Result>(
-  fn: (...args: Args) => Result,
-  wait: number,
-  options: MemoizeOptions<Args, Result> = {},
-): (...args: Args) => Result {
-  const memoized = memoize(fn, options)
-  let timeoutId: NodeJS.Timeout | undefined
-
-  return function debounced(...args: Args): Result {
-    if (timeoutId) {
-      clearTimeout(timeoutId)
-    }
-
-    timeoutId = setTimeout(() => {
-      memoized(...args)
-    }, wait)
-
-    // For immediate return, try cached value or compute synchronously
-    return memoized(...args)
-  }
-}
-
 /**
  * Memoize with WeakMap for object keys.
  * Allows garbage collection when objects are no longer referenced.

test/unit/memoization.test.mts

@@ -5,7 +5,6 @@
  * - memoize() caches synchronous function results
  * - memoizeAsync() caches async function results with promise deduplication
  * - memoizeWeak() uses WeakMap for object key caching
- * - memoizeDebounced() combines memoization with debouncing
  * - once() ensures function executes exactly once
  * - Memoize() decorator for class methods
  * - clearAllMemoizationCaches() global cache clearing
@@ -17,7 +16,6 @@ import {
   Memoize,
   memoize,
   memoizeAsync,
-  memoizeDebounced,
   memoizeWeak,
   once,
 } from '@socketsecurity/lib/memoization'
@@ -542,66 +540,6 @@ describe('memoization', () => {
     })
   })
 
-  describe('memoizeDebounced', () => {
-    it('should debounce and memoize function calls', async () => {
-      const fn = vi.fn((n: number) => n * 2)
-      const debounced = memoizeDebounced(fn, 100)
-
-      // First call - computes immediately
-      expect(debounced(5)).toBe(10)
-      expect(fn).toHaveBeenCalledTimes(1)
-
-      // Immediate second call - returns cached
-      expect(debounced(5)).toBe(10)
-      expect(fn).toHaveBeenCalledTimes(1)
-
-      // Wait for debounce
-      await new Promise(resolve => setTimeout(resolve, 500))
-
-      // After debounce, still cached
-      expect(debounced(5)).toBe(10)
-      expect(fn).toHaveBeenCalledTimes(1)
-    })
-
-    it('should clear debounce timeout on subsequent calls', async () => {
-      const fn = vi.fn((n: number) => n * 2)
-      const debounced = memoizeDebounced(fn, 100)
-
-      debounced(5)
-      debounced(5)
-      debounced(5)
-
-      expect(fn).toHaveBeenCalledTimes(1)
-
-      await new Promise(resolve => setTimeout(resolve, 500))
-
-      // Should still only be called once
-      expect(fn).toHaveBeenCalledTimes(1)
-    })
-
-    it('should handle different arguments', async () => {
-      const fn = vi.fn((n: number) => n * 2)
-      const debounced = memoizeDebounced(fn, 50)
-
-      expect(debounced(1)).toBe(2)
-      expect(debounced(2)).toBe(4)
-      expect(debounced(1)).toBe(2) // Cached
-
-      expect(fn).toHaveBeenCalledTimes(2)
-    })
-
-    it('should respect memoization options', () => {
-      const fn = vi.fn((n: number) => n * 2)
-      const debounced = memoizeDebounced(fn, 50, { maxSize: 1 })
-
-      debounced(1)
-      debounced(2) // Evicts 1
-      debounced(1) // Cache miss
-
-      expect(fn).toHaveBeenCalledTimes(3)
-    })
-  })
-
   describe('edge cases', () => {
     it('should handle very large cache sizes', () => {
       const fn = vi.fn((n: number) => n * 2)