import axios from 'axios';
import { useCache, SessionCacheStorage } from 'axios-cache-interceptor';
// An axios instance with modified types
const api = useCache(axios.create(), {
/* options */
});
// Make a simple request, with caching support, to the api
const resp1 = await api.get('https://api.example.com/');
// resp1.cached = false
const resp2 = await api.get('https://api.example.com/');
// resp2.cached = true- Table of contents
- Installing
- Support list
- Getting Started
- What we support
- Basic Knowledge
- Global configuration
- Per-request configuration
- License
- Contact
Axios is a peer dependency and must be installed separately.
# Npm
npm install --save axios axios-cache-interceptor
# Yarn
yarn add axios axios-cache-interceptorBelow you can check what version of this package is supported by your version of axios. But that does not mean that won't work with any version. Most of "breaking changes" made by axios was it's types.
NOTE: Below v0.3, axios was not configured as a peer dependency
| Version | Axios |
|---|---|
~v0.5 |
>= v0.24 |
~v0.4 |
>= v0.23 |
~v0.3 |
>= v0.22 |
<= v0.2 |
v0.21 |
To you use this cache interceptor, you can apply to an existing instance or create a new one.
import { useCache } from 'axios-cache-interceptor';
// Your axios instance
let axios;
// Return the same axios instance, but with a modified Typescript type.
axios = useCache(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.
- Concurrent requests
- Typescript support
- Unit tests
- Header interpretation
- Infinity storage options
- Cache revalidation from responses
- External storages, like redis
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/' }.
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.
Every response that came from our custom axios instance, will have some extras properties, that you can retrieve like that:
const result = await cache.get(/* ... */);
const id = result['propertyName'];A simple boolean to check whether this request was cached or not.
NOTE: The first response of a request capable of being cached will return
cached: false, as only your next requests will return cached: true.
The request id resolved. This property represents the ID used throughout the internal code. Remember that, depending on the config.keyGenerator, it can be different as the provided on the request.id.
When applying the interceptor, you can customize some properties:
const axios = createCache({
// Properties here
});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)
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.
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.
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.
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.
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:
You can override the request id used by this property.
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.
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.
Specify what request methods should be cached.
Defaults to only GET methods.
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':
}
}
}
});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 };
}
}
}
});Licensed under the MIT. See LICENSE for more informations.
See my contact information on my github profile or open a new issue.