@boxcustodia/library 2.0.0-alpha.19 → 2.0.0-alpha.20

package/src/hooks/use-async/use-async.test.ts

@@ -0,0 +1,397 @@
+/// <reference types="vitest/globals" />
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useAsync } from "./use-async";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Creates a promise that can be resolved/rejected externally. */
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+// ---------------------------------------------------------------------------
+// Test 1 — enabled: false → idle initial state, fn never called
+// ---------------------------------------------------------------------------
+describe("useAsync", () => {
+  it("test 1: enabled: false → idle state, fn never called", () => {
+    const fn = vi.fn().mockResolvedValue("data");
+    const { result } = renderHook(() => useAsync({ fn, enabled: false }));
+
+    expect(result.current.status).toBe("idle");
+    expect(result.current.loading).toBe(false);
+    expect(result.current.data).toBeNull();
+    expect(result.current.error).toBeNull();
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 2 — enabled: true (default) → initial status "pending", loading true
+  // -------------------------------------------------------------------------
+  it("test 2: enabled: true → initial status pending, loading true", () => {
+    const { promise } = deferred<string>();
+    const fn = vi.fn().mockReturnValue(promise);
+    const { result } = renderHook(() => useAsync({ fn }));
+
+    expect(result.current.status).toBe("pending");
+    expect(result.current.loading).toBe(true);
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 3 — success path
+  // -------------------------------------------------------------------------
+  it("test 3: success path — data set, status success, loading false", async () => {
+    const fn = vi.fn().mockResolvedValue(42);
+    const { result } = renderHook(() => useAsync({ fn }));
+
+    await waitFor(() => expect(result.current.status).toBe("success"));
+    expect(result.current.data).toBe(42);
+    expect(result.current.error).toBeNull();
+    expect(result.current.loading).toBe(false);
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 4 — error path
+  // -------------------------------------------------------------------------
+  it("test 4: error path — error set, status error, loading false", async () => {
+    const fn = vi.fn().mockRejectedValue(new Error("fail"));
+    const { result } = renderHook(() => useAsync({ fn }));
+
+    await waitFor(() => expect(result.current.status).toBe("error"));
+    expect(result.current.error?.message).toBe("fail");
+    expect(result.current.data).toBeNull();
+    expect(result.current.loading).toBe(false);
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 5 — onSuccess fires with resolved data
+  // -------------------------------------------------------------------------
+  it("test 5: onSuccess callback fires with resolved data", async () => {
+    const onSuccess = vi.fn();
+    const fn = vi.fn().mockResolvedValue("hello");
+    renderHook(() => useAsync({ fn, onSuccess }));
+
+    await waitFor(() => expect(onSuccess).toHaveBeenCalledWith("hello"));
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 6 — onError fires with rejection reason
+  // -------------------------------------------------------------------------
+  it("test 6: onError callback fires with rejection reason", async () => {
+    const onError = vi.fn();
+    const fn = vi.fn().mockRejectedValue(new Error("boom"));
+    renderHook(() => useAsync({ fn, onError }));
+
+    await waitFor(() =>
+      expect(onError).toHaveBeenCalledWith(expect.any(Error)),
+    );
+    expect(onError.mock.calls[0][0].message).toBe("boom");
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 7 — onSettled fires on success
+  // -------------------------------------------------------------------------
+  it("test 7: onSettled(data, null) fires on success", async () => {
+    const onSettled = vi.fn();
+    const fn = vi.fn().mockResolvedValue("result");
+    renderHook(() => useAsync({ fn, onSettled }));
+
+    await waitFor(() => expect(onSettled).toHaveBeenCalledWith("result", null));
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 8 — onSettled fires on error
+  // -------------------------------------------------------------------------
+  it("test 8: onSettled(null, error) fires on error", async () => {
+    const onSettled = vi.fn();
+    const fn = vi.fn().mockRejectedValue(new Error("err"));
+    renderHook(() => useAsync({ fn, onSettled }));
+
+    await waitFor(() =>
+      expect(onSettled).toHaveBeenCalledWith(null, expect.any(Error)),
+    );
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 9 — latest callback ref: change onSuccess between renders
+  // -------------------------------------------------------------------------
+  it("test 9: callback identity — latest onSuccess called, not captured", async () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const d = deferred<string>();
+    const fn = vi.fn().mockReturnValue(d.promise);
+
+    const { rerender } = renderHook(
+      ({ onSuccess }: { onSuccess: (data: string) => void }) =>
+        useAsync({ fn, onSuccess }),
+      { initialProps: { onSuccess: first } },
+    );
+
+    // Change the callback before the promise resolves
+    rerender({ onSuccess: second });
+
+    await act(async () => {
+      d.resolve("data");
+    });
+
+    await waitFor(() => expect(second).toHaveBeenCalledWith("data"));
+    expect(first).not.toHaveBeenCalled();
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 10 — refetch triggers new execution
+  // -------------------------------------------------------------------------
+  it("test 10: refetch transitions to pending and calls fn again", async () => {
+    const fn = vi.fn().mockResolvedValue("value");
+    const { result } = renderHook(() => useAsync({ fn }));
+
+    await waitFor(() => expect(result.current.status).toBe("success"));
+    expect(fn).toHaveBeenCalledTimes(1);
+
+    act(() => result.current.refetch());
+
+    await waitFor(() => expect(fn).toHaveBeenCalledTimes(2));
+    await waitFor(() => expect(result.current.status).toBe("success"));
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 11 — race condition: second call result wins
+  // -------------------------------------------------------------------------
+  it("test 11: race condition — second call result wins, first discarded", async () => {
+    const first = deferred<string>();
+    const second = deferred<string>();
+    let callCount = 0;
+    const fn = vi.fn().mockImplementation((_signal: AbortSignal) => {
+      callCount++;
+      return callCount === 1 ? first.promise : second.promise;
+    });
+
+    const { result } = renderHook(
+      ({ deps }: { deps: number[] }) => useAsync({ fn, deps }),
+      { initialProps: { deps: [1] } },
+    );
+
+    // Wait until fn is called (first call in flight)
+    await waitFor(() => expect(fn).toHaveBeenCalledTimes(1));
+
+    // Trigger second call by changing deps
+    act(() => {
+      // rerender with new deps to trigger second call
+    });
+
+    // Instead use refetch for the second call
+    act(() => result.current.refetch());
+    await waitFor(() => expect(fn).toHaveBeenCalledTimes(2));
+
+    // Resolve second first, then first — first result should be discarded
+    await act(async () => {
+      second.resolve("second-result");
+    });
+    await waitFor(() => expect(result.current.status).toBe("success"));
+    expect(result.current.data).toBe("second-result");
+
+    // Now resolve the stale first call — state should NOT change
+    await act(async () => {
+      first.resolve("stale-result");
+    });
+    // State must remain second-result
+    expect(result.current.data).toBe("second-result");
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 12 — unmount during pending: no setState after unmount
+  // -------------------------------------------------------------------------
+  it("test 12: unmount during pending — no setState after unmount", async () => {
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const d = deferred<string>();
+    const fn = vi.fn().mockReturnValue(d.promise);
+
+    const { unmount } = renderHook(() => useAsync({ fn }));
+
+    // Unmount before the promise resolves
+    unmount();
+
+    // Resolve after unmount
+    await act(async () => {
+      d.resolve("late");
+    });
+
+    // No React "can't perform state update on unmounted component" error
+    expect(consoleSpy).not.toHaveBeenCalledWith(
+      expect.stringContaining("unmounted"),
+    );
+    consoleSpy.mockRestore();
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 13 — AbortSignal passed to fn
+  // -------------------------------------------------------------------------
+  it("test 13: AbortSignal instance passed to fn", () => {
+    let receivedSignal: unknown;
+    const fn = vi.fn().mockImplementation((signal: AbortSignal) => {
+      receivedSignal = signal;
+      return new Promise(() => {}); // never resolves
+    });
+
+    renderHook(() => useAsync({ fn }));
+
+    expect(receivedSignal).toBeInstanceOf(AbortSignal);
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 14 — keepPreviousData: true — data preserved during re-fetch
+  // -------------------------------------------------------------------------
+  it("test 14: keepPreviousData true — previous data preserved while pending", async () => {
+    const first = deferred<string>();
+    let callCount = 0;
+    const fn = vi.fn().mockImplementation(() => {
+      callCount++;
+      if (callCount === 1) return first.promise;
+      return new Promise(() => {}); // second call never resolves
+    });
+
+    const { result } = renderHook(() =>
+      useAsync({ fn, keepPreviousData: true }),
+    );
+
+    // Resolve first call
+    await act(async () => {
+      first.resolve("first-data");
+    });
+    await waitFor(() => expect(result.current.status).toBe("success"));
+    expect(result.current.data).toBe("first-data");
+
+    // Trigger re-fetch
+    act(() => result.current.refetch());
+
+    await waitFor(() => expect(result.current.status).toBe("pending"));
+    // Previous data must still be present
+    expect(result.current.data).toBe("first-data");
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 15 — keepPreviousData: false — data nulled on re-fetch start
+  // -------------------------------------------------------------------------
+  it("test 15: keepPreviousData false — data null immediately on re-fetch", async () => {
+    const first = deferred<string>();
+    let callCount = 0;
+    const fn = vi.fn().mockImplementation(() => {
+      callCount++;
+      if (callCount === 1) return first.promise;
+      return new Promise(() => {}); // second call never resolves
+    });
+
+    const { result } = renderHook(() =>
+      useAsync({ fn, keepPreviousData: false }),
+    );
+
+    await act(async () => {
+      first.resolve("first-data");
+    });
+    await waitFor(() => expect(result.current.status).toBe("success"));
+    expect(result.current.data).toBe("first-data");
+
+    // Trigger re-fetch
+    act(() => result.current.refetch());
+
+    await waitFor(() => expect(result.current.status).toBe("pending"));
+    // Data must be null now
+    expect(result.current.data).toBeNull();
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 16 — dep change triggers re-run
+  // -------------------------------------------------------------------------
+  it("test 16: dep change triggers abort of previous call and starts new one", async () => {
+    const receivedSignals: AbortSignal[] = [];
+    const fn = vi.fn().mockImplementation((signal: AbortSignal) => {
+      receivedSignals.push(signal);
+      return new Promise<string>((resolve) => {
+        // Resolve after a tick so there's time for the signal to abort
+        setTimeout(() => resolve("data"), 10);
+      });
+    });
+
+    const { rerender } = renderHook(
+      ({ dep }: { dep: string }) => useAsync({ fn, deps: [dep] }),
+      { initialProps: { dep: "a" } },
+    );
+
+    await waitFor(() => expect(fn).toHaveBeenCalledTimes(1));
+
+    // Change dep — should trigger second call
+    rerender({ dep: "b" });
+
+    await waitFor(() => expect(fn).toHaveBeenCalledTimes(2));
+
+    // First signal must be aborted
+    expect(receivedSignals[0].aborted).toBe(true);
+    // Second signal is still active
+    expect(receivedSignals[1].aborted).toBe(false);
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 17 — enabled: false → true transition
+  // -------------------------------------------------------------------------
+  it("test 17: enabled false → true transitions to pending and calls fn", async () => {
+    const fn = vi.fn().mockResolvedValue("ok");
+    const { result, rerender } = renderHook(
+      ({ enabled }: { enabled: boolean }) => useAsync({ fn, enabled }),
+      { initialProps: { enabled: false } },
+    );
+
+    expect(result.current.status).toBe("idle");
+    expect(fn).not.toHaveBeenCalled();
+
+    rerender({ enabled: true });
+
+    await waitFor(() => expect(fn).toHaveBeenCalledTimes(1));
+    await waitFor(() => expect(result.current.status).toBe("success"));
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 18 — refetch identity stable across re-renders
+  // -------------------------------------------------------------------------
+  it("test 18: refetch reference is stable across re-renders", async () => {
+    const fn = vi.fn().mockResolvedValue("val");
+    const { result, rerender } = renderHook(() => useAsync({ fn }));
+
+    await waitFor(() => expect(result.current.status).toBe("success"));
+
+    const first = result.current.refetch;
+    rerender();
+    const second = result.current.refetch;
+
+    expect(first).toBe(second);
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 19 — SSR snapshot: hook initial return is idle (effect doesn't run)
+  // -------------------------------------------------------------------------
+  it("test 19: SSR snapshot — initial return shape with enabled false", () => {
+    // Simulate SSR: the hook returns idle state on first render
+    // when enabled is false (effect-free path)
+    const fn = vi.fn();
+    const { result } = renderHook(() => useAsync({ fn, enabled: false }));
+
+    // Immediate synchronous check before any async work
+    expect(result.current).toMatchObject({
+      status: "idle",
+      loading: false,
+      data: null,
+      error: null,
+    });
+    expect(typeof result.current.refetch).toBe("function");
+    expect(typeof result.current.isIdle).toBe("boolean");
+    expect(typeof result.current.isSuccess).toBe("boolean");
+    expect(typeof result.current.isError).toBe("boolean");
+  });
+});

package/src/hooks/use-async/use-async.ts

@@ -1,57 +1,135 @@
-import { DependencyList, useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useLatestRef } from "../internal/use-latest-ref";
 
-interface UseAsyncOptions<T> {
-  onError?: (error: Error) => void;
+export type AsyncStatus = "idle" | "pending" | "success" | "error";
+
+export interface UseAsyncOptions<T> {
+  fn: (signal: AbortSignal) => Promise<T>;
+  deps?: readonly unknown[];
+  enabled?: boolean;
+  keepPreviousData?: boolean;
   onSuccess?: (data: T) => void;
-  onFinish?: () => void;
+  onError?: (error: Error) => void;
+  onSettled?: (data: T | null, error: Error | null) => void;
 }
 
-interface AsyncState<T> {
-  loading: boolean;
-  error: Error | null;
+export interface UseAsyncReturn<T> {
   data: T | null;
+  error: Error | null;
+  status: AsyncStatus;
+  loading: boolean;
+  isIdle: boolean;
+  isSuccess: boolean;
+  isError: boolean;
   refetch: () => void;
 }
 
-interface Props<T> extends UseAsyncOptions<T> {
-  fn: () => Promise<T>;
-  dependencies?: DependencyList;
-}
-
 export function useAsync<T>({
   fn,
-  dependencies = [],
-  onError,
+  deps = [],
+  enabled = true,
+  keepPreviousData = false,
   onSuccess,
-  onFinish,
-}: Props<T>): AsyncState<T> {
-  const [loading, setLoading] = useState<boolean>(true);
-  const [error, setError] = useState<Error | null>(null);
+  onError,
+  onSettled,
+}: UseAsyncOptions<T>): UseAsyncReturn<T> {
+  const [status, setStatus] = useState<AsyncStatus>(
+    enabled ? "pending" : "idle",
+  );
   const [data, setData] = useState<T | null>(null);
+  const [error, setError] = useState<Error | null>(null);
 
-  const fnMemoized = useCallback(() => {
-    setLoading(true);
-    setError(null);
-    setData(null);
-    fn()
-      .then((result) => {
-        onSuccess?.(result);
+  // Stable callback refs — never cause effect re-subscriptions
+  const fnRef = useLatestRef(fn);
+  const onSuccessRef = useLatestRef(onSuccess);
+  const onErrorRef = useLatestRef(onError);
+  const onSettledRef = useLatestRef(onSettled);
+
+  // Monotonically incrementing request ID — guards stale setState
+  const requestIdRef = useRef(0);
+
+  // Tick cell — bumping this from refetch() forces the effect to re-run
+  // without creating a new execute function identity
+  const [refetchTick, setRefetchTick] = useState(0);
+
+  // Stable execute — never changes identity; receives AbortSignal + request id
+  const execute = useCallback(
+    async (signal: AbortSignal, id: number): Promise<void> => {
+      let settled: T | null = null;
+      let settledError: Error | null = null;
+
+      try {
+        const result = await fnRef.current(signal);
+
+        // Stale-skip: abort or superseded by a newer request
+        if (id !== requestIdRef.current || signal.aborted) return;
+
+        settled = result;
         setData(result);
-      })
-      .catch((err: Error) => {
-        onError?.(err);
-        setError(err);
-      })
-      .finally(() => {
-        onFinish?.();
-        setLoading(false);
-      });
-  }, dependencies);
+        setStatus("success");
+        onSuccessRef.current?.(result);
+      } catch (err) {
+        // Abort errors are swallowed — not surfaced to error state or onError
+        if (signal.aborted) return;
+
+        // Stale-skip for non-abort errors too
+        if (id !== requestIdRef.current) return;
+
+        const coerced = err instanceof Error ? err : new Error(String(err));
+        settledError = coerced;
+        setError(coerced);
+        setStatus("error");
+        onErrorRef.current?.(coerced);
+      } finally {
+        // Only call onSettled if this is still the current request and not aborted
+        if (id === requestIdRef.current && !signal.aborted) {
+          onSettledRef.current?.(settled, settledError);
+        }
+      }
+    },
+    // All deps are refs — this callback is effectively stable
+    [fnRef, onSuccessRef, onErrorRef, onSettledRef],
+  );
+
+  // Stable refetch — bumps tick to trigger the effect
+  const refetch = useCallback(() => {
+    setRefetchTick((n) => n + 1);
+  }, []);
 
   useEffect(() => {
-    fnMemoized();
-  }, [fnMemoized]);
+    if (!enabled) {
+      setStatus("idle");
+      return;
+    }
 
-  return { loading, error, data, refetch: fnMemoized };
-}
+    // Bump request ID and capture local copy for stale-skip checks
+    requestIdRef.current += 1;
+    const id = requestIdRef.current;
+
+    const controller = new AbortController();
+
+    setStatus("pending");
+    setError(null);
+    if (!keepPreviousData) {
+      setData(null);
+    }
 
+    execute(controller.signal, id);
+
+    return () => {
+      controller.abort();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [...deps, enabled, execute, refetchTick]);
+
+  return {
+    data,
+    error,
+    status,
+    loading: status === "pending",
+    isIdle: status === "idle",
+    isSuccess: status === "success",
+    isError: status === "error",
+    refetch,
+  };
+}

package/src/hooks/use-boolean/index.ts

@@ -0,0 +1 @@
+export * from "./use-boolean";