From fe2445675b26022550a41a0f80dc6f3cc32b1aef Mon Sep 17 00:00:00 2001 From: clover caruso Date: Wed, 11 Nov 2026 09:56:11 -0800 Subject: [PATCH] fix: attribute helper restores and refetches to their call Optimistic helpers were created once per channel and registered their restores straight onto the channel's rollback list, uncounted. A call retired its rollbacks by splicing its count from the front of that list, so a succeeded call left its helper restores behind (or retired another call's entry in their place), and a later failure on the same key replayed them, putting back the value from before the confirmed write. The throw, no-op snapshot and debounced paths spliced by count from the end with the same blind spot. Refetches were shared the same way. The shared helpers' refetch dedupe was never cleared, so while a listener kept the channel alive only the first call refetched a query, and a settling call ran every queued call's refetches before their writes landed, leaving the cache stale after the later write succeeded. Each call now creates its own helpers and owns its restores and refetches. Success drops them with the call; failure runs the restores of the failed, queued and pending debounced calls newest first, then the refetches of the failed and cancelled calls; a throw, a no-op snapshot and a superseded debounced call run only their own restores. The public API is unchanged. Assisted-by: claude-opus-5.5 --- jsr.json | 2 +- readme.changes.md | 16 ++ src/mutation.ts | 180 +++++++++------------ test/tanstack-query-helpers.test.ts | 235 +++++++++++++++++++++++++++- 4 files changed, 324 insertions(+), 109 deletions(-) diff --git a/jsr.json b/jsr.json index d2c7493f1d760a714d367e73f2032c6e2811ab07..1fa797aa97da3152cc2ba78ca7fe36686157153c 100644 --- a/jsr.json +++ b/jsr.json @@ -1,6 +1,6 @@ { "name": "@clo/react-mutation", - "version": "3.0.3", + "version": "3.0.4", "exports": { ".": "./src/mod.ts", "./tanstack-query": "./src/tanstack-query.ts", diff --git a/readme.changes.md b/readme.changes.md index dd6053b89e6c4f1ea80f67f2ffe09a65399ca6c7..4a1c9d44b766dff6b6cf616f397bca537e058f0f 100644 --- a/readme.changes.md +++ b/readme.changes.md @@ -1,5 +1,21 @@ # notable changes in React Mutation +## v3.0.4 + +### bugfixes + +- resolve a failed call replaying the optimistic helper restores of an earlier + call on the same key that had succeeded, putting back the value from before + the confirmed write +- resolve a successful call that also used optimistic helpers retiring another + call's `onRestore` callbacks instead of its own +- resolve helper updates not being rolled back when `optimistic` throws, when + `snapshot` skips a no-op call, or when a debounced call is superseded +- resolve helpers refetching a query only for the first call on a key while a + `useMutate` stays subscribed to it +- resolve a queued call's refetches running when the call ahead of it settled, + before its own write, which left the cache stale after both succeeded + ## v3.0.3 ### bugfixes diff --git a/src/mutation.ts b/src/mutation.ts index 7b6cd23dc13efd4f6b487678f40abd01b13651ee..1b14c1bd4bcdf0adba6a7d3ff3d1f0593ecca605 100644 --- a/src/mutation.ts +++ b/src/mutation.ts @@ -124,8 +124,8 @@ interface PendingDebouncedState { args: Args; /** Context captured when the most recent call was allowed */ context: Context; - /** Number of rollbacks the most recent call added */ - rollbackCount: number; + /** Restores registered by the most recent call */ + rollbacks: Array<() => void>; /** All pending promises from all superseded calls */ pending: Array<{ resolve: (result: Result) => void; @@ -133,6 +133,8 @@ interface PendingDebouncedState { }>; /** Success callbacks from the most recent call */ onSuccess: Array<(result: Result) => void>; + /** Refetch callbacks from the most recent call */ + refetches: Array<() => Promise>; /** Initial snapshot before any debounced calls (for no-op detection) */ initialSnapshot?: unknown; /** Whether the last call wanted global handlers to be called */ @@ -157,14 +159,10 @@ function unwrapMutationError(caught: unknown) { return { error: caught, description: null }; } -interface Channel { +interface Channel { listeners: Set<(update: MutationEvent) => void>; status: "idle" | "waiting" | "mutating" | "refetching" | "skipped"; - rollbacks: Array<() => void>; - refetches: Array<() => Promise>; queue: Array>; - // Shared optimistic helpers instance for the channel - helpers: OptimisticHelpers | null; // Debounce state (only used if debounce option is set) debounceTimer: ReturnType | null; pendingDebounced: PendingDebouncedState | null; @@ -175,7 +173,8 @@ interface Channel { interface Item { args: Args; context: Context; - rollbacks: number; + rollbacks: Array<() => void>; + refetches: Array<() => Promise>; onSuccess: Array<(result: Result) => void>; resolve: (result: Result) => void; reject: (error: unknown) => void; @@ -191,7 +190,7 @@ export class BlockingMutation< #client: MutationClientFromConfig; #channels: Map< string, - Channel> + Channel> > = new Map(); client: MutationClientFromConfig; @@ -255,14 +254,10 @@ export class BlockingMutation< #getOrPutChannel(key: string) { let channel = this.#channels.get(key); if (!channel) { - const rollbacks: Array<() => []> = []; channel = { listeners: new Set(), status: "idle", - rollbacks, - refetches: [], queue: [], - helpers: null, debounceTimer: null, pendingDebounced: null, lastDebouncedExecutionTime: null, @@ -282,7 +277,7 @@ export class BlockingMutation< } #notify( - channel: Channel>, + channel: Channel>, status: MutationEvent["status"], result: Result | null = null, error: unknown = null, @@ -293,7 +288,7 @@ export class BlockingMutation< #setIdle( key: string, - channel: Channel>, + channel: Channel>, ) { // Check if there are pending debounced calls waiting if (channel.pendingDebounced !== null) { @@ -303,8 +298,6 @@ export class BlockingMutation< } else { // Normal idle transition channel.status = "idle"; - // Discard any unconsumed refetch callbacks - channel.refetches = []; this.#notify(channel, "idle", null, null); // Clean up the channel if there are no listeners if (channel.listeners.size === 0) { @@ -477,44 +470,39 @@ export class BlockingMutation< ? this.#options.snapshot.call(context, { ...context, args }) : undefined; - // Create shared optimistic helpers instance for the channel if it doesn't exist - if (channel.helpers === null) { - const onRefetch = (cb: () => Promise) => { - channel.refetches.push(cb); - }; - - channel.helpers = this.#client.getOptimisticHelpers({ - onRestore: (cb: () => void) => { - channel.rollbacks.push(cb); - }, - onRefetch, - }); - } - const onSuccess: Array<(result: Result) => void> = []; let expired = false; - let rollbacks = 0; + const rollbacks: Array<() => void> = []; + const refetches: Array<() => Promise> = []; const onRestore = (cb: () => void) => { if (expired) { throw new Error( "Can only call onRestore from within the optimistic update function.", ); } - channel.rollbacks.push(cb); - rollbacks += 1; + rollbacks.push(cb); }; // Register user's onRestore callback if provided if (userOnRestore) { - channel.rollbacks.push(userOnRestore); - rollbacks += 1; + rollbacks.push(userOnRestore); } + // Per call, so restores, refetches and refetch dedupe belong to this call + const helpers = this.#client.getOptimisticHelpers({ + onRestore: (cb) => { + rollbacks.push(cb); + }, + onRefetch: (cb) => { + refetches.push(cb); + }, + }); + try { this.#options.optimistic({ ...context, args, - helpers: channel.helpers, + helpers, onRestore, onSuccess(cb) { if (expired) { @@ -530,17 +518,13 @@ export class BlockingMutation< "Can only call onRefetch from within the optimistic update function.", ); } - channel.refetches.push(cb); + refetches.push(cb); }, }); } catch (error) { expired = true; let next; - while ( - next = channel.rollbacks.splice(channel.rollbacks.length - rollbacks, 1)[0] - ) { - next(); - } + while (next = rollbacks.pop()) next(); return Promise.reject(error); } expired = true; @@ -555,11 +539,7 @@ export class BlockingMutation< if (isNoOp) { let next; - while ( - next = channel.rollbacks.splice(channel.rollbacks.length - rollbacks, 1)[0] - ) { - next(); - } + while (next = rollbacks.pop()) next(); // Notify listeners of skipped status this.#notify(channel, "skipped"); @@ -573,6 +553,7 @@ export class BlockingMutation< args, context, rollbacks, + refetches, onSuccess, resolve, reject, @@ -587,7 +568,7 @@ export class BlockingMutation< #executeNext( key: string, - channel: Channel>, + channel: Channel>, ) { const item = channel.queue.shift(); if (!item) { @@ -595,21 +576,19 @@ export class BlockingMutation< return; } - const { args, context, onSuccess, resolve, reject } = item; + const { args, context, refetches, onSuccess, resolve, reject } = item; channel.status = "mutating"; this.#notify(channel, "mutating"); new Promise((resolve) => resolve(this.#options.mutate.call(context, ...args))).then((result) => { - // remove rollbacks and apply optimistic success handlers - channel.rollbacks.splice(0, item.rollbacks); + // the call's rollbacks retire with it; apply optimistic success handlers onSuccess.forEach((cb) => cb(result)); if (this.#options.refetchOnSuccess !== false) { channel.status = "refetching"; this.#notify(channel, "refetching", result); // Call refetch and all refetch callbacks in parallel - const refetchCallbacks = channel.refetches.splice(0); - Promise.allSettled(refetchCallbacks.map((cb) => cb())).then( + Promise.allSettled(refetches.map((cb) => cb())).then( (results) => { // Report any errors from refetch or callbacks results.forEach((result) => { @@ -623,8 +602,6 @@ export class BlockingMutation< this.#executeNext(key, channel); }); } else { - // Discard refetch callbacks if refetchOnSuccess is false - channel.refetches = []; // Notify listeners with success status and result before moving to next this.#notify(channel, "mutating", result); this.#executeNext(key, channel); @@ -635,12 +612,14 @@ export class BlockingMutation< const description = this.describe(...args); const wrappedError = new MutationError(error, description); - // if an error happens, then every rollback is called in reverse order - let next; - while (next = channel.rollbacks.pop()) next(); - - // Cancel all remaining items in the channel + // if an error happens, then every pending call's rollbacks are called in reverse order const remainingItems = channel.queue.splice(0); + for (const call of [item, ...remainingItems, channel.pendingDebounced].reverse()) { + let next; + while (next = call?.rollbacks.pop()) next(); + } + + // Cancel all remaining items in the channel remainingItems.forEach((queuedItem) => { queuedItem.reject(wrappedError); }); @@ -651,8 +630,8 @@ export class BlockingMutation< // Refetch to restore correct state channel.status = "refetching"; this.#notify(channel, "refetching", null, error); - // Call refetch and all refetch callbacks in parallel - const refetchCallbacks = channel.refetches.splice(0); + // Refetch for the failed and cancelled calls in parallel + const refetchCallbacks = [item, ...remainingItems].flatMap((call) => call.refetches); Promise.allSettled(refetchCallbacks.map((cb) => cb())).then((results) => { // Report any errors from refetch or callbacks results.forEach((result) => { @@ -672,7 +651,7 @@ export class BlockingMutation< #runDebouncedAndReturn( args: Args, key: string, - channel: Channel>, + channel: Channel>, context: Context, userOnRestore: (() => void) | undefined, shouldExecuteImmediate: boolean, @@ -693,44 +672,40 @@ export class BlockingMutation< this.#rollbackPendingDebounced(channel); } - // Create shared helpers if needed (same as current implementation) - if (channel.helpers === null) { - const onRefetch = (cb: () => Promise) => { - channel.refetches.push(cb); - }; - channel.helpers = this.#client.getOptimisticHelpers({ - onRestore: (cb: () => void) => { - channel.rollbacks.push(cb); - }, - onRefetch, - }); - } - // Apply optimistic update (same logic as current runAndReturn) const onSuccess: Array<(result: Result) => void> = []; let expired = false; - let rollbacks = 0; + const rollbacks: Array<() => void> = []; + const refetches: Array<() => Promise> = []; const onRestore = (cb: () => void) => { if (expired) { throw new Error( "Can only call onRestore from within the optimistic update function.", ); } - channel.rollbacks.push(cb); - rollbacks += 1; + rollbacks.push(cb); }; // Register user's onRestore callback if provided if (userOnRestore) { - channel.rollbacks.push(userOnRestore); - rollbacks += 1; + rollbacks.push(userOnRestore); } + // Per call, so restores, refetches and refetch dedupe belong to this call + const helpers = this.#client.getOptimisticHelpers({ + onRestore: (cb) => { + rollbacks.push(cb); + }, + onRefetch: (cb) => { + refetches.push(cb); + }, + }); + try { this.#options.optimistic({ ...context, args, - helpers: channel.helpers, + helpers, onRestore, onSuccess(cb) { if (expired) { @@ -746,18 +721,14 @@ export class BlockingMutation< "Can only call onRefetch from within the optimistic update function.", ); } - channel.refetches.push(cb); + refetches.push(cb); }, }); } catch (error) { expired = true; // Roll back the rollbacks we just added let next; - while ( - next = channel.rollbacks.splice(channel.rollbacks.length - rollbacks, 1)[0] - ) { - next(); - } + while (next = rollbacks.pop()) next(); return Promise.reject(error); } expired = true; @@ -778,11 +749,7 @@ export class BlockingMutation< ) { // No-op detected - rollback optimistic update let next; - while ( - next = channel.rollbacks.splice(channel.rollbacks.length - rollbacks, 1)[0] - ) { - next(); - } + while (next = rollbacks.pop()) next(); // Clear debounce timer if (channel.debounceTimer !== null) { @@ -810,9 +777,10 @@ export class BlockingMutation< channel.pendingDebounced = { args, context, - rollbackCount: rollbacks, + rollbacks, pending: [{ resolve, reject }], onSuccess, + refetches, initialSnapshot: isFirstDebouncedCall ? initialSnapshot : undefined, shouldCallGlobalHandler, }; @@ -826,9 +794,10 @@ export class BlockingMutation< // Subsequent debounced call - update state channel.pendingDebounced.args = args; channel.pendingDebounced.context = context; - channel.pendingDebounced.rollbackCount = rollbacks; + channel.pendingDebounced.rollbacks = rollbacks; channel.pendingDebounced.pending.push({ resolve, reject }); channel.pendingDebounced.onSuccess = onSuccess; + channel.pendingDebounced.refetches = refetches; channel.pendingDebounced.shouldCallGlobalHandler = shouldCallGlobalHandler; // Keep the initial snapshot from the first call // Status stays "waiting" @@ -849,18 +818,15 @@ export class BlockingMutation< } #rollbackPendingDebounced( - channel: Channel>, + channel: Channel>, ) { if (!channel.pendingDebounced) return; - const { rollbackCount } = channel.pendingDebounced; + const { rollbacks } = channel.pendingDebounced; // Roll back this call's optimistic updates (in reverse order) - // Remove from the end of the rollbacks array - for (let i = 0; i < rollbackCount; i++) { - const rollback = channel.rollbacks.pop(); - if (rollback) rollback(); - } + let next; + while (next = rollbacks.pop()) next(); // Note: We do NOT reject the promises here // They will all resolve when the final call completes @@ -868,7 +834,7 @@ export class BlockingMutation< #enqueueDebouncedCall( key: string, - channel: Channel>, + channel: Channel>, ) { // Clear timer channel.debounceTimer = null; @@ -879,7 +845,8 @@ export class BlockingMutation< return; } - const { args, context, rollbackCount, pending, onSuccess, shouldCallGlobalHandler } = channel.pendingDebounced; + const { args, context, rollbacks, pending, onSuccess, refetches, shouldCallGlobalHandler } = + channel.pendingDebounced; channel.pendingDebounced = null; // Track execution time for debounceImmediate @@ -928,7 +895,8 @@ export class BlockingMutation< channel.queue.push({ args, context, - rollbacks: rollbackCount, + rollbacks, + refetches, onSuccess, resolve: wrapperResolve, reject: wrapperReject, diff --git a/test/tanstack-query-helpers.test.ts b/test/tanstack-query-helpers.test.ts index 97da68e6d9267c82af87865e5f0634c12989f418..06b814e3c538eba6daf73b4aa1c24a7413f9d8e3 100644 --- a/test/tanstack-query-helpers.test.ts +++ b/test/tanstack-query-helpers.test.ts @@ -1,6 +1,8 @@ +import { delay } from "@clo/lib/async.ts"; import { assertEquals } from "@std/assert"; -import { QueryClient, queryOptions } from "@tanstack/react-query"; -import { test } from "vitest"; +import { QueryClient, QueryObserver, queryOptions } from "@tanstack/react-query"; +import { test, vi } from "vitest"; +import { MutationClient } from "../src/client.ts"; import { queryClientOptimisticHelpers, reactiveFromQueryCache } from "../src/tanstack-query.ts"; interface TestData { @@ -1114,3 +1116,232 @@ test("integration - multiple operations work together", () => { assertEquals(restored?.active, true); assertEquals(restored?.items.length, 3); }); + +// ============================================================================ +// Mutation integration: each call owns the restores and refetches its helpers register +// ============================================================================ + +function createToggleClient() { + const queryClient = new QueryClient({ + defaultOptions: { queries: { retry: false } }, + }); + const server = { enabled: true, online: true, fetches: 0 }; + + const queryToggle = queryOptions({ + queryKey: ["toggle"], + queryFn: async () => { + server.fetches += 1; + if (!server.online) throw new Error("offline"); + return { enabled: server.enabled }; + }, + }); + queryClient.setQueryData(queryToggle.queryKey, { enabled: true }); + // Observed, so invalidation refetches it; the refetch fails while offline. + new QueryObserver(queryClient, queryToggle).subscribe(() => {}); + + const mutations = new MutationClient({ + context: {}, + getOptimisticHelpers: queryClientOptimisticHelpers(queryClient), + reportError: () => {}, + }); + + const save = async (enabled: boolean) => { + await delay(10); + if (!server.online) throw new Error("offline"); + server.enabled = enabled; + return enabled; + }; + const read = () => queryClient.getQueryData(queryToggle.queryKey)?.enabled; + + return { queryClient, queryToggle, server, mutations, save, read }; +} + +test("a failure does not replay the helper restores of a call that succeeded", async () => { + vi.useFakeTimers(); + const { queryToggle, server, mutations, save, read } = createToggleClient(); + const mutToggle = mutations.define({ + id: "toggle", + mutate: save, + optimistic: ({ helpers, args: [enabled] }) => { + helpers.updateExisting(queryToggle, { enabled }); + }, + describe: "toggle", + describeResult: null, + }); + // `useMutate` keeps the channel alive between calls + mutToggle.subscribe(mutToggle.key([true]), () => {}); + + mutToggle.run(false); + await vi.advanceTimersByTimeAsync(100); + assertEquals([server.enabled, read()], [false, false]); + + server.online = false; + mutToggle.run(true); + assertEquals(read(), true); + await vi.advanceTimersByTimeAsync(100); + assertEquals(read(), false); +}); + +test("a queued failure does not replay the helper restores of the call ahead of it", async () => { + vi.useFakeTimers(); + const { queryToggle, server, mutations, save, read } = createToggleClient(); + const mutToggle = mutations.define({ + id: "toggle", + mutate: save, + optimistic: ({ helpers, args: [enabled] }) => { + helpers.updateExisting(queryToggle, { enabled }); + }, + describe: "toggle", + describeResult: null, + }); + + mutToggle.run(false); + mutToggle.run(true); + await vi.advanceTimersByTimeAsync(10); + assertEquals(server.enabled, false); + + server.online = false; + await vi.advanceTimersByTimeAsync(100); + assertEquals(read(), false); +}); + +test("a success retires its own onRestore callbacks, not the channel's oldest restores", async () => { + vi.useFakeTimers(); + const { queryToggle, server, mutations, save, read } = createToggleClient(); + let lastChoice: boolean | null = null; + const mutToggle = mutations.define({ + id: "toggle", + mutate: save, + optimistic: ({ helpers, args: [enabled], onRestore }) => { + helpers.updateExisting(queryToggle, { enabled }); + const prev = lastChoice; + lastChoice = enabled; + onRestore(() => { + lastChoice = prev; + }); + }, + describe: "toggle", + describeResult: null, + }); + mutToggle.subscribe(mutToggle.key([true]), () => {}); + + mutToggle.run(false); + await vi.advanceTimersByTimeAsync(100); + + server.online = false; + mutToggle.run(true); + await vi.advanceTimersByTimeAsync(100); + assertEquals([lastChoice, read()], [false, false]); +}); + +test("an optimistic update that throws restores its helper updates", () => { + const { queryToggle, mutations, save, read } = createToggleClient(); + const mutToggle = mutations.define({ + id: "toggle", + mutate: save, + optimistic: ({ helpers, args: [enabled] }) => { + helpers.updateExisting(queryToggle, { enabled }); + throw new Error("optimistic update failed"); + }, + describe: "toggle", + describeResult: null, + }); + + mutToggle.run(false); + assertEquals(read(), true); +}); + +test("a skipped no-op call's helper restores are not replayed by a later failure", async () => { + vi.useFakeTimers(); + const { queryClient, queryToggle, server, mutations, save, read } = createToggleClient(); + const mutToggle = mutations.define({ + id: "toggle", + mutate: save, + optimistic: ({ helpers, args: [enabled] }) => { + helpers.updateExisting(queryToggle, { enabled }); + }, + snapshot: () => read(), + describe: "toggle", + describeResult: null, + }); + + mutToggle.run(true); + // Another client turns it off. + server.enabled = false; + queryClient.setQueryData(queryToggle.queryKey, { enabled: false }); + + server.online = false; + mutToggle.run(true); + await vi.advanceTimersByTimeAsync(100); + assertEquals(read(), false); +}); + +test("a debounced success retires the helper restores of every call it covers", async () => { + vi.useFakeTimers(); + const { queryToggle, server, mutations, save, read } = createToggleClient(); + const mutToggle = mutations.define({ + id: "toggle", + mutate: save, + optimistic: ({ helpers, args: [enabled] }) => { + helpers.updateExisting(queryToggle, { enabled }); + }, + describe: "toggle", + describeResult: null, + debounceMs: 50, + }); + mutToggle.subscribe(mutToggle.key([true]), () => {}); + + mutToggle.run(false); + mutToggle.run(false); + await vi.advanceTimersByTimeAsync(200); + assertEquals([server.enabled, read()], [false, false]); + + server.online = false; + mutToggle.run(true); + await vi.advanceTimersByTimeAsync(200); + assertEquals(read(), false); +}); + +test("every call refetches the queries its helpers touched", async () => { + vi.useFakeTimers(); + const { queryToggle, server, mutations, save } = createToggleClient(); + const mutToggle = mutations.define({ + id: "toggle", + mutate: save, + optimistic: ({ helpers, args: [enabled] }) => { + helpers.updateExisting(queryToggle, { enabled }); + }, + describe: "toggle", + describeResult: null, + }); + mutToggle.subscribe(mutToggle.key([true]), () => {}); + await vi.advanceTimersByTimeAsync(0); + const fetchesBefore = server.fetches; + + mutToggle.run(false); + await vi.advanceTimersByTimeAsync(100); + assertEquals(server.fetches, fetchesBefore + 1); + + mutToggle.run(true); + await vi.advanceTimersByTimeAsync(100); + assertEquals(server.fetches, fetchesBefore + 2); +}); + +test("a queued call refetches after its own write, not with the call ahead of it", async () => { + vi.useFakeTimers(); + const { queryToggle, server, mutations, save, read } = createToggleClient(); + const mutToggle = mutations.define({ + id: "toggle", + mutate: save, + optimistic: ({ helpers, args: [enabled] }) => { + helpers.updateExisting(queryToggle, { enabled }); + }, + describe: "toggle", + describeResult: null, + }); + + mutToggle.run(false); + mutToggle.run(true); + await vi.advanceTimersByTimeAsync(100); + assertEquals([server.enabled, read()], [true, true]); +}); -- 2.54.1