diff --git a/gitbook/reactjrx/queries/react/useswitchmutationusd.md b/gitbook/reactjrx/queries/react/useswitchmutationusd.md index 6ed78d1..707e6c8 100644 --- a/gitbook/reactjrx/queries/react/useswitchmutationusd.md +++ b/gitbook/reactjrx/queries/react/useswitchmutationusd.md @@ -20,7 +20,19 @@ onError: (error) => { } ``` -A cancelled call is not retried, whatever `retry` says. A call cancelled while TanStack Query waits to retry it settles once that wait ends. +A cancelled call is not retried, whatever `retry` says. A call cancelled while it waits `retryDelay` fails at once. One that TanStack Query holds, such as while the device is offline, fails when TanStack Query resumes it. + +## Retries + +`retry` and `retryDelay` take the same values as in TanStack Query, the client's defaults included. TanStack Query cannot stop its wait between two attempts, so the hook waits `retryDelay` itself, at the end of the failed attempt, and gives TanStack Query a `retryDelay` of 0, which a `MutationCache` sees. TanStack Query then holds the retry while the device is offline or the page hidden, as it does after its own wait. + +Three things differ from TanStack Query: + +- `failureCount` and `failureReason` change when the wait ends, not when the attempt fails. A call cancelled during the wait never records that failure. +- A `retry` function runs twice for each failure: once in the hook, to know whether to wait, and once in TanStack Query. +- A change to `retry` or `retryDelay` applies to the calls already running. TanStack Query keeps the values that a call started with. + +As in TanStack Query, `retryDelay` must not throw. Here, its error replaces the attempt's error, and the retry starts at once. ## Variables diff --git a/src/lib/binding/useSubscribeEffect.ts b/src/lib/binding/useSubscribeEffect.ts index 2f77de7..37104a0 100644 --- a/src/lib/binding/useSubscribeEffect.ts +++ b/src/lib/binding/useSubscribeEffect.ts @@ -1,12 +1,8 @@ import { useCallback } from "react" import { retry, tap, throwError, timer } from "rxjs" import { makeObservable } from "../utils/makeObservable" -import { - exponentialBackoffDelay, - getDelay, -} from "../utils/operators/retryBackoff" import { useLiveRef } from "../utils/react/useLiveRef" -import { shouldRetry } from "../utils/shouldRetry" +import { getRetryDelay, shouldRetry } from "../utils/retry" import type { SubscribeSource } from "./useSubscribe/types" import { useSubscribe } from "./useSubscribe/useSubscribe" @@ -36,9 +32,6 @@ export interface UseSubscribeEffectOptions { retryDelay?: number | ((attempt: number, error: unknown) => number) } -const defaultRetryDelay = (attempt: number) => - getDelay(exponentialBackoffDelay(attempt, 1000), 30_000) - /** * Subscribes to `source` while the component is mounted. Options are read * at each error, so changing them never subscribes again. @@ -62,18 +55,13 @@ export function useSubscribeEffect( resetOnSuccess: true, delay: (error, retryCount) => { const attempt = retryCount - 1 - const { retry: retryOption, retryDelay = defaultRetryDelay } = - optionsRef.current ?? {} + const { retry: retryOption, retryDelay } = optionsRef.current ?? {} if (!shouldRetry(retryOption, attempt, error)) { return throwError(() => error) } - return timer( - typeof retryDelay === "function" - ? retryDelay(attempt, error) - : retryDelay, - ) + return timer(getRetryDelay(retryDelay, attempt, error)) }, }), ) diff --git a/src/lib/queries/useSwitchMutation$.test.tsx b/src/lib/queries/useSwitchMutation$.test.tsx index 75dc1ab..619bd0c 100644 --- a/src/lib/queries/useSwitchMutation$.test.tsx +++ b/src/lib/queries/useSwitchMutation$.test.tsx @@ -1,4 +1,9 @@ -import { QueryClient, QueryClientProvider } from "@tanstack/react-query" +import { + focusManager, + onlineManager, + QueryClient, + QueryClientProvider, +} from "@tanstack/react-query" import { fireEvent } from "@testing-library/dom" import { cleanup, @@ -8,7 +13,17 @@ import { waitFor, } from "@testing-library/react" import { act, useState } from "react" -import { delay, EMPTY, finalize, map, NEVER, of, throwError, timer } from "rxjs" +import { + delay, + EMPTY, + finalize, + map, + NEVER, + type Observable, + of, + throwError, + timer, +} from "rxjs" import { afterEach, beforeEach, @@ -445,35 +460,273 @@ describe("useSwitchMutation$", () => { expect(cancelled?.state.failureCount).toBe(1) }) - it("should settle a call cancelled during a retry wait once the wait ends, without another attempt", async () => { - const client = new QueryClient() - const mutationFn = vi.fn((value: string) => - value === "first" ? throwError(() => new Error("failed")) : of(value), + describe("Given a call that fails", () => { + beforeEach(() => { + vi.useFakeTimers() + }) + + afterEach(() => { + vi.useRealTimers() + onlineManager.setOnline(true) + focusManager.setFocused(undefined) + }) + + it("should fail at once when it is cancelled while it waits retryDelay, without another attempt", async () => { + const client = new QueryClient() + const mutationFn = vi.fn((value: string) => + value === "first" ? throwError(() => new Error("failed")) : of(value), + ) + const { result } = renderHook( + () => + useSwitchMutation$({ + scope: { id: "save" }, + retry: 3, + retryDelay: 10_000, + mutationFn, + }), + { wrapper: createWrapper(client) }, + ) + + act(() => result.current.mutate("first")) + await act(() => vi.advanceTimersByTimeAsync(1)) + act(() => result.current.mutate("second")) + await act(() => vi.advanceTimersByTimeAsync(1)) + + const [cancelled, next] = client.getMutationCache().getAll() + + expect(cancelled?.state.error).toBeInstanceOf(SwitchMutationCancelError) + expect(next?.state.status).toBe("success") + expect(mutationFn.mock.calls.map(([value]) => value)).toEqual([ + "first", + "second", + ]) + }) + + it.each([ + { + change: "the device goes offline", + leave: () => onlineManager.setOnline(false), + comeBack: () => onlineManager.setOnline(true), + }, + { + change: "the page is hidden", + leave: () => focusManager.setFocused(false), + comeBack: () => focusManager.setFocused(true), + }, + ])( + "should hold the retry when $change during the wait, until it comes back", + async ({ leave, comeBack }) => { + const client = new QueryClient() + const mutationFn = vi.fn((_value: number) => + mutationFn.mock.calls.length === 1 + ? throwError(() => new Error("failed")) + : of("saved"), + ) + const { result } = renderHook( + () => + useSwitchMutation$({ retry: 1, retryDelay: 1000, mutationFn }), + { wrapper: createWrapper(client) }, + ) + + act(() => result.current.mutate(1)) + await act(() => vi.advanceTimersByTimeAsync(10)) + act(leave) + await act(() => vi.advanceTimersByTimeAsync(2000)) + + expect(mutationFn).toHaveBeenCalledTimes(1) + expect(result.current.isPaused).toBe(true) + + act(comeBack) + await act(() => vi.advanceTimersByTimeAsync(0)) + + expect(mutationFn).toHaveBeenCalledTimes(2) + expect(result.current.data).toBe("saved") + }, ) - const { result } = renderHook( - () => - useSwitchMutation$({ - scope: { id: "save" }, - retry: 3, - retryDelay: 150, - mutationFn, - }), - { wrapper: createWrapper(client) }, + + it("should fail once it resumes when it is cancelled while TanStack Query holds its retry", async () => { + const client = new QueryClient() + const mutationFn = vi.fn((value: string) => + value === "first" ? throwError(() => new Error("failed")) : of(value), + ) + const { result } = renderHook( + () => useSwitchMutation$({ retry: 1, retryDelay: 100, mutationFn }), + { wrapper: createWrapper(client) }, + ) + + act(() => result.current.mutate("first")) + await act(() => vi.advanceTimersByTimeAsync(10)) + act(() => onlineManager.setOnline(false)) + await act(() => vi.advanceTimersByTimeAsync(200)) + act(() => result.current.mutate("second")) + await act(() => vi.advanceTimersByTimeAsync(200)) + + const [cancelled] = client.getMutationCache().getAll() + + expect(cancelled?.state.status).toBe("pending") + expect(cancelled?.state.isPaused).toBe(true) + + act(() => onlineManager.setOnline(true)) + await act(() => vi.advanceTimersByTimeAsync(0)) + + expect(cancelled?.state.error).toBeInstanceOf(SwitchMutationCancelError) + expect(mutationFn.mock.calls.map(([value]) => value)).toEqual([ + "first", + "second", + ]) + }) + + it.each([ + { + source: "its retryDelay", + options: { retryDelay: 300 }, + defaults: {}, + delay: 300, + }, + { + source: "the client's default retryDelay", + options: {}, + defaults: { retryDelay: 300 }, + delay: 300, + }, + { + source: "TanStack Query's default delay", + options: {}, + defaults: {}, + delay: 1000, + }, + ])( + "should wait $source before it retries", + async ({ options, defaults, delay }) => { + const mutationFn = vi.fn((_value: number) => + throwError(() => new Error("failed")), + ) + const client = new QueryClient({ + defaultOptions: { mutations: { retry: 1, ...defaults } }, + }) + const { result } = renderHook( + () => useSwitchMutation$({ ...options, mutationFn }), + { wrapper: createWrapper(client) }, + ) + + act(() => result.current.mutate(1)) + await act(() => vi.advanceTimersByTimeAsync(delay - 1)) + + expect(mutationFn).toHaveBeenCalledTimes(1) + + await act(() => vi.advanceTimersByTimeAsync(10)) + + expect(mutationFn).toHaveBeenCalledTimes(2) + }, ) - act(() => result.current.mutate("first")) + it("should wait retryDelay when mutationFn throws", async () => { + const mutationFn = vi.fn((_value: number): Observable => { + throw new Error("invalid") + }) + const { result } = renderHook( + () => useSwitchMutation$({ retry: 1, retryDelay: 1000, mutationFn }), + { wrapper: createWrapper(new QueryClient()) }, + ) - const [cancelled] = client.getMutationCache().getAll() + act(() => result.current.mutate(1)) + await act(() => vi.advanceTimersByTimeAsync(999)) - await waitFor(() => expect(cancelled?.state.failureCount).toBe(1)) - await act(() => result.current.mutateAsync("second")) + expect(mutationFn).toHaveBeenCalledTimes(1) - expect(cancelled?.state.error).toBeInstanceOf(SwitchMutationCancelError) - expect(cancelled?.state.failureCount).toBe(2) - expect(mutationFn.mock.calls.map(([value]) => value)).toEqual([ - "first", - "second", - ]) + await act(() => vi.advanceTimersByTimeAsync(10)) + + expect(mutationFn).toHaveBeenCalledTimes(2) + }) + + it("should follow a retry option changed while it waits", async () => { + const mutationFn = vi.fn((_value: number) => + throwError(() => new Error("failed")), + ) + const { result, rerender } = renderHook( + ({ retry }: { retry: boolean }) => + useSwitchMutation$({ retry, retryDelay: 1000, mutationFn }), + { + wrapper: createWrapper(new QueryClient()), + initialProps: { retry: true }, + }, + ) + + act(() => result.current.mutate(1)) + await act(() => vi.advanceTimersByTimeAsync(10)) + rerender({ retry: false }) + await act(() => vi.advanceTimersByTimeAsync(2000)) + + expect(mutationFn).toHaveBeenCalledTimes(1) + expect(result.current.status).toBe("error") + }) + + it("should wait a retryDelay changed while the call runs from its next failure on", async () => { + const mutationFn = vi.fn((_value: number) => + throwError(() => new Error("failed")), + ) + const { result, rerender } = renderHook( + ({ retryDelay }: { retryDelay: number }) => + useSwitchMutation$({ retry: 2, retryDelay, mutationFn }), + { + wrapper: createWrapper(new QueryClient()), + initialProps: { retryDelay: 1000 }, + }, + ) + + act(() => result.current.mutate(1)) + await act(() => vi.advanceTimersByTimeAsync(10)) + rerender({ retryDelay: 100 }) + await act(() => vi.advanceTimersByTimeAsync(1000)) + + expect(mutationFn).toHaveBeenCalledTimes(2) + + await act(() => vi.advanceTimersByTimeAsync(50)) + + expect(mutationFn).toHaveBeenCalledTimes(2) + + await act(() => vi.advanceTimersByTimeAsync(60)) + + expect(mutationFn).toHaveBeenCalledTimes(3) + }) + + it("should fail at once when its source fails with SwitchMutationCancelError", async () => { + const mutationFn = vi.fn((_value: number) => + throwError(() => new SwitchMutationCancelError()), + ) + const { result } = renderHook( + () => + useSwitchMutation$({ retry: 3, retryDelay: 10_000, mutationFn }), + { wrapper: createWrapper(new QueryClient()) }, + ) + + act(() => result.current.mutate(1)) + await act(() => vi.advanceTimersByTimeAsync(1)) + + expect(result.current.status).toBe("error") + expect(mutationFn).toHaveBeenCalledTimes(1) + }) + + it("should give retryDelay the failure count and the error of the failure it retries", async () => { + const errors = [new Error("first"), new Error("second")] + const mutationFn = vi.fn((_value: number) => + throwError(() => errors[mutationFn.mock.calls.length - 1]), + ) + const retryDelay = vi.fn((_failureCount: number, _error: Error) => 100) + const { result } = renderHook( + () => useSwitchMutation$({ retry: 2, retryDelay, mutationFn }), + { wrapper: createWrapper(new QueryClient()) }, + ) + + act(() => result.current.mutate(1)) + await act(() => vi.advanceTimersByTimeAsync(1000)) + + expect(mutationFn).toHaveBeenCalledTimes(3) + expect(retryDelay.mock.calls).toEqual([ + [0, errors[0]], + [1, errors[1]], + ]) + }) }) it("should retry another error as its retry option says", async () => { @@ -489,21 +742,5 @@ describe("useSwitchMutation$", () => { expect(mutationFn).toHaveBeenCalledTimes(2) }) - - it("should retry another error as the default retry says", async () => { - const mutationFn = vi.fn((_value: number) => - throwError(() => new Error("failed")), - ) - const client = new QueryClient({ - defaultOptions: { mutations: { retry: 1, retryDelay: 0 } }, - }) - const { result } = renderHook(() => useSwitchMutation$({ mutationFn }), { - wrapper: createWrapper(client), - }) - - await act(() => result.current.mutateAsync(1).catch(() => undefined)) - - expect(mutationFn).toHaveBeenCalledTimes(2) - }) }) }) diff --git a/src/lib/queries/useSwitchMutation$.ts b/src/lib/queries/useSwitchMutation$.ts index cbc09d7..c7c4b05 100644 --- a/src/lib/queries/useSwitchMutation$.ts +++ b/src/lib/queries/useSwitchMutation$.ts @@ -4,17 +4,24 @@ import { type UseMutationOptions, useQueryClient, } from "@tanstack/react-query" -import { useCallback } from "react" +import { type RefObject, useCallback } from "react" import { + catchError, defaultIfEmpty, + defer, first, fromEvent, ignoreElements, merge, + of, + switchMap, tap, + throwError, + timer, } from "rxjs" import { useRefOnce } from "../utils" -import { shouldRetry } from "../utils/shouldRetry" +import { useLiveRef } from "../utils/react/useLiveRef" +import { getRetryDelay, shouldRetry } from "../utils/retry" import { resolveMutationFnSource } from "./mutationOptions" import { type UseMutation$Options, useMutation$ } from "./useMutation$" @@ -46,39 +53,111 @@ type WithCallerVariables = TResult extends { /** * Keyed as required, so that spreading them after the caller's options - * replaces the caller's callbacks, which take the raw variables. + * replaces the caller's options of the same name. */ type SwitchOverrides = { [K in + | "mutationFn" | "onMutate" | "onSuccess" | "onError" | "onSettled" - | "retry"]: UseMutationOptions< - TData, + | "retry" + | "retryDelay"]: UseMutation$Options< + TData | null, TError, SwitchVariables, TOnMutateResult >[K] } +type RetryOptions = Pick< + UseMutationOptions, + "retry" | "retryDelay" +> + /** - * The options the hook passes over the caller's: the callbacks, adapted to - * the `{ variables, abort }` the hook runs the mutation with, and a `retry` - * that never retries a cancelled call. They replace the client's defaults, - * so they are built from the options merged with those defaults. + * The options the hook passes over the caller's, built from the caller's + * options merged with the client's defaults. + * + * TanStack Query waits between two attempts with a timer that nothing outside + * it can stop. So it gets a `retryDelay` of 0, and a failed attempt waits the + * delay before it hands its error over, where a cancel ends the wait. TanStack + * Query then checks, as after its own wait, that the device is online and the + * page visible before it retries. + * + * The wait and TanStack Query's `retry` must agree on whether a failure is + * retried. TanStack Query keeps the `retry` of the render that started the + * call, while each attempt runs the latest render's `mutationFn`, so both + * read `retryOptions`, the latest render's `retry` and `retryDelay`. */ function createSwitchOverrides( client: QueryClient, - options: Omit< - UseMutation$Options, - "mutationFn" - >, + { + mutationFn, + onMutate, + onSuccess, + onError, + onSettled, + }: UseMutation$Options, + retryOptions: RefObject>, ): SwitchOverrides { - const { onMutate, onSuccess, onError, onSettled, retry } = - client.defaultMutationOptions(options) + const willRetry = (failureCount: number, error: TError) => + !(error instanceof SwitchMutationCancelError) && + shouldRetry(retryOptions.current.retry, failureCount, error) + + /** + * Waits `retryDelay` when TanStack Query will retry the failure, and not at + * all for the last one. The failures recorded on the call's mutation are the + * attempt count TanStack Query will pass to `retry`. A call whose mutation + * left the cache, through `MutationCache.clear()`, counts from 0. + */ + const waitBeforeRetry = ( + call: SwitchVariables, + error: TError, + ) => { + const failureCount = + client + .getMutationCache() + .find({ predicate: (mutation) => mutation.state.variables === call }) + ?.state.failureCount ?? 0 + + const delay = willRetry(failureCount, error) + ? getRetryDelay(retryOptions.current.retryDelay, failureCount, error) + : 0 + + return delay > 0 ? timer(delay) : of(0) + } return { + mutationFn: (call: SwitchVariables) => { + if (call.abort.aborted) { + throw new SwitchMutationCancelError() + } + + /** + * `defaultIfEmpty` must sit on the source itself: the abort stream + * never completes, so the merged stream never completes either and + * a `defaultIfEmpty` placed after it would never fire — an empty + * source would leave the mutation pending forever. + */ + return merge( + defer(() => resolveMutationFnSource(mutationFn, call.variables)).pipe( + defaultIfEmpty(null), + catchError((error: TError) => + waitBeforeRetry(call, error).pipe( + switchMap(() => throwError(() => error)), + ), + ), + ), + fromEvent(call.abort, "abort").pipe( + tap(() => { + throw new SwitchMutationCancelError() + }), + ignoreElements(), + ), + ).pipe(first()) + }, onMutate: onMutate && (({ variables }, ...rest) => onMutate(variables, ...rest)), onSuccess: @@ -91,17 +170,16 @@ function createSwitchOverrides( onSettled && ((data, error, { variables }, ...rest) => onSettled(data, error, variables, ...rest)), - retry: (failureCount, error) => - !(error instanceof SwitchMutationCancelError) && - shouldRetry(retry, failureCount, error), + retry: willRetry, + retryDelay: 0, } } /** * Runs a mutation, and cancels the call still running when a new one starts. - * A cancelled call fails with `SwitchMutationCancelError` and is not retried. - * A call cancelled while TanStack waits to retry it settles once that wait - * ends. + * A cancelled call fails with `SwitchMutationCancelError` and is not retried: + * at once while it runs or waits `retryDelay`, and on resuming when TanStack + * Query holds it, such as while the device is offline. * * The callbacks, the client's defaults included, receive the variables given * to `mutate`, and `result.variables` holds them. A `MutationCache` and @@ -114,16 +192,24 @@ export function useSwitchMutation$< TVariables = void, TOnMutateResult = unknown, >( - { - mutationFn, - ...options - }: UseMutation$Options, + options: UseMutation$Options< + TData | null, + TError, + TVariables, + TOnMutateResult + >, queryClient?: QueryClient, ) { const previousMutationCancelRef = useRefOnce(() => new AbortController()) type TDataOrNull = TData | null const client = useQueryClient(queryClient) + const { mutationFn, ...callerOptions } = options + const defaultedOptions = client.defaultMutationOptions(callerOptions) + const retryOptions = useLiveRef>({ + retry: defaultedOptions.retry, + retryDelay: defaultedOptions.retryDelay, + }) const { mutate, mutateAsync, ...rest } = useMutation$< TDataOrNull, @@ -133,33 +219,11 @@ export function useSwitchMutation$< >( { ...options, - mutationFn: useCallback( - ({ variables, abort }: SwitchVariables) => { - if (abort.aborted) { - throw new SwitchMutationCancelError() - } - - const source = resolveMutationFnSource(mutationFn, variables) - - /** - * `defaultIfEmpty` must sit on the source itself: the abort stream - * never completes, so the merged stream never completes either and - * a `defaultIfEmpty` placed after it would never fire — an empty - * source would leave the mutation pending forever. - */ - return merge( - source.pipe(defaultIfEmpty(null)), - fromEvent(abort, "abort").pipe( - tap(() => { - throw new SwitchMutationCancelError() - }), - ignoreElements(), - ), - ).pipe(first()) - }, - [mutationFn], + ...createSwitchOverrides( + client, + { ...defaultedOptions, mutationFn }, + retryOptions, ), - ...createSwitchOverrides(client, options), }, client, ) diff --git a/src/lib/utils/retry.ts b/src/lib/utils/retry.ts new file mode 100644 index 0000000..163236a --- /dev/null +++ b/src/lib/utils/retry.ts @@ -0,0 +1,47 @@ +import { exponentialBackoffDelay, getDelay } from "./operators/retryBackoff" + +/** + * The retry options, read the way TanStack Query reads a mutation's, in + * checks it does not export. `attempt` counts the retries already made: 0 + * before the first one. + */ + +/** + * Whether to retry: a function decides, a number caps the retries, `true` + * never stops, and no value never retries. + */ +export const shouldRetry = ( + retry: + | boolean + | number + | ((attempt: number, error: TError) => boolean) + | undefined, + attempt: number, + error: TError, +) => { + if (typeof retry === "function") return retry(attempt, error) + + if (typeof retry === "number") return attempt < retry + + return retry === true +} + +/** + * 1 s, doubled at each retry, up to 30 s. + */ +const defaultRetryDelay = (attempt: number) => + getDelay(exponentialBackoffDelay(attempt, 1000), 30_000) + +/** + * The time to wait before a retry, in milliseconds: a number, or a function + * of the attempt and the error, `defaultRetryDelay` when there is none. + */ +export const getRetryDelay = ( + retryDelay: number | ((attempt: number, error: TError) => number) | undefined, + attempt: number, + error: TError, +) => { + const delay = retryDelay ?? defaultRetryDelay + + return typeof delay === "function" ? delay(attempt, error) : delay +} diff --git a/src/lib/utils/shouldRetry.ts b/src/lib/utils/shouldRetry.ts deleted file mode 100644 index 2d71e21..0000000 --- a/src/lib/utils/shouldRetry.ts +++ /dev/null @@ -1,21 +0,0 @@ -/** - * Whether to retry after `attempt` retries (0 before the first one): a - * function decides, a number caps the retries, `true` never stops, and no - * value never retries. TanStack Query reads a mutation's `retry` the same - * way, in a check it does not export. - */ -export const shouldRetry = ( - retry: - | boolean - | number - | ((attempt: number, error: TError) => boolean) - | undefined, - attempt: number, - error: TError, -) => { - if (typeof retry === "function") return retry(attempt, error) - - if (typeof retry === "number") return attempt < retry - - return retry === true -}