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]>

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,97 @@ 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);
+  });
+
+  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();
+  });
 
-    expect(callback).toHaveBeenCalledExactlyOnceWith("test");
+  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);
   });
 });

src/hooks/useDebouncedCallback/useDebouncedCallback.test.ts

@@ -1,10 +1,9 @@
-import type { DebounceOptions } from "es-toolkit";
-import { debounce } from "es-toolkit";
+import type { DebounceOptions } from "../../utils/debounce";
 import { useEffect, useMemo } 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,
+export function useDebouncedCallback<Args extends unknown[]>(
+  callback: (...args: Args) => void,
   wait: number,
   options?: DebounceOptions,
 ) {