feat: add useDelayState hook

Author: zombieJ

src/hooks/useDelayState.ts

@@ -0,0 +1,59 @@
+import * as React from 'react';
+import raf from '../raf';
+import useEvent from './useEvent';
+
+export type DelayConfig =
+  { frame: number; ms?: never } | { frame?: never; ms: number };
+
+export type SetDelayState<T> = (
+  nextValue: React.SetStateAction<T>,
+  /** `true` updates immediately. `false` delays the update by one frame. */
+  immediatelyOrDelay?: boolean | DelayConfig,
+) => void;
+
+/**
+ * Similar to `useState`, but updates on the next frame by default.
+ * Pending updates are always replaced by the latest one.
+ */
+export default function useDelayState<T>(
+  defaultValue: T | (() => T),
+): [T, SetDelayState<T>] {
+  const [value, setValue] = React.useState(defaultValue);
+  const rafRef = React.useRef<number>(null);
+  const timeoutRef = React.useRef<ReturnType<typeof setTimeout>>(null);
+
+  const cancelPending = useEvent(() => {
+    raf.cancel(rafRef.current!);
+    clearTimeout(timeoutRef.current!);
+    rafRef.current = null;
+    timeoutRef.current = null;
+  });
+
+  const setDelayValue = useEvent<SetDelayState<T>>(
+    (nextValue, immediatelyOrDelay) => {
+      cancelPending();
+
+      if (immediatelyOrDelay === true) {
+        setValue(nextValue);
+      } else if (
+        typeof immediatelyOrDelay === 'object' &&
+        'ms' in immediatelyOrDelay
+      ) {
+        timeoutRef.current = setTimeout(
+          () => setValue(nextValue),
+          immediatelyOrDelay.ms,
+        );
+      } else {
+        const frame =
+          typeof immediatelyOrDelay === 'object'
+            ? immediatelyOrDelay.frame
+            : undefined;
+        rafRef.current = raf(() => setValue(nextValue), frame);
+      }
+    },
+  );
+
+  React.useEffect(() => cancelPending, [cancelPending]);
+
+  return [value, setDelayValue];
+}

src/index.ts

@@ -1,6 +1,8 @@
 export { default as useEvent } from './hooks/useEvent';
 export { default as useMergedState } from './hooks/useMergedState';
 export { default as useControlledState } from './hooks/useControlledState';
+export { default as useDelayState } from './hooks/useDelayState';
+export type { DelayConfig, SetDelayState } from './hooks/useDelayState';
 export { default as useId, getId } from './hooks/useId';
 export {
   default as useLayoutEffect,

tests/useDelayState.test.tsx

@@ -0,0 +1,144 @@
+import { act, renderHook } from '@testing-library/react';
+import useDelayState from '../src/hooks/useDelayState';
+
+describe('useDelayState', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.runOnlyPendingTimers();
+    jest.useRealTimers();
+  });
+
+  it('updates on the next frame by default', () => {
+    const { result } = renderHook(() => useDelayState(0));
+
+    act(() => {
+      result.current[1](1);
+    });
+    expect(result.current[0]).toBe(0);
+
+    act(() => {
+      jest.advanceTimersByTime(16);
+    });
+    expect(result.current[0]).toBe(1);
+  });
+
+  it('updates immediately', () => {
+    const { result } = renderHook(() => useDelayState(0));
+
+    act(() => {
+      result.current[1](1, true);
+    });
+    expect(result.current[0]).toBe(1);
+  });
+
+  it('delays when immediate is false', () => {
+    const { result } = renderHook(() => useDelayState(0));
+
+    act(() => {
+      result.current[1](1, false);
+    });
+    expect(result.current[0]).toBe(0);
+
+    act(() => {
+      jest.advanceTimersByTime(16);
+    });
+    expect(result.current[0]).toBe(1);
+  });
+
+  it('supports frame delay', () => {
+    const { result } = renderHook(() => useDelayState(0));
+
+    act(() => {
+      result.current[1](1, { frame: 2 });
+      jest.advanceTimersByTime(16);
+    });
+    expect(result.current[0]).toBe(0);
+
+    act(() => {
+      jest.advanceTimersByTime(16);
+    });
+    expect(result.current[0]).toBe(1);
+  });
+
+  it('supports millisecond delay', () => {
+    const { result } = renderHook(() => useDelayState(0));
+
+    act(() => {
+      result.current[1](1, { ms: 100 });
+      jest.advanceTimersByTime(99);
+    });
+    expect(result.current[0]).toBe(0);
+
+    act(() => {
+      jest.advanceTimersByTime(1);
+    });
+    expect(result.current[0]).toBe(1);
+  });
+
+  it('uses the latest pending update', () => {
+    const { result } = renderHook(() => useDelayState(0));
+
+    act(() => {
+      result.current[1](1, { ms: 100 });
+      result.current[1](2);
+      jest.advanceTimersByTime(16);
+    });
+    expect(result.current[0]).toBe(2);
+
+    act(() => {
+      jest.advanceTimersByTime(100);
+    });
+    expect(result.current[0]).toBe(2);
+
+    act(() => {
+      result.current[1](3, { frame: 2 });
+      result.current[1](4, { ms: 100 });
+      jest.advanceTimersByTime(32);
+    });
+    expect(result.current[0]).toBe(2);
+
+    act(() => {
+      jest.advanceTimersByTime(68);
+    });
+    expect(result.current[0]).toBe(4);
+  });
+
+  it('cancels a pending update when updating immediately', () => {
+    const { result } = renderHook(() => useDelayState(0));
+
+    act(() => {
+      result.current[1](1, { frame: 2 });
+      result.current[1](2, true);
+    });
+    expect(result.current[0]).toBe(2);
+
+    act(() => {
+      jest.advanceTimersByTime(32);
+    });
+    expect(result.current[0]).toBe(2);
+  });
+
+  it('supports updater function', () => {
+    const { result } = renderHook(() => useDelayState(1));
+
+    act(() => {
+      result.current[1](value => value + 1);
+      jest.advanceTimersByTime(16);
+    });
+    expect(result.current[0]).toBe(2);
+  });
+
+  it('cancels pending update on unmount', () => {
+    const { result, unmount } = renderHook(() => useDelayState(0));
+
+    act(() => {
+      result.current[1](1, { ms: 100 });
+    });
+    unmount();
+
+    expect(jest.getTimerCount()).toBe(0);
+  });
+});