refactor(shared): update utilities, API layer, and types

src/shared/lib/utils/debounce/debounce.ts

@@ -1,28 +1,24 @@
-/**
- * ============================================================================
- * DEBOUNCE UTILITY
- * ============================================================================
- *
- * Creates a debounced function that delays execution until after wait milliseconds
- * have elapsed since the last time it was invoked.
- *
- * @example
- * ```typescript
- * const debouncedSearch = debounce((query: string) => {
- *     console.log('Searching for:', query);
- * }, 300);
- *
- * debouncedSearch('hello');
- * debouncedSearch('hello world'); // Only this will execute after 300ms
- * ```
- */
-
 /**
  * Creates a debounced version of a function
  *
+ * Delays function execution until after `wait` milliseconds have elapsed
+ * since the last invocation. Useful for rate-limiting expensive operations
+ * like API calls or expensive DOM updates.
+ *
+ * @example
+ * ```ts
+ * const search = debounce((query: string) => {
+ *     console.log('Searching for:', query);
+ * }, 300);
+ *
+ * search('a');
+ * search('ab');
+ * search('abc'); // Only this triggers the function after 300ms
+ * ```
+ *
  * @param fn - The function to debounce
  * @param wait - The delay in milliseconds
- * @returns A debounced function that will execute after the specified delay
+ * @returns A debounced function that executes after the delay
  */
 export function debounce<T extends (...args: any[]) => any>(
     fn: T,