fix: expose the control methods on useDebouncedValue

The hook already returned the setter with control options, but it wasn't exposed to TypeScript. Adjust this so you can properly access them, and add tests to validate it.

README.md

@@ -43,6 +43,26 @@ setDebouncedValue("World");
 console.log(debouncedValue); // Will log "Hello" until 500ms has passed
 ```
 
+The `setDebouncedValue` also contains a few control methods, that can be useful:
+
+- `flush`: Call the callback immediately, and cancel debouncing.
+- `cancel`: Cancel debouncing, and the callback will never be called.
+- `isPending`: Check if the callback is waiting to be called.
+  You can use them like this:
+
+```tsx
+const [debouncedValue, setDebouncedValue] = useDebouncedValue(
+  initialValue,
+  500,
+);
+
+setDebouncedValue("Hello");
+setDebouncedValue.isPending(); // true
+setDebouncedValue.flush(); // Logs "Hello"
+setDebouncedValue("world");
+setDebouncedValue.cancel(); // Will never log "world"
+```
+
 ### `useDebouncedCallback`
 
 Debounce a callback function. The callback will only be called after the delay has passed without the function being called again.
@@ -58,10 +78,10 @@ debouncedCallback("Hello");
 debouncedCallback("World"); // Will only log "World" after 500ms
 ```
 
-The `debouncedCallback` also contains a few methods, that can be useful:
+The `debouncedCallback` also contains a few control methods, that can be useful:
 
-- `flush`: Call the callback immediately, and cancel the debounce.
-- `cancel`: Cancel the debounce, and the callback will never be called.
+- `flush`: Call the callback immediately, and cancel debouncing.
+- `cancel`: Cancel debouncing, and the callback will never be called.
 - `isPending`: Check if the callback is waiting to be called.
 
 You can use them like this:

src/__tests__/useDebouncedValue.test.tsx

@@ -48,7 +48,6 @@ test("should update if 'initial value' is changed", async () => {
   const { result, rerender } = renderHook((initialValue = "hello") =>
     useDebouncedValue(initialValue, 500),
   );
-
   expect(result.current[0]).toBe("hello");
   rerender("world");
 
@@ -77,3 +76,29 @@ test("should update the value immediately if leading is true", async () => {
     vi.runAllTimers();
   });
 });
+
+test("should be able to flush the debounce", async () => {
+  const initialValue = "hello";
+  const { result } = renderHook(() => useDebouncedValue(initialValue, 500));
+
+  expect(result.current[0]).toBe(initialValue);
+  result.current[1]("world");
+  expect(result.current[1].isPending()).toBe(true);
+  act(() => {
+    result.current[1].flush();
+  });
+  expect(result.current[0]).toBe("world");
+});
+
+test("should be able to cancel the debounce", async () => {
+  const initialValue = "hello";
+  const { result } = renderHook(() => useDebouncedValue(initialValue, 500));
+
+  expect(result.current[0]).toBe(initialValue);
+  result.current[1]("world");
+  expect(result.current[1].isPending()).toBe(true);
+  act(() => {
+    result.current[1].cancel();
+  });
+  expect(result.current[0]).toBe("hello");
+});

src/hooks/useDebouncedValue.ts

@@ -31,7 +31,7 @@ export function useDebouncedValue<T>(
   initialValue: T,
   wait: number,
   options: DebounceOptions = { trailing: true },
-): [T, (value: T) => void] {
+) {
   const [debouncedValue, setDebouncedValue] = useState<T>(initialValue);
   const previousValueRef = useRef<T | undefined>(initialValue);
 
@@ -47,5 +47,5 @@ export function useDebouncedValue<T>(
     previousValueRef.current = initialValue;
   }
 
-  return [debouncedValue, updateDebouncedValue];
+  return [debouncedValue, updateDebouncedValue] as const;
 }