@usefy/use-debounce 0.0.2

package/dist/index.d.mts

@@ -0,0 +1,69 @@
+/**
+ * Options for useDebounce hook
+ */
+interface UseDebounceOptions {
+    /**
+     * Maximum time the debounced value can be delayed
+     * @default undefined (no maximum)
+     */
+    maxWait?: number;
+    /**
+     * Whether to update the debounced value on the leading edge
+     * @default false
+     */
+    leading?: boolean;
+    /**
+     * Whether to update the debounced value on the trailing edge
+     * @default true
+     */
+    trailing?: boolean;
+}
+/**
+ * Debounces a value by delaying updates until after a specified delay period has elapsed
+ * since the last time the value changed.
+ *
+ * @template T - The type of the value to debounce
+ * @param value - The value to debounce
+ * @param delay - The delay in milliseconds (default: 500ms)
+ * @param options - Additional options for controlling debounce behavior
+ * @returns The debounced value
+ *
+ * @example
+ * ```tsx
+ * function SearchInput() {
+ *   const [searchTerm, setSearchTerm] = useState('');
+ *   const debouncedSearchTerm = useDebounce(searchTerm, 500);
+ *
+ *   useEffect(() => {
+ *     if (debouncedSearchTerm) {
+ *       // API call with debounced value
+ *       searchAPI(debouncedSearchTerm);
+ *     }
+ *   }, [debouncedSearchTerm]);
+ *
+ *   return (
+ *     <input
+ *       type="text"
+ *       value={searchTerm}
+ *       onChange={(e) => setSearchTerm(e.target.value)}
+ *       placeholder="Search..."
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With leading edge update
+ * const debouncedValue = useDebounce(value, 300, { leading: true });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With maximum wait time
+ * const debouncedValue = useDebounce(value, 500, { maxWait: 2000 });
+ * ```
+ */
+declare function useDebounce<T>(value: T, delay?: number, options?: UseDebounceOptions): T;
+
+export { type UseDebounceOptions, useDebounce };

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Options for useDebounce hook
+ */
+interface UseDebounceOptions {
+    /**
+     * Maximum time the debounced value can be delayed
+     * @default undefined (no maximum)
+     */
+    maxWait?: number;
+    /**
+     * Whether to update the debounced value on the leading edge
+     * @default false
+     */
+    leading?: boolean;
+    /**
+     * Whether to update the debounced value on the trailing edge
+     * @default true
+     */
+    trailing?: boolean;
+}
+/**
+ * Debounces a value by delaying updates until after a specified delay period has elapsed
+ * since the last time the value changed.
+ *
+ * @template T - The type of the value to debounce
+ * @param value - The value to debounce
+ * @param delay - The delay in milliseconds (default: 500ms)
+ * @param options - Additional options for controlling debounce behavior
+ * @returns The debounced value
+ *
+ * @example
+ * ```tsx
+ * function SearchInput() {
+ *   const [searchTerm, setSearchTerm] = useState('');
+ *   const debouncedSearchTerm = useDebounce(searchTerm, 500);
+ *
+ *   useEffect(() => {
+ *     if (debouncedSearchTerm) {
+ *       // API call with debounced value
+ *       searchAPI(debouncedSearchTerm);
+ *     }
+ *   }, [debouncedSearchTerm]);
+ *
+ *   return (
+ *     <input
+ *       type="text"
+ *       value={searchTerm}
+ *       onChange={(e) => setSearchTerm(e.target.value)}
+ *       placeholder="Search..."
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With leading edge update
+ * const debouncedValue = useDebounce(value, 300, { leading: true });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With maximum wait time
+ * const debouncedValue = useDebounce(value, 500, { maxWait: 2000 });
+ * ```
+ */
+declare function useDebounce<T>(value: T, delay?: number, options?: UseDebounceOptions): T;
+
+export { type UseDebounceOptions, useDebounce };

package/dist/index.js

@@ -0,0 +1,160 @@
+"use strict";
+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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useDebounce: () => useDebounce
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useDebounce.ts
+var import_react = require("react");
+function useDebounce(value, delay = 500, options = {}) {
+  const wait = delay || 0;
+  const leading = options.leading ?? false;
+  const trailing = options.trailing !== void 0 ? options.trailing : true;
+  const maxing = "maxWait" in options;
+  const maxWait = maxing ? Math.max(options.maxWait || 0, wait) : void 0;
+  const [debouncedValue, setDebouncedValue] = (0, import_react.useState)(value);
+  const timerIdRef = (0, import_react.useRef)(
+    void 0
+  );
+  const lastCallTimeRef = (0, import_react.useRef)(void 0);
+  const lastInvokeTimeRef = (0, import_react.useRef)(0);
+  const lastValueRef = (0, import_react.useRef)(value);
+  const prevValueRef = (0, import_react.useRef)(value);
+  const waitRef = (0, import_react.useRef)(wait);
+  const leadingRef = (0, import_react.useRef)(leading);
+  const trailingRef = (0, import_react.useRef)(trailing);
+  const maxingRef = (0, import_react.useRef)(maxing);
+  const maxWaitRef = (0, import_react.useRef)(maxWait);
+  waitRef.current = wait;
+  leadingRef.current = leading;
+  trailingRef.current = trailing;
+  maxingRef.current = maxing;
+  maxWaitRef.current = maxWait;
+  const now = () => Date.now();
+  const shouldInvokeRef = (0, import_react.useRef)(() => false);
+  const invokeRef = (0, import_react.useRef)(() => {
+  });
+  const remainingWaitRef = (0, import_react.useRef)(() => 0);
+  const timerExpiredRef = (0, import_react.useRef)(() => {
+  });
+  const trailingEdgeRef = (0, import_react.useRef)(() => {
+  });
+  const leadingEdgeRef = (0, import_react.useRef)(() => {
+  });
+  shouldInvokeRef.current = (time) => {
+    const lastCallTime = lastCallTimeRef.current;
+    if (lastCallTime === void 0) {
+      return true;
+    }
+    const timeSinceLastCall = time - lastCallTime;
+    const timeSinceLastInvoke = time - lastInvokeTimeRef.current;
+    return timeSinceLastCall >= waitRef.current || timeSinceLastCall < 0 || // System time went backwards
+    maxingRef.current && timeSinceLastInvoke >= maxWaitRef.current;
+  };
+  invokeRef.current = (time) => {
+    setDebouncedValue(lastValueRef.current);
+    lastInvokeTimeRef.current = time;
+  };
+  remainingWaitRef.current = (time) => {
+    const lastCallTime = lastCallTimeRef.current;
+    if (lastCallTime === void 0) {
+      return waitRef.current;
+    }
+    const timeSinceLastCall = time - lastCallTime;
+    const timeSinceLastInvoke = time - lastInvokeTimeRef.current;
+    const timeWaiting = waitRef.current - timeSinceLastCall;
+    return maxingRef.current ? Math.min(
+      timeWaiting,
+      maxWaitRef.current - timeSinceLastInvoke
+    ) : timeWaiting;
+  };
+  trailingEdgeRef.current = (time) => {
+    timerIdRef.current = void 0;
+    if (trailingRef.current && lastCallTimeRef.current !== void 0) {
+      invokeRef.current(time);
+    }
+  };
+  timerExpiredRef.current = () => {
+    const time = now();
+    if (shouldInvokeRef.current(time)) {
+      trailingEdgeRef.current(time);
+    } else {
+      timerIdRef.current = setTimeout(
+        () => timerExpiredRef.current(),
+        remainingWaitRef.current(time)
+      );
+    }
+  };
+  leadingEdgeRef.current = (time) => {
+    lastInvokeTimeRef.current = time;
+    timerIdRef.current = setTimeout(
+      () => timerExpiredRef.current(),
+      waitRef.current
+    );
+    if (leadingRef.current) {
+      invokeRef.current(time);
+    }
+  };
+  (0, import_react.useEffect)(() => {
+    return () => {
+      if (timerIdRef.current !== void 0) {
+        clearTimeout(timerIdRef.current);
+      }
+    };
+  }, []);
+  (0, import_react.useEffect)(() => {
+    if (Object.is(prevValueRef.current, value)) {
+      return;
+    }
+    prevValueRef.current = value;
+    const time = now();
+    const isInvoking = shouldInvokeRef.current(time);
+    lastValueRef.current = value;
+    lastCallTimeRef.current = time;
+    if (isInvoking) {
+      if (timerIdRef.current === void 0) {
+        leadingEdgeRef.current(time);
+      } else if (maxingRef.current) {
+        clearTimeout(timerIdRef.current);
+        timerIdRef.current = setTimeout(
+          () => timerExpiredRef.current(),
+          waitRef.current
+        );
+        invokeRef.current(time);
+      }
+    } else {
+      if (timerIdRef.current === void 0) {
+        timerIdRef.current = setTimeout(
+          () => timerExpiredRef.current(),
+          waitRef.current
+        );
+      }
+    }
+  }, [value]);
+  return debouncedValue;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useDebounce
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/useDebounce.ts"],"sourcesContent":["export { useDebounce, type UseDebounceOptions } from \"./useDebounce\";\r\n","import { useEffect, useRef, useState } from \"react\";\r\n\r\n/**\r\n * Options for useDebounce hook\r\n */\r\nexport interface UseDebounceOptions {\r\n  /**\r\n   * Maximum time the debounced value can be delayed\r\n   * @default undefined (no maximum)\r\n   */\r\n  maxWait?: number;\r\n  /**\r\n   * Whether to update the debounced value on the leading edge\r\n   * @default false\r\n   */\r\n  leading?: boolean;\r\n  /**\r\n   * Whether to update the debounced value on the trailing edge\r\n   * @default true\r\n   */\r\n  trailing?: boolean;\r\n}\r\n\r\n/**\r\n * Debounces a value by delaying updates until after a specified delay period has elapsed\r\n * since the last time the value changed.\r\n *\r\n * @template T - The type of the value to debounce\r\n * @param value - The value to debounce\r\n * @param delay - The delay in milliseconds (default: 500ms)\r\n * @param options - Additional options for controlling debounce behavior\r\n * @returns The debounced value\r\n *\r\n * @example\r\n * ```tsx\r\n * function SearchInput() {\r\n *   const [searchTerm, setSearchTerm] = useState('');\r\n *   const debouncedSearchTerm = useDebounce(searchTerm, 500);\r\n *\r\n *   useEffect(() => {\r\n *     if (debouncedSearchTerm) {\r\n *       // API call with debounced value\r\n *       searchAPI(debouncedSearchTerm);\r\n *     }\r\n *   }, [debouncedSearchTerm]);\r\n *\r\n *   return (\r\n *     <input\r\n *       type=\"text\"\r\n *       value={searchTerm}\r\n *       onChange={(e) => setSearchTerm(e.target.value)}\r\n *       placeholder=\"Search...\"\r\n *     />\r\n *   );\r\n * }\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // With leading edge update\r\n * const debouncedValue = useDebounce(value, 300, { leading: true });\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // With maximum wait time\r\n * const debouncedValue = useDebounce(value, 500, { maxWait: 2000 });\r\n * ```\r\n */\r\nexport function useDebounce<T>(\r\n  value: T,\r\n  delay: number = 500,\r\n  options: UseDebounceOptions = {}\r\n): T {\r\n  // Parse options\r\n  const wait = delay || 0;\r\n  const leading = options.leading ?? false;\r\n  const trailing = options.trailing !== undefined ? options.trailing : true;\r\n  const maxing = \"maxWait\" in options;\r\n  const maxWait = maxing ? Math.max(options.maxWait || 0, wait) : undefined;\r\n\r\n  const [debouncedValue, setDebouncedValue] = useState<T>(value);\r\n  const timerIdRef = useRef<ReturnType<typeof setTimeout> | undefined>(\r\n    undefined\r\n  );\r\n  const lastCallTimeRef = useRef<number | undefined>(undefined);\r\n  const lastInvokeTimeRef = useRef<number>(0);\r\n  const lastValueRef = useRef<T>(value);\r\n  const prevValueRef = useRef<T>(value); // Track previous value to detect actual changes\r\n\r\n  // Store options in refs to access latest values in timer callbacks\r\n  const waitRef = useRef(wait);\r\n  const leadingRef = useRef(leading);\r\n  const trailingRef = useRef(trailing);\r\n  const maxingRef = useRef(maxing);\r\n  const maxWaitRef = useRef(maxWait);\r\n\r\n  // Update refs when options change\r\n  waitRef.current = wait;\r\n  leadingRef.current = leading;\r\n  trailingRef.current = trailing;\r\n  maxingRef.current = maxing;\r\n  maxWaitRef.current = maxWait;\r\n\r\n  // Helper function to get current time\r\n  const now = () => Date.now();\r\n\r\n  // Define helper functions using refs for latest values\r\n  const shouldInvokeRef = useRef<(time: number) => boolean>(() => false);\r\n  const invokeRef = useRef<(time: number) => void>(() => {});\r\n  const remainingWaitRef = useRef<(time: number) => number>(() => 0);\r\n  const timerExpiredRef = useRef<() => void>(() => {});\r\n  const trailingEdgeRef = useRef<(time: number) => void>(() => {});\r\n  const leadingEdgeRef = useRef<(time: number) => void>(() => {});\r\n\r\n  // Helper function: shouldInvoke\r\n  shouldInvokeRef.current = (time: number): boolean => {\r\n    const lastCallTime = lastCallTimeRef.current;\r\n    if (lastCallTime === undefined) {\r\n      return true; // First call\r\n    }\r\n\r\n    const timeSinceLastCall = time - lastCallTime;\r\n    const timeSinceLastInvoke = time - lastInvokeTimeRef.current;\r\n\r\n    return (\r\n      timeSinceLastCall >= waitRef.current ||\r\n      timeSinceLastCall < 0 || // System time went backwards\r\n      (maxingRef.current &&\r\n        timeSinceLastInvoke >= (maxWaitRef.current as number))\r\n    );\r\n  };\r\n\r\n  // Helper function: invokeFunc\r\n  invokeRef.current = (time: number): void => {\r\n    setDebouncedValue(lastValueRef.current);\r\n    lastInvokeTimeRef.current = time;\r\n  };\r\n\r\n  // Helper function: remainingWait\r\n  remainingWaitRef.current = (time: number): number => {\r\n    const lastCallTime = lastCallTimeRef.current;\r\n    if (lastCallTime === undefined) {\r\n      return waitRef.current;\r\n    }\r\n\r\n    const timeSinceLastCall = time - lastCallTime;\r\n    const timeSinceLastInvoke = time - lastInvokeTimeRef.current;\r\n    const timeWaiting = waitRef.current - timeSinceLastCall;\r\n\r\n    return maxingRef.current\r\n      ? Math.min(\r\n          timeWaiting,\r\n          (maxWaitRef.current as number) - timeSinceLastInvoke\r\n        )\r\n      : timeWaiting;\r\n  };\r\n\r\n  // Helper function: trailingEdge\r\n  trailingEdgeRef.current = (time: number): void => {\r\n    timerIdRef.current = undefined;\r\n\r\n    // Only invoke if we have `lastValueRef.current` which means `value` has been\r\n    // debounced at least once.\r\n    if (trailingRef.current && lastCallTimeRef.current !== undefined) {\r\n      invokeRef.current(time);\r\n    }\r\n  };\r\n\r\n  // Helper function: timerExpired\r\n  timerExpiredRef.current = (): void => {\r\n    const time = now();\r\n    if (shouldInvokeRef.current(time)) {\r\n      trailingEdgeRef.current(time);\r\n    } else {\r\n      // Restart the timer.\r\n      timerIdRef.current = setTimeout(\r\n        () => timerExpiredRef.current(),\r\n        remainingWaitRef.current(time)\r\n      );\r\n    }\r\n  };\r\n\r\n  // Helper function: leadingEdge\r\n  leadingEdgeRef.current = (time: number): void => {\r\n    // Reset any `maxWait` timer.\r\n    lastInvokeTimeRef.current = time;\r\n    // Start the timer for the trailing edge.\r\n    timerIdRef.current = setTimeout(\r\n      () => timerExpiredRef.current(),\r\n      waitRef.current\r\n    );\r\n    // Invoke the leading edge.\r\n    if (leadingRef.current) {\r\n      invokeRef.current(time);\r\n    }\r\n  };\r\n\r\n  // Cleanup on unmount only\r\n  useEffect(() => {\r\n    return () => {\r\n      if (timerIdRef.current !== undefined) {\r\n        clearTimeout(timerIdRef.current);\r\n      }\r\n    };\r\n  }, []);\r\n\r\n  // Main debounce effect - runs when value changes\r\n  useEffect(() => {\r\n    // Skip if value hasn't actually changed (prevents initial render from consuming leading edge)\r\n    if (Object.is(prevValueRef.current, value)) {\r\n      return;\r\n    }\r\n    prevValueRef.current = value;\r\n\r\n    const time = now();\r\n    const isInvoking = shouldInvokeRef.current(time);\r\n\r\n    // Update lastValueRef with current value\r\n    lastValueRef.current = value;\r\n    lastCallTimeRef.current = time;\r\n\r\n    if (isInvoking) {\r\n      if (timerIdRef.current === undefined) {\r\n        leadingEdgeRef.current(time);\r\n      } else if (maxingRef.current) {\r\n        // Handle invocations in a tight loop.\r\n        clearTimeout(timerIdRef.current);\r\n        timerIdRef.current = setTimeout(\r\n          () => timerExpiredRef.current(),\r\n          waitRef.current\r\n        );\r\n        invokeRef.current(time);\r\n      }\r\n    } else {\r\n      if (timerIdRef.current === undefined) {\r\n        // Start timer with wait\r\n        // remainingWait is only used inside timerExpired for restarting\r\n        timerIdRef.current = setTimeout(\r\n          () => timerExpiredRef.current(),\r\n          waitRef.current\r\n        );\r\n      }\r\n    }\r\n    // No cleanup here - timer should persist across value changes\r\n    // This is the key difference from the previous implementation\r\n  }, [value]);\r\n\r\n  return debouncedValue;\r\n}\r\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -0,0 +1,133 @@
+// src/useDebounce.ts
+import { useEffect, useRef, useState } from "react";
+function useDebounce(value, delay = 500, options = {}) {
+  const wait = delay || 0;
+  const leading = options.leading ?? false;
+  const trailing = options.trailing !== void 0 ? options.trailing : true;
+  const maxing = "maxWait" in options;
+  const maxWait = maxing ? Math.max(options.maxWait || 0, wait) : void 0;
+  const [debouncedValue, setDebouncedValue] = useState(value);
+  const timerIdRef = useRef(
+    void 0
+  );
+  const lastCallTimeRef = useRef(void 0);
+  const lastInvokeTimeRef = useRef(0);
+  const lastValueRef = useRef(value);
+  const prevValueRef = useRef(value);
+  const waitRef = useRef(wait);
+  const leadingRef = useRef(leading);
+  const trailingRef = useRef(trailing);
+  const maxingRef = useRef(maxing);
+  const maxWaitRef = useRef(maxWait);
+  waitRef.current = wait;
+  leadingRef.current = leading;
+  trailingRef.current = trailing;
+  maxingRef.current = maxing;
+  maxWaitRef.current = maxWait;
+  const now = () => Date.now();
+  const shouldInvokeRef = useRef(() => false);
+  const invokeRef = useRef(() => {
+  });
+  const remainingWaitRef = useRef(() => 0);
+  const timerExpiredRef = useRef(() => {
+  });
+  const trailingEdgeRef = useRef(() => {
+  });
+  const leadingEdgeRef = useRef(() => {
+  });
+  shouldInvokeRef.current = (time) => {
+    const lastCallTime = lastCallTimeRef.current;
+    if (lastCallTime === void 0) {
+      return true;
+    }
+    const timeSinceLastCall = time - lastCallTime;
+    const timeSinceLastInvoke = time - lastInvokeTimeRef.current;
+    return timeSinceLastCall >= waitRef.current || timeSinceLastCall < 0 || // System time went backwards
+    maxingRef.current && timeSinceLastInvoke >= maxWaitRef.current;
+  };
+  invokeRef.current = (time) => {
+    setDebouncedValue(lastValueRef.current);
+    lastInvokeTimeRef.current = time;
+  };
+  remainingWaitRef.current = (time) => {
+    const lastCallTime = lastCallTimeRef.current;
+    if (lastCallTime === void 0) {
+      return waitRef.current;
+    }
+    const timeSinceLastCall = time - lastCallTime;
+    const timeSinceLastInvoke = time - lastInvokeTimeRef.current;
+    const timeWaiting = waitRef.current - timeSinceLastCall;
+    return maxingRef.current ? Math.min(
+      timeWaiting,
+      maxWaitRef.current - timeSinceLastInvoke
+    ) : timeWaiting;
+  };
+  trailingEdgeRef.current = (time) => {
+    timerIdRef.current = void 0;
+    if (trailingRef.current && lastCallTimeRef.current !== void 0) {
+      invokeRef.current(time);
+    }
+  };
+  timerExpiredRef.current = () => {
+    const time = now();
+    if (shouldInvokeRef.current(time)) {
+      trailingEdgeRef.current(time);
+    } else {
+      timerIdRef.current = setTimeout(
+        () => timerExpiredRef.current(),
+        remainingWaitRef.current(time)
+      );
+    }
+  };
+  leadingEdgeRef.current = (time) => {
+    lastInvokeTimeRef.current = time;
+    timerIdRef.current = setTimeout(
+      () => timerExpiredRef.current(),
+      waitRef.current
+    );
+    if (leadingRef.current) {
+      invokeRef.current(time);
+    }
+  };
+  useEffect(() => {
+    return () => {
+      if (timerIdRef.current !== void 0) {
+        clearTimeout(timerIdRef.current);
+      }
+    };
+  }, []);
+  useEffect(() => {
+    if (Object.is(prevValueRef.current, value)) {
+      return;
+    }
+    prevValueRef.current = value;
+    const time = now();
+    const isInvoking = shouldInvokeRef.current(time);
+    lastValueRef.current = value;
+    lastCallTimeRef.current = time;
+    if (isInvoking) {
+      if (timerIdRef.current === void 0) {
+        leadingEdgeRef.current(time);
+      } else if (maxingRef.current) {
+        clearTimeout(timerIdRef.current);
+        timerIdRef.current = setTimeout(
+          () => timerExpiredRef.current(),
+          waitRef.current
+        );
+        invokeRef.current(time);
+      }
+    } else {
+      if (timerIdRef.current === void 0) {
+        timerIdRef.current = setTimeout(
+          () => timerExpiredRef.current(),
+          waitRef.current
+        );
+      }
+    }
+  }, [value]);
+  return debouncedValue;
+}
+export {
+  useDebounce
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useDebounce.ts"],"sourcesContent":["import { useEffect, useRef, useState } from \"react\";\r\n\r\n/**\r\n * Options for useDebounce hook\r\n */\r\nexport interface UseDebounceOptions {\r\n  /**\r\n   * Maximum time the debounced value can be delayed\r\n   * @default undefined (no maximum)\r\n   */\r\n  maxWait?: number;\r\n  /**\r\n   * Whether to update the debounced value on the leading edge\r\n   * @default false\r\n   */\r\n  leading?: boolean;\r\n  /**\r\n   * Whether to update the debounced value on the trailing edge\r\n   * @default true\r\n   */\r\n  trailing?: boolean;\r\n}\r\n\r\n/**\r\n * Debounces a value by delaying updates until after a specified delay period has elapsed\r\n * since the last time the value changed.\r\n *\r\n * @template T - The type of the value to debounce\r\n * @param value - The value to debounce\r\n * @param delay - The delay in milliseconds (default: 500ms)\r\n * @param options - Additional options for controlling debounce behavior\r\n * @returns The debounced value\r\n *\r\n * @example\r\n * ```tsx\r\n * function SearchInput() {\r\n *   const [searchTerm, setSearchTerm] = useState('');\r\n *   const debouncedSearchTerm = useDebounce(searchTerm, 500);\r\n *\r\n *   useEffect(() => {\r\n *     if (debouncedSearchTerm) {\r\n *       // API call with debounced value\r\n *       searchAPI(debouncedSearchTerm);\r\n *     }\r\n *   }, [debouncedSearchTerm]);\r\n *\r\n *   return (\r\n *     <input\r\n *       type=\"text\"\r\n *       value={searchTerm}\r\n *       onChange={(e) => setSearchTerm(e.target.value)}\r\n *       placeholder=\"Search...\"\r\n *     />\r\n *   );\r\n * }\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // With leading edge update\r\n * const debouncedValue = useDebounce(value, 300, { leading: true });\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // With maximum wait time\r\n * const debouncedValue = useDebounce(value, 500, { maxWait: 2000 });\r\n * ```\r\n */\r\nexport function useDebounce<T>(\r\n  value: T,\r\n  delay: number = 500,\r\n  options: UseDebounceOptions = {}\r\n): T {\r\n  // Parse options\r\n  const wait = delay || 0;\r\n  const leading = options.leading ?? false;\r\n  const trailing = options.trailing !== undefined ? options.trailing : true;\r\n  const maxing = \"maxWait\" in options;\r\n  const maxWait = maxing ? Math.max(options.maxWait || 0, wait) : undefined;\r\n\r\n  const [debouncedValue, setDebouncedValue] = useState<T>(value);\r\n  const timerIdRef = useRef<ReturnType<typeof setTimeout> | undefined>(\r\n    undefined\r\n  );\r\n  const lastCallTimeRef = useRef<number | undefined>(undefined);\r\n  const lastInvokeTimeRef = useRef<number>(0);\r\n  const lastValueRef = useRef<T>(value);\r\n  const prevValueRef = useRef<T>(value); // Track previous value to detect actual changes\r\n\r\n  // Store options in refs to access latest values in timer callbacks\r\n  const waitRef = useRef(wait);\r\n  const leadingRef = useRef(leading);\r\n  const trailingRef = useRef(trailing);\r\n  const maxingRef = useRef(maxing);\r\n  const maxWaitRef = useRef(maxWait);\r\n\r\n  // Update refs when options change\r\n  waitRef.current = wait;\r\n  leadingRef.current = leading;\r\n  trailingRef.current = trailing;\r\n  maxingRef.current = maxing;\r\n  maxWaitRef.current = maxWait;\r\n\r\n  // Helper function to get current time\r\n  const now = () => Date.now();\r\n\r\n  // Define helper functions using refs for latest values\r\n  const shouldInvokeRef = useRef<(time: number) => boolean>(() => false);\r\n  const invokeRef = useRef<(time: number) => void>(() => {});\r\n  const remainingWaitRef = useRef<(time: number) => number>(() => 0);\r\n  const timerExpiredRef = useRef<() => void>(() => {});\r\n  const trailingEdgeRef = useRef<(time: number) => void>(() => {});\r\n  const leadingEdgeRef = useRef<(time: number) => void>(() => {});\r\n\r\n  // Helper function: shouldInvoke\r\n  shouldInvokeRef.current = (time: number): boolean => {\r\n    const lastCallTime = lastCallTimeRef.current;\r\n    if (lastCallTime === undefined) {\r\n      return true; // First call\r\n    }\r\n\r\n    const timeSinceLastCall = time - lastCallTime;\r\n    const timeSinceLastInvoke = time - lastInvokeTimeRef.current;\r\n\r\n    return (\r\n      timeSinceLastCall >= waitRef.current ||\r\n      timeSinceLastCall < 0 || // System time went backwards\r\n      (maxingRef.current &&\r\n        timeSinceLastInvoke >= (maxWaitRef.current as number))\r\n    );\r\n  };\r\n\r\n  // Helper function: invokeFunc\r\n  invokeRef.current = (time: number): void => {\r\n    setDebouncedValue(lastValueRef.current);\r\n    lastInvokeTimeRef.current = time;\r\n  };\r\n\r\n  // Helper function: remainingWait\r\n  remainingWaitRef.current = (time: number): number => {\r\n    const lastCallTime = lastCallTimeRef.current;\r\n    if (lastCallTime === undefined) {\r\n      return waitRef.current;\r\n    }\r\n\r\n    const timeSinceLastCall = time - lastCallTime;\r\n    const timeSinceLastInvoke = time - lastInvokeTimeRef.current;\r\n    const timeWaiting = waitRef.current - timeSinceLastCall;\r\n\r\n    return maxingRef.current\r\n      ? Math.min(\r\n          timeWaiting,\r\n          (maxWaitRef.current as number) - timeSinceLastInvoke\r\n        )\r\n      : timeWaiting;\r\n  };\r\n\r\n  // Helper function: trailingEdge\r\n  trailingEdgeRef.current = (time: number): void => {\r\n    timerIdRef.current = undefined;\r\n\r\n    // Only invoke if we have `lastValueRef.current` which means `value` has been\r\n    // debounced at least once.\r\n    if (trailingRef.current && lastCallTimeRef.current !== undefined) {\r\n      invokeRef.current(time);\r\n    }\r\n  };\r\n\r\n  // Helper function: timerExpired\r\n  timerExpiredRef.current = (): void => {\r\n    const time = now();\r\n    if (shouldInvokeRef.current(time)) {\r\n      trailingEdgeRef.current(time);\r\n    } else {\r\n      // Restart the timer.\r\n      timerIdRef.current = setTimeout(\r\n        () => timerExpiredRef.current(),\r\n        remainingWaitRef.current(time)\r\n      );\r\n    }\r\n  };\r\n\r\n  // Helper function: leadingEdge\r\n  leadingEdgeRef.current = (time: number): void => {\r\n    // Reset any `maxWait` timer.\r\n    lastInvokeTimeRef.current = time;\r\n    // Start the timer for the trailing edge.\r\n    timerIdRef.current = setTimeout(\r\n      () => timerExpiredRef.current(),\r\n      waitRef.current\r\n    );\r\n    // Invoke the leading edge.\r\n    if (leadingRef.current) {\r\n      invokeRef.current(time);\r\n    }\r\n  };\r\n\r\n  // Cleanup on unmount only\r\n  useEffect(() => {\r\n    return () => {\r\n      if (timerIdRef.current !== undefined) {\r\n        clearTimeout(timerIdRef.current);\r\n      }\r\n    };\r\n  }, []);\r\n\r\n  // Main debounce effect - runs when value changes\r\n  useEffect(() => {\r\n    // Skip if value hasn't actually changed (prevents initial render from consuming leading edge)\r\n    if (Object.is(prevValueRef.current, value)) {\r\n      return;\r\n    }\r\n    prevValueRef.current = value;\r\n\r\n    const time = now();\r\n    const isInvoking = shouldInvokeRef.current(time);\r\n\r\n    // Update lastValueRef with current value\r\n    lastValueRef.current = value;\r\n    lastCallTimeRef.current = time;\r\n\r\n    if (isInvoking) {\r\n      if (timerIdRef.current === undefined) {\r\n        leadingEdgeRef.current(time);\r\n      } else if (maxingRef.current) {\r\n        // Handle invocations in a tight loop.\r\n        clearTimeout(timerIdRef.current);\r\n        timerIdRef.current = setTimeout(\r\n          () => timerExpiredRef.current(),\r\n          waitRef.current\r\n        );\r\n        invokeRef.current(time);\r\n      }\r\n    } else {\r\n      if (timerIdRef.current === undefined) {\r\n        // Start timer with wait\r\n        // remainingWait is only used inside timerExpired for restarting\r\n        timerIdRef.current = setTimeout(\r\n          () => timerExpiredRef.current(),\r\n          waitRef.current\r\n        );\r\n      }\r\n    }\r\n    // No cleanup here - timer should persist across value changes\r\n    // This is the key difference from the previous implementation\r\n  }, [value]);\r\n\r\n  return debouncedValue;\r\n}\r\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@usefy/use-debounce",
+  "version": "0.0.2",
+  "description": "A React hook for value debouncing with leading/trailing edge and maxWait options",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
+    "jsdom": "^27.3.0",
+    "react": "^19.0.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geon0529/usefy.git",
+    "directory": "packages/use-debounce"
+  },
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "hooks",
+    "debounce",
+    "delay",
+    "throttle"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}