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
  • Installation
  • Usage
    • Add serializer feature to axios
    • or axios instance
  • Behavior
    • Option.unique
    • Option.orderly
  • API Reference
    • axiosSeries
    • axiosSeries.clear
    • axiosSeries.series
  • Using unpkg CDN
  • Support & Issues
  • License

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 |

unique

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/[email protected]/dist/axios.min.js"></script>
<script src="https://unpkg.com/[email protected]/dist/index.global.prod.js"></script>
<script>
  const http = axiosSeries(axios)
</script>

Support & Issues

Please open an issue here.

License

MIT