archive-gh-me/axios-cache-interceptor
1
0
Fork 0
mirror of https://github.com/arthurfiorette/axios-cache-interceptor.git synced 2025-12-08 17:36:16 +00:00
Code Issues Projects Releases Wiki Activity

feat: improved docs again

Browse Source
This commit is contained in:
arthurfiorette 2023-02-04 01:21:38 -03:00
parent e3b92b9039
commit 913b1e166a
No known key found for this signature in database
GPG Key ID: 9D190CD53C53C555
14 changed files with 1448 additions and 142 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
docs/.vitepress/config.ts
View File

@ -227,11 +227,11 @@ export default defineConfig({
nav: [
{ text: 'Guide', link: `/guide` },
{ text: 'Config', link: `/config` },
{ text: 'Others', link: `/others/license` },
{
text: VERSION,
items: [
{ text: 'Latest', link: 'https://axios-cache-interceptor.js.org/' },
{ text: 'v1.x', link: 'https://axios-cache-interceptor.js.org/v1/' },
{ text: 'v0.x', link: 'https://axios-cache-interceptor.js.org/v0/' }
].filter((i) =>
BASE_URL === '/' ? i.text !== 'Latest' : !i.link.includes(BASE_URL)
@ -283,6 +283,13 @@ export default defineConfig({
{ text: 'Request Specifics', link: '/config/request-specifics' },
{ text: 'Response Object', link: '/config/response-object' }
]
},
{
text: 'Others',
items: [
{ text: 'MIT License', link: '/others/license' },
{ text: 'Changelog', link: '/others/changelog' },
]
}
]
},

9
docs/.vitepress/theme/custom.css
View File

@ -1,8 +1,13 @@
:root {
--vp-c-brand: rgb(229, 151, 42);
--vp-c-brand: hsl(35, 78%, 53%);
--vp-c-brand-light: hsla(35, 78%, 53%, 36.5%);
--vp-c-brand-lighter: hsla(35, 78%, 53%, 36.5%);
--vp-c-brand-dark: hsl(35, 78%, 53%);
--vp-c-brand-darker: hsl(35, 78%, 53%);
--vp-c-brand-dimm: hsl(35, 0%, 21%);
--vp-c-brand-dimm: #363636;
--vp-home-hero-name-color: transparent;
--vp-home-hero-name-background: -webkit-linear-gradient(120deg, hsl(35, 78%, 53%), hsl(55, 78%, 53%));
--vp-home-hero-image-background-image: -webkit-linear-gradient(50deg, hsl(35, 78%, 53%), hsl(55, 78%, 53%));
--vp-home-hero-image-filter: blur(60px);
}

10
docs/src/guide/comparison.md
View File

@ -39,9 +39,9 @@
## Benchmark
There's an simple
[benchmark](https://github.com/arthurfiorette/axios-cache-interceptor/blob/main/docs/benchmark.js)
in form of a stress test to compare the performance of this library, `axios-cache-adapter`
and axios as it is.
The
[benchmark](https://github.com/arthurfiorette/axios-cache-interceptor/blob/main/benchmark/index.js)
is composed of axios throughput tests to compare the performance of this library,
`axios-cache-adapter` and axios as it is.
<<< @/generated/benchmark.md {5,11,17}
<<< @/generated/benchmark.md {5,11}

15
docs/src/guide/debugging.md
View File

@ -11,6 +11,7 @@ You can use it by changing the `setupCache` import:
```ts [EcmaScript]
import Axios from 'axios';
// Only import from `/dev` where you import `setupCache`.
import { setupCache } from 'axios-cache-interceptor'; // [!code --]
import { setupCache } from 'axios-cache-interceptor/dev'; // [!code ++]
@ -23,6 +24,7 @@ const axios = setupCache(Axios, {
```ts [Common JS]
const Axios = require('axios');
// Only import from `/dev` where you import `setupCache`.
const { setupCache } = require('axios-cache-interceptor'); // [!code --]
const { setupCache } = require('axios-cache-interceptor/dev'); // [!code ++]
@ -47,6 +49,7 @@ const axios = setupCache(Axios, {
```ts {5,11} [Skypack]
import Axios from 'https://cdn.skypack.dev/axios';
// Only import from `/dev` where you import `setupCache`.
import { setupCache } from 'https://cdn.skypack.dev/axios-cache-interceptor'; // [!code --]
import { setupCache } from 'https://cdn.skypack.dev/axios-cache-interceptor/dev'; // [!code ++]
@ -58,15 +61,12 @@ const axios = setupCache(Axios, {
:::
::: tip
You only need to import from `/dev` where you import the `setupCache` function.
:::
And much more, depending on your context, situation and configuration. **Any misbehavior
that you find will have a log to explain it.**
::: details Sample of logs sent to console.
```json
```json
[
{
"id": "-644704205",
@ -130,6 +130,3 @@ You only need to import from `/dev` where you import the `setupCache` function.
```
:::
And much more, depending on your context, situation and configuration. **I'm sure any
misbehavior that you find will have a log to explain it.**

17
docs/src/guide/getting-started.md
View File

@ -1,17 +1,10 @@
# Getting Started
## Prerequisites
[Looking for axios v0?](https://axios-cache-interceptor.js.org/v0/)
- [Node.js](https://nodejs.org/) `(>= 12)` _Lower version requires a custom build with
polyfills._
## Install Axios Cache Interceptor
- [Axios](https://axios-http.com/) `(>= 0.21 or >= 1.1)` _Lower version requires a custom
build with polyfills._
## Quick Start
The fastest way to get axios with cache set up and running is to install it with npm or
yarn
Add Axios Cache Interceptor and Axios to your project using your favorite package manager:
::: code-group
@ -46,6 +39,8 @@ import { setupCache } from 'https://cdn.skypack.dev/axios-cache-interceptor';
:::
## Setup Axios Cache Interceptor
After installing, you can import the package and apply the interceptor to your axios
instance, as shown below:
@ -122,7 +117,7 @@ cache behavior by passing a configuration object to the `setupCache` function. A
also customize some behaviors each request by using the `cache` option in the request
config.
### Support Table
## Support Table
Most of axios v0 breaking changes were about typing issues, so your version may work with
one outside of this table. **Axios and Axios Cache Interceptor v0 are not compatible with

11
docs/src/guide/interceptors.md
View File

@ -5,13 +5,10 @@ inconsistences. Which is explained in the next section.
## TL;DR
- **Request** interceptors registered **before** `setupCache()` are ran **before** and
registrations made **after** are ran **after**.
- **Response** interceptors registered
<strong style="color: var(--vp-c-yellow-light)">before</strong> `setupCache()` are ran
<strong style="color: var(--vp-c-yellow-light)">after</strong> and registrations made
<strong style="color: var(--vp-c-yellow-light)">after</strong> are ran
<strong style="color: var(--vp-c-yellow-light)">before</strong>.
- **Request** interceptors registered before `setupCache()` are ran before and
registrations made after are ran after.
- **Response** interceptors registered before `setupCache()` are ran **after** and
registrations made after are ran **before**.
## Explanation

67
docs/src/guide/invalidating-cache.md
View File

@ -10,9 +10,8 @@ real time without communicating with the server.
**All available revalidation methods only works when the request is successful.**
If you are wanting to revalidate with a non standard `2XX` status code, make sure to
enable it on the [`validateStatus`](https://axios-http.com/docs/handling_errors) axios
option or revalidate it manually as shown
[below](#updating-cache-through-external-sources).
enable it at [`validateStatus`](https://axios-http.com/docs/handling_errors) or revalidate
it manually as shown [below](#updating-cache-through-external-sources).
:::
@ -41,7 +40,7 @@ after.
:::
### Updating cache programmatically
## Programmatically
If the mutation you made was just simple changes, you can get the mutation response and
update programmatically your cache.
@ -51,38 +50,42 @@ cache and we are good to go.
```ts
// Uses `list-posts` id to be able to reference it later.
function listPosts() {
return axios.get('/posts', { // [!code focus:3]
function listPosts() {
return axios.get('/posts', {
id: 'list-posts'
});
}
function createPost(data) {
return axios.post('/posts', data, { // [!code focus:22]
cache: {
update: {
// Will perform a cache update for the `list-posts` respective
// cache entry.
'list-posts': (listPostsCache, createPostResponse) => {
// If the cache is does not has a cached state, we don't need
// to update it
if (listPostsCache.state !== 'cached') {
return 'ignore';
return axios.post(
'/posts',
data,
/* [!code focus:25] */ {
cache: {
update: {
// Will perform a cache update for the `list-posts` respective
// cache entry.
'list-posts': (listPostsCache, createPostResponse) => {
// If the cache is does not has a cached state, we don't need
// to update it
if (listPostsCache.state !== 'cached') {
return 'ignore';
}
// Imagine the server response for the `list-posts` request
// is: { posts: Post[]; }, and the `create-post` response
// comes with the newly created post.
// Adds the created post to the end of the post's list
listPostsCache.data.posts.push(createPostResponse.data);
// Return the same cache state, but a updated one.
return listPostsCache;
}
// Imagine the server response for the `list-posts` request
// is: { posts: Post[]; }, and the `create-post` response
// comes with the newly created post.
// Adds the created post to the end of the post's list
listPostsCache.data.posts.push(createPostResponse.data);
// Return the same cache state, but a updated one.
return listPostsCache;
}
}
}
});
);
}
```
@ -90,7 +93,7 @@ This will update the `list-posts` cache at the client side, making it equal to t
When operations like this are possible to be made, they are the preferred. That's because
we do not contact the server again and update ourselves the cache.
### Updating cache through network
## Through network
Sometimes, the mutation you made is not simple enough and would need a lot of copied
service code to replicate all changes the backend made, turning it into a duplication and
@ -102,13 +105,15 @@ the server, and updating the cache with the new network response.
```ts
// Uses `list-posts` id to be able to reference it later.
function listPosts() {
return axios.get('/posts', { // [!code focus:3]
return axios.get('/posts', {
// [!code focus:3]
id: 'list-posts'
});
}
function createPost(data) {
return axios.post('/posts', data, { // [!code focus:9]
return axios.post('/posts', data, {
// [!code focus:9]
cache: {
update: {
// Will, internally, call storage.remove('list-posts') and let the
@ -125,7 +130,7 @@ Still using the first example, while we are at the step **3**, automatically, th
cache-interceptor instance will request the server again and do required changes in the
cache before the promise resolves and your page gets rendered.
### Updating cache through external sources
## Through external sources
If you have any other type of external communication, like when listening to a websocket
for changes, you may want to update your axios cache without be in a request context.

32
docs/src/guide/license.md
View File

@ -1,32 +0,0 @@
```
MIT License
Copyright (c) 2021-present Arthur Fiorette & Contributors
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
```
<br />
<a
href="https://app.fossa.com/projects/git%2Bgithub.com%2Farthurfiorette%2Faxios-cache-interceptor?ref=badge_large"
alt="FOSSA Status"
><img
src="https://app.fossa.com/api/projects/git%2Bgithub.com%2Farthurfiorette%2Faxios-cache-interceptor.svg?type=large"
/></a>

37
docs/src/guide/request-id.md
View File

@ -8,16 +8,7 @@ it later and to make the interceptor use the same cache for requests to the same
and parameters.
The default id generator is smart enough to generate the same ID for theoretically same
requests. E.g. `{ baseURL: 'https://a.com/', url: '/b' }` results to the same ID as
`{ url: 'https://a.com/b/' }`.
::: warning
If you send two different requests forcefully with the same ID. This
library will ignore any possible differences between them and share the same cache for
both.
:::
requests. `{ baseURL: 'https://a.com/', url: '/b' }` **==** `{ url: 'https://a.com/b/' }`.
::: code-group
@ -29,11 +20,10 @@ const axios = setupCache(Axios);
// [!code focus:5]
// These two requests are from completely endpoints, but they will share
// the same resources and cache, as both have the same ID.
const request1 = await axios.get('some endpoint', { id: 'custom-id' });
const request2 = await axios.get('different endpoint', { id: 'custom-id' });
const reqA = await axios.get('/a', { id: 'custom-id' });
const reqB = await axios.get('/b', { id: 'custom-id' });
```
```ts [Different contexts]
import Axios from 'axios';
import { setupCache } from 'axios-cache-interceptor';
@ -41,14 +31,19 @@ import { setupCache } from 'axios-cache-interceptor';
const axios = setupCache(Axios);
// [!code focus:7]
// You can use the same logic to create two caches for the same endpoint.
// These two requests will have different caches, as they have different
// IDs. This allows you to have different use cases and scenarios for the
// coincident same endpoint.
const userForPageX = await axios.get('api.com/users/id', { id: 'page-x' });
const userForPageY = await axios.get('api.com/users/id', { id: 'page-y' });
// Allows you to have different use cases for the coincident same endpoint.
const userForPageX = await axios.get('/users', { id: 'users-page-x' });
const userForPageY = await axios.get('/users', { id: 'users-page-y' });
```
:::
:::
::: warning
If you send two different requests forcefully with the same ID. This library will ignore
any possible differences between them and share the same cache for both.
:::
## Custom Generator
@ -66,9 +61,9 @@ properties:
import Axios from 'axios';
import { setupCache, buildKeyGenerator } from 'axios-cache-interceptor';
const axios = setupCache(Axios, {
keyGenerator: buildKeyGenerator((request) => ({
// [!code focus:5]
keyGenerator: buildKeyGenerator((request/* [!code focus:5] */) => ({
method: request.method,
url: request.url,
custom: logicWith(request.method, request.url)

18
docs/src/guide/storages.md
View File

@ -124,28 +124,28 @@ object to build the storage. It has 3 methods:
Receives the key and optionally the current request. It should return the value from the
storage or `undefined` if not found.
### Node Redis v4 Example
## Node Redis Example
To inspire you, here is an example for a server-side application that uses Redis as the
storage.
```ts{8,13,21}
import axios from 'axios';
import { createClient } from 'redis';
import { buildStorage, setupCache, canStale } from 'axios-cache-interceptor';
```ts{4}
import { createClient } from 'redis'; // v4
import { buildStorage, canStale } from 'axios-cache-interceptor';
const client = createClient(/* connection config */);
// [!code focus:6]
const redisStorage = buildStorage({
async find(key) {
const result = await client.get(`axios-cache:${key}`);
return JSON.parse(result);
},
async set(key, value) {
// We use canStale function here because we shouldn't let
// redis remove automatically the key if it can enter the
// stale state.
async set(key, value) { // [!code focus:10]
await client.set(`axios-cache:${key}`, JSON.stringify(value), {
// We use canStale function here because we shouldn't let
// redis remove it if it can stale.
PXAT: canStale(value) ? value.expiresAt : undefined
});
},

40
docs/src/index.md
View File

@ -5,32 +5,46 @@ hero:
name: Axios Cache Interceptor
text: Performant, small and powerful
tagline: A cache interceptor for axios made with developers and performance in mind.
image: /rocket.png
image:
src: /rocket.png
alt: Rocket
title: We need a designer :)
actions:
- theme: brand
text: Get Started
link: /guide
- theme: alt
text: Why cache?
link: https://arthur.place/implications-of-cache-or-state
- theme: alt
text: View on GitHub
link: https://github.com/arthurfiorette/axios-cache-interceptor
features:
- icon: 📦
title: Super small bundle!
details: The library is only 4.3kb minified and gzipped.
- icon: ⚡
title: Faster
details: Serving 21x more requests per second than pure axios.
- icon: 📖
title: Supports all specified cache mechanisms!
- icon: 📦
title: Handy builds
details: Pre built for CDN, EcmaScript, UMD, CommonJS and URL imports.
- icon: 🔩
title: Hassle free
details: Works for everyone, no matter the current adapter or interceptors.
- icon: 🛠️
title: Rich Features
details: MDN, RFCs, and other specifications are followed.
- icon: ✨
title: Never worry about duplicate requests again!
details:
We will handle everything for you. You just call axios and we will do the rest.
- icon: 🌐
title: No network waste!
details: Network speed should not matter for your users.
- icon: 🚀
- icon: 🔑
title: TypeScript!
details:
Axios Cache Interceptor is written in TypeScript and has type definitions included.
details: Flexible interceptors with full TypeScript typing.
---

1304
docs/src/others/changelog.md Normal file
View File

File diff suppressed because it is too large Load Diff

19
docs/src/others/license.md Normal file
View File

@ -0,0 +1,19 @@
### MIT License
> Copyright (c) 2021-present Arthur Fiorette & Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy of this
software and associated documentation files (the "Software"), to deal in the Software
without restriction, including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

2
package.json
View File

@ -30,7 +30,7 @@
"check": "sh build/check.sh",
"format": "prettier --write .",
"lint": "eslint . --ext .ts",
"version": "auto-changelog -p && git add CHANGELOG.md",
"version": "auto-changelog -p && cp CHANGELOG.md docs/src/others/changelog.md git add CHANGELOG.md docs/src/others/changelog.md",
"benchmark": "cd benchmark && yarn start",
"docs:dev": "vitepress dev docs --port 1227",
"docs:build": "vitepress build docs",