axios-cache-interceptor

What is axios-cache-interceptor?

The axios-cache-interceptor package is a middleware for Axios that provides caching capabilities. It allows you to cache HTTP requests and responses, reducing the number of network requests and improving performance.

What are axios-cache-interceptor's main functionalities?

Basic Caching

This feature allows you to set up basic caching for your Axios requests. The example demonstrates how to create a cache with a maximum age of 15 minutes and use it with an Axios instance.

const axios = require('axios');
const { setupCache } = require('axios-cache-interceptor');

const cache = setupCache({
  maxAge: 15 * 60 * 1000 // 15 minutes
});

const api = axios.create({
  adapter: cache.adapter
});

api.get('https://api.example.com/data')
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

Custom Cache Key

This feature allows you to define a custom cache key. The example shows how to create a cache key based on the request URL, method, and parameters.

const axios = require('axios');
const { setupCache } = require('axios-cache-interceptor');

const cache = setupCache({
  key: req => req.url + req.method + JSON.stringify(req.params)
});

const api = axios.create({
  adapter: cache.adapter
});

api.get('https://api.example.com/data', { params: { id: 1 } })
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

Cache Invalidation

This feature allows you to manually invalidate the cache for specific requests. The example demonstrates how to invalidate the cache for a specific URL.

const axios = require('axios');
const { setupCache } = require('axios-cache-interceptor');

const cache = setupCache();

const api = axios.create({
  adapter: cache.adapter
});

api.get('https://api.example.com/data')
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

// Invalidate the cache for a specific request
cache.invalidate({ url: 'https://api.example.com/data' });

Other packages similar to axios-cache-interceptor

axios-cache-adapter

axios-cache-adapter is another caching library for Axios. It provides similar functionality to axios-cache-interceptor, allowing you to cache HTTP requests and responses. However, axios-cache-adapter offers more configuration options for cache storage, such as using localStorage or a custom store.

axios-extensions

axios-extensions is a package that extends Axios with additional features, including caching. It provides a simple way to add caching to your Axios requests and supports various cache strategies. Compared to axios-cache-interceptor, axios-extensions offers more flexibility in defining cache strategies and expiration times.

README

  

  
🗄️📦💿
Axios Cache Interceptor
  

  

This library is in beta and can have breaking changes until v1.
Not ready for production usage!

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.

Basic Knowledge

Request id

A good thing to know is that every request passed through this interceptor. 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 the same request. 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.

Existing implementations:

• MemoryStorage
• Session and Local Storage
• 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.

Changelog

v0.2.2 - 2021-09-20

Commits

• ci: codeql action a71c16d
• docs: initial docs 2d3cbda
• docs: removed readme example dedicated file 1178fd4
• tag: v0.2.2 7e1134e