@tiny-codes/react-easy 1.4.15 → 1.4.16

package/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/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,37 @@
+/// <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): (...args: Parameters<T>) => void;
+export default useDebounce;

package/es/hooks/useDebounce.js

@@ -0,0 +1,92 @@
+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';
+/**
+ * - **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
+
+  // 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
+  return useCallback(function () {
+    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);
+  }, // eslint-disable-next-line @tiny-codes/react-hooks/exhaustive-deps
+  [wait, maxWait, executeFunction, leading].concat(_toConsumableArray(deps)));
+}
+export default useDebounce;
+//# sourceMappingURL=useDebounce.js.map

package/es/hooks/useDebounce.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useCallback","useEffect","useRef","useDebounce","fn","deps","options","arguments","length","undefined","_options$wait","wait","_options$maxWait","maxWait","_options$leading","leading","timeoutRef","fnRef","lastExecutedTimeRef","lastArgsRef","current","clearTimeout","executeFunction","Date","now","apply","_toConsumableArray","_len","args","Array","_key","setTimeout","concat"],"sources":["../../src/hooks/useDebounce.ts"],"sourcesContent":["import { useCallback, useEffect, useRef } from 'react';\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): (...args: Parameters<T>) => void {\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\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  return useCallback(\n    (...args: Parameters<T>) => {\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    },\n    // eslint-disable-next-line @tiny-codes/react-hooks/exhaustive-deps\n    [wait, maxWait, executeFunction, leading, ...deps]\n  );\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,37 @@
+/// <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): (...args: Parameters<T>) => void;
+export default useDebounce;

package/lib/hooks/useDebounce.js

@@ -0,0 +1,71 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __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");
+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)([]);
+  (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);
+  }, []);
+  return (0, import_react.useCallback)(
+    (...args) => {
+      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);
+    },
+    // eslint-disable-next-line @tiny-codes/react-hooks/exhaustive-deps
+    [wait, maxWait, executeFunction, leading, ...deps]
+  );
+}
+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';\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): (...args: Parameters<T>) => void {\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\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  return useCallback(\n    (...args: Parameters<T>) => {\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    },\n    // eslint-disable-next-line @tiny-codes/react-hooks/exhaustive-deps\n    [wait, maxWait, executeFunction, leading, ...deps]\n  );\n}\n\nexport default useDebounce;\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAA+C;AAoC/C,SAAS,YACP,IACA,MACA,UAA8B,CAAC,GACG;AAClC,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;AAGxC,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,aAAO;AAAA,IACL,IAAI,SAAwB;AAC1B,YAAM,MAAM,KAAK,IAAI;AACrB,kBAAY,UAAU;AAGtB,UAAI,WAAW,WAAW,YAAY,QAAQ,MAAM,oBAAoB,WAAW,MAAM;AACvF,wBAAgB;AAChB;AAAA,MACF;AAGA,UAAI,WAAW,YAAY,MAAM;AAC/B,qBAAa,WAAW,OAAO;AAC/B,mBAAW,UAAU;AAAA,MACvB;AAGA,UAAI,UAAU,KAAK,MAAM,oBAAoB,WAAW,SAAS;AAC/D,wBAAgB;AAChB;AAAA,MACF;AAGA,iBAAW,UAAU,WAAW,iBAAiB,IAAI;AAAA,IACvD;AAAA;AAAA,IAEA,CAAC,MAAM,SAAS,iBAAiB,SAAS,GAAG,IAAI;AAAA,EACnD;AACF;AAEA,IAAO,sBAAQ;",
+  "names": []
+}

package/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",