index.md - v1.2.0

axios-series

A tool to extend axios to return sequentially

When multiple requests are made to the same interface in a short period of time, axios-series can be useful if you need to ensure that the request executed first returns the results first

Documentation • Change Log

Read this in other languages: English | 简体中文

axiosSeries

Experience online

Experience the axios-series features online Edit in CodeSandbox

Installing

# use pnpm
$ pnpm install axios-series

# use npm
$ npm install axios-series --save

Usage

Add serializer feature to axios

import axios from 'axios'
import wrapper from 'axios-series'

const axiosSeries = wrapper(axios, {
  // unique: false,
  // orderly: true
})

export default axiosSeries

or axios instance

import axios from 'axios'
import wrapper from 'axios-series'

const instance = axios.create({
  withCredentials: true
})
const axiosSeries = wrapper(instance, {
  // unique: false,
  // orderly: true
})

export default axiosSeries

Behavior

serializer options

Parameters	Description	Type	Optional	Required	Default
unique	make request unique, clear all similar requests	`boolean`	true/false	false	false
orderly	resolve results orderly	`boolean`	true/false	false	true
onCancel	callback function for cancel requests	`(err: any, config: InternalAxiosRequestConfig): void`	-	false	null

When multiple requests are made to the same interface (url is the same but data can be different) at the same time (or at short intervals), the user may only need the result of the last request, and when unique is set to true, the previous request will be cancelled.

Here's the magic: when multiple requests are made to the same interface at the same time, axiosSerios does not wait rigidly for the previous interface to return before starting the request. All requests are made at the same time, so axiosSerios has no loss in performance

Since: 1.0.0
Show:

//                                                              |
//                                                              |
axiosSeries({ url: '/api/1' }); axiosSeries({ url: '/api/1' }); | axiosSeries({ url: '/api/1' });
//            \___________/                   \___________/     |               \___________/
//                  |                               |           |                     |
//              request 1                       request 2       | When request 3 start, 1 & 2 will be cancelled
//                                                              |

Example:

Make 2 requests to /test/api/1 (data can be different) at the same time (or at very short intervals). set unique to true

// request 1
axiosSeries({
  url: '/test/api/1',
  data: { id: 1 }
})
// request 2
axiosSeries({
  url: '/test/api/1',
  data: { id: 2 }
})

// request 1 will be cancelled

orderly

When multiple requests are launched to the same interface (url is the same but data can be different) at the same time (or a short interval), the first request executed cannot be guaranteed to return the result first due to network reasons, and this orderly parameter is used to solve this problem. When orderly is set to true, the first request will definitely return the result before the second request.

Since: 1.0.0
Show:

//             ->               |                ->               |                ->
//                              |                                 |
axiosSeries({ url: '/api/1' }); | axiosSeries({ url: '/api/1' }); | axiosSeries({ url: '/api/1' });
//            \___________/     |               \___________/     |               \___________/
//                  |           |                     |           |                     |
//              request 1       |      request 2 will wait for    |        request 3 will wait for
//                              |     request 1 before returning  |      request 1 & 2 before returning
//                              |                                 |

Example:

Make 2 requests to xxx (data can be different) at the same time (or at very short intervals). set orderly to true

// request 1
axiosSeries({
  url: '/test/api/1',
  data: { id: 1 }
})
// request 2
axiosSeries({
  url: '/test/api/1',
  data: { id: 2 }
})

// request 1 will definitely return the result before the request 2

API Reference

axiosSeries

axios serializer wrapper function

Since: 1.0.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
instance	axios or axios instance	`AxiosInstance`	axios/axiosInstance	true	-
options	serializer options	`SerializerOptions`	-	false	-

Returns: new axios instance with serializer
Example:

const http = axiosSeries(instance, {
  // unique: false,
  // orderly: true
})

Types:

function axiosWithSeries<T = any, R = AxiosResponse<T>, D = any>(
  config: SerializerRequestOptions<D>
): Promise<R>
function axiosWithSeries<T = any, R = AxiosResponse<T>, D = any>(
  url: string,
  config?: SerializerRequestOptions<D>
): Promise<R>

axiosSeries.clear

clear all series

Since: 1.0.0
Arguments: none
Returns: 'none'
Example:

const http = axiosSeries(instance, {})

http.clear()

Types:

type clear = () => void

axiosSeries.series

all waiting series

Since: 1.0.0
Arguments: none
Returns: 'WaitingList'
Example:

const http = axiosSeries(instance, {})

console.log(http.series) // []

Types:

declare interface Series {
  promiseKey: symbol
  promise: Promise<any>
  source: CancelTokenSource
  abortController?: AbortController
}

declare type WaitingList = Record<string, Series[]>

Using unpkg CDN

<script src="https://unpkg.com/browse/axios@1.4.0/dist/axios.min.js"></script>
<script src="https://unpkg.com/axios-series@1.0.0/dist/index.global.prod.js"></script>
<script>
  const http = axiosSeries(axios)
</script>

Support & Issues

Please open an issue here.

License

MIT