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 axios/axios#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 -Sor
yarn add axios-extensionsor
// 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): AxiosAdapterWhere 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 invokedcustom 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 requestcustom 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): AxiosAdapterWhere 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): AxiosAdapterWhere 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 });