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

src/shared/lib/utils/throttle/throttle.ts

@@ -1,9 +1,23 @@
 /**
- * Throttle function execution to a maximum frequency.
+ * Throttles a function to limit execution frequency
  *
- * @param fn Function to throttle.
- * @param wait Maximum time between function calls.
- * @returns Throttled function.
+ * Ensures a function executes at most once per `wait` milliseconds.
+ * Unlike debounce, throttled functions execute on the leading edge
+ * and trailing edge if called repeatedly.
+ *
+ * @example
+ * ```ts
+ * const logScroll = throttle(() => {
+ *     console.log('Scroll position:', window.scrollY);
+ * }, 100);
+ *
+ * window.addEventListener('scroll', logScroll);
+ * // Will log at most once every 100ms
+ * ```
+ *
+ * @param fn - Function to throttle
+ * @param wait - Minimum time between executions in milliseconds
+ * @returns Throttled function
  */
 export function throttle<T extends (...args: any[]) => any>(
     fn: T,
@@ -20,7 +34,7 @@ export function throttle<T extends (...args: any[]) => any>(
             lastCall = now;
             fn(...args);
         } else {
-            // Schedule for end of wait period
+            // Schedule for end of wait period (trailing edge)
             if (timeoutId) clearTimeout(timeoutId);
             timeoutId = setTimeout(() => {
                 lastCall = Date.now();