feat: add useDebounce hook

Author: shijistar

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 # Changelog
 
+## 1.4.16
+
+2025-9-18
+
+### Features
+
+#### `useDebounce`
+
+- ✨ add `useDebounce` hook
+
 ## 1.4.15
 
 2025-9-16

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-codes/react-easy",
-  "version": "1.4.15",
+  "version": "1.4.16",
   "description": "Simplify React and AntDesign development with practical components and hooks",
   "keywords": [
     "react",

src/hooks/index.ts

@@ -1,14 +1,15 @@
 export { default as useAudioPlayer } from './useAudioPlayer';
+export { default as useDebounce } from './useDebounce';
 export { default as useRefValue } from './useRefValue';
 export { default as useRefFunction } from './useRefFunction';
 export * from './useSSE';
 export { default as useSSE } from './useSSE';
 export * from './useStompSocket';
 export { default as useStompSocket } from './useStompSocket';
+export * from './useUserMedia';
+export { default as useUserMedia } from './useUserMedia';
 export type { ValidatorRuleMap } from './useValidators';
 export { default as useValidators } from './useValidators';
 export { default as useValidator } from './useValidator';
 export type { Validator, RuleRegExpFlags, ValidatorRule, BuilderOptions } from './useValidatorBuilder';
 export { default as useValidatorBuilder } from './useValidatorBuilder';
-export * from './useUserMedia';
-export { default as useUserMedia } from './useUserMedia';

src/hooks/useDebounce.ts

@@ -0,0 +1,102 @@
+import { useCallback, useEffect, useRef } from 'react';
+
+export interface UseDebounceOptions {
+  /**
+   * - **EN** Whether to execute at the start of the wait period. Default is `false`.
+   * - **CN** 是否在等待周期开始时执行，默认值为 `false`
+   */
+  leading?: boolean;
+  /**
+   * - **EN** Regular debounce interval in milliseconds. Default is `0`, meaning no debounce.
+   * - **CN** 常规防抖间隔 (ms)，默认值为 `0`, 表示不进行防抖
+   */
+  wait?: number;
+  /**
+   * - **EN** Maximum wait time in milliseconds. Default is `0`, meaning no maximum wait.
+   * - **CN** 最大等待时间 (ms)，默认值为 `0`, 表示不限制最大等待时间
+   */
+  maxWait?: number;
+}
+/**
+ * - **EN** Debounce Hook with dual trigger mechanisms:
+ *
+ *   1. Traditional debounce: Executes after a specified interval without new calls.
+ *   2. Max wait: Forces execution after exceeding a specified maximum wait time.
+ * - **CN** 防抖 Hook：具有两种触发机制:
+ *
+ *   1. 传统防抖：等待指定时间内无新调用后执行
+ *   2. 最大等待：超过指定最大等待时间后强制执行
+ *
+ * @param fn The function to debounce | 需要防抖的函数
+ * @param deps Dependency array, re-creates the debounced function when dependencies change |
+ *   依赖项数组，当依赖变化时重新创建防抖函数
+ * @param options Configuration options | 配置选项
+ *
+ * @returns The debounced function | 防抖处理后的函数
+ */
+function useDebounce<T extends (...args: any[]) => unknown>(
+  fn: T,
+  deps: React.DependencyList,
+  options: UseDebounceOptions = {}
+): (...args: Parameters<T>) => void {
+  const { wait = 0, maxWait = 0, leading = false } = options;
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const fnRef = useRef<T>(fn);
+  const lastExecutedTimeRef = useRef<number>(0); // The last execution timestamp
+  const lastArgsRef = useRef<unknown[]>([]); // The last call arguments
+
+  // Update the latest function reference
+  useEffect(() => {
+    fnRef.current = fn;
+  }, [fn]);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+    };
+  }, []);
+
+  // The actual execution function
+  const executeFunction = useCallback(() => {
+    timeoutRef.current = null;
+    lastExecutedTimeRef.current = Date.now();
+    fnRef.current(...lastArgsRef.current);
+  }, []);
+
+  // The debounced function
+  return useCallback(
+    (...args: Parameters<T>) => {
+      const now = Date.now();
+      lastArgsRef.current = args;
+
+      // If leading is true and it's the first call, execute immediately
+      if (leading && timeoutRef.current === null && now - lastExecutedTimeRef.current >= wait) {
+        executeFunction();
+        return;
+      }
+
+      // 1. Clear the existing timer
+      if (timeoutRef.current !== null) {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+
+      // 2. Check if the maximum wait time has been exceeded, if so, execute immediately
+      if (maxWait > 0 && now - lastExecutedTimeRef.current >= maxWait) {
+        executeFunction();
+        return;
+      }
+
+      // 3. Set a new debounce timer
+      timeoutRef.current = setTimeout(executeFunction, wait);
+    },
+    // eslint-disable-next-line @tiny-codes/react-hooks/exhaustive-deps
+    [wait, maxWait, executeFunction, leading, ...deps]
+  );
+}
+
+export default useDebounce;