cursedbelt 5.89.0 → 5.90.0

package/src/react/createApiHooks.spec.tsx

@@ -0,0 +1,77 @@
+import { afterEach, beforeEach, describe, expect, type Mock, spyOn, test } from 'bun:test';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { act, renderHook } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { createApiHooks, OptimisticFailure } from './createApiHooks.js';
+import { toast } from './Toast.js';
+
+type Rom = { id: string; favorite: boolean };
+
+let toastError: Mock<typeof toast.error>;
+beforeEach(() => {
+  toastError = spyOn(toast, 'error').mockImplementation(() => 0);
+});
+afterEach(() => toastError.mockRestore());
+
+const setup = (request: (rom: Rom) => Promise<void>) => {
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  queryClient.setQueryData<Rom[]>(['roms'], [{ id: 'r1', favorite: false }]);
+  const appToaster = { success: () => undefined, error: () => undefined };
+  const errorSpy = spyOn(appToaster, 'error');
+  const { useApiMutation } = createApiHooks({ useClient: () => null, useToaster: () => appToaster });
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+  const { result } = renderHook(
+    () =>
+      useApiMutation<Rom, void>({
+        mutationFn: (_client, rom) => request(rom),
+        optimistic: {
+          label: (rom) => `favorite ${rom.id}`,
+          edits: (rom) => [
+            {
+              queryKey: ['roms'],
+              apply: (roms: Rom[]) => roms.map((r) => (r.id === rom.id ? { ...r, favorite: !r.favorite } : r)),
+            },
+          ],
+        },
+      }),
+    { wrapper },
+  );
+  return { queryClient, result, errorSpy };
+};
+
+describe('useApiMutation — optimistic', () => {
+  test('the cache changes before the request settles', async () => {
+    let finish!: () => void;
+    const { queryClient, result } = setup(() => new Promise<void>((resolve) => (finish = resolve)));
+    let done!: Promise<void>;
+    act(() => {
+      done = result.current.mutateAsync({ id: 'r1', favorite: false });
+    });
+    await act(async () => {
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+    expect(queryClient.getQueryData<Rom[]>(['roms'])?.[0]?.favorite).toBe(true);
+    await act(async () => {
+      finish();
+      await done;
+    });
+  });
+
+  test('a refusal reverts the cache, shows ONE Retry toast, and rejects with the cause', async () => {
+    const { queryClient, result, errorSpy } = setup(() => Promise.reject(new Error('nope')));
+    let caught: unknown;
+    await act(async () => {
+      await result.current.mutateAsync({ id: 'r1', favorite: false }).catch((e: unknown) => {
+        caught = e;
+      });
+    });
+    expect(queryClient.getQueryData<Rom[]>(['roms'])?.[0]?.favorite).toBe(false);
+    expect(caught).toBeInstanceOf(OptimisticFailure);
+    expect((caught as Error).cause).toBeInstanceOf(Error);
+    expect(toastError).toHaveBeenCalledTimes(1);
+    expect(errorSpy).not.toHaveBeenCalled();
+  });
+});

package/src/react/createApiHooks.ts

@@ -6,6 +6,8 @@ import {
   useQueryClient,
 } from '@tanstack/react-query';
 import type { ReactNode } from 'react';
+import { type OptimisticQueryClient, optimistic as runOptimistic, queryTarget } from './optimistic/optimistic.js';
+import type { IdOf } from './optimistic/revert.js';
 
 // IMPORTANT: this factory's PUBLIC surface is deliberately free of @tanstack's
 // class-shaped types (UseQueryResult/UseQueryOptions/QueryClient). Those carry
@@ -121,6 +123,32 @@ export interface ApiMutationConfig<Client, TArgs, TData> {
   onSuccess?: (data: TData, args: TArgs) => void;
   /** Extra error handling, in addition to the automatic error toast. */
   onError?: (error: unknown, args: TArgs) => void;
+  /**
+   * Show the change before the server answers (STA-10). Each edit is a cache entry and the
+   * forward change to its data; the rollback is derived, and a refusal reverts only what this
+   * call touched and toasts "Couldn't <label>" with Retry — in place of the plain error toast.
+   * Every edited key is refetched once the request settles.
+   *
+   *   optimistic: {
+   *     label: (rom) => `favorite “${rom.title}”`,
+   *     edits: (rom) => [{ queryKey: ['roms'], apply: (roms: Rom[]) => roms.map(...) }],
+   *   }
+   */
+  optimistic?: ApiOptimistic<TArgs>;
+}
+
+export interface ApiOptimistic<TArgs> {
+  /** The verb phrase the failure toast completes: "Couldn't " + label. */
+  label: string | ((args: TArgs) => string);
+  /** The cache entries to change at once, each with its forward edit. */
+  edits: (args: TArgs) => ReadonlyArray<{
+    queryKey: QueryKey;
+    apply: (data: any) => any;
+    /** How the entry's array items are told apart when they carry neither `id` nor `key`. */
+    idOf?: IdOf;
+  }>;
+  /** Serialize requests that share a key — e.g. the record's id. */
+  key?: (args: TArgs) => string;
 }
 
 export interface ApiHooks<Client> {
@@ -130,6 +158,14 @@ export interface ApiHooks<Client> {
   ) => ApiMutationResult<TArgs, TData>;
 }
 
+/** The rejection an optimistic mutation's `mutateAsync` gives: the server's own error is `cause`. */
+export class OptimisticFailure extends Error {
+  constructor(cause: unknown) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause });
+    this.name = 'OptimisticFailure';
+  }
+}
+
 /**
  * Build a pair of TanStack-Query hooks bound to your app's request client + toaster.
  * Standardizes the data-fetching boilerplate every app reinvents: apply a fallback
@@ -182,12 +218,28 @@ export const createApiHooks = <Client>({
     invalidate,
     onSuccess,
     onError,
+    optimistic,
   }: ApiMutationConfig<Client, TArgs, TData>): ApiMutationResult<TArgs, TData> => {
     const client = useClient();
     const queryClient = useQueryClient();
     const toaster = useToaster?.();
     return useMutation<TData, unknown, TArgs>({
-      mutationFn: (args) => mutationFn(client, args),
+      mutationFn: optimistic
+        ? async (args) => {
+            const outcome = await runOptimistic({
+              label: typeof optimistic.label === 'function' ? optimistic.label(args) : optimistic.label,
+              key: optimistic.key?.(args),
+              targets: optimistic.edits(args).map(({ queryKey, apply, idOf }) => ({
+                ...queryTarget(queryClient as unknown as OptimisticQueryClient, queryKey),
+                apply,
+                ...(idOf ? { idOf } : {}),
+              })),
+              request: () => mutationFn(client, args),
+            });
+            if (!outcome.ok) throw new OptimisticFailure(outcome.error);
+            return outcome.value;
+          }
+        : (args) => mutationFn(client, args),
       onSuccess: (data, args) => {
         if (successToast && toaster) {
           toaster.success(
@@ -201,6 +253,11 @@ export const createApiHooks = <Client>({
         onSuccess?.(data, args);
       },
       onError: (error, args) => {
+        // An optimistic call has already reverted and shown its own Retry toast.
+        if (error instanceof OptimisticFailure) {
+          onError?.(error.cause, args);
+          return;
+        }
         toaster?.error(error);
         onError?.(error, args);
       },

package/src/react/index.ts

@@ -757,6 +757,7 @@ export { Wizard } from './components/Wizard/Wizard.js';
 export * from './confirm.js';
 export { VIEWPORT_META } from './constants/viewport.js';
 export * from './createApiHooks.js';
+export * from './optimistic/index.js';
 export {
   EmojiAutocomplete,
   type EmojiAutocompleteProps,
@@ -960,6 +961,7 @@ export * from './nav/index.js';
 export * from './palette/index.js';
 export * from './prompt.js';
 export { sessionAuthHeaders } from './sessionAuth.js';
+export { LazyToaster } from './LazyToaster.js';
 export { Toaster, type ToasterProps, toast } from './Toast.js';
 export { TestReportViewer, type TestReportViewerProps } from './testReport/index.js';
 export { UiScaleControl, type UiScaleControlProps } from './uiScale/UiScaleControl.js';

package/src/react/optimistic/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Optimistic changes — the UI does what the user asked at once, the server is told after, and
+ * only a refusal takes it back (with a Retry toast). `optimistic.ts` has the contract; the rule
+ * for WHEN to use it is STA-10 in the design law (`docs/design/states-and-feedback.md`).
+ */
+import { useSyncExternalStore } from 'react';
+import { type PendingChange, pendingChanges, subscribePendingChanges } from './optimistic.js';
+
+export {
+  type OptimisticOptions,
+  type OptimisticOutcome,
+  type OptimisticQueryClient,
+  type OptimisticStep,
+  type OptimisticTarget,
+  optimistic,
+  type PendingChange,
+  pendingChanges,
+  queryTarget,
+  subscribePendingChanges,
+  target,
+  whenSettled,
+} from './optimistic.js';
+export { counterRevert } from './revert.js';
+
+const none: readonly PendingChange[] = [];
+
+/**
+ * The optimistic changes still waiting on the server — all of them, or those under one `key`.
+ * For a quiet "Saving…" beside a record, or a sync dot in the shell; never a spinner that holds
+ * the user back, since the change has already happened on screen.
+ */
+export function usePendingChanges(key?: string): readonly PendingChange[] {
+  const all = useSyncExternalStore(subscribePendingChanges, pendingChanges, () => none);
+  if (key === undefined) return all;
+  return all.filter((change) => change.key === key);
+}

package/src/react/optimistic/optimistic.spec.tsx

@@ -0,0 +1,225 @@
+import { afterEach, beforeEach, describe, expect, type Mock, spyOn, test } from 'bun:test';
+import { act, renderHook } from '@testing-library/react';
+import { useState } from 'react';
+import { toast } from '../Toast.js';
+import { counterRevert, optimistic, pendingChanges, queryTarget, usePendingChanges, whenSettled } from './index.js';
+
+// A spy on the real toast, restored after each test — `mock.module` would outlive this file.
+let toastError: Mock<typeof toast.error>;
+beforeEach(() => {
+  toastError = spyOn(toast, 'error').mockImplementation(() => 0);
+});
+afterEach(() => toastError.mockRestore());
+
+type Row = { id: string; title: string };
+const rows: Row[] = [
+  { id: 'a', title: 'A' },
+  { id: 'b', title: 'B' },
+  { id: 'c', title: 'C' },
+];
+
+/** A promise the test settles by hand — the server's answer, on the test's schedule. */
+const deferred = <T,>() => {
+  let resolve!: (value: T) => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+};
+
+/** Plain state with a setState-shaped setter, standing in for a store. */
+const box = <S,>(initial: S) => {
+  const b = {
+    value: initial,
+    set: (updater: (s: S) => S) => {
+      b.value = updater(b.value);
+    },
+  };
+  return b;
+};
+
+describe('optimistic', () => {
+  test('the change shows BEFORE the request settles, and stays when it succeeds', async () => {
+    const state = box(rows);
+    const server = deferred<string>();
+    const done = optimistic({
+      label: 'delete “B”',
+      targets: { set: state.set, apply: (r: Row[]) => r.filter((x) => x.id !== 'b') },
+      request: () => server.promise,
+    });
+    expect(state.value.map((r) => r.id)).toEqual(['a', 'c']);
+    expect(pendingChanges()).toHaveLength(1);
+    server.resolve('ok');
+    expect(await done).toEqual({ ok: true, value: 'ok' });
+    expect(state.value.map((r) => r.id)).toEqual(['a', 'c']);
+    expect(pendingChanges()).toHaveLength(0);
+    expect(toastError).not.toHaveBeenCalled();
+  });
+
+  test('a refusal reverts only its own change, toasts with Retry, and Retry tries again', async () => {
+    const state = box(rows);
+    const total = box(3);
+    const first = deferred<void>();
+    const failing = optimistic({
+      label: 'delete “A”',
+      targets: [
+        { set: state.set, apply: (r: Row[]) => r.filter((x) => x.id !== 'a') },
+        { set: total.set, apply: (n: number) => n - 1, revert: counterRevert },
+      ],
+      request: () => first.promise,
+    });
+    const second = optimistic({
+      label: 'delete “B”',
+      targets: [
+        { set: state.set, apply: (r: Row[]) => r.filter((x) => x.id !== 'b') },
+        { set: total.set, apply: (n: number) => n - 1, revert: counterRevert },
+      ],
+      request: () => Promise.resolve(),
+    });
+    await second;
+    first.reject(new Error('the server said no'));
+    const outcome = await failing;
+    expect(outcome.ok).toBe(false);
+    expect(state.value.map((r) => r.id)).toEqual(['a', 'c']);
+    expect(total.value).toBe(2);
+
+    expect(toastError).toHaveBeenCalledTimes(1);
+    const [message, data] = toastError.mock.calls[0] as unknown as [string, { description: string; action: { label: string; onClick: () => void } }];
+    expect(message).toBe('Couldn’t delete “A”');
+    expect(data.description).toBe('the server said no');
+    expect(data.action.label).toBe('Retry');
+  });
+
+  test('a step (imperative now/undo) runs at once and undoes on a refusal', async () => {
+    const log: string[] = [];
+    await optimistic({
+      label: 'favorite',
+      toast: false,
+      targets: { now: () => log.push('now'), undo: () => log.push('undo') },
+      request: () => Promise.reject(new Error('no')),
+    });
+    expect(log).toEqual(['now', 'undo']);
+  });
+
+  test('a rollback skips state that belongs to another view by now', async () => {
+    const state = box(rows);
+    let view = 'folder-1';
+    const server = deferred<void>();
+    const done = optimistic({
+      label: 'delete “A”',
+      toast: false,
+      targets: { set: state.set, apply: (r: Row[]) => r.filter((x) => x.id !== 'a'), scope: () => view },
+      request: () => server.promise,
+    });
+    view = 'folder-2';
+    state.value = [{ id: 'z', title: 'Z' }];
+    server.reject(new Error('no'));
+    await done;
+    expect(state.value.map((r) => r.id)).toEqual(['z']);
+  });
+
+  test('requests under one key reach the server in order; the UI never waits for the queue', async () => {
+    const state = box({ title: 'A' });
+    const order: string[] = [];
+    const gate = deferred<void>();
+    const one = optimistic({
+      label: 'rename',
+      key: 'row-a',
+      targets: { set: state.set, apply: (s: { title: string }) => ({ ...s, title: 'X' }) },
+      request: async () => {
+        order.push('X sent');
+        await gate.promise;
+        order.push('X done');
+      },
+    });
+    const two = optimistic({
+      label: 'rename',
+      key: 'row-a',
+      targets: { set: state.set, apply: (s: { title: string }) => ({ ...s, title: 'Y' }) },
+      request: async () => {
+        order.push('Y sent');
+      },
+    });
+    expect(state.value.title).toBe('Y');
+    await Promise.resolve();
+    expect(order).toEqual(['X sent']);
+    gate.resolve();
+    await Promise.all([one, two]);
+    expect(order).toEqual(['X sent', 'X done', 'Y sent']);
+  });
+
+  test('the page asks before closing while a change is unsent, and stops asking after', async () => {
+    const server = deferred<void>();
+    const done = optimistic({ label: 'save', request: () => server.promise, toast: false });
+    const event = new Event('beforeunload', { cancelable: true });
+    window.dispatchEvent(event);
+    expect(event.defaultPrevented).toBe(true);
+    server.resolve();
+    await done;
+    const later = new Event('beforeunload', { cancelable: true });
+    window.dispatchEvent(later);
+    expect(later.defaultPrevented).toBe(false);
+  });
+
+  test('works through a React setter, and usePendingChanges follows the request', async () => {
+    const server = deferred<void>();
+    const { result } = renderHook(() => {
+      const [list, setList] = useState(rows);
+      return { list, setList, pending: usePendingChanges('row-b') };
+    });
+    let done!: Promise<unknown>;
+    act(() => {
+      done = optimistic({
+        label: 'delete “B”',
+        key: 'row-b',
+        targets: { set: result.current.setList, apply: (r: Row[]) => r.filter((x) => x.id !== 'b') },
+        request: () => server.promise,
+      });
+    });
+    expect(result.current.list.map((r) => r.id)).toEqual(['a', 'c']);
+    expect(result.current.pending).toHaveLength(1);
+    await act(async () => {
+      server.reject(new Error('no'));
+      await done;
+    });
+    expect(result.current.list.map((r) => r.id)).toEqual(['a', 'b', 'c']);
+    expect(result.current.pending).toHaveLength(0);
+  });
+
+  test('queryTarget cancels the in-flight fetch, writes the cache, and refetches on settle', async () => {
+    const calls: string[] = [];
+    let data: unknown = rows;
+    const client = {
+      cancelQueries: () => void calls.push('cancel'),
+      setQueryData: (_k: readonly unknown[], updater: (old: unknown) => unknown) => {
+        data = updater(data);
+        calls.push('set');
+      },
+      invalidateQueries: () => void calls.push('invalidate'),
+    };
+    await optimistic({
+      label: 'delete “C”',
+      targets: { ...queryTarget<Row[]>(client, ['rows']), apply: (r: Row[]) => r.filter((x) => x.id !== 'c') },
+      request: () => Promise.resolve(),
+    });
+    expect((data as Row[]).map((r) => r.id)).toEqual(['a', 'b']);
+    expect(calls).toEqual(['cancel', 'set', 'invalidate']);
+  });
+
+  test('whenSettled resolves once nothing is pending', async () => {
+    const server = deferred<void>();
+    const done = optimistic({ label: 'save', toast: false, request: () => server.promise });
+    let quiet = false;
+    const waiting = whenSettled().then(() => {
+      quiet = true;
+    });
+    await Promise.resolve();
+    expect(quiet).toBe(false);
+    server.resolve();
+    await done;
+    await waiting;
+    expect(quiet).toBe(true);
+  });
+});