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