retriable request

strategy type

use hook

Before using extension hooks, make sure you are familiar with the basic usage of alova.

A use hook that can automatically retry a request failure, you can use it for important requests.

Features

• Customize the number of retries or judge whether retry is required according to the conditions;
• Retry delay mechanism;
• Manually stop retrying;

Usage

Basic usage

import { useRetriableRequest } from 'alova/client';

const {
  // Loading status, always true during retry, until retry succeeds or fails
  loading,

  // response data
  data,

  // Request error information, every time a request or retry fails, there will be an error instance
  // The last error instance will be overwritten
  error,

  // Every time a request or retry fails, the onError event will be triggered
  onError,

  // Request retry event, triggered immediately after each retry request is issued
  onRetry,

  // request retry failure event
  // The request is not successful after reaching the maximum number of retries, or manually stopping retries will trigger
  onFail,

  // request or retry success event
  onSuccess,

  // Every request or retry, regardless of success or failure, will trigger the completion event
  onComplete
} = useRetriableRequest(request);

The maximum number of request retries for useRetriableRequest defaults to 3, and each retry will be delayed by 1 second. It will also make a request by default, you can change the behavior by setting immediate to false.

Set the static maximum number of retries

The maximum number of retries indicates the maximum number of times to retry the request after the first request fails. During this period, if the request succeeds, it will stop continuing to retry. The default maximum number of retries is 3, and you can customize the settings in the following ways.

When the request reaches the maximum number of retries and still fails, the onFail event will be triggered and the request retry will stop. If you want to continue to retry after the failure, you can call the send function, and it will perform a new round request and retry.

const { send } = useRetriableRequest(request, {
  //...
  // Set the maximum number of retries to 5
  retry: 5
});

Dynamically set the maximum number of retries

Maybe sometimes you want to use a certain condition to determine whether to continue to retry. At this time, you can set retry as a function that returns a boolean value to dynamically determine whether to continue to retry.

useRetriableRequest(request, {
  //...
  // The first parameter is the last error instance, and the parameters passed in from the second parameter to send
  retry(error, ...args) {
    // If the request times out, continue to retry
    return /network timeout/i.test(error.message);
  }
});

Set delay time

The default retry delay time is 1 second, you can customize the setting in the following ways.

useRetriableRequest(request, {
  //...
  backoff: {
    // Set the delay time to 2 seconds
    delay: 2000
  }
});

Set an unfixed retry delay time

Sometimes you want that the delay time of each request is not fixed, you can set the delay growth multiple in the following way, and the delay time will increase exponentially according to the number of retries.

useRetriableRequest(request, {
  //...
  backoff: {
    delay: 2000,
    // When the multiplier is set to 2, the first retry delay is 2 seconds, the second is 4 seconds, the third is 8 seconds, and so on.
    multiplier: 2
  }
});

not enough? You can even add a random jitter value to each delay to make it look less regular.

useRetriableRequest(request, {
   //...
   backoff: {
     delay: 2000,
     multiplier: 2,
     /**
      * The initial jitter percentage value of the delay request, the range is 0-1
      * When only startQuiver is set, endQuiver defaults to 1
      * For example set to 0.5, it will add 50% to 100% random time on the current delay time
      * If endQuiver has a value, the delay time will be increased by a random value in the range of startQuiver and endQuiver
      */
     startQuiver: 0.5,

     /**
      * The jitter end percentage value of the delayed request, the range is 0-1
      * When only endQuiver is set, startQuiver defaults to 0
      * For example set to 0.8, it will add a random time from 0% to 80% on the current delay time
      * If startQuiver has a value, the delay time will increase the random value in the range of startQuiver and endQuiver
      */
     endQuiver: 0.8;
   }
});

Manually stop retrying

In some cases, you need to manually stop the retry, whether you are currently requesting or waiting for the next retry, you can use stop to stop it.

const { stop } = useRetriableRequest(request, {
  //...
});

const handleStop = () => {
  stop();
};

API

Hook configuration

Inherit all configurations from useRequest.

| Name | Description | Type | Default | Version | | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------------------- | ------- | --- | | retry | The maximum number of retries can also be set as a function returning a boolean value to dynamically determine whether to continue to retry. | number | (error: Error, ...args: any[]) => boolean | 3 | - | | backoff | Backoff policy, set retry delay time, etc. | BackoffPolicy | - | - |

BackoffPolicy

Name	Description	Type	Default	Version
delay	Delay time for another request, in milliseconds	number	1000	-
multiplier	Specify the delay multiplier, for example, when multiplier is set to 2 and delay is 1 second, the first retry is 1 second, the second is 2 seconds, the third is 4 seconds, and so on	number	1	-
startQuiver	The initial jitter percentage value of the delay request, ranging from 0-1. When only startQuiver is set, endQuiver defaults to 1. For example, if it is set to 0.5, it will increase the current delay time by 50% to 100% randomly Time, if endQuiver has a value, the delay time will be increased by a random value in the range of startQuiver and endQuiver	number	0	-
endQuiver	The jitter end percentage value of the delayed request, the range is 0-1, when onlyWhen endQuiver is set, startQuiver defaults to 0. For example, if it is set to 0.5, it will add a random time from 0% to 50% to the current delay time. If startQuiver has a value, the delay time will increase the random value in the range of startQuiver and endQuiver	number	0	-

Responsive data

Inherit all responsive data from useRequest.

Action function

Inherit all action functions of useRequest.

name	description	function parameters	return value	version
stop	Stop retrying, it is only valid during retrying, and the onFail event will be triggered immediately after stopping	-	-	-

Event

Inherit all events from useRequest.

Name	Description	Callback Parameters	Version
onRetry	Retry event bindings, they will fire after a retry is initiated	Retry event instance RetriableRetryEvent	-
onFail	Triggered when the request fails. It will be triggered when no more retries are made. For example, when the maximum number of retries is reached, when the retry callback returns false, manually call stop to stop retrying Note: 1 The .onError event will be triggered every time an error is reported. 2. If there are no retries, onError, onComplete and onFail will be triggered at the same time	Retry event instance RetriableFailEvent	-

RetriableRetryEvent

Event event instance inherited from alova.

Name	Description	Type	Default	Version
retryTimes	current retry times	number	required	-
retryDelay	The delay time of this retry, in ms	number	required	-

RetriableFailEvent

Event event instance inherited from alova.

Name	Description	Type	Default	Version
retryTimes	current retry times	number	required	-