Wondering what’s next for npm?Check out our public roadmap! »

    axios-extensions
    TypeScript icon, indicating that this package has built-in type declarations

    3.1.3 • Public • Published

    axios-extensions

    npm version coverage npm downloads Build Status

    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.

    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(adapterAxiosAdapter, optionsOptions)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 requests most once per threshold milliseconds

    throttleAdapterEnhancer(adapterAxiosAdapter, optionsOptions)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.

    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(adapterAxiosAdapter, optionsOptions)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 });

    Install

    npm i axios-extensions

    DownloadsWeekly Downloads

    44,019

    Version

    3.1.3

    License

    MIT

    Unpacked Size

    337 kB

    Total Files

    73

    Last publish

    Collaborators

    • avatar