@tiny-codes/react-easy 1.4.15 → 1.4.17

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 # Changelog
 
+## 1.4.17
+
+2025-9-23
+
+### Features
+
+#### `useDebounce`
+
+- ✨ enhance `useDebounce` with `cancel`, `disable`, `enable`, and `isDisabled` methods
+
+## 1.4.16
+
+2025-9-18
+
+### Features
+
+#### `useDebounce`
+
+- ✨ add `useDebounce` hook
+
 ## 1.4.15
 
 2025-9-16

package/es/hooks/index.d.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';

package/es/hooks/index.js

@@ -1,13 +1,14 @@
 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 { default as useValidators } from "./useValidators";
 export { default as useValidator } from "./useValidator";
 export { default as useValidatorBuilder } from "./useValidatorBuilder";
-export * from "./useUserMedia";
-export { default as useUserMedia } from "./useUserMedia";
 //# sourceMappingURL=index.js.map

package/es/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["default","useAudioPlayer","useRefValue","useRefFunction","useSSE","useStompSocket","useValidators","useValidator","useValidatorBuilder","useUserMedia"],"sources":["../../src/hooks/index.ts"],"sourcesContent":["export { default as useAudioPlayer } from './useAudioPlayer';\nexport { default as useRefValue } from './useRefValue';\nexport { default as useRefFunction } from './useRefFunction';\nexport * from './useSSE';\nexport { default as useSSE } from './useSSE';\nexport * from './useStompSocket';\nexport { default as useStompSocket } from './useStompSocket';\nexport type { ValidatorRuleMap } from './useValidators';\nexport { default as useValidators } from './useValidators';\nexport { default as useValidator } from './useValidator';\nexport type { Validator, RuleRegExpFlags, ValidatorRule, BuilderOptions } from './useValidatorBuilder';\nexport { default as useValidatorBuilder } from './useValidatorBuilder';\nexport * from './useUserMedia';\nexport { default as useUserMedia } from './useUserMedia';\n"],"mappings":"AAAA,SAASA,OAAO,IAAIC,cAAc;AAClC,SAASD,OAAO,IAAIE,WAAW;AAC/B,SAASF,OAAO,IAAIG,cAAc;AAClC;AACA,SAASH,OAAO,IAAII,MAAM;AAC1B;AACA,SAASJ,OAAO,IAAIK,cAAc;AAElC,SAASL,OAAO,IAAIM,aAAa;AACjC,SAASN,OAAO,IAAIO,YAAY;AAEhC,SAASP,OAAO,IAAIQ,mBAAmB;AACvC;AACA,SAASR,OAAO,IAAIS,YAAY"}
+{"version":3,"names":["default","useAudioPlayer","useDebounce","useRefValue","useRefFunction","useSSE","useStompSocket","useUserMedia","useValidators","useValidator","useValidatorBuilder"],"sources":["../../src/hooks/index.ts"],"sourcesContent":["export { default as useAudioPlayer } from './useAudioPlayer';\nexport { default as useDebounce } from './useDebounce';\nexport { default as useRefValue } from './useRefValue';\nexport { default as useRefFunction } from './useRefFunction';\nexport * from './useSSE';\nexport { default as useSSE } from './useSSE';\nexport * from './useStompSocket';\nexport { default as useStompSocket } from './useStompSocket';\nexport * from './useUserMedia';\nexport { default as useUserMedia } from './useUserMedia';\nexport type { ValidatorRuleMap } from './useValidators';\nexport { default as useValidators } from './useValidators';\nexport { default as useValidator } from './useValidator';\nexport type { Validator, RuleRegExpFlags, ValidatorRule, BuilderOptions } from './useValidatorBuilder';\nexport { default as useValidatorBuilder } from './useValidatorBuilder';\n"],"mappings":"AAAA,SAASA,OAAO,IAAIC,cAAc;AAClC,SAASD,OAAO,IAAIE,WAAW;AAC/B,SAASF,OAAO,IAAIG,WAAW;AAC/B,SAASH,OAAO,IAAII,cAAc;AAClC;AACA,SAASJ,OAAO,IAAIK,MAAM;AAC1B;AACA,SAASL,OAAO,IAAIM,cAAc;AAClC;AACA,SAASN,OAAO,IAAIO,YAAY;AAEhC,SAASP,OAAO,IAAIQ,aAAa;AACjC,SAASR,OAAO,IAAIS,YAAY;AAEhC,SAAST,OAAO,IAAIU,mBAAmB"}

package/es/hooks/useDebounce.d.ts

@@ -0,0 +1,65 @@
+/// <reference types="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 | 防抖处理后的函数
+ */
+declare function useDebounce<T extends (...args: any[]) => unknown>(fn: T, deps: React.DependencyList, options?: UseDebounceOptions): DebouncedFunc<T>;
+export interface DebouncedFunc<T extends (...args: any[]) => unknown> {
+    /**
+     * - **EN:** The debounced function.
+     * - **CN:** 防抖处理后的函数
+     */
+    (...args: Parameters<T>): ReturnType<T>;
+    /**
+     * - **EN:** Cancel any pending execution of the debounced function.
+     * - **CN:** 取消防抖函数的任何待执行操作
+     */
+    cancel: () => void;
+    /**
+     * - **EN:** Disable the debounce functionality. Once disabled, subsequent calls to the function
+     *   will have no effect until re-enabled.
+     * - **CN:** 禁用此防抖函数，一旦被禁用，再次调用改函数将不会有任何效果，除非重新启用
+     */
+    disable: () => void;
+    /**
+     * - **EN:** Re-enable the debounce functionality after it has been disabled.
+     * - **CN:** 重新启用此防抖函数
+     */
+    enable: () => void;
+    /**
+     * - **EN:** Check if the debounce functionality is currently disabled.
+     * - **CN:** 检查此防抖函数当前是否被禁用
+     */
+    isDisabled(): boolean;
+}
+export default useDebounce;

package/es/hooks/useDebounce.js

@@ -0,0 +1,112 @@
+function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread(); }
+function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _iterableToArray(iter) { if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter); }
+function _arrayWithoutHoles(arr) { if (Array.isArray(arr)) return _arrayLikeToArray(arr); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+import { useCallback, useEffect, useRef } from 'react';
+import useRefFunction from "./useRefFunction";
+/**
+ * - **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(fn, deps) {
+  var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+  var _options$wait = options.wait,
+    wait = _options$wait === void 0 ? 0 : _options$wait,
+    _options$maxWait = options.maxWait,
+    maxWait = _options$maxWait === void 0 ? 0 : _options$maxWait,
+    _options$leading = options.leading,
+    leading = _options$leading === void 0 ? false : _options$leading;
+  var timeoutRef = useRef(null);
+  var fnRef = useRef(fn);
+  var lastExecutedTimeRef = useRef(0); // The last execution timestamp
+  var lastArgsRef = useRef([]); // The last call arguments
+  var isDisabledRef = useRef(false); // Whether debounce is disabled
+
+  // Update the latest function reference
+  useEffect(function () {
+    fnRef.current = fn;
+  }, [fn]);
+
+  // Cleanup on unmount
+  useEffect(function () {
+    return function () {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+    };
+  }, []);
+
+  // The actual execution function
+  var executeFunction = useCallback(function () {
+    timeoutRef.current = null;
+    lastExecutedTimeRef.current = Date.now();
+    fnRef.current.apply(fnRef, _toConsumableArray(lastArgsRef.current));
+  }, []);
+
+  // The debounced function
+  var debouncedFunction = useRefFunction(function () {
+    if (isDisabledRef.current) {
+      return;
+    }
+    var now = Date.now();
+    for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
+      args[_key] = arguments[_key];
+    }
+    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);
+  });
+  debouncedFunction.cancel = function () {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  };
+  debouncedFunction.disable = function () {
+    isDisabledRef.current = true;
+  };
+  debouncedFunction.enable = function () {
+    isDisabledRef.current = false;
+  };
+  debouncedFunction.isDisabled = function () {
+    return isDisabledRef.current;
+  };
+  return debouncedFunction;
+}
+export default useDebounce;
+//# sourceMappingURL=useDebounce.js.map

package/es/hooks/useDebounce.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useCallback","useEffect","useRef","useRefFunction","useDebounce","fn","deps","options","arguments","length","undefined","_options$wait","wait","_options$maxWait","maxWait","_options$leading","leading","timeoutRef","fnRef","lastExecutedTimeRef","lastArgsRef","isDisabledRef","current","clearTimeout","executeFunction","Date","now","apply","_toConsumableArray","debouncedFunction","_len","args","Array","_key","setTimeout","cancel","disable","enable","isDisabled"],"sources":["../../src/hooks/useDebounce.ts"],"sourcesContent":["import { useCallback, useEffect, useRef } from 'react';\nimport useRefFunction from './useRefFunction';\n\nexport interface UseDebounceOptions {\n  /**\n   * - **EN:** Whether to execute at the start of the wait period. Default is `false`.\n   * - **CN:** 是否在等待周期开始时执行，默认值为 `false`\n   */\n  leading?: boolean;\n  /**\n   * - **EN:** Regular debounce interval in milliseconds. Default is `0`, meaning no debounce.\n   * - **CN:** 常规防抖间隔 (ms)，默认值为 `0`, 表示不进行防抖\n   */\n  wait?: number;\n  /**\n   * - **EN:** Maximum wait time in milliseconds. Default is `0`, meaning no maximum wait.\n   * - **CN:** 最大等待时间 (ms)，默认值为 `0`, 表示不限制最大等待时间\n   */\n  maxWait?: number;\n}\n/**\n * - **EN:** Debounce Hook with dual trigger mechanisms:\n *\n *   1. Traditional debounce: Executes after a specified interval without new calls.\n *   2. Max wait: Forces execution after exceeding a specified maximum wait time.\n * - **CN:** 防抖 Hook：具有两种触发机制:\n *\n *   1. 传统防抖：等待指定时间内无新调用后执行\n *   2. 最大等待：超过指定最大等待时间后强制执行\n *\n * @param fn The function to debounce | 需要防抖的函数\n * @param deps Dependency array, re-creates the debounced function when dependencies change |\n *   依赖项数组，当依赖变化时重新创建防抖函数\n * @param options Configuration options | 配置选项\n *\n * @returns The debounced function | 防抖处理后的函数\n */\nfunction useDebounce<T extends (...args: any[]) => unknown>(\n  fn: T,\n  deps: React.DependencyList,\n  options: UseDebounceOptions = {}\n): DebouncedFunc<T> {\n  const { wait = 0, maxWait = 0, leading = false } = options;\n  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n  const fnRef = useRef<T>(fn);\n  const lastExecutedTimeRef = useRef<number>(0); // The last execution timestamp\n  const lastArgsRef = useRef<unknown[]>([]); // The last call arguments\n  const isDisabledRef = useRef<boolean>(false); // Whether debounce is disabled\n\n  // Update the latest function reference\n  useEffect(() => {\n    fnRef.current = fn;\n  }, [fn]);\n\n  // Cleanup on unmount\n  useEffect(() => {\n    return () => {\n      if (timeoutRef.current) {\n        clearTimeout(timeoutRef.current);\n        timeoutRef.current = null;\n      }\n    };\n  }, []);\n\n  // The actual execution function\n  const executeFunction = useCallback(() => {\n    timeoutRef.current = null;\n    lastExecutedTimeRef.current = Date.now();\n    fnRef.current(...lastArgsRef.current);\n  }, []);\n\n  // The debounced function\n  const debouncedFunction = useRefFunction((...args: Parameters<T>) => {\n    if (isDisabledRef.current) {\n      return;\n    }\n    const now = Date.now();\n    lastArgsRef.current = args;\n\n    // If leading is true and it's the first call, execute immediately\n    if (leading && timeoutRef.current === null && now - lastExecutedTimeRef.current >= wait) {\n      executeFunction();\n      return;\n    }\n\n    // 1. Clear the existing timer\n    if (timeoutRef.current !== null) {\n      clearTimeout(timeoutRef.current);\n      timeoutRef.current = null;\n    }\n\n    // 2. Check if the maximum wait time has been exceeded, if so, execute immediately\n    if (maxWait > 0 && now - lastExecutedTimeRef.current >= maxWait) {\n      executeFunction();\n      return;\n    }\n\n    // 3. Set a new debounce timer\n    timeoutRef.current = setTimeout(executeFunction, wait);\n  }) as DebouncedFunc<T>;\n  debouncedFunction.cancel = () => {\n    if (timeoutRef.current) {\n      clearTimeout(timeoutRef.current);\n      timeoutRef.current = null;\n    }\n  };\n  debouncedFunction.disable = () => {\n    isDisabledRef.current = true;\n  };\n  debouncedFunction.enable = () => {\n    isDisabledRef.current = false;\n  };\n  debouncedFunction.isDisabled = () => isDisabledRef.current;\n  return debouncedFunction;\n}\n\nexport interface DebouncedFunc<T extends (...args: any[]) => unknown> {\n  /**\n   * - **EN:** The debounced function.\n   * - **CN:** 防抖处理后的函数\n   */\n  (...args: Parameters<T>): ReturnType<T>;\n  /**\n   * - **EN:** Cancel any pending execution of the debounced function.\n   * - **CN:** 取消防抖函数的任何待执行操作\n   */\n  cancel: () => void;\n  /**\n   * - **EN:** Disable the debounce functionality. Once disabled, subsequent calls to the function\n   *   will have no effect until re-enabled.\n   * - **CN:** 禁用此防抖函数，一旦被禁用，再次调用改函数将不会有任何效果，除非重新启用\n   */\n  disable: () => void;\n  /**\n   * - **EN:** Re-enable the debounce functionality after it has been disabled.\n   * - **CN:** 重新启用此防抖函数\n   */\n  enable: () => void;\n  /**\n   * - **EN:** Check if the debounce functionality is currently disabled.\n   * - **CN:** 检查此防抖函数当前是否被禁用\n   */\n  isDisabled(): boolean;\n}\n\nexport default useDebounce;\n"],"mappings":"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"}

package/lib/hooks/index.d.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';

package/lib/hooks/index.js

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var hooks_exports = {};
 __export(hooks_exports, {
   useAudioPlayer: () => import_useAudioPlayer.default,
+  useDebounce: () => import_useDebounce.default,
   useRefFunction: () => import_useRefFunction.default,
   useRefValue: () => import_useRefValue.default,
   useSSE: () => import_useSSE.default,
@@ -42,20 +43,22 @@ __export(hooks_exports, {
 });
 module.exports = __toCommonJS(hooks_exports);
 var import_useAudioPlayer = __toESM(require("./useAudioPlayer"));
+var import_useDebounce = __toESM(require("./useDebounce"));
 var import_useRefValue = __toESM(require("./useRefValue"));
 var import_useRefFunction = __toESM(require("./useRefFunction"));
 __reExport(hooks_exports, require("./useSSE"), module.exports);
 var import_useSSE = __toESM(require("./useSSE"));
 __reExport(hooks_exports, require("./useStompSocket"), module.exports);
 var import_useStompSocket = __toESM(require("./useStompSocket"));
+__reExport(hooks_exports, require("./useUserMedia"), module.exports);
+var import_useUserMedia = __toESM(require("./useUserMedia"));
 var import_useValidators = __toESM(require("./useValidators"));
 var import_useValidator = __toESM(require("./useValidator"));
 var import_useValidatorBuilder = __toESM(require("./useValidatorBuilder"));
-__reExport(hooks_exports, require("./useUserMedia"), module.exports);
-var import_useUserMedia = __toESM(require("./useUserMedia"));
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   useAudioPlayer,
+  useDebounce,
   useRefFunction,
   useRefValue,
   useSSE,

package/lib/hooks/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/hooks/index.ts"],
-  "sourcesContent": ["export { default as useAudioPlayer } from './useAudioPlayer';\nexport { default as useRefValue } from './useRefValue';\nexport { default as useRefFunction } from './useRefFunction';\nexport * from './useSSE';\nexport { default as useSSE } from './useSSE';\nexport * from './useStompSocket';\nexport { default as useStompSocket } from './useStompSocket';\nexport type { ValidatorRuleMap } from './useValidators';\nexport { default as useValidators } from './useValidators';\nexport { default as useValidator } from './useValidator';\nexport type { Validator, RuleRegExpFlags, ValidatorRule, BuilderOptions } from './useValidatorBuilder';\nexport { default as useValidatorBuilder } from './useValidatorBuilder';\nexport * from './useUserMedia';\nexport { default as useUserMedia } from './useUserMedia';\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,4BAA0C;AAC1C,yBAAuC;AACvC,4BAA0C;AAC1C,0BAAc,qBAHd;AAIA,oBAAkC;AAClC,0BAAc,6BALd;AAMA,4BAA0C;AAE1C,2BAAyC;AACzC,0BAAwC;AAExC,iCAA+C;AAC/C,0BAAc,2BAZd;AAaA,0BAAwC;",
+  "sourcesContent": ["export { default as useAudioPlayer } from './useAudioPlayer';\nexport { default as useDebounce } from './useDebounce';\nexport { default as useRefValue } from './useRefValue';\nexport { default as useRefFunction } from './useRefFunction';\nexport * from './useSSE';\nexport { default as useSSE } from './useSSE';\nexport * from './useStompSocket';\nexport { default as useStompSocket } from './useStompSocket';\nexport * from './useUserMedia';\nexport { default as useUserMedia } from './useUserMedia';\nexport type { ValidatorRuleMap } from './useValidators';\nexport { default as useValidators } from './useValidators';\nexport { default as useValidator } from './useValidator';\nexport type { Validator, RuleRegExpFlags, ValidatorRule, BuilderOptions } from './useValidatorBuilder';\nexport { default as useValidatorBuilder } from './useValidatorBuilder';\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,4BAA0C;AAC1C,yBAAuC;AACvC,yBAAuC;AACvC,4BAA0C;AAC1C,0BAAc,qBAJd;AAKA,oBAAkC;AAClC,0BAAc,6BANd;AAOA,4BAA0C;AAC1C,0BAAc,2BARd;AASA,0BAAwC;AAExC,2BAAyC;AACzC,0BAAwC;AAExC,iCAA+C;",
   "names": []
 }

package/lib/hooks/useDebounce.d.ts

@@ -0,0 +1,65 @@
+/// <reference types="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 | 防抖处理后的函数
+ */
+declare function useDebounce<T extends (...args: any[]) => unknown>(fn: T, deps: React.DependencyList, options?: UseDebounceOptions): DebouncedFunc<T>;
+export interface DebouncedFunc<T extends (...args: any[]) => unknown> {
+    /**
+     * - **EN:** The debounced function.
+     * - **CN:** 防抖处理后的函数
+     */
+    (...args: Parameters<T>): ReturnType<T>;
+    /**
+     * - **EN:** Cancel any pending execution of the debounced function.
+     * - **CN:** 取消防抖函数的任何待执行操作
+     */
+    cancel: () => void;
+    /**
+     * - **EN:** Disable the debounce functionality. Once disabled, subsequent calls to the function
+     *   will have no effect until re-enabled.
+     * - **CN:** 禁用此防抖函数，一旦被禁用，再次调用改函数将不会有任何效果，除非重新启用
+     */
+    disable: () => void;
+    /**
+     * - **EN:** Re-enable the debounce functionality after it has been disabled.
+     * - **CN:** 重新启用此防抖函数
+     */
+    enable: () => void;
+    /**
+     * - **EN:** Check if the debounce functionality is currently disabled.
+     * - **CN:** 检查此防抖函数当前是否被禁用
+     */
+    isDisabled(): boolean;
+}
+export default useDebounce;

package/lib/hooks/useDebounce.js

@@ -0,0 +1,96 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/hooks/useDebounce.ts
+var useDebounce_exports = {};
+__export(useDebounce_exports, {
+  default: () => useDebounce_default
+});
+module.exports = __toCommonJS(useDebounce_exports);
+var import_react = require("react");
+var import_useRefFunction = __toESM(require("./useRefFunction"));
+function useDebounce(fn, deps, options = {}) {
+  const { wait = 0, maxWait = 0, leading = false } = options;
+  const timeoutRef = (0, import_react.useRef)(null);
+  const fnRef = (0, import_react.useRef)(fn);
+  const lastExecutedTimeRef = (0, import_react.useRef)(0);
+  const lastArgsRef = (0, import_react.useRef)([]);
+  const isDisabledRef = (0, import_react.useRef)(false);
+  (0, import_react.useEffect)(() => {
+    fnRef.current = fn;
+  }, [fn]);
+  (0, import_react.useEffect)(() => {
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+    };
+  }, []);
+  const executeFunction = (0, import_react.useCallback)(() => {
+    timeoutRef.current = null;
+    lastExecutedTimeRef.current = Date.now();
+    fnRef.current(...lastArgsRef.current);
+  }, []);
+  const debouncedFunction = (0, import_useRefFunction.default)((...args) => {
+    if (isDisabledRef.current) {
+      return;
+    }
+    const now = Date.now();
+    lastArgsRef.current = args;
+    if (leading && timeoutRef.current === null && now - lastExecutedTimeRef.current >= wait) {
+      executeFunction();
+      return;
+    }
+    if (timeoutRef.current !== null) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+    if (maxWait > 0 && now - lastExecutedTimeRef.current >= maxWait) {
+      executeFunction();
+      return;
+    }
+    timeoutRef.current = setTimeout(executeFunction, wait);
+  });
+  debouncedFunction.cancel = () => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  };
+  debouncedFunction.disable = () => {
+    isDisabledRef.current = true;
+  };
+  debouncedFunction.enable = () => {
+    isDisabledRef.current = false;
+  };
+  debouncedFunction.isDisabled = () => isDisabledRef.current;
+  return debouncedFunction;
+}
+var useDebounce_default = useDebounce;
+//# sourceMappingURL=useDebounce.js.map

package/lib/hooks/useDebounce.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/hooks/useDebounce.ts"],
+  "sourcesContent": ["import { useCallback, useEffect, useRef } from 'react';\nimport useRefFunction from './useRefFunction';\n\nexport interface UseDebounceOptions {\n  /**\n   * - **EN:** Whether to execute at the start of the wait period. Default is `false`.\n   * - **CN:** 是否在等待周期开始时执行，默认值为 `false`\n   */\n  leading?: boolean;\n  /**\n   * - **EN:** Regular debounce interval in milliseconds. Default is `0`, meaning no debounce.\n   * - **CN:** 常规防抖间隔 (ms)，默认值为 `0`, 表示不进行防抖\n   */\n  wait?: number;\n  /**\n   * - **EN:** Maximum wait time in milliseconds. Default is `0`, meaning no maximum wait.\n   * - **CN:** 最大等待时间 (ms)，默认值为 `0`, 表示不限制最大等待时间\n   */\n  maxWait?: number;\n}\n/**\n * - **EN:** Debounce Hook with dual trigger mechanisms:\n *\n *   1. Traditional debounce: Executes after a specified interval without new calls.\n *   2. Max wait: Forces execution after exceeding a specified maximum wait time.\n * - **CN:** 防抖 Hook：具有两种触发机制:\n *\n *   1. 传统防抖：等待指定时间内无新调用后执行\n *   2. 最大等待：超过指定最大等待时间后强制执行\n *\n * @param fn The function to debounce | 需要防抖的函数\n * @param deps Dependency array, re-creates the debounced function when dependencies change |\n *   依赖项数组，当依赖变化时重新创建防抖函数\n * @param options Configuration options | 配置选项\n *\n * @returns The debounced function | 防抖处理后的函数\n */\nfunction useDebounce<T extends (...args: any[]) => unknown>(\n  fn: T,\n  deps: React.DependencyList,\n  options: UseDebounceOptions = {}\n): DebouncedFunc<T> {\n  const { wait = 0, maxWait = 0, leading = false } = options;\n  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n  const fnRef = useRef<T>(fn);\n  const lastExecutedTimeRef = useRef<number>(0); // The last execution timestamp\n  const lastArgsRef = useRef<unknown[]>([]); // The last call arguments\n  const isDisabledRef = useRef<boolean>(false); // Whether debounce is disabled\n\n  // Update the latest function reference\n  useEffect(() => {\n    fnRef.current = fn;\n  }, [fn]);\n\n  // Cleanup on unmount\n  useEffect(() => {\n    return () => {\n      if (timeoutRef.current) {\n        clearTimeout(timeoutRef.current);\n        timeoutRef.current = null;\n      }\n    };\n  }, []);\n\n  // The actual execution function\n  const executeFunction = useCallback(() => {\n    timeoutRef.current = null;\n    lastExecutedTimeRef.current = Date.now();\n    fnRef.current(...lastArgsRef.current);\n  }, []);\n\n  // The debounced function\n  const debouncedFunction = useRefFunction((...args: Parameters<T>) => {\n    if (isDisabledRef.current) {\n      return;\n    }\n    const now = Date.now();\n    lastArgsRef.current = args;\n\n    // If leading is true and it's the first call, execute immediately\n    if (leading && timeoutRef.current === null && now - lastExecutedTimeRef.current >= wait) {\n      executeFunction();\n      return;\n    }\n\n    // 1. Clear the existing timer\n    if (timeoutRef.current !== null) {\n      clearTimeout(timeoutRef.current);\n      timeoutRef.current = null;\n    }\n\n    // 2. Check if the maximum wait time has been exceeded, if so, execute immediately\n    if (maxWait > 0 && now - lastExecutedTimeRef.current >= maxWait) {\n      executeFunction();\n      return;\n    }\n\n    // 3. Set a new debounce timer\n    timeoutRef.current = setTimeout(executeFunction, wait);\n  }) as DebouncedFunc<T>;\n  debouncedFunction.cancel = () => {\n    if (timeoutRef.current) {\n      clearTimeout(timeoutRef.current);\n      timeoutRef.current = null;\n    }\n  };\n  debouncedFunction.disable = () => {\n    isDisabledRef.current = true;\n  };\n  debouncedFunction.enable = () => {\n    isDisabledRef.current = false;\n  };\n  debouncedFunction.isDisabled = () => isDisabledRef.current;\n  return debouncedFunction;\n}\n\nexport interface DebouncedFunc<T extends (...args: any[]) => unknown> {\n  /**\n   * - **EN:** The debounced function.\n   * - **CN:** 防抖处理后的函数\n   */\n  (...args: Parameters<T>): ReturnType<T>;\n  /**\n   * - **EN:** Cancel any pending execution of the debounced function.\n   * - **CN:** 取消防抖函数的任何待执行操作\n   */\n  cancel: () => void;\n  /**\n   * - **EN:** Disable the debounce functionality. Once disabled, subsequent calls to the function\n   *   will have no effect until re-enabled.\n   * - **CN:** 禁用此防抖函数，一旦被禁用，再次调用改函数将不会有任何效果，除非重新启用\n   */\n  disable: () => void;\n  /**\n   * - **EN:** Re-enable the debounce functionality after it has been disabled.\n   * - **CN:** 重新启用此防抖函数\n   */\n  enable: () => void;\n  /**\n   * - **EN:** Check if the debounce functionality is currently disabled.\n   * - **CN:** 检查此防抖函数当前是否被禁用\n   */\n  isDisabled(): boolean;\n}\n\nexport default useDebounce;\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAA+C;AAC/C,4BAA2B;AAoC3B,SAAS,YACP,IACA,MACA,UAA8B,CAAC,GACb;AAClB,QAAM,EAAE,OAAO,GAAG,UAAU,GAAG,UAAU,MAAM,IAAI;AACnD,QAAM,iBAAa,qBAA6C,IAAI;AACpE,QAAM,YAAQ,qBAAU,EAAE;AAC1B,QAAM,0BAAsB,qBAAe,CAAC;AAC5C,QAAM,kBAAc,qBAAkB,CAAC,CAAC;AACxC,QAAM,oBAAgB,qBAAgB,KAAK;AAG3C,8BAAU,MAAM;AACd,UAAM,UAAU;AAAA,EAClB,GAAG,CAAC,EAAE,CAAC;AAGP,8BAAU,MAAM;AACd,WAAO,MAAM;AACX,UAAI,WAAW,SAAS;AACtB,qBAAa,WAAW,OAAO;AAC/B,mBAAW,UAAU;AAAA,MACvB;AAAA,IACF;AAAA,EACF,GAAG,CAAC,CAAC;AAGL,QAAM,sBAAkB,0BAAY,MAAM;AACxC,eAAW,UAAU;AACrB,wBAAoB,UAAU,KAAK,IAAI;AACvC,UAAM,QAAQ,GAAG,YAAY,OAAO;AAAA,EACtC,GAAG,CAAC,CAAC;AAGL,QAAM,wBAAoB,sBAAAA,SAAe,IAAI,SAAwB;AACnE,QAAI,cAAc,SAAS;AACzB;AAAA,IACF;AACA,UAAM,MAAM,KAAK,IAAI;AACrB,gBAAY,UAAU;AAGtB,QAAI,WAAW,WAAW,YAAY,QAAQ,MAAM,oBAAoB,WAAW,MAAM;AACvF,sBAAgB;AAChB;AAAA,IACF;AAGA,QAAI,WAAW,YAAY,MAAM;AAC/B,mBAAa,WAAW,OAAO;AAC/B,iBAAW,UAAU;AAAA,IACvB;AAGA,QAAI,UAAU,KAAK,MAAM,oBAAoB,WAAW,SAAS;AAC/D,sBAAgB;AAChB;AAAA,IACF;AAGA,eAAW,UAAU,WAAW,iBAAiB,IAAI;AAAA,EACvD,CAAC;AACD,oBAAkB,SAAS,MAAM;AAC/B,QAAI,WAAW,SAAS;AACtB,mBAAa,WAAW,OAAO;AAC/B,iBAAW,UAAU;AAAA,IACvB;AAAA,EACF;AACA,oBAAkB,UAAU,MAAM;AAChC,kBAAc,UAAU;AAAA,EAC1B;AACA,oBAAkB,SAAS,MAAM;AAC/B,kBAAc,UAAU;AAAA,EAC1B;AACA,oBAAkB,aAAa,MAAM,cAAc;AACnD,SAAO;AACT;AA+BA,IAAO,sBAAQ;",
+  "names": ["useRefFunction"]
+}

package/package.json

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