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

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

@@ -0,0 +1,359 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useMutation } from "../use-mutation";
+
+describe("useMutation", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  // 1 — Initial state
+  it("initializes with idle status and null data/error", () => {
+    const { result } = renderHook(() =>
+      useMutation({ fn: () => Promise.resolve("x") }),
+    );
+
+    expect(result.current.status).toBe("idle");
+    expect(result.current.isIdle).toBe(true);
+    expect(result.current.isPending).toBe(false);
+    expect(result.current.isSuccess).toBe(false);
+    expect(result.current.isError).toBe(false);
+    expect(result.current.data).toBeNull();
+    expect(result.current.error).toBeNull();
+  });
+
+  // 2 — isPending while in flight
+  it("sets isPending=true while mutation is in flight", async () => {
+    let resolve!: (v: string) => void;
+    const deferred = new Promise<string>((res) => {
+      resolve = res;
+    });
+
+    const { result } = renderHook(() => useMutation({ fn: () => deferred }));
+
+    act(() => {
+      result.current.mutate(undefined);
+    });
+
+    expect(result.current.status).toBe("pending");
+    expect(result.current.isPending).toBe(true);
+    expect(result.current.isIdle).toBe(false);
+    expect(result.current.isSuccess).toBe(false);
+    expect(result.current.isError).toBe(false);
+
+    await act(async () => {
+      resolve("done");
+      await Promise.resolve();
+    });
+  });
+
+  // 3 — Success path
+  it("sets status=success and data on successful mutation", async () => {
+    const { result } = renderHook(() =>
+      useMutation({ fn: () => Promise.resolve("ok") }),
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync(undefined);
+    });
+
+    expect(result.current.status).toBe("success");
+    expect(result.current.isSuccess).toBe(true);
+    expect(result.current.data).toBe("ok");
+    expect(result.current.error).toBeNull();
+  });
+
+  // 4 — Error path
+  it("sets status=error and error on failed mutation", async () => {
+    const err = new Error("boom");
+    const { result } = renderHook(() =>
+      useMutation({ fn: () => Promise.reject(err) }),
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync(undefined).catch(() => {});
+    });
+
+    expect(result.current.status).toBe("error");
+    expect(result.current.isError).toBe(true);
+    expect(result.current.error).toBe(err);
+    expect(result.current.data).toBeNull();
+  });
+
+  // 5 — mutateAsync resolves with data
+  it("mutateAsync resolves with the value returned by fn", async () => {
+    const { result } = renderHook(() =>
+      useMutation({ fn: () => Promise.resolve(42) }),
+    );
+
+    let resolved: number | undefined;
+    await act(async () => {
+      resolved = await result.current.mutateAsync(undefined);
+    });
+
+    expect(resolved).toBe(42);
+  });
+
+  // 6 — mutateAsync re-throws on error
+  it("mutateAsync re-throws on error", async () => {
+    const err = new Error("rethrow-me");
+    const { result } = renderHook(() =>
+      useMutation({ fn: () => Promise.reject(err) }),
+    );
+
+    let caught: Error | undefined;
+    await act(async () => {
+      caught = await result.current.mutateAsync(undefined).catch((e) => e);
+    });
+
+    expect(caught).toBe(err);
+  });
+
+  // 7 — mutate is fire-and-forget (void, no throw)
+  it("mutate returns void and does not throw on error", async () => {
+    const fn = vi.fn().mockRejectedValue(new Error("ignored"));
+    const { result } = renderHook(() => useMutation({ fn }));
+
+    let threw = false;
+    await act(async () => {
+      try {
+        result.current.mutate(undefined);
+        await Promise.resolve();
+      } catch {
+        threw = true;
+      }
+    });
+
+    expect(threw).toBe(false);
+  });
+
+  // 8 — onMutate called before fn resolves
+  it("calls onMutate(variables) before fn resolves", async () => {
+    const callOrder: string[] = [];
+    let resolveFn!: () => void;
+    const fn = vi.fn(
+      () =>
+        new Promise<string>((res) => {
+          resolveFn = () => res("done");
+        }),
+    );
+    const onMutate = vi.fn(() => {
+      callOrder.push("onMutate");
+    });
+
+    const { result } = renderHook(() => useMutation({ fn, onMutate }));
+
+    act(() => {
+      result.current.mutate(undefined);
+    });
+
+    // onMutate called synchronously — fn has not resolved yet
+    expect(onMutate).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(callOrder).toEqual(["onMutate"]);
+
+    await act(async () => {
+      resolveFn();
+      await Promise.resolve();
+    });
+  });
+
+  // 9 — onSuccess(data, variables)
+  it("calls onSuccess(data, variables) on success", async () => {
+    const onSuccess = vi.fn();
+    const vars = { id: 99 };
+
+    const { result } = renderHook(() =>
+      useMutation({
+        fn: (v: { id: number }) => Promise.resolve(`result-${v.id}`),
+        onSuccess,
+      }),
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync(vars);
+    });
+
+    expect(onSuccess).toHaveBeenCalledOnce();
+    expect(onSuccess).toHaveBeenCalledWith("result-99", vars);
+  });
+
+  // 10 — onError(error, variables)
+  it("calls onError(error, variables) on error", async () => {
+    const err = new Error("fail");
+    const onError = vi.fn();
+    const vars = { id: 7 };
+
+    const { result } = renderHook(() =>
+      useMutation({
+        fn: (_v: { id: number }) => Promise.reject(err),
+        onError,
+      }),
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync(vars).catch(() => {});
+    });
+
+    expect(onError).toHaveBeenCalledOnce();
+    expect(onError).toHaveBeenCalledWith(err, vars);
+  });
+
+  // 11 — onSettled(data, null, variables) on success
+  it("calls onSettled(data, null, variables) on success", async () => {
+    const onSettled = vi.fn();
+    const vars = { id: 1 };
+
+    const { result } = renderHook(() =>
+      useMutation({
+        fn: (v: { id: number }) => Promise.resolve(`ok-${v.id}`),
+        onSettled,
+      }),
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync(vars);
+    });
+
+    expect(onSettled).toHaveBeenCalledOnce();
+    expect(onSettled).toHaveBeenCalledWith("ok-1", null, vars);
+  });
+
+  // 12 — onSettled(null, error, variables) on error
+  it("calls onSettled(null, error, variables) on error", async () => {
+    const err = new Error("oops");
+    const onSettled = vi.fn();
+    const vars = { id: 2 };
+
+    const { result } = renderHook(() =>
+      useMutation({
+        fn: (_v: { id: number }) => Promise.reject(err),
+        onSettled,
+      }),
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync(vars).catch(() => {});
+    });
+
+    expect(onSettled).toHaveBeenCalledOnce();
+    expect(onSettled).toHaveBeenCalledWith(null, err, vars);
+  });
+
+  // 13 — reset after success
+  it("reset() after success returns to idle and clears data", async () => {
+    const { result } = renderHook(() =>
+      useMutation({ fn: () => Promise.resolve("done") }),
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync(undefined);
+    });
+
+    expect(result.current.status).toBe("success");
+
+    act(() => {
+      result.current.reset();
+    });
+
+    expect(result.current.status).toBe("idle");
+    expect(result.current.data).toBeNull();
+    expect(result.current.error).toBeNull();
+  });
+
+  // 14 — reset after error
+  it("reset() after error returns to idle and clears error", async () => {
+    const { result } = renderHook(() =>
+      useMutation({ fn: () => Promise.reject(new Error("e")) }),
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync(undefined).catch(() => {});
+    });
+
+    expect(result.current.status).toBe("error");
+
+    act(() => {
+      result.current.reset();
+    });
+
+    expect(result.current.status).toBe("idle");
+    expect(result.current.error).toBeNull();
+    expect(result.current.data).toBeNull();
+  });
+
+  // 15 — mutate identity stable across fn re-renders
+  it("mutate reference is stable when inline fn changes", () => {
+    let fn = vi.fn().mockResolvedValue("a");
+
+    const { result, rerender } = renderHook(() => useMutation({ fn }));
+
+    const mutateRef1 = result.current.mutate;
+
+    fn = vi.fn().mockResolvedValue("b");
+    rerender();
+
+    expect(result.current.mutate).toBe(mutateRef1);
+  });
+
+  // 16 — mutate stable when onSuccess changes
+  it("mutate reference is stable when onSuccess changes between renders", () => {
+    let onSuccess = vi.fn();
+
+    const { result, rerender } = renderHook(() =>
+      useMutation({ fn: () => Promise.resolve("x"), onSuccess }),
+    );
+
+    const mutateRef1 = result.current.mutate;
+
+    onSuccess = vi.fn();
+    rerender();
+
+    expect(result.current.mutate).toBe(mutateRef1);
+  });
+
+  // 17 — variables forwarded to fn and all callbacks
+  it("forwards variables to fn, onMutate, onSuccess, and onSettled", async () => {
+    const vars = { userId: 42, name: "Alice" };
+    const fn = vi.fn().mockResolvedValue("created");
+    const onMutate = vi.fn();
+    const onSuccess = vi.fn();
+    const onSettled = vi.fn();
+
+    const { result } = renderHook(() =>
+      useMutation({ fn, onMutate, onSuccess, onSettled }),
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync(vars);
+    });
+
+    expect(fn).toHaveBeenCalledWith(vars);
+    expect(onMutate).toHaveBeenCalledWith(vars);
+    expect(onSuccess).toHaveBeenCalledWith("created", vars);
+    expect(onSettled).toHaveBeenCalledWith("created", null, vars);
+  });
+
+  // 18 — onSettled called even when onError throws
+  it("onSettled is called even when onError throws", async () => {
+    const err = new Error("mutation-fail");
+    const onError = vi.fn().mockImplementation(() => {
+      throw new Error("onError itself throws");
+    });
+    const onSettled = vi.fn();
+
+    const { result } = renderHook(() =>
+      useMutation({ fn: () => Promise.reject(err), onError, onSettled }),
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync(undefined).catch(() => {});
+    });
+
+    expect(onSettled).toHaveBeenCalledOnce();
+  });
+});

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

@@ -0,0 +1,97 @@
+import { useCallback, useState } from "react";
+import { useLatestRef } from "../internal/use-latest-ref";
+
+type MutationStatus = "idle" | "pending" | "success" | "error";
+
+export interface UseMutationOptions<TVariables = void, TData = unknown> {
+  fn: (variables: TVariables) => Promise<TData>;
+  onMutate?: (variables: TVariables) => void;
+  onSuccess?: (data: TData, variables: TVariables) => void;
+  onError?: (error: Error, variables: TVariables) => void;
+  onSettled?: (
+    data: TData | null,
+    error: Error | null,
+    variables: TVariables,
+  ) => void;
+}
+
+export interface UseMutationReturn<TVariables = void, TData = unknown> {
+  mutate: (variables: TVariables) => void;
+  mutateAsync: (variables: TVariables) => Promise<TData>;
+  reset: () => void;
+  data: TData | null;
+  error: Error | null;
+  status: MutationStatus;
+  isIdle: boolean;
+  isPending: boolean;
+  isSuccess: boolean;
+  isError: boolean;
+}
+
+export const useMutation = <TVariables = void, TData = unknown>(
+  options: UseMutationOptions<TVariables, TData>,
+): UseMutationReturn<TVariables, TData> => {
+  const [status, setStatus] = useState<MutationStatus>("idle");
+  const [data, setData] = useState<TData | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fnRef = useLatestRef(options.fn);
+  const onMutateRef = useLatestRef(options.onMutate);
+  const onSuccessRef = useLatestRef(options.onSuccess);
+  const onErrorRef = useLatestRef(options.onError);
+  const onSettledRef = useLatestRef(options.onSettled);
+
+  const mutateAsync = useCallback(
+    async (variables: TVariables): Promise<TData> => {
+      onMutateRef.current?.(variables);
+      setStatus("pending");
+      setData(null);
+      setError(null);
+
+      let result: TData | null = null;
+      let caught: Error | null = null;
+      try {
+        result = await fnRef.current(variables);
+        setData(result);
+        setStatus("success");
+        onSuccessRef.current?.(result, variables);
+        return result;
+      } catch (err) {
+        caught = err as Error;
+        setError(caught);
+        setStatus("error");
+        onErrorRef.current?.(caught, variables);
+        throw caught;
+      } finally {
+        onSettledRef.current?.(result, caught, variables);
+      }
+    },
+    [fnRef, onMutateRef, onSuccessRef, onErrorRef, onSettledRef],
+  );
+
+  const mutate = useCallback(
+    (variables: TVariables): void => {
+      mutateAsync(variables).catch(() => {});
+    },
+    [mutateAsync],
+  );
+
+  const reset = useCallback(() => {
+    setStatus("idle");
+    setData(null);
+    setError(null);
+  }, []);
+
+  return {
+    mutate,
+    mutateAsync,
+    reset,
+    data,
+    error,
+    status,
+    isIdle: status === "idle",
+    isPending: status === "pending",
+    isSuccess: status === "success",
+    isError: status === "error",
+  };
+};