@mr-hooks/use-retry
v1.0.1
Published
A hook for auto retrying asynchronous operations with a backoff strategy
Downloads
655
Maintainers
Readme
useRetry
useRetry is a hook that can call a retry function for you in the case that an asyncronous action fails.
Its most common use case is to retry failed data loads in conjunction with data fetching hooks such as swr
, use-fetch
and fetchye
;
useRetry allows you to completely customize your backoff strategy allowing you to be in complete control of how when the retry occurs.
Usage
This hook can be used alongside any other async operation, be it another hook (such as swr or fetchye), or HOC (such as with redux-thunk or redux-saga).
As long as you can pass to useRetry
a running, error, and success status, and a function to retry the operation.
Example with SWR
import useRetry, {makeSimpleBackoffStrategy, ABANDONED, BACKOFF} from "@mr-hooks/use-retry";
import useSWRImmutable from "swr/immutable";
const MyDataComponent = () => {
// use your favourite data hook like normal
const {data, error, isLoading, mutate} = useSWRImmutable('unreliable.api.com')
// Pass the loading, error, and success status to useRetry, along with the retry function
// itself, and optionally a backoff strategy
const {retryCount, status} = useRetry({
isFailing: !!error,
isSucceeded: !!data,
isRunning: isLoading,
retry: mutate,
backoffStrategy: makeSimpleBackoffStrategy(1000, 5)
})
// render the status to your application however you see fit
// you likely dont want to show all statuses to your users
return (
<div>
{isLoading && (
<p>Loading...</p>
)}
{error && (
<p>{error.message}</p>
)}
{status === BACKOFF && (
<p>Waiting before retry number {retryCount}</p>
)}
{status === ABANDONED && (
<p>Call failed</p>
)}
{data && (
<p>We got data</p>
)}
</div>
);
};
export default MyDataComponent;
Example with Fetchye
import useRetry, {makeSimpleBackoffStrategy, ABANDONED, BACKOFF} from "@mr-hooks/use-retry";
import {useFetchye} from 'fetchye';
const MyDataComponent = () => {
// use your favourite data hook like normal
const {data, isLoading, error, run} = useFetchye('unreliable.api.com')
// Pass the loading, error, and success status to useRetry, along with the retry function
// itself, and optionally a backoff strategy
const {retryCount, status} = useRetry({
isFailing: !!error,
isSucceeded: !!data,
isRunning: isLoading,
retry: run,
backoffStrategy: makeSimpleBackoffStrategy(1000, 5)
})
// As previous example
return <></>;
};
export default MyDataComponent;
Example with Thunk
import useRetry, {makeSimpleBackoffStrategy, ABANDONED, BACKOFF} from "@mr-hooks/use-retry";
import { fetchData } from './thunks';
/* Redux state shape:
* { data: {
* 'unreliable-api-com': { data: <...>, isLoading: <...>, error: <...> }
* }}
*/
const MyDataComponent = () => {
// Hook into the redux store, which is shaped intentionally for use with useRetry
const {data, isLoading, error} = useSelector((state) => state.data['unreliable-api-com'])
const dispatch = useDispatch();
const fetchData = () => dispatch(fetchData('unreliable.api.com'));
// Pass the loading, error, and success status to useRetry, along with the retry function
// itself, and optionally a backoff strategy
const {retryCount, status} = useRetry({
isFailing: !!error,
isSucceeded: !!data,
isRunning: isLoading,
retry: fetchData,
backoffStrategy: makeSimpleBackoffStrategy(1000, 5)
})
// kick off the initial call
useEffect(() => {
fetchData()
}, [])
// As previous example
return <></>;
};
export default MyDataComponent;
What is a backoff strategy?
Before we talk about anything else, lets talk about backoff.
Backoff lets you retry less frequently so that retrys don't overload your servers (if you are retrying api calls).
useRetry takes a function 'backoffStrategy' of type BackoffStrategy = (retryCount : number) => number
This function is called with how many retries there have been, starting at 0, and should return a number of millisecond that should be waited before retrying the call.
If this function returns a negative number, the call is considered abandoned, and the call will no-longer be called.
This lets you 'build in' the max number of retries to your backoff strategy.
The backoff strategy should be a stable reference, so if you are making them in functions, they should be wrapped in React.useCallback.
Example
Let's look at the defaut implementation of the backoff strategy, 'makeSimpleBackoffStrategy':
import React from 'react';
import { BackoffStrategy } from './common';
export type MakeSimpleBackoffStrategy = (timeout: number, maxRetries: number) => BackoffStrategy;
export const makeSimpleBackoffStrategy : MakeSimpleBackoffStrategy = (timeout, maxRetries) => (
React.useCallback((retryCount) => (retryCount < maxRetries ? timeout : -1), [])
);
As you can see, this backofStrategy maker creates a React.useCallback that wll return a fixed timeout for the first n retries, then -1, thus abandoning the call.
You don't need to make these 'maker' functions yourself, if you just want a hard coded strategy.
Consider this backoff strategy that returns the number of retries in seconds, until 10 have passed:
import { BackoffStrategy } from '@mr-hooks/use-retry';
export const linearTenTimesBackoffStrategy : BackoffStrategy = (retryCount) =>
(retryCount > 10 ? -1 : retryCount * 1000);
Whats with all these statuses?
Next lets look at the statuses useRetry and understand what the lifecycle of useRetry is
status === IDLE
The first status is IDLE. This is the stating status of useRetry, and will be the status until either isFailing, isSucceeded, or isRunning is true.
status === SUCCEEDED
The SUCCEEDED status will always be returned if the isSucceeded option is true
regardless of the other options passed.
In this state, the retry count will also be reset. This means if you start your async operation again, and it then goes into a failed state, the backoff strategy will start again.
status === RUNNING
RUNNING is the status when isRunning is true
(and isSucceeded is false
).
In this state useRetry will do nothing, its waiting for your async operation to either succeed, or fail!
status === BACKOFF
If isFailing is ever true
while isRunning and isSucceeded are both false
, useRetry will begin the retry process.
First if calls the backoffStrategy
function and gets the backoff duration.
It then increments the retryCount
It then schedules the retry
function to be called after the backoff duration.
While the retry
function is waiting to be run, the status will be BACKOFF.
It means 'nothing is happening right now, but the retry is scheduled'.
You might think there would be a status for 'The retry function has been called' but actually, useRetry expects you to once again be passing isRunning: true
in this case.
useRetry relies on this. You must pass isRunning: true
while your async operation is running, else useRetry wont be-able to detect when the current retry fails (if it fails for a second time).
status === ABANDONED
Finally, if isFailing is ever true
while isRunning and isSucceeded are both false
, but the backoffStrategy
function returns a negative number, the status will be set to ABANDONED.
In this case useRetry will not schedule your retry function, meaning that with no other external action, the call is now considered truly failed.
When status is ABANDONED, useRetry will also reset the retryCount. This ensures if your async operation goes isRunning: true
again (such as if the user presses a button to manually retry) and that call fails, the backoffStrategy will start aagain.
A nice parcel (Suggested usages)
useRetry takes a few complex options, and returns a few complex options.
Consider creating your own custom hook over useRetry to simlify it somewhat:
Set the backoff ahead of time
This option does not reduce the boilerplate much, but would let you have a 'global' backoff strategy
// useLinearRetry.tx
const useLinerRetry = (options) => (
useRetry({
...options,
backoffStrategy: (retryCount) => (retryCount > 10 ? -1 : retryCount * 1000)
})
)
// MyComponent.tsx excerpt
const {data, isLoading, error, run} = useFetchye('exampleUnreliableUrl.com');
// Pass the loading, error, and success status to useRetry, along with the retry function
// itself, and optionally a backoff strategy
const {retryCount, status} = useLinerRetry({
isFailing: !!error,
isSucceeded: !!data,
isRunning: isLoading,
retry: run,
})
Wrap up the hooks together
This option is the recommended usage for large teams where boilerplate reduction is key
// useDataWithRetry.tx
const useDataWithRetry = (...params) => {
const data = useFetchye(...params);
const retry = useRetry({
isFailing: !!data.error,
isSucceeded: !!data.data,
isRunning: data.isLoading,
retry: data.run,
backoffStrategy: (retryCount) => (retryCount > 10 ? -1 : retryCount * 1000)
})
return {data, retry}
}
// MyComponent.tsx excerpt
const {data: {data, error}, retry: {status}} = useDataWithRetry('exampleUnreliableUrl.com');
API
export type BackoffStrategy = (retryCount: number) => number;
export type Status = typeof IDLE
| typeof BACKOFF
| typeof ABANDONED
| typeof SUCCEEDED
| typeof RUNNING;
export type UseRetry = (options: {
isFailing: boolean,
isSucceeded: boolean,
isRunning: boolean,
retry: () => any,
backoffStrategy?: BackoffStrategy
}) => { retryCount: number, status: Status };
param: isFailing {boolean}
If this input is true
while isRunning and isSucceeded are false
, useRetry will begin the retry process
param: isSucceeded {boolean}
If this input is ever true
useRetry will consider the call to have been a success.
useRetry will reset the retryCount, then do nothing
param: isRunning {boolean}
If this input is true
while isSucceeded is false
, useRetry will consider the async operation to be running, and do nothing
param: retry {() => any}
This is the function that will be called after the backoff duration when isFailing is true
param: backoffStrategy {(retryCount: number) => number | undefined}
This function is called when useRetry wants to schedule the retry function.
It is passed the retry count, and should return either
- A positive integer representing the number of milliseconds to wait before calling the retry function
- Any negative integer, to indicate to useRetry that the current async operation should be abandoned.
The default value for the backoff strategy is constructed as:
backoffStrategy = makeSimpleBackoffStrategy(({ timeout: 1000, maxRetries: 5 }))
There are two other built in backoff strategies (see below)
return: { retryCount: number, status: Status }
Returns the current retry count and the status
Note: the current retryCount is incremented just before the retry function is schedule so it will be +1 during the BACKOFF
status
Backoff Strategies
The hook comes with three backoff strategies to help you build meaningful retries out the box
makeSimpleBackoffStrategy {( options: { timeout: number, maxRetries: number } ) => BackoffStrategy}
Creates a fixed backoff strategy that waits the same number of milliseconds for a fixed number of retries
After maxRetries
it will always return -1
makeFibonacciBackoffStrategy {( options: { timeoutMultiplier?: number = 1000, maxRetries: number } ) => BackoffStrategy}
Creates a fiboacci backoff strategy that waits an increasing number of ms in accordance with a slightly modifieg fibonacci sequence.
After maxRetries
it will always return -1
Each number is multiplied by the timeoutMultiplier
which defaults to 1000
thus producing a sequence of seconds.
This implementation starts at 1, and returns 2 next (skipping the first 0 and 1 in the fibonacci sequence)
This implementation only goes up to 4181
, from then on it repeats that number
This implementation uses a precalculated list of fibonacci numbers for cpu efficiency at the cost of memory
MakeExponentialBackoffStrategy {( options: { timeoutMultiplier?: number = 100, base?: number = 2, offset?: number = 2, maxRetries: number } ) => BackoffStrategy}
Creates an exponential backoff strategy that waits an increasing number of ms in accordance with the exponential function ((base ** (retryCount + offset)) * timeoutMultiplier).
After maxRetries
it will always return -1.
By default, it will produce a power of two sequence in 100's of ms starting with 400ms.
Even with very small bases, this function grows very fast, so take care when you are using it that you dont run into int_max.