refactor(debounce): replace es-toolkit with custom debounce (#2707)

* refactor(debounce): replace es-toolkit with custom debounce implementation

Drops the `es-toolkit` dependency in favor of an in-repo debounce utility.
The custom implementation fixes a re-entrancy bug present in es-toolkit
(pending args lost when the callback re-invokes the debounced function),
preserves `this` context, and adds `maxWait` support plus runtime input
validation.

- Add `src/utils/debounce` with `debounce` and `DebouncedFunction<Args>`
- Remove `src/utils/asyncDebounce` (thin wrapper over es-toolkit)
- Retype `useDebouncedCallback` with `Args extends unknown[]` (no `any`)

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

* fix : lint

* refactor(debounce): rename baselineTime, unify wait, document stability

- Rename `lastInvokeTime` → `baselineTime` to reflect its actual role as the maxWait baseline
- Replace sentinel `0` with `undefined` so `Date.now() === 0` edge cases do not misfire
- Unify parameter name `debounceMs` → `wait` across `debounce()` (matches lodash/es-toolkit and `useDebouncedCallback`)
- Add JSDoc to `useDebouncedCallback` warning about passing stable references for `callback` / `options`

No behavior change. 92/92 tests pass, `pnpm check` clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

* refactor(debounce): stabilize callback ref, add dispose, tidy tests

- useDebouncedCallback: hold latest callback in a ref so inline arrows
  no longer drop pending timers; normalize edges via booleans so array
  reference/order changes don't recreate the debounced instance
- debounce: add dispose() to detach the external signal abort listener
  via an internal AbortController, short-circuit schedule() when there
  is nothing to do, and switch Reflect.apply to func.apply
- tests: parameterize validation and "no-op from terminal state"
  matrices with it.for, add retention/dispose/edges-identity cases,
  and cover the maxWait forced-fire branch; 100% coverage on both files

* fix: lint

---------

Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>

Author: devmgn

AGENTS.md

@@ -7,7 +7,7 @@
 - **TanStack Query** with queryOptions helper
 - **React Hook Form + Zod v4** with @hookform/resolvers
 - **UI**: @radix-ui primitives, tailwind-variants, tailwind-merge
-- **Utilities**: es-toolkit (lodash alternative)
+- **Utilities**: custom debounce (`src/utils/debounce`)
 - **nuqs** for URL state management (NuqsAdapter in RootProvider)
 - **OxC** (Oxlint + Oxfmt) for linting and formatting
   - jsPlugins: @tanstack/eslint-plugin-query, eslint-plugin-react-hooks

package.json

@@ -33,7 +33,6 @@
     "@radix-ui/react-slot": "1.2.4",
     "@tanstack/react-query": "5.99.0",
     "@tanstack/react-query-devtools": "5.99.0",
-    "es-toolkit": "1.45.1",
     "next": "16.2.4",
     "nuqs": "2.8.9",
     "react": "19.2.5",

pnpm-lock.yaml

@@ -1,7 +1,6 @@
 "use client";
 
 import { FaceIcon } from "@radix-ui/react-icons";
-import { isArray } from "es-toolkit/compat";
 import { Backdrop } from "../../../components/Backdrop";
 import { Card } from "../../../components/Card";
 import { Spinner } from "../../../components/Spinner";
@@ -11,7 +10,6 @@ import { useDisclosure } from "../../../hooks/useDisclosure";
 import { useIsComposing } from "../../../hooks/useIsComposing";
 import { useLocalStorage } from "../../../hooks/useLocalStorage";
 import { useMediaQuery } from "../../../hooks/useMediaQuery";
-import { asyncDebounce } from "../../../utils/asyncDebounce";
 import { createCustomEvent } from "../../../utils/createCustomEvent";
 import { isKeyOf } from "../../../utils/isKeyOf";
 import { isValueOf } from "../../../utils/isValueOf";
@@ -25,16 +23,13 @@ export default function Page() {
   useIsComposing();
   useLocalStorage("dummy", "");
   useMediaQuery("(min-width: 768px)");
-  asyncDebounce(() => {
-    // noop
-  }, 1000);
   // oxlint-disable-next-line typescript/no-unsafe-type-assertion
   createCustomEvent("" as keyof GlobalEventHandlersEventMap);
   const _isServer = isServer;
   const _isDevelopment = isDevelopment;
   const _isKeyOf = isKeyOf({}, "");
   const _isValueOf = isValueOf({}, "");
-  const _isArray = isArray([]);
+  const _isArray = Array.isArray([]);
 
   return (
     <>

src/app/(sandbox)/dummy/page.tsx

@@ -144,20 +144,182 @@ describe(useDebouncedCallback, () => {
     expect(callback).toHaveBeenCalledTimes(1);
   });
 
-  it("schedule メソッドでdebounce実行をスケジュールできること", () => {
+  it("schedule メソッドで保留中のタイマーが延長され lastArgs が保持されること", () => {
     const callback = vi.fn();
     const { result } = renderHook(() => useDebouncedCallback(callback, 500));
 
     act(() => {
       result.current("test");
+    });
+
+    // 発火直前まで進める
+    act(() => {
+      vi.advanceTimersByTime(400);
+    });
+    expect(callback).not.toHaveBeenCalled();
+
+    // schedule でタイマーを再スタート
+    act(() => {
       result.current.schedule();
     });
+
+    // 旧タイマーが発火するはずの時間を過ぎても未発火
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
     expect(callback).not.toHaveBeenCalled();
 
+    // 新タイマー分の経過で lastArgs を保持したまま発火
+    act(() => {
+      vi.advanceTimersByTime(400);
+    });
+    expect(callback).toHaveBeenCalledExactlyOnceWith("test");
+  });
+
+  it("edges: ['leading'] オプションで先頭のみ実行され trailing は発火しないこと", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() =>
+      useDebouncedCallback(callback, 500, { edges: ["leading"] }),
+    );
+
+    act(() => {
+      result.current();
+    });
+    expect(callback).toHaveBeenCalledTimes(1);
+
+    // クールダウン中の呼び出しは発火しない
+    act(() => {
+      result.current();
+    });
+    expect(callback).toHaveBeenCalledTimes(1);
+
+    // trailing 無効なのでタイマー経過後も追加発火なし
     act(() => {
       vi.advanceTimersByTime(500);
     });
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
 
-    expect(callback).toHaveBeenCalledExactlyOnceWith("test");
+  it("AbortSignal が abort されると保留中および以降の呼び出しが無効化されること", () => {
+    const callback = vi.fn();
+    const controller = new AbortController();
+    const { result } = renderHook(() =>
+      useDebouncedCallback(callback, 500, { signal: controller.signal }),
+    );
+
+    act(() => {
+      result.current();
+    });
+
+    // abort で保留中の実行がキャンセルされる
+    act(() => {
+      controller.abort();
+      vi.advanceTimersByTime(500);
+    });
+    expect(callback).not.toHaveBeenCalled();
+
+    // abort 後の呼び出しも無効
+    act(() => {
+      result.current();
+      vi.advanceTimersByTime(500);
+    });
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it("依存が変化しない再レンダリングで同一の debounced 関数が返されること", () => {
+    const callback = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ wait }) => useDebouncedCallback(callback, wait),
+      { initialProps: { wait: 500 } },
+    );
+
+    const prev = result.current;
+    rerender({ wait: 500 });
+    expect(result.current).toBe(prev);
+  });
+
+  it("毎レンダリングで新しいアロー関数を渡しても保留中のタイマーと引数が失われず、最新のコールバックで発火すること", () => {
+    const spy = vi.fn();
+    let current = 0;
+    const { result, rerender } = renderHook(
+      ({ value }) =>
+        useDebouncedCallback((arg: string) => {
+          spy(value, arg);
+        }, 500),
+      { initialProps: { value: current } },
+    );
+
+    // 最初の呼び出しでタイマー開始
+    const first = result.current;
+    act(() => {
+      first("args");
+    });
+
+    // value を更新して再レンダリング。ここで debounced が再生成されると
+    // タイマーが失われてしまう。
+    current = 1;
+    rerender({ value: current });
+
+    // 同一の debounced 関数が返り続けること
+    expect(result.current).toBe(first);
+
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+
+    // 最新の callback (value=1) で、保持された引数 "args" で発火する
+    expect(spy).toHaveBeenCalledExactlyOnceWith(1, "args");
+  });
+
+  it("options.edges の配列参照が毎レンダリング変わっても、内容が同じなら同一 debounced 関数が返ること", () => {
+    const callback = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ edges }) =>
+        useDebouncedCallback(callback, 500, {
+          edges,
+        }),
+      { initialProps: { edges: ["leading"] as Array<"leading" | "trailing"> } },
+    );
+
+    const prev = result.current;
+    // 内容は同じで新しい配列参照を渡す
+    rerender({
+      edges: ["leading"] as Array<"leading" | "trailing">,
+    });
+
+    expect(result.current).toBe(prev);
+  });
+
+  it("edges が undefined と ['trailing'] (default 相当) で同一 debounced を返すこと", () => {
+    const callback = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ edges }: { edges: Array<"leading" | "trailing"> | undefined }) =>
+        useDebouncedCallback(callback, 500, { edges }),
+      {
+        initialProps: {
+          edges: undefined as Array<"leading" | "trailing"> | undefined,
+        },
+      },
+    );
+
+    const prev = result.current;
+    rerender({ edges: ["trailing"] });
+    expect(result.current).toBe(prev);
+  });
+
+  it("edges の順序が異なっても内容が同じなら同一 debounced を返すこと", () => {
+    const callback = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ edges }) => useDebouncedCallback(callback, 500, { edges }),
+      {
+        initialProps: {
+          edges: ["leading", "trailing"] as Array<"leading" | "trailing">,
+        },
+      },
+    );
+
+    const prev = result.current;
+    rerender({ edges: ["trailing", "leading"] });
+    expect(result.current).toBe(prev);
   });
 });

src/hooks/useDebouncedCallback/useDebouncedCallback.test.ts

@@ -1,21 +1,50 @@
-import type { DebounceOptions } from "es-toolkit";
-import { debounce } from "es-toolkit";
-import { useEffect, useMemo } from "react";
+import type { DebounceOptions } from "../../utils/debounce";
+import { useEffect, useMemo, useRef } from "react";
+import { debounce } from "../../utils/debounce";
 
-// oxlint-disable-next-line typescript-eslint/no-explicit-any -- es-toolkit の debounce<F extends (...args: any[]) => void> に合わせる
-export function useDebouncedCallback<F extends (...args: any[]) => void>(
-  callback: F,
+/**
+ * 最新の `callback` 参照を ref で保持することで、インラインのアロー関数を渡しても
+ * 保留中のタイマー・leading クールダウン状態が失われないようにする。
+ * debounced 関数は `wait`/`edges`/`signal`/`maxWait` が変化したときだけ再生成される。
+ * `edges` は boolean 正規化しているため `undefined` と `["trailing"]`、
+ * `["leading","trailing"]` と `["trailing","leading"]` はそれぞれ同じ扱いになる。
+ */
+export function useDebouncedCallback<Args extends unknown[]>(
+  callback: (...args: Args) => void,
   wait: number,
   options?: DebounceOptions,
 ) {
-  const debouncedFn = useMemo(
-    () => debounce(callback, wait, options),
-    [callback, options, wait],
-  );
+  const callbackRef = useRef(callback);
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  const rawEdges = options?.edges;
+  // debounce 側 default (["trailing"]) と整合させる
+  const hasLeading = rawEdges?.includes("leading") ?? false;
+  const hasTrailing = rawEdges?.includes("trailing") ?? true;
+  const signal = options?.signal;
+  const maxWait = options?.maxWait;
+
+  const debouncedFn = useMemo(() => {
+    const invokeLatest = (...args: Args) => {
+      callbackRef.current(...args);
+    };
+    const edges: Array<"leading" | "trailing"> = [];
+    if (hasLeading) {
+      edges.push("leading");
+    }
+    if (hasTrailing) {
+      edges.push("trailing");
+    }
+    // ref は debounce のタイマーから非同期に読まれるだけで、レンダリング中には評価しない
+    // oxlint-disable-next-line react-compiler-rules/refs
+    return debounce(invokeLatest, wait, { edges, signal, maxWait });
+  }, [hasLeading, hasTrailing, maxWait, signal, wait]);
 
   useEffect(() => {
     return () => {
-      debouncedFn.cancel();
+      debouncedFn.dispose();
     };
   }, [debouncedFn]);