Merge pull request #6 from Tracktor/feat/use-debounce

feat: add useDebouncedFn hook for debouncing functions in React components

Author: MickaelAustoni

CHANGELOG.md

@@ -1,4 +1,4 @@
 # [Versions](https://github.com/Tracktor/react-utils/releases)
 
-## v1.24.2
-- **[chore]** : Migrate to Bun & GH Actions for CI/CD workflows.
+## v1.25.0
+- **[feat]** : Add `useDebouncedFn` hook for creating debounced functions in React components. (#123)

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tracktor/react-utils",
   "description": "React data table and react data grid",
-  "version": "1.24.2",
+  "version": "1.25.0",
   "private": false,
   "license": "ISC",
   "type": "module",

src/hooks/useDebounce/useDebouncedFn.ts

@@ -0,0 +1,58 @@
+import { useCallback, useEffect, useRef } from "react";
+
+/**
+ * Creates a debounced version of a callback function that delays invoking the function
+ * until after the specified delay has elapsed since the last time it was invoked.
+ *
+ * This hook is useful for optimizing performance by limiting the rate at which a function
+ * can fire, particularly useful for:
+ * - Search input handlers
+ * - Auto-save functionality
+ * - API calls triggered by user input
+ * - Window resize/scroll handlers
+ *
+ * @example
+ * const debouncedSearch = useDebouncedCallback((query: string) => {
+ *   fetchSearchResults(query);
+ * }, 500);
+ *
+ * // Will only execute after user stops typing for 500ms
+ * debouncedSearch(inputValue);
+ */
+const useDebouncedFn = <T extends (...args: never[]) => unknown>(callback: T, delay = 300): ((...args: Parameters<T>) => void) => {
+  // Store the latest callback to avoid stale closures
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  // Store the timeout ID for cleanup
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Create the debounced function (only recreates if delay changes)
+  const debouncedCallback = useCallback(
+    (...args: Parameters<T>) => {
+      // Clear any existing timeout
+      if (timeoutRef.current !== null) {
+        clearTimeout(timeoutRef.current);
+      }
+
+      // Set a new timeout to execute the callback after the delay
+      timeoutRef.current = setTimeout(() => {
+        callbackRef.current(...args);
+      }, delay);
+    },
+    [delay],
+  );
+
+  // Cleanup: clear timeout when component unmounts
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current !== null) {
+        clearTimeout(timeoutRef.current);
+      }
+    };
+  }, []);
+
+  return debouncedCallback;
+};
+
+export default useDebouncedFn;

src/main.ts

@@ -2,6 +2,8 @@
 
 export * from "@/hooks/useDebounce/useDebounce";
 export { default as useDebounce } from "@/hooks/useDebounce/useDebounce";
+export * from "@/hooks/useDebounce/useDebouncedFn";
+export { default as useDebouncedFn } from "@/hooks/useDebounce/useDebouncedFn";
 export * from "@/hooks/useDocumentTitle/useDocumentTitle";
 export { default as useDocumentTitle } from "@/hooks/useDocumentTitle/useDocumentTitle";
 export * from "@/hooks/useEventListener/useEventListener";