axios-extensions

A non-invasive, simple, reliable collection of axios extension

Extension List

v3.x has a lot of api changes, if you are looking for v2.x doc, see here

Not working with axios v0.19.0 as its custom config bug, See https://github.com/axios/axios/pull/2207.

• cacheAdapterEnhancer makes request cacheable
• throttleAdapterEnhancer makes GET requests throttled automatically
• retryAdapterEnhancer makes request retry with special times while it failed

Installing

npm i axios-extensions -S

or

yarn add axios-extensions

or

// exposed as window['axios-extensions']
<script src="https://unpkg.com/axios-extensions/dist/axios-extensions.min.js"></script>

Usage

import axios from 'axios';
import { cacheAdapterEnhancer, throttleAdapterEnhancer } from 'axios-extensions';

// enhance the original axios adapter with throttle and cache enhancer 
const http = axios.create({
	baseURL: '/',
	headers: { 'Cache-Control': 'no-cache' },
	adapter: throttleAdapterEnhancer(cacheAdapterEnhancer(axios.defaults.adapter))
});

Enable Logging

It is highly recommended to enable the request logging recorder in development environment(disabled by default).

browser (webpack)

new webpack.DefinePlugin({
  'process.env.LOGGER_LEVEL': JSON.stringify('info')
})

node

// package.json
"scripts": {
	"start": "cross-env LOGGER_LEVEL=info node server.js"
}

API

cacheAdapterEnhancer

Makes axios cacheable

cacheAdapterEnhancer(adapter: AxiosAdapter, options: Options): AxiosAdapter

Where adapter is an axios adapter which following the axios adapter standard, options is an optional that configuring caching:

| Param | Type | Default value | Description | | ---------------- | ---------------------------------------- | ------------------------------------------------------------ | ---- | | enabledByDefault | boolean | true | Enables cache for all requests without explicit definition in request config (e.g. cache: true) | | cacheFlag | string | 'cache' | Configures key (flag) for explicit definition of cache usage in axios request | | defaultCache | CacheLike | new LRUCache({ maxAge: FIVE_MINUTES, max: 100 }) | a CacheLike instance that will be used for storing requests by default, except you define a custom Cache with your request config |

cacheAdapterEnhancer enhances the given adapter and returns a new cacheable adapter back, so you can compose it with any other enhancers, e.g. throttleAdapterEnhancer.

basic usage

import axios from 'axios';
import { cacheAdapterEnhancer } from 'axios-extensions';

const http = axios.create({
	baseURL: '/',
	headers: { 'Cache-Control': 'no-cache' },
	// cache will be enabled by default
	adapter: cacheAdapterEnhancer(axios.defaults.adapter)
});

http.get('/users'); // make real http request
http.get('/users'); // use the response from the cache of previous request, without real http request made
http.get('/users', { cache: false }); // disable cache manually and the the real http request invoked

custom cache flag

const http = axios.create({
	baseURL: '/',
	headers: { 'Cache-Control': 'no-cache' },
	// disable the default cache and set the cache flag
	adapter: cacheAdapterEnhancer(axios.defaults.adapter, { enabledByDefault: false, cacheFlag: 'useCache'})
});

http.get('/users'); // default cache was disabled and then the real http request invoked 
http.get('/users', { useCache: true }); // make the request cacheable(real http request made due to first request invoke)
http.get('/users', { useCache: true }); // use the response cache from previous request

custom cache typing

Note that if you are using custom cache flag and typescript, you may need to add the typing declaration like below:

import { ICacheLike } from 'axios-extensions';
declare module 'axios' {
  interface AxiosRequestConfig {
    // if your cacheFlag was setting to 'useCache'
    useCache?: boolean | ICacheLike<any>;
  }
}

more advanced

Besides configuring the request through the cacheAdapterEnhancer, we can enjoy more advanced features via configuring every individual request.

import axios from 'axios';
import { cacheAdapterEnhancer, Cache } from 'axios-extensions';

const http = axios.create({
	baseURL: '/',
	headers: { 'Cache-Control': 'no-cache' },
	// disable the default cache
	adapter: cacheAdapterEnhancer(axios.defaults.adapter, { enabledByDefault: false })
});

http.get('/users', { cache: true }); // make the request cacheable(real http request made due to first request invoke)

// define a cache manually
const cacheA = new Cache();
// or a cache-like instance
const cacheB = { get() {/*...*/}, set() {/*...*/}, del() {/*...*/} };

// two actual request will be made due to the different cache 
http.get('/users', { cache: cacheA });
http.get('/users', { cache: cacheB });

// a actual request made and cached due to force update configured
http.get('/users', { cache: cacheA, forceUpdate: true });

Note: If you are using typescript, do not forget to enable "esModuleInterop": true and "allowSyntheticDefaultImports": true for better development experience.

throttleAdapterEnhancer

Throttle GET requests most once per threshold milliseconds

throttleAdapterEnhancer(adapter: AxiosAdapter, options: Options): AxiosAdapter

Where adapter is an axios adapter which following the axios adapter standard, options is an optional object that configuring throttling:

| Param | Type |Default value | Description | | --------- | ---- |--------------------------- | ------------------------------------------------------------ | | threshold | number |1000 | The number of milliseconds to throttle request invocations to | | cache | CacheLike |new LRUCache({ max: 10 }) | CacheLike instance that will be used for storing throttled requests |

Basically we recommend using the throttleAdapterEnhancer with cacheAdapterEnhancer together for the maximum caching benefits. Note that POST and other methods besides GET are not affected.

throttleAdapterEnhancer(cacheAdapterEnhancer(axios.defaults.adapter))

Check David Corbacho's article to learn more details about throttle and how it differs from debounce.

basic usage

import axios from 'axios';
import { throttleAdapterEnhancer } from 'axios-extensions';

const http = axios.create({
	baseURL: '/',
	headers: { 'Cache-Control': 'no-cache' },
	adapter: throttleAdapterEnhancer(axios.defaults.adapter, { threshold: 2 * 1000 })
});

http.get('/users'); // make real http request
http.get('/users'); // responsed from the cache
http.get('/users'); // responsed from the cache

setTimeout(() => {
	http.get('/users'); // after 2s, the real request makes again
}, 2 * 1000);

retryAdapterEnhancer

Retry the failed request with special times

retryAdapterEnhancer(adapter: AxiosAdapter, options: Options): AxiosAdapter

Where adapter is an axios adapter which following the axios adapter standard, options is an optional that configuring caching: | Param | Type | Default value | Description | | ---------------- | ---------------------------------------- | ------------------------------------------------------------ | ---- | | times | number | 2 | Set the retry times for failed request globally. |

basic usage

import axios from 'axios';
import { retryAdapterEnhancer } from 'axios-extensions';

const http = axios.create({
	baseURL: '/',
	headers: { 'Cache-Control': 'no-cache' },
	adapter: retryAdapterEnhancer(axios.defaults.adapter)
});

// this request will retry two times if it failed
http.get('/users');

// you could also set the retry times for a special request
http.get('/special', { retryTimes: 3 });