refactor: separate internal debounce and throttle hooks

.github/workflows/integration.yml

@@ -10,6 +10,9 @@ on:
       - main
       - v1-base
 
+env:
+  INTERNAL_HOOKS_PATH: 'packages/*/src/hooks/_internal/*'
+
 jobs:
   quality:
     runs-on: ubuntu-latest
@@ -227,6 +230,9 @@ jobs:
       - name: Check for JSDoc comments
         run: |
           for file in ${{ needs.check-changes.outputs.changed_files }}; do
+            case "$file" in
+              $INTERNAL_HOOKS_PATH) continue ;;
+            esac
             dir_name=$(basename $(dirname "$file"))
             base_name=$(basename $dir_name)
             implementation="$(dirname "$file")/$base_name.ts"
@@ -279,6 +285,9 @@ jobs:
       - name: Check JSDoc structure
         run: |
           for file in ${{ needs.check-changes.outputs.changed_files }}; do
+            case "$file" in
+              $INTERNAL_HOOKS_PATH) continue ;;
+            esac
             directory=$(basename "$(dirname "$file")")
             filename=$(basename $file)
             filename="${filename%%.*}"
@@ -357,6 +366,10 @@ jobs:
                   continue
                 fi
 
+                case "$impl_dir" in
+                  $INTERNAL_HOOKS_PATH) continue ;;
+                esac
+
                 impl_name=$(basename "$impl_dir")
                 impl_index="$impl_dir/index.ts"
                 impl_file=""

.scripts/verifyDocsI18n.ts

@@ -137,7 +137,7 @@ try {
         async directory =>
           (
             await fs.readdir(path.join(root, 'packages/react-simplikit/src', directory), { withFileTypes: true })
-          ).filter(entry => entry.isDirectory()).length
+          ).filter(entry => entry.isDirectory() && entry.name !== '_internal').length
       )
     )
   ).reduce((total, count) => total + count, 0);

.vitepress/libs/legacyRedirects.mts

@@ -61,10 +61,12 @@ export function collectLegacyRedirects(): RedirectPair[] {
 
 function collectReferenceRedirects(): RedirectPair[] {
   return ['hooks', 'components', 'utils'].flatMap(category =>
-    listDirectories(path.join(packageSourceRoot, category)).map(name => ({
-      from: `${RETIRED_MOBILE_PAGES.has(name) ? 'mobile' : 'core'}/${category}/${name}.html`,
-      to: `${category}/${name}.html`,
-    }))
+    listDirectories(path.join(packageSourceRoot, category))
+      .filter(name => name !== '_internal')
+      .map(name => ({
+        from: `${RETIRED_MOBILE_PAGES.has(name) ? 'mobile' : 'core'}/${category}/${name}.html`,
+        to: `${category}/${name}.html`,
+      }))
   );
 }
 

.vitepress/shared.mts

@@ -10,6 +10,6 @@ export const docsRoot = path.join(projectRoot, 'docs');
 export function listDirectories(directory: string): string[] {
   return fs
     .readdirSync(directory, { withFileTypes: true })
-    .filter(entry => entry.isDirectory())
+    .filter(entry => entry.isDirectory() && entry.name !== '_internal')
     .map(entry => entry.name);
 }

packages/react-simplikit/src/hooks/_internal/useDebounce/debounce.ts

@@ -0,0 +1,93 @@
+// Simplified version of https://github.com/toss/es-toolkit/blob/main/src/function/debounce.ts
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- generic function constraint requires `any[]` due to parameter contravariance
+export type DebouncedFunction<F extends (...args: any[]) => void> = {
+  (...args: Parameters<F>): void;
+  cancel: () => void;
+};
+
+type DebounceOptions = {
+  /**
+   * An optional array specifying whether the function should be invoked on the leading edge, trailing edge, or both.
+   * If `edges` includes "leading", the function will be invoked at the start of the delay period.
+   * If `edges` includes "trailing", the function will be invoked at the end of the delay period.
+   * If both "leading" and "trailing" are included, the function will be invoked at both the start and end of the delay period.
+   * @default ["leading", "trailing"]
+   */
+  edges?: Array<'leading' | 'trailing'>;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- generic function constraint requires `any[]` due to parameter contravariance
+export function debounce<F extends (...args: any[]) => void>(
+  func: F,
+  debounceMs: number,
+  { edges = ['leading', 'trailing'] }: DebounceOptions = {}
+): DebouncedFunction<F> & { schedule: () => void } {
+  let pendingThis: ThisParameterType<F> | undefined = undefined;
+  let pendingArgs: Parameters<F> | null = null;
+
+  const leading = edges != null && edges.includes('leading');
+  const trailing = edges == null || edges.includes('trailing');
+
+  const invoke = () => {
+    if (pendingArgs !== null) {
+      func.apply(pendingThis, pendingArgs);
+      pendingThis = undefined;
+      pendingArgs = null;
+    }
+  };
+
+  const onTimerEnd = () => {
+    if (trailing) {
+      invoke();
+    }
+
+    cancel();
+  };
+
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+  const schedule = () => {
+    if (timeoutId != null) {
+      clearTimeout(timeoutId);
+    }
+
+    timeoutId = setTimeout(() => {
+      timeoutId = null;
+
+      onTimerEnd();
+    }, debounceMs);
+  };
+
+  const cancelTimer = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+  };
+
+  const cancel = () => {
+    cancelTimer();
+    pendingThis = undefined;
+    pendingArgs = null;
+  };
+
+  const debounced = function (this: ThisParameterType<F>, ...args: Parameters<F>) {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    pendingThis = this;
+    pendingArgs = args;
+
+    const isFirstCall = timeoutId == null;
+
+    schedule();
+
+    if (leading && isFirstCall) {
+      invoke();
+    }
+  };
+
+  debounced.schedule = schedule;
+  debounced.cancel = cancel;
+
+  return debounced;
+}

packages/react-simplikit/src/hooks/_internal/useDebounce/useDebounce.spec.ts

@@ -0,0 +1,99 @@
+import { beforeEach, describe, expect, expectTypeOf, it, vi } from 'vitest';
+
+import { renderHookSSR } from '../../../_internal/test-utils/renderHookSSR.tsx';
+
+import { DebouncedFunction } from './debounce.ts';
+import { useDebounce } from './useDebounce.ts';
+
+describe('useDebounce', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  it('is safe on server side rendering', () => {
+    const callback = vi.fn();
+    renderHookSSR.serverOnly(() => useDebounce(callback, 100));
+
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it('should debounce the callback with default options', async () => {
+    const callback = vi.fn();
+    const { result } = await renderHookSSR(() => useDebounce(callback, 100));
+
+    result.current();
+    expect(callback).not.toBeCalled();
+
+    vi.advanceTimersByTime(50);
+    expect(callback).not.toBeCalled();
+
+    vi.advanceTimersByTime(50);
+    expect(callback).toBeCalledTimes(1);
+  });
+
+  it('should handle leading edge', async () => {
+    const callback = vi.fn();
+    const { result } = await renderHookSSR(() => useDebounce(callback, 100, { leading: true }));
+
+    result.current();
+    expect(callback).toBeCalledTimes(1);
+
+    result.current();
+    vi.advanceTimersByTime(50);
+    expect(callback).toBeCalledTimes(1);
+
+    vi.advanceTimersByTime(40);
+    expect(callback).toBeCalledTimes(1);
+
+    vi.advanceTimersByTime(10);
+    expect(callback).toBeCalledTimes(2);
+  });
+
+  it('should handle trailing edge', async () => {
+    const callback = vi.fn();
+    const { result } = await renderHookSSR(() => useDebounce(callback, 100, { trailing: true }));
+
+    result.current();
+    expect(callback).not.toBeCalled();
+
+    vi.advanceTimersByTime(50);
+    result.current();
+    expect(callback).not.toBeCalled();
+
+    vi.advanceTimersByTime(100);
+    expect(callback).toBeCalledTimes(1);
+  });
+
+  it('should handle both leading and trailing edges', async () => {
+    const callback = vi.fn();
+    const { result } = await renderHookSSR(() => useDebounce(callback, 100, { leading: true, trailing: true }));
+
+    result.current();
+    expect(callback).toBeCalledTimes(1);
+
+    result.current();
+    vi.advanceTimersByTime(150);
+    expect(callback).toBeCalledTimes(2);
+  });
+
+  it('should inference the callback type', async () => {
+    const callback = (value: string) => {
+      console.log('test::', value);
+    };
+
+    const { result } = renderHookSSR(() => useDebounce(callback, 100));
+
+    expectTypeOf(result.current).toEqualTypeOf<DebouncedFunction<typeof callback>>();
+  });
+
+  it('should cleanup on unmount', async () => {
+    const callback = vi.fn();
+    const { result, unmount } = await renderHookSSR(() => useDebounce(callback, 100));
+
+    result.current();
+    unmount();
+    vi.advanceTimersByTime(100);
+
+    expect(callback).not.toBeCalled();
+  });
+});

packages/react-simplikit/src/hooks/_internal/useDebounce/useDebounce.ts

@@ -0,0 +1,60 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { useEffect } from 'react';
+import { useMemo } from 'react';
+
+import { usePreservedCallback } from '../../usePreservedCallback/usePreservedCallback.ts';
+
+import { debounce, DebouncedFunction } from './debounce.ts';
+
+type DebounceOptions = {
+  leading?: boolean;
+  trailing?: boolean;
+};
+
+/**
+ * An internal React hook shared by debounce-related hooks.
+ * It debounces the provided callback and manages execution timing and cancellation of pending calls.
+ *
+ * With the default options, the last call runs after `debounceMs` milliseconds without another call.
+ * Pending calls are cancelled when the component unmounts or when `debounceMs`, `leading`,
+ * or `trailing` changes.
+ *
+ * `.cancel()` only cancels a pending callback; it does not stop work that has already started.
+ */
+export function useDebounce<F extends (...args: any[]) => unknown>(
+  callback: F,
+  debounceMs: number,
+  options: DebounceOptions = {}
+): DebouncedFunction<F> {
+  const preservedCallback = usePreservedCallback(callback) as F;
+
+  const { leading = false, trailing = true } = options;
+
+  const edges = useMemo(() => {
+    const _edges: Array<'leading' | 'trailing'> = [];
+    if (leading) {
+      _edges.push('leading');
+    }
+
+    if (trailing) {
+      _edges.push('trailing');
+    }
+
+    return _edges;
+  }, [leading, trailing]);
+
+  const debounced = useMemo(() => {
+    return debounce<F>(preservedCallback, debounceMs, { edges });
+  }, [preservedCallback, debounceMs, edges]);
+
+  useEffect(
+    function cancelDebouncedOnUnmount() {
+      return () => {
+        debounced.cancel();
+      };
+    },
+    [debounced]
+  );
+
+  return debounced;
+}