🗄️🔥💨
Axios Cache Interceptor
  

  

axios-cache-interceptor is a axios wrapper for caching and preventing unneeded requests

import axios from 'axios';
import { createCache, SessionCacheStorage } from 'axios-cache-interceptor';

// Any custom axios instance
const api = axios.create();

// Other axios instance with caching enabled
const cachedApi = createCache(api, {
  // Store values on window.sessionStorage
  storage: new SessionCacheStorage(),

  // Use the max-age header to determine the cache expiration time
  interpretHeader: true
});

// Make a simple request, with caching support, to the api
const { data } = await cachedApi.get('https://api.example.com/');

Installing

Axios is a peer dependency and must be installed separately.

# Npm
npm install --save axios axios-cache-interceptor

# Yarn
yarn add axios axios-cache-interceptor

Getting Started

To you use this cache interceptor, you can apply to an existing instance or create a new one.

import { applyCache } from 'axios-cache-interceptor';

// Your axios instance
let axios;

// Return the same axios instance, but with a modified Typescript type.
axios = applyCache(axios, {
  /* options here */
});

or by creating a new one:

import { createCache } from 'axios-cache-interceptor';

const axios = createCache({
  /* options here */
});

After that, you can made your own requests normally.

What we support

• Cache concurrent requests
• Typescript support
• Unit tests
• Header interpretation
• Infinity storage options
• Cache revalidation from responses
• External storages, like redis

Basic Knowledge

Request id

A good thing to know is that every request passed through this interceptor, has an id. This does not mean that is a unique id. The id is used in a number of ways, but the most important is to bind a request to its cache.

The id generation is good enough to generate the same id for theoretically sames requests. The example of this is a request with { baseUrl: 'https://a.com/', url: '/b' } results to the same id with { url: 'https://a.com/b/' }.

The id is retrieved with the response object.

const result = await cache.get(/* ... */);

const id = result.id; // <-- The id to find the cache and more;

Also, a custom id can be used to treat two requests as the same.

axios.get('...', {
  id: 'my-custom-id',
  cache: {
    // other properties...
  }
});

The default id generation can clarify this idea.

Global configuration

When applying the interceptor, you can customize some properties:

const axios = createCache({
  // Properties here
});

storage

The storage used to save the cache. Here will probably be the most changed property. Defaults to MemoryStorage.

You can create your own implementation by implementing CacheStorage.

There are few built in storage implementations, you can use them by importing:

import /* ... */ 'axios-cache-interceptor/dist/storage/{name}';

• MemoryStorage import 'axios-cache-interceptor/dist/storage/memory';
• Session and Local Storage import 'axios-cache-interceptor/dist/storage/web';
• Maybe your own? (PR's are welcome)

generateKey

The function used to create different keys for each request. Defaults to a function that priorizes the id, and if not specified, a string is generated using the method, baseUrl, params, and url.

waiting

A simple object that will hold a promise for each pending request. Used to handle concurrent requests.

Can also be used as type of listener to know when a request is finished.

headerInterpreter

The function used to interpret all headers from a request and determine a time to live (ttl) number.

Check out the inline documentation to know how to modify your own.

requestInterceptor and responseInterceptor

The used request and response interceptor. Basically the core function of this library. Check out the used request and response to see the default used.

Per-request configuration

By using this axios client and using an ide with intellisense, you'll see a custom property called cache.

The inline documentation is self explanatory, but here are some examples and information:

ttl

The time that the request will remain in cache. Some custom storage implementations may not respect 100% the time.

When using interpretHeader, this value is ignored.

interpretHeader

If activated, when the response is received, the ttl property will be inferred from the requests headers. See the actual implementation of the interpretHeader method for more information. You can override the default behavior by setting the headerInterpreter when creating the cached axios client.

methods

Specify what request methods should be cached.

Defaults to only GET methods.

cachePredicate

An object or function that will be tested against the response to test if it can be cached. See the inline documentation for more.

An simple example with all values:

axios.get('url', {
  cache: {
    cachePredicate: {
      // Only cache if the response comes with a *good* status code
      statusCheck: [200, 399],

      // Tests against any header present in the response.
      containsHeader: {
        'x-custom-header': true,
        'x-custom-header-2': 'only if matches this string',
        'x-custom-header-3': (value) => /* some calculation */ true
      },

      // Check custom response body
      responseMatch: (response) => {
        // Sample that only caches if the response is authenticated
        return response.auth.status === 'authenticated':
      }
    }
  }
});

update

Once the request is resolved, this specifies what other responses should change their cache. Can be used to update the request or delete other caches. It is a simple Record with the request id.

Example:

// Retrieved together with their responses
let otherResponseId;
let userInfoResponseId;

axios.get('url', {
  cache: {
    update: {
      // Evict the otherRequestId cache when this response arrives
      [otherResponseId]: 'delete',

      // An example that update the "user info response cache" when doing a login.
      // Imagine this request is a login one.
      [userInfoResponseId]: (cachedValue, thisResponse) => {
        return { ...cachedValue, user: thisResponse.user.info };
      }
    }
  }
});

Inspiration

This project is highly inspired by several projects, written entirely in typescript, supporting https headers and much more.

Take a look at some similar projects:

• axios-cache-adapter
• axios-cache-plugin
• @tusbar/cache-control

License

Licensed under the MIT. See LICENSE for more informations.

Contact

See my contact information on my github profile or open a new issue.