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

package/src/hooks/use-async/use-async.stories.tsx

@@ -0,0 +1,272 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button } from "../../components";
+import { useAsync } from "./use-async";
+
+// ─── Types ─────────────────────────────────────────────────────────────────────
+
+interface DemoData {
+  message: string;
+  timestamp: string;
+}
+
+// ─── Demo component ────────────────────────────────────────────────────────────
+
+type AsyncDemoProps = {
+  /** Simulated async delay in ms */
+  delay?: number;
+  /** When true the demo's fn rejects with a simulated error */
+  shouldFail?: boolean;
+  enabled?: boolean;
+  keepPreviousData?: boolean;
+  onSuccess?: (data: DemoData) => void;
+  onError?: (error: Error) => void;
+  onSettled?: (data: DemoData | null, error: Error | null) => void;
+};
+
+const AsyncDemo = ({
+  delay = 800,
+  shouldFail = false,
+  enabled = true,
+  keepPreviousData = false,
+  onSuccess,
+  onError,
+  onSettled,
+}: AsyncDemoProps) => {
+  const [log, setLog] = useState<string[]>([]);
+
+  const addLog = (msg: string) =>
+    setLog((prev) => [
+      `[${new Date().toISOString().slice(11, 23)}] ${msg}`,
+      ...prev,
+    ]);
+
+  const { status, data, error, loading, refetch } = useAsync<DemoData>({
+    fn: async (signal) => {
+      await new Promise<void>((res, rej) => {
+        const timer = setTimeout(() => {
+          if (shouldFail) rej(new Error("Simulated failure"));
+          else res();
+        }, delay);
+        signal.addEventListener("abort", () => clearTimeout(timer));
+      });
+      return {
+        message: "Data loaded successfully",
+        timestamp: new Date().toLocaleTimeString(),
+      };
+    },
+    enabled,
+    keepPreviousData,
+    onSuccess: (d) => {
+      addLog(`onSuccess — ${d.message} at ${d.timestamp}`);
+      onSuccess?.(d);
+    },
+    onError: (e) => {
+      addLog(`onError — ${e.message}`);
+      onError?.(e);
+    },
+    onSettled: (d, e) => {
+      addLog(
+        `onSettled — data: ${d ? d.timestamp : "null"}, error: ${e?.message ?? "null"}`,
+      );
+      onSettled?.(d, e);
+    },
+  });
+
+  return (
+    <div className="flex flex-col gap-4 max-w-sm">
+      <Button variant="outline" onClick={refetch} disabled={loading}>
+        {loading ? "Loading…" : "Refetch"}
+      </Button>
+
+      <pre className="rounded-md bg-slate-950 p-3 text-xs text-white leading-relaxed">
+        {JSON.stringify(
+          {
+            status,
+            loading,
+            data,
+            error: error?.message ?? null,
+          },
+          null,
+          2,
+        )}
+      </pre>
+
+      {log.length > 0 && (
+        <div className="rounded-md border bg-muted p-3 text-xs font-mono space-y-0.5">
+          {log.map((entry, i) => (
+            // biome-ignore lint/suspicious/noArrayIndexKey: log is append-only
+            <div key={i}>{entry}</div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+// ─── Meta ─────────────────────────────────────────────────────────────────────
+
+const meta: Meta<typeof AsyncDemo> = {
+  title: "hooks/useAsync",
+  component: AsyncDemo,
+  parameters: {
+    docs: {
+      description: {
+        component: `
+\`useAsync\` runs an async function automatically when its \`deps\` change.
+
+**API summary**
+
+\`\`\`ts
+const { data, error, status, loading, isIdle, isSuccess, isError, refetch } =
+  useAsync({ fn, deps?, enabled?, keepPreviousData?, onSuccess?, onError?, onSettled? });
+\`\`\`
+
+**Key behaviors**
+- \`fn(signal)\` receives an \`AbortSignal\` — pass it to \`fetch\` to cancel in-flight requests on cleanup.
+- Runs on mount (when \`enabled: true\`) and re-runs whenever \`deps\` change.
+- Race-safe: if \`deps\` change before \`fn\` resolves, the stale response is silently discarded.
+- \`enabled: false\` keeps the hook in \`'idle'\` state — no request fires until \`enabled\` becomes \`true\`.
+- \`keepPreviousData: true\` retains the last resolved \`data\` while a new request is in-flight.
+- \`refetch()\` manually re-triggers without changing deps. Stable reference across renders.
+- All callbacks read through \`useLatestRef\` — inline functions never cause re-subscriptions.
+        `.trim(),
+      },
+    },
+  },
+  argTypes: {
+    delay: {
+      control: { type: "range", min: 0, max: 3000, step: 100 },
+      description:
+        "Simulated async delay in ms. Demo control only — not a hook option.",
+      table: { category: "Demo controls" },
+    },
+    shouldFail: {
+      control: "boolean",
+      description:
+        "When true the demo's fn rejects. Toggle then click Refetch to see the error state.",
+      table: { category: "Demo controls" },
+    },
+    enabled: {
+      control: "boolean",
+      description:
+        "When false the hook stays idle and no request fires. Set to true to trigger the first run.",
+      table: {
+        category: "Hook options",
+        type: { summary: "boolean" },
+        defaultValue: { summary: "true" },
+      },
+    },
+    keepPreviousData: {
+      control: "boolean",
+      description:
+        "When true, `data` is preserved while a new request is in-flight instead of being reset to null.",
+      table: {
+        category: "Hook options",
+        type: { summary: "boolean" },
+        defaultValue: { summary: "false" },
+      },
+    },
+    onSuccess: {
+      action: "onSuccess",
+      description: "Called with `data` after `fn` resolves successfully.",
+      table: {
+        category: "Hook options",
+        type: { summary: "(data: T) => void" },
+      },
+    },
+    onError: {
+      action: "onError",
+      description:
+        "Called with the thrown `Error` when `fn` rejects. Abort errors are swallowed and never reach this callback.",
+      table: {
+        category: "Hook options",
+        type: { summary: "(error: Error) => void" },
+      },
+    },
+    onSettled: {
+      action: "onSettled",
+      description:
+        "Always called after `fn` settles — regardless of success or failure.",
+      table: {
+        category: "Hook options",
+        type: { summary: "(data: T | null, error: Error | null) => void" },
+      },
+    },
+  },
+  render: (args) => <AsyncDemo {...args} />,
+};
+
+export default meta;
+type Story = StoryObj<typeof AsyncDemo>;
+
+// ─── Stories ──────────────────────────────────────────────────────────────────
+
+export const Default: Story = {
+  args: {
+    delay: 800,
+    shouldFail: false,
+    enabled: true,
+    keepPreviousData: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Runs on mount, transitions through `pending` → `success`, then populates `data`. Click **Refetch** to re-trigger manually. Toggle **shouldFail** in controls then refetch to see the error path.",
+      },
+    },
+  },
+};
+
+export const ErrorState: Story = {
+  name: "Error",
+  args: {
+    delay: 600,
+    shouldFail: true,
+    enabled: true,
+    keepPreviousData: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`fn` rejects immediately — `status` becomes `'error'`, `error` is populated, and `data` stays null. `onError` and `onSettled` both fire. Toggle **shouldFail** off then click Refetch to recover.",
+      },
+    },
+  },
+};
+
+export const WithEnabled: Story = {
+  args: {
+    delay: 800,
+    shouldFail: false,
+    enabled: false,
+    keepPreviousData: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Starts with `enabled: false` — the hook is in `'idle'` state and no request fires. Flip **enabled** to true in controls to trigger the first run.",
+      },
+    },
+  },
+};
+
+export const WithKeepPreviousData: Story = {
+  args: {
+    delay: 1500,
+    shouldFail: false,
+    enabled: true,
+    keepPreviousData: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "With `keepPreviousData: true`, the previous `data` stays visible while the next request is in-flight (`status: 'pending'`). Click **Refetch** to see stale data persist during the 1.5 s delay.",
+      },
+    },
+  },
+};

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");
+  });
+});