cursedbelt 5.89.0 → 5.90.0

package/src/react/optimistic/optimistic.ts

@@ -0,0 +1,326 @@
+/**
+ * `optimistic()` — do what the user asked NOW, tell the server after, and take it back only if
+ * the server says no.
+ *
+ * The owner, 2026-10-22 (forge task 3583): *"I want the cursedforge apps to use optimistic
+ * updates, where the UI doesn't wait for the server before doing what the user wants … if the
+ * delete fails it can popup a toast error but it would already be on the next track either way."*
+ *
+ *   optimistic({
+ *     label: `delete “${track.title}”`,
+ *     targets: [
+ *       { set: setTracks, apply: (rows) => rows.filter((r) => r.id !== track.id) },
+ *       { set: setTotal, apply: (n) => n - 1, revert: counterRevert },
+ *     ],
+ *     request: () => api.deleteTracks({ ids: [track.id] }),
+ *   });
+ *
+ * What it does, in order:
+ *
+ * 1. **Applies every target's forward edit at once**, through a setState-shaped `set` — React's
+ *    own setter, a store's, or {@link queryTarget} for a TanStack cache. It records the state
+ *    each edit started from and produced, inside the updater, so the rollback is derived
+ *    (`revert.ts`) and no caller writes an undo by hand.
+ * 2. **Sends the request** — after any earlier request with the same `key` has settled, so two
+ *    quick edits to one record reach the server in the order they were made. The UI never waits
+ *    for that queue; only the network does.
+ * 3. **On failure**, reverts exactly what this change touched (concurrent changes survive) and
+ *    shows an error toast naming what did not happen, with **Retry** (OVL-9) — Retry applies the
+ *    change again and resends it.
+ * 4. **While anything is in flight**, the page asks before it is closed or reloaded, because the
+ *    user has already seen the change happen and would otherwise lose it without knowing.
+ *
+ * Side effects that must NOT be undone stay outside it — the user's own words: a deleted song
+ * that comes back after a failed delete comes back to the list, but the player stays on the next
+ * track. Call the player before `optimistic()`, not as a target.
+ *
+ * It never rejects: the resolved {@link OptimisticOutcome} says what happened, so a fire-and-forget
+ * call (`void optimistic(...)`) cannot leak an unhandled rejection.
+ */
+import { defaultIdOf, type IdOf, inverseOf } from './revert.js';
+
+/** A setState-shaped writer: takes an updater from the current state to the next. */
+export type Setter<S> = (updater: (current: S) => S) => void;
+
+export interface OptimisticTarget<S> {
+  /** Where the state lives — `setRows` from `useState`, a store's setter, `queryTarget(...)`. */
+  set: Setter<S>;
+  /** The forward change. Pure: React may call it twice in StrictMode. */
+  apply: (current: S) => S;
+  /** Replace the derived rollback — e.g. {@link counterRevert} for a count. */
+  revert?: (current: S, before: S, after: S) => S;
+  /** How array items are told apart, when they carry neither `id` nor `key`. */
+  idOf?: IdOf;
+  /** Runs once, when the change is made — {@link queryTarget} counts its changes in flight here. */
+  begin?: () => void;
+  /** Runs once the request settles either way — {@link queryTarget} refetches the truth here. */
+  settled?: () => void;
+  /**
+   * Which view this state belongs to, when one piece of state is reused for many — a track list
+   * that holds whichever folder is open. Read when the change is made and again when it would be
+   * reverted: if it differs, the state is a different list by now, so the rollback leaves it alone
+   * (that view's next load is the server's truth). Without it, a failed delete made in one folder
+   * would put the row back into whatever folder is open when the refusal arrives.
+   */
+  scope?: () => unknown;
+}
+
+/**
+ * A change to state that is not setState-shaped — an imperative store, a player's queue, a
+ * callback that patches rows. `now` makes the change; `undo` takes it back if the server refuses.
+ * Prefer a {@link OptimisticTarget} when there is a setter: its rollback is derived, and survives
+ * changes made since. An `undo` here is the caller's, so it should undo only what `now` did.
+ */
+export interface OptimisticStep {
+  now: () => void;
+  undo: () => void;
+}
+
+export interface OptimisticOptions<R> {
+  /**
+   * What the user did, as a verb phrase the failure toast completes: `delete “Song”` →
+   * "Couldn't delete “Song”". Also names the change in {@link pendingChanges}.
+   */
+  label: string;
+  /**
+   * The state edits to make at once. Typed loosely on purpose: one change usually spans several
+   * pieces of state of different types (rows, a count, a selection). Each target's own `apply` is
+   * still checked against its `set` where it is written — {@link target} keeps them paired.
+   */
+  targets?: OptimisticTarget<any> | OptimisticStep | ReadonlyArray<OptimisticTarget<any> | OptimisticStep>;
+  /** The server call. A rejection is a failure; anything it resolves to is success. */
+  request: () => Promise<R>;
+  /**
+   * Requests with the same key go one at a time, in order — use the record's id for edits to one
+   * record. No key: the request goes at once.
+   */
+  key?: string;
+  /** After the server said yes — reconcile a temporary id, refresh a summary. Not reverted. */
+  onSuccess?: (result: R) => void;
+  /** After the rollback, beside the toast. */
+  onError?: (error: unknown) => void;
+  /** `false` silences the failure toast (the caller shows the failure itself). Default on. */
+  toast?: boolean;
+  /** The toast's second line. Default: the error's own message. */
+  describeError?: (error: unknown) => string | undefined;
+}
+
+export type OptimisticOutcome<R> = { ok: true; value: R } | { ok: false; error: unknown };
+
+/** Pair a setter with its edit so the two are type-checked against each other. */
+export const target = <S>(t: OptimisticTarget<S>): OptimisticTarget<S> => t;
+
+// ── what is in flight ─────────────────────────────────────────────────────────────────────
+
+export interface PendingChange {
+  id: number;
+  label: string;
+  key?: string;
+  startedAt: number;
+}
+
+let pending: readonly PendingChange[] = [];
+let nextId = 1;
+const listeners = new Set<() => void>();
+const queues = new Map<string, Promise<unknown>>();
+
+const emit = () => {
+  for (const listener of listeners) listener();
+};
+
+/** Every optimistic change whose request has not settled, oldest first. */
+export const pendingChanges = (): readonly PendingChange[] => pending;
+
+/** Subscribe to {@link pendingChanges} — the `useSyncExternalStore` shape. */
+export const subscribePendingChanges = (listener: () => void): (() => void) => {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+/**
+ * Resolves once nothing is pending — the moment to re-read a list that is not a TanStack query,
+ * so a read that started before the last change landed cannot draw it as undone.
+ */
+export const whenSettled = (): Promise<void> =>
+  pending.length === 0
+    ? Promise.resolve()
+    : new Promise((resolve) => {
+        const off = subscribePendingChanges(() => {
+          if (pending.length > 0) return;
+          off();
+          resolve();
+        });
+      });
+
+/**
+ * Closing the tab while a change is unsent loses it, and the user has already seen it happen.
+ * The listener exists only while something is pending, so an idle page leaves bfcache alone.
+ */
+const onBeforeUnload = (event: BeforeUnloadEvent) => {
+  event.preventDefault();
+  // Chrome still wants returnValue set; the text itself is never shown.
+  event.returnValue = '';
+};
+
+const track = (change: PendingChange): (() => void) => {
+  const wasIdle = pending.length === 0;
+  pending = [...pending, change];
+  if (wasIdle && typeof window !== 'undefined') window.addEventListener('beforeunload', onBeforeUnload);
+  emit();
+  return () => {
+    pending = pending.filter((p) => p.id !== change.id);
+    if (pending.length === 0 && typeof window !== 'undefined') {
+      window.removeEventListener('beforeunload', onBeforeUnload);
+    }
+    emit();
+  };
+};
+
+/** Run `task` after every earlier task under `key` has settled. */
+const enqueue = <R>(key: string | undefined, task: () => Promise<R>): Promise<R> => {
+  if (key === undefined) return task();
+  const run = (queues.get(key) ?? Promise.resolve()).then(task, task);
+  const tail = run.catch(() => undefined);
+  queues.set(key, tail);
+  void tail.then(() => {
+    if (queues.get(key) === tail) queues.delete(key);
+  });
+  return run;
+};
+
+// ── the change ────────────────────────────────────────────────────────────────────────────
+
+interface Applied {
+  rollback: () => void;
+  settled: () => void;
+}
+
+const isStep = (t: OptimisticTarget<unknown> | OptimisticStep): t is OptimisticStep =>
+  typeof (t as OptimisticStep).now === 'function';
+
+function applyStep(step: OptimisticStep): Applied {
+  step.now();
+  return { rollback: step.undo, settled: () => undefined };
+}
+
+function applyTarget<S>(t: OptimisticTarget<S>): Applied {
+  // Captured INSIDE the updater: React runs updaters during render, not when `set` is called.
+  // The rollback updater is queued behind this one, so by the time it runs the capture is there.
+  let seen: { before: S; after: S } | undefined;
+  const scope = t.scope?.();
+  t.begin?.();
+  t.set((current) => {
+    const after = t.apply(current);
+    seen = { before: current, after };
+    return after;
+  });
+  return {
+    rollback: () => {
+      if (t.scope && !Object.is(t.scope(), scope)) return; // another view is on screen now
+      t.set((current) => {
+        if (!seen) return current; // the edit never ran (its owner unmounted) — nothing to undo
+        const { before, after } = seen;
+        return t.revert ? t.revert(current, before, after) : inverseOf(before, after, t.idOf ?? defaultIdOf)(current);
+      });
+    },
+    settled: () => t.settled?.(),
+  };
+}
+
+const messageOf = (error: unknown): string | undefined => {
+  if (error instanceof Error) return error.message || undefined;
+  if (typeof error === 'string') return error || undefined;
+  return undefined;
+};
+
+/** Apply now, send, revert on failure. See the file header. */
+export function optimistic<R>(options: OptimisticOptions<R>): Promise<OptimisticOutcome<R>> {
+  const { label, request, key, onSuccess, onError } = options;
+  const targets = options.targets === undefined ? [] : Array.isArray(options.targets) ? options.targets : [options.targets];
+  const applied = (targets as (OptimisticTarget<unknown> | OptimisticStep)[]).map((t) =>
+    isStep(t) ? applyStep(t) : applyTarget(t),
+  );
+  const done = track({ id: nextId++, label, key, startedAt: Date.now() });
+
+  return enqueue(key, request).then(
+    (value): OptimisticOutcome<R> => {
+      done();
+      for (const a of applied) a.settled();
+      onSuccess?.(value);
+      return { ok: true, value };
+    },
+    async (error: unknown): Promise<OptimisticOutcome<R>> => {
+      done();
+      // Newest-first, so a target listed twice unwinds in the order it was wound.
+      for (const a of [...applied].reverse()) a.rollback();
+      for (const a of applied) a.settled();
+      onError?.(error);
+      if (options.toast !== false) {
+        // Loaded at the first refusal, never before: a static import would put sonner (~10 kB
+        // gzip) back on every app's entry chunk, which cursedbelt 5.64 took it off (forge task
+        // 2900) — flix's and roms' entries grew by it the first time they imported this.
+        const { toast } = await import('../Toast.js');
+        toast.error(`Couldn’t ${label}`, {
+          id: `optimistic:${key ?? label}`,
+          description: options.describeError ? options.describeError(error) : messageOf(error),
+          action: { label: 'Retry', onClick: () => void optimistic(options) },
+        });
+      }
+      return { ok: false, error };
+    },
+  );
+}
+
+// ── TanStack Query ────────────────────────────────────────────────────────────────────────
+
+/**
+ * The query-client surface {@link queryTarget} needs — structural, so this module never imports
+ * `@tanstack/react-query` (an optional peer) and a second copy of it cannot break the types.
+ */
+export interface OptimisticQueryClient {
+  cancelQueries: (filters: { queryKey: readonly unknown[]; exact?: boolean }) => unknown;
+  setQueryData: (queryKey: readonly unknown[], updater: (old: unknown) => unknown) => unknown;
+  invalidateQueries: (filters: { queryKey: readonly unknown[] }) => unknown;
+}
+
+/** Changes in flight per cache entry, so the entry is refetched once, after the LAST of them. */
+const inFlight = new Map<string, number>();
+
+/**
+ * A TanStack cache entry as a target's `set`: cancels the key's in-flight fetch first (so a
+ * response already on the wire cannot land on top of the change), writes through `setQueryData`,
+ * and refetches the key once the request settles, so the cache ends on the server's truth.
+ * An entry with no data yet is left alone.
+ *
+ * 🔴 The refetch waits for the LAST change in flight on the entry. Refetching after each one
+ * (the first version) meant two quick deletes drew the second row back for a moment: the first
+ * answer's refetch read the server before the second delete had landed (collections and desk
+ * both met it, forge task 3583; TanStack's own docs gate on `isMutating`).
+ *
+ *   targets: [{ ...queryTarget(queryClient, ['lists']), apply: (lists) => lists.filter(...) }]
+ */
+export function queryTarget<S>(
+  client: OptimisticQueryClient,
+  queryKey: readonly unknown[],
+  { refetch = true }: { refetch?: boolean } = {},
+): Pick<OptimisticTarget<S>, 'set' | 'begin' | 'settled'> {
+  const entry = JSON.stringify(queryKey);
+  return {
+    set: (updater) => {
+      void client.cancelQueries({ queryKey, exact: true });
+      client.setQueryData(queryKey, (old) => (old === undefined ? old : updater(old as S)));
+    },
+    begin: () => inFlight.set(entry, (inFlight.get(entry) ?? 0) + 1),
+    settled: () => {
+      const left = (inFlight.get(entry) ?? 1) - 1;
+      if (left > 0) {
+        inFlight.set(entry, left);
+        return;
+      }
+      inFlight.delete(entry);
+      if (refetch) void client.invalidateQueries({ queryKey });
+    },
+  };
+}

package/src/react/optimistic/queryTarget.spec.ts

@@ -0,0 +1,64 @@
+/**
+ * `queryTarget` refetches a cache entry once, after the LAST optimistic change on it settles.
+ * Refetching after each one drew the second of two quick deletes back for a moment: the first
+ * answer's refetch read the server before the second delete had landed (collections and desk both
+ * met it, forge task 3583). Its own file so it imports only what predates the fix.
+ */
+import { afterEach, beforeEach, describe, expect, type Mock, spyOn, test } from 'bun:test';
+import { toast } from '../Toast.js';
+import { optimistic, queryTarget } from './optimistic.js';
+
+type Row = { id: string; title: string };
+const rows: Row[] = [
+  { id: 'a', title: 'A' },
+  { id: 'b', title: 'B' },
+  { id: 'c', title: 'C' },
+];
+
+const deferred = <T,>() => {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+};
+
+let toastError: Mock<typeof toast.error>;
+beforeEach(() => {
+  toastError = spyOn(toast, 'error').mockImplementation(() => 0);
+});
+afterEach(() => toastError.mockRestore());
+
+describe('queryTarget', () => {
+  test('two changes on one cache entry refetch it ONCE, after the last settles', async () => {
+    const calls: string[] = [];
+    let data: unknown = rows;
+    const client = {
+      cancelQueries: () => undefined,
+      setQueryData: (_k: readonly unknown[], updater: (old: unknown) => unknown) => {
+        data = updater(data);
+      },
+      invalidateQueries: () => void calls.push('invalidate'),
+    };
+    const first = deferred<void>();
+    const second = deferred<void>();
+    const one = optimistic({
+      label: 'delete “A”',
+      targets: { ...queryTarget<Row[]>(client, ['rows']), apply: (r: Row[]) => r.filter((x) => x.id !== 'a') },
+      request: () => first.promise,
+    });
+    const two = optimistic({
+      label: 'delete “B”',
+      targets: { ...queryTarget<Row[]>(client, ['rows']), apply: (r: Row[]) => r.filter((x) => x.id !== 'b') },
+      request: () => second.promise,
+    });
+    first.resolve();
+    await one;
+    expect(calls).toEqual([]); // B is still in flight: a refetch now would draw it back
+    second.resolve();
+    await two;
+    expect(calls).toEqual(['invalidate']);
+    expect((data as Row[]).map((r) => r.id)).toEqual(['c']);
+  });
+
+});

package/src/react/optimistic/revert.spec.ts

@@ -0,0 +1,114 @@
+import { describe, expect, test } from 'bun:test';
+import { counterRevert, inverseOf } from './revert.js';
+
+type Row = { id: string; title: string; liked?: boolean };
+const rows: Row[] = [
+  { id: 'a', title: 'A' },
+  { id: 'b', title: 'B' },
+  { id: 'c', title: 'C' },
+];
+const without = (list: Row[], id: string) => list.filter((r) => r.id !== id);
+const rename = (list: Row[], id: string, title: string) => list.map((r) => (r.id === id ? { ...r, title } : r));
+
+describe('inverseOf — arrays of records', () => {
+  test('a removed row comes back where it was', () => {
+    const after = without(rows, 'b');
+    expect(inverseOf(rows, after)(after)).toEqual(rows);
+  });
+
+  test('two deletes, the FIRST fails: only that row returns, the second stays gone', () => {
+    const afterA = without(rows, 'a');
+    const afterB = without(afterA, 'b');
+    expect(inverseOf(rows, afterA)(afterB).map((r) => r.id)).toEqual(['a', 'c']);
+  });
+
+  test('a removed row returns beside its surviving neighbor when rows before it went too', () => {
+    const afterB = without(rows, 'b');
+    const now = without(afterB, 'a'); // another change took A since
+    expect(inverseOf(rows, afterB)(now).map((r) => r.id)).toEqual(['b', 'c']);
+  });
+
+  test('a row the server or a refetch already put back is not doubled', () => {
+    const after = without(rows, 'b');
+    expect(inverseOf(rows, after)(rows)).toBe(rows);
+  });
+
+  test('an added row is taken out; rows added since stay', () => {
+    const after = [...rows, { id: 'tmp', title: 'New' }];
+    const now = [...after, { id: 'd', title: 'D' }];
+    expect(inverseOf(rows, after)(now).map((r) => r.id)).toEqual(['a', 'b', 'c', 'd']);
+  });
+
+  test('a patch reverts only the fields it set, and keeps a later edit to another field', () => {
+    const after = rows.map((r) => (r.id === 'b' ? { ...r, liked: true } : r));
+    const now = rename(after, 'b', 'Renamed since');
+    const reverted = inverseOf(rows, after)(now);
+    expect(reverted[1]).toEqual({ id: 'b', title: 'Renamed since' });
+  });
+
+  test('rename twice, the first fails: the second title stands', () => {
+    const first = rename(rows, 'b', 'X');
+    const second = rename(first, 'b', 'Y');
+    expect(inverseOf(rows, first)(second)[1]?.title).toBe('Y');
+  });
+
+  test('a reorder is undone only while the optimistic order still stands', () => {
+    const after = [rows[2], rows[0], rows[1]] as Row[];
+    expect(inverseOf(rows, after)(after).map((r) => r.id)).toEqual(['a', 'b', 'c']);
+    const movedAgain = [rows[0], rows[2], rows[1]] as Row[];
+    expect(inverseOf(rows, after)(movedAgain)).toBe(movedAgain);
+  });
+
+  test('nothing to revert returns the same reference, so a setter does not re-render', () => {
+    const after = without(rows, 'b');
+    const unrelated = [{ id: 'z', title: 'Z' }];
+    // `b` is not there, but neither is its neighbor; it still comes back, at the top.
+    expect(inverseOf(rows, after)(unrelated).map((r) => r.id)).toEqual(['b', 'z']);
+    expect(inverseOf(rows, rows)(unrelated)).toBe(unrelated);
+  });
+
+  test('a custom idOf names rows that carry no id', () => {
+    const files = [{ path: '/a' }, { path: '/b' }];
+    const after = files.slice(1);
+    const idOf = (f: unknown) => (f as { path: string }).path;
+    expect(inverseOf(files, after, idOf)(after)).toEqual(files);
+  });
+});
+
+describe('inverseOf — other shapes', () => {
+  test('primitive arrays behave as sets of values (a tag list)', () => {
+    const tags = ['x', 'y'];
+    const after = ['x', 'y', 'z'];
+    expect(inverseOf(tags, after)(['x', 'y', 'z', 'w'])).toEqual(['x', 'y', 'w']);
+  });
+
+  test('objects recurse key by key: a page { items, total }', () => {
+    const before = { items: rows, total: 3 };
+    const after = { items: without(rows, 'a'), total: 2 };
+    expect(inverseOf(before, after)(after)).toEqual(before);
+  });
+
+  test('a key the change added goes; one it removed comes back', () => {
+    const before: Record<string, number> = { a: 1, b: 2 };
+    const after: Record<string, number> = { a: 1, c: 3 };
+    expect(inverseOf(before, after)(after)).toEqual({ a: 1, b: 2 });
+  });
+
+  test('Set and Map members', () => {
+    const before = new Set(['a']);
+    const after = new Set(['a', 'b']);
+    expect([...inverseOf(before, after)(new Set(['a', 'b', 'c']))]).toEqual(['a', 'c']);
+    const mBefore = new Map([['a', { n: 1 }]]);
+    const mAfter = new Map<string, { n: number }>();
+    expect(inverseOf(mBefore, mAfter)(new Map()).get('a')).toEqual({ n: 1 });
+  });
+
+  test('a scalar returns only if it still holds the optimistic value', () => {
+    expect(inverseOf(false, true)(true)).toBe(false);
+    expect(inverseOf(1, 2)(3)).toBe(3);
+  });
+
+  test('counterRevert gives back the difference, whatever happened since', () => {
+    expect(counterRevert(8, 10, 9)).toBe(9);
+  });
+});