feat(v0.6.3): add persistent cache functionality to filesystem resolve #33

Author: suhaotian

CHANGELOG.md

@@ -1,8 +1,13 @@
 # CHANGELOG 📝
 
+## v0.6.3
+
+- Refactor: Add `cacheKey` to cache plugin for persistent cache
+- Tests: Add persistent cache test
+
 ## v0.6.2
 
-- Refactor: minor improvment
+- Refactor: minor improvement
 - Refactor: use `'./utils'` instead of `'xior/utils'`, fix [Unable to resolve module xior/utils #34](https://github.com/suhaotian/xior/issues/34)
 
 ## v0.6.1
@@ -11,7 +16,7 @@
 
 ## v0.6.0
 
-- Fix: response interceptors should run after plugins(Fix https://github.com/suhaotian/xior/issues/29)
+- Fix: response interceptors should run after plugins (Fix https://github.com/suhaotian/xior/issues/29)
 
 ## v0.5.5
 
@@ -27,7 +32,7 @@
 
 ## v0.5.2 2024/7/9
 
-- Fix(core): if params include `Date` value, call `.toISOString()` and utils `encodeParams` support options `allowDot: true` and `arrayFormat: 'indices' | 'repeat' | 'brackets'`(default is `'indices'`). Fix [issues/22](https://github.com/suhaotian/xior/issues/22) and [issues/23](https://github.com/suhaotian/xior/issues/23)
+- Fix(core): if params include `Date` value, call `.toISOString()` and utils `encodeParams` support options `allowDot: true` and `arrayFormat: 'indices' | 'repeat' | 'brackets'` (default is `'indices'`). Fix [issues/22](https://github.com/suhaotian/xior/issues/22) and [issues/23](https://github.com/suhaotian/xior/issues/23)
 
 ---
 
@@ -100,12 +105,12 @@ import { Xior } from 'xior';
 
 This version is about Axios compatible issue in some cases. Fixing https://github.com/suhaotian/xior/issues/12 and https://github.com/suhaotian/xior/issues/15.
 
-- Feat(core): when `responseType: 'blob' | 'arrarybuffer'` then the `resposne.data` is `Blob` and `ArrayBuffer`, no need `response.blob()` or `response.arraybuffer()` anymore.
-- Fix(interceptors): make sure the multiple response interceptors chain behaviour same as axios's interceptors.
+- Feat(core): when `responseType: 'blob' | 'arraybuffer'` then the `response.data` is `Blob` and `ArrayBuffer`, no need `response.blob()` or `response.arraybuffer()` anymore.
+- Fix(interceptors): make sure the multiple response interceptors chain behavior same as axios's interceptors.
 
 ## v0.3.13 2024/04/21
 
-- Feat(plugin): add custom paramaters of LRU in plugins: cache, error-cache, throttle
+- Feat(plugin): add custom parameters of LRU in plugins: cache, error-cache, throttle
 - Feat(plugin): add `cacheTime` to cache plugin
 
 ## v0.3.12 2024/04/13
@@ -198,7 +203,7 @@ http.plugins.use(
 
 ## v0.3.0 2024/03/24
 
-- fix(core): POST/DELETE/PUT/PATCH methods when `content-type=application/x-www-form-urlencoded`, use formData to in body(previous put in url)
+- fix(core): POST/DELETE/PUT/PATCH methods when `content-type=application/x-www-form-urlencoded`, use formData to in body (previous put in url)
 - refactor(core): default request interceptors should work before send fetch
 - refactor(core): remove `_data` in request config
 - refactor(core): remove `encode` in options, use `paramsSerializer` option instead
@@ -212,7 +217,7 @@ http.plugins.use(
 ## v0.2.5 2024/03/20
 
 - fix(plugin): fix `error-retry` plugin default options override bugs
-- fix(plugin): `requestConfig` with plugins should always get latest config from `requestinterceptors`
+- fix(plugin): `requestConfig` with plugins should always get latest config from `request interceptors`
 
 ## v0.2.4
 
@@ -227,13 +232,13 @@ http.plugins.use(
 
 - fix(plugin): fix `error-retry` plugin, `TypeError` should retry too
 - feat(plugin): `error-retry` plugin, `retryInterval` can be `function` too, and add `onRetry` to options
-- chore(core): minor improvment
+- chore(core): minor improvement
 
 ## v0.2.1 2024/03/17
 
 - feat(core): support direct call `xior.get/post..` similar to `axios.get/post..` API, no need create instance at first
 - fix(core): `DELETE` and `OPTIONS` method's data option should be url encoded format like `GET` / `HEAD`
-- feat: add `UMD`(Universal Module Definition) format bundle(now you can directly load xior in browser)
+- feat: add `UMD` (Universal Module Definition) format bundle (now you can directly load xior in browser)
 - feat: add `VERSION` to `xior`, now you can get current version of xior by: `import xior from 'xior'; console.log(xior.VERSION)`
 - feat(new plugin): add `error-cache` plugin
 - feat(new plugin): add `dedupe` plugin
@@ -295,7 +300,7 @@ instance.options('/options_api_path', { params: { a: 1, text: 'this is data' } }
 
 ## v0.1.1 2024-03-04
 
-- Fix: compatiable `delete` method with axios, and `delete` method shouldn't have body
+- Fix: compatible `delete` method with axios, and `delete` method shouldn't have body
 - Chore: remove unused code in core module
 
 **Breaking change:**
@@ -319,15 +324,15 @@ http.delete('/', { params: { a: 1, b: 2 } });
 
 ## v0.0.9 2024-02-29
 
-- fix(plugins): resolve import plugins not found file error in expo(react-native) project
+- fix(plugins): resolve import plugins not found file error in expo (react-native) project
 
 ## v0.0.8 2024-02-29
 
-- feat(core): compatiable axios's options: `paramsSerializer` and `withCredentials`
+- feat(core): compatible axios's options: `paramsSerializer` and `withCredentials`
 
 ## v0.0.7 2024-02-27
 
-- feat(core): suport nested object paramaters in default
+- feat(core): support nested object parameters in default
 - feat(plugin): implemented **error retry**, **cache**, **throttle**, and upload/download **progress** plugins
 - fix(build): resolved Bunchee build output error with Vite projects.
 - chore(doc): updated README.md
@@ -344,7 +349,7 @@ http.delete('/', { params: { a: 1, b: 2 } });
 
 ## v0.0.4
 
-- feat: support url as first paramter in xiorInstance.request('/url')
+- feat: support url as first parameter in xiorInstance.request('/url')
 - feat: Removed first parameter `url` from `xiorInstance.request`
 
 ## v0.0.3

README.md

@@ -1,5 +1,5 @@
 [![Build](https://github.com/suhaotian/xior/actions/workflows/check.yml/badge.svg)](https://github.com/suhaotian/xior/actions/workflows/check.yml)
-[![Size](https://deno.bundlejs.com/badge?q=xior@0.6.2&badge=detailed)](https://bundlejs.com/?q=xior%400.6.2)
+[![Size](https://deno.bundlejs.com/badge?q=xior@0.6.3&badge=detailed)](https://bundlejs.com/?q=xior%400.6.3)
 [![npm version](https://badgen.net/npm/v/xior?color=green)](https://www.npmjs.com/package/xior)
 ![Downloads](https://img.shields.io/npm/dm/xior.svg?style=flat)
 ![typescript](https://badgen.net/badge/icon/typescript?icon=typescript&label&color=blue)
@@ -41,6 +41,7 @@ A lite request lib based on **fetch** with plugin support and similar API to axi
   - [Request dedupe plugin](#request-dedupe-plugin)
   - [Error cache plugin](#error-cache-plugin)
   - [Cache plugin](#cache-plugin)
+  - [Persist cache data](#persist-cache-data)
   - [Upload and download progress plugin](#upload-and-download-progress-plugin)
   - [Mock plugin](#mock-plugin)
   - [Auth refresh token plugin(from community)](#auth-refresh-token-pluginfrom-community)
@@ -95,12 +96,12 @@ yarn add xior
 
 #### Use CDN
 
-> Since v0.2.1, xior support UMD format
+> Since v0.2.1, xior supports UMD format
 
 Use jsDelivr CDN:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/xior@0.6.2/dist/xior.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/xior@0.6.3/dist/xior.umd.js"></script>
 
 <!-- Usage -->
 <script>
@@ -115,7 +116,7 @@ Use jsDelivr CDN:
 Use unpkg CDN:
 
 ```html
-<script src="https://unpkg.com/xior@0.6.2/dist/xior.umd.js"></script>
+<script src="https://unpkg.com/xior@0.6.3/dist/xior.umd.js"></script>
 
 <!-- Usage -->
 <script>
@@ -131,7 +132,7 @@ Use unpkg CDN:
 import xior from 'xior';
 
 export const xiorInstance = xior.create({
-  baseURL: 'https://apiexampledomian.com/api',
+  baseURL: 'https://apiexampledomain.com/api',
   headers: {
     // put your common custom headers here
   },
@@ -187,7 +188,7 @@ async function run() {
 import xior from 'xior';
 
 export const xiorInstance = xior.create({
-  baseURL: 'https://apiexampledomian.com/api',
+  baseURL: 'https://apiexampledomain.com/api',
 });
 
 function setAccessToken(token: string) {
@@ -207,7 +208,7 @@ function removeUserToken() {
 import xior from 'xior';
 
 const xiorInstance = xior.create({
-  baseURL: 'https://apiexampledomian.com/api',
+  baseURL: 'https://apiexampledomain.com/api',
 });
 
 const { data, headers } = await xiorInstance.get('/');
@@ -598,9 +599,9 @@ Use CDN:
 Using jsDelivr CDN:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/xior@0.6.2/dist/xior.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/xior@0.6.3/dist/xior.umd.js"></script>
 <!-- Load plugin -->
-<script src="https://cdn.jsdelivr.net/npm/xior@0.6.2/plugins/error-retry.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/xior@0.6.3/plugins/error-retry.umd.js"></script>
 
 <!-- Usage -->
 <script>
@@ -613,10 +614,10 @@ Using jsDelivr CDN:
 Using unpkg CDN:
 
 ```html
-<script src="https://unpkg.com/xior@0.6.2/dist/xior.umd.js"></script>
+<script src="https://unpkg.com/xior@0.6.3/dist/xior.umd.js"></script>
 
 <!-- Load plugin -->
-<script src="https://unpkg.com/xior@0.6.2/plugins/error-retry.umd.js"></script>
+<script src="https://unpkg.com/xior@0.6.3/plugins/error-retry.umd.js"></script>
 
 <!-- Usage -->
 <script>
@@ -709,9 +710,9 @@ Use CDN:
 Using jsDelivr CDN:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/xior@0.6.2/dist/xior.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/xior@0.6.3/dist/xior.umd.js"></script>
 <!-- Load plugin -->
-<script src="https://cdn.jsdelivr.net/npm/xior@0.6.2/plugins/throttle.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/xior@0.6.3/plugins/throttle.umd.js"></script>
 
 <!-- Usage -->
 <script>
@@ -724,10 +725,10 @@ Using jsDelivr CDN:
 Using unpkg CDN:
 
 ```html
-<script src="https://unpkg.com/xior@0.6.2/dist/xior.umd.js"></script>
+<script src="https://unpkg.com/xior@0.6.3/dist/xior.umd.js"></script>
 
 <!-- Load plugin -->
-<script src="https://unpkg.com/xior@0.6.2/plugins/throttle.umd.js"></script>
+<script src="https://unpkg.com/xior@0.6.3/plugins/throttle.umd.js"></script>
 
 <!-- Usage -->
 <script>
@@ -782,9 +783,9 @@ Use CDN:
 Using jsDelivr CDN:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/xior@0.6.2/dist/xior.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/xior@0.6.3/dist/xior.umd.js"></script>
 <!-- Load plugin -->
-<script src="https://cdn.jsdelivr.net/npm/xior@0.6.2/plugins/dedupe.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/xior@0.6.3/plugins/dedupe.umd.js"></script>
 
 <!-- Usage -->
 <script>
@@ -797,10 +798,10 @@ Using jsDelivr CDN:
 Using unpkg CDN:
 
 ```html
-<script src="https://unpkg.com/xior@0.6.2/dist/xior.umd.js"></script>
+<script src="https://unpkg.com/xior@0.6.3/dist/xior.umd.js"></script>
 
 <!-- Load plugin -->
-<script src="https://unpkg.com/xior@0.6.2/plugins/dedupe.umd.js"></script>
+<script src="https://unpkg.com/xior@0.6.3/plugins/dedupe.umd.js"></script>
 
 <!-- Usage -->
 <script>
@@ -862,9 +863,9 @@ Use CDN:
 Using jsDelivr CDN:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/xior@0.6.2/dist/xior.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/xior@0.6.3/dist/xior.umd.js"></script>
 <!-- Load plugin -->
-<script src="https://cdn.jsdelivr.net/npm/xior@0.6.2/plugins/error-cache.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/xior@0.6.3/plugins/error-cache.umd.js"></script>
 
 <!-- Usage -->
 <script>
@@ -877,10 +878,10 @@ Using jsDelivr CDN:
 Using unpkg CDN:
 
 ```html
-<script src="https://unpkg.com/xior@0.6.2/dist/xior.umd.js"></script>
+<script src="https://unpkg.com/xior@0.6.3/dist/xior.umd.js"></script>
 
 <!-- Load plugin -->
-<script src="https://unpkg.com/xior@0.6.2/plugins/error-cache.umd.js"></script>
+<script src="https://unpkg.com/xior@0.6.3/plugins/error-cache.umd.js"></script>
 
 <!-- Usage -->
 <script>
@@ -942,7 +943,7 @@ http.post('/users', { enableCache: true }); // make real http request
 const res = await http.post('/users', { enableCache: true }); // get cache from previous request
 if (res.fromCache) {
   // if `fromCache` is true, means data from cache!
-  console.log('data from cache!', res.cacheTime);
+  console.log('data from cache!', res.cacheKey, res.cacheTime);
 }
 ```
 
@@ -974,6 +975,12 @@ const cacheA = lru(100);
 http.get('/users', { enableCache: true, defaultCache: cacheA, forceUpdate: true });
 ```
 
+### Persist cache data
+
+How to persist cache data to the filesystem to prevent loss after a server restart?
+
+For more details, refer to this GitHub issue: [GitHub issue 33](https://github.com/suhaotian/xior/issues/33)
+
 ### Upload and download progress plugin
 
 > Enable upload and download progress like axios, but the progress is simulated,
@@ -1025,9 +1032,9 @@ Use CDN:
 Using jsDelivr CDN:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/xior@0.6.2/dist/xior.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/xior@0.6.3/dist/xior.umd.js"></script>
 <!-- Load plugin -->
-<script src="https://cdn.jsdelivr.net/npm/xior@0.6.2/plugins/progress.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/xior@0.6.3/plugins/progress.umd.js"></script>
 
 <!-- Usage -->
 <script>
@@ -1040,10 +1047,10 @@ Using jsDelivr CDN:
 Using unpkg CDN:
 
 ```html
-<script src="https://unpkg.com/xior@0.6.2/dist/xior.umd.js"></script>
+<script src="https://unpkg.com/xior@0.6.3/dist/xior.umd.js"></script>
 
 <!-- Load plugin -->
-<script src="https://unpkg.com/xior@0.6.2/plugins/progress.umd.js"></script>
+<script src="https://unpkg.com/xior@0.6.3/plugins/progress.umd.js"></script>
 
 <!-- Usage -->
 <script>
@@ -1150,9 +1157,9 @@ Use CDN:
 Using jsDelivr CDN:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/xior@0.6.2/dist/xior.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/xior@0.6.3/dist/xior.umd.js"></script>
 <!-- Load plugin -->
-<script src="https://cdn.jsdelivr.net/npm/xior@0.6.2/plugins/mock.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/xior@0.6.3/plugins/mock.umd.js"></script>
 
 <!-- Usage -->
 <script>
@@ -1165,10 +1172,10 @@ Using jsDelivr CDN:
 Using unpkg CDN:
 
 ```html
-<script src="https://unpkg.com/xior@0.6.2/dist/xior.umd.js"></script>
+<script src="https://unpkg.com/xior@0.6.3/dist/xior.umd.js"></script>
 
 <!-- Load plugin -->
-<script src="https://unpkg.com/xior@0.6.2/plugins/mock.umd.js"></script>
+<script src="https://unpkg.com/xior@0.6.3/plugins/mock.umd.js"></script>
 
 <!-- Usage -->
 <script>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "xior",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "A lite request lib based on fetch with plugin support and similar API to axios.",
   "repository": "suhaotian/xior",
   "bugs": "https://github.com/suhaotian/xior/issues",

src/plugins/cache/index.ts

@@ -30,6 +30,12 @@ declare module 'xior' {
     cacheTime?: number;
     cacheKey?: string;
   }
+
+  interface XiorResponseInterceptorConfig {
+    fromCache?: boolean;
+    cacheTime?: number;
+    cacheKey?: string;
+  }
 }
 
 export default function xiorCachePlugin(options: XiorCacheOptions = {}): XiorPlugin {
@@ -79,7 +85,9 @@ export default function xiorCachePlugin(options: XiorCacheOptions = {}): XiorPlu
         if (!responsePromise || forceUpdate) {
           responsePromise = (async () => {
             try {
-              return await adapter(config);
+              const res = await adapter(config);
+              if (res) (res as any).cacheKey = key;
+              return res;
             } catch (reason) {
               if ('delete' in cache) {
                 cache.delete(key);
@@ -98,7 +106,7 @@ export default function xiorCachePlugin(options: XiorCacheOptions = {}): XiorPlu
         return responsePromise.then((res) => {
           (res as any).fromCache = true;
           (res as any).cacheTime = Date.now();
-          (res as any).cacheKey = key;
+          if (key) (res as any).cacheKey = key;
 
           return res;
         });

src/xior.ts

@@ -47,7 +47,7 @@ export class Xior {
   static create(options?: XiorRequestConfig): XiorInstance {
     return new Xior(options);
   }
-  static VERSION = '0.6.2';
+  static VERSION = '0.6.3';
 
   config?: XiorRequestConfig;
   defaults: XiorInterceptorRequestConfig;

tests/.gitignore

@@ -0,0 +1 @@
+cache.json

tests/package.json

@@ -3,7 +3,8 @@
   "private": true,
   "scripts": {
     "build:lib": "rm -rf lib && tsc --project tsconfig.json",
-    "test": "pnpm build:lib && node --test ./lib"
+    "test": "pnpm build:lib && node --test ./lib",
+    "test:cache": "pnpm build:lib && node --test ./lib/plugins/persist-cache.test.js"
   },
   "devDependencies": {
     "xior": "workspace:*"

tests/src/tests/plugins/persist-cache.test.ts

@@ -0,0 +1,112 @@
+import fs from 'fs/promises';
+import assert from 'node:assert';
+import { after, before, describe, it } from 'node:test';
+import { lru, LRU } from 'tiny-lru';
+import { Xior as xior, delay, Xior } from 'xior';
+import xiorCachePlugin from 'xior/plugins/cache';
+
+import { startServer } from '../server';
+
+let close: Function;
+const port = 7778;
+const baseURL = `http://localhost:${port}`;
+before(async () => {
+  close = await startServer(port);
+});
+
+after(async () => {
+  return close(1);
+});
+
+export function persistCachePlugin(
+  xiorInstance: Xior,
+  cache: LRU<any>,
+  filePath: string,
+  debounceTime = 500
+) {
+  xiorInstance.interceptors.response.use((response) => {
+    if (!response.fromCache && response.cacheKey) {
+      debouncedSyncToFs();
+    }
+    return response;
+  });
+
+  async function initFromFs() {
+    try {
+      const data = JSON.parse(await fs.readFile(filePath, 'utf-8'));
+      data.forEach(([key, value]: [string, any]) => {
+        if (value) {
+          cache.set(key, Promise.resolve(value));
+        }
+      });
+    } catch (e) {
+      console.error('initFromFs error:', e);
+    }
+  }
+
+  async function syncToFs() {
+    const keys = cache.keys();
+    const data = await Promise.all(keys.map(async (key) => [key, await cache.get(key)]));
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2));
+  }
+  const debouncedSyncToFs = debounce(syncToFs, debounceTime);
+
+  function debounce(func: () => Promise<void>, wait: number) {
+    let timeout: NodeJS.Timeout | null = null;
+    return () => {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      timeout = setTimeout(() => {
+        func();
+      }, wait);
+    };
+  }
+
+  return { initFromFs, debouncedSyncToFs };
+}
+
+const instance = xior.create({ baseURL });
+const cache = lru(100, 1000 * 60 * 5);
+instance.plugins.use(
+  xiorCachePlugin({
+    enableCache: (config) => config?.method === 'GET' || config?.isGet === true,
+    defaultCache: cache,
+  })
+);
+const { initFromFs } = persistCachePlugin(instance, cache, './cache.json', 500);
+
+describe('xior cache plugin tests', async () => {
+  it('Generate cache data should work', async () => {
+    for (const key of [1, 2, 3, 4, 5, 6, 7, 8]) {
+      const { data } = await instance.get<{ value: string }>('/get', {
+        params: { idx: key },
+        headers: {
+          'x-custom-value': key,
+        },
+      });
+      assert.strictEqual(data.value, key + '');
+    }
+    assert.strictEqual(cache.size, 8);
+    await delay(600);
+  });
+
+  it('Async cache should work', async () => {
+    cache.clear();
+    assert.strictEqual(cache.size, 0);
+
+    await initFromFs();
+
+    assert.strictEqual(cache.size, 8);
+    for (const key of [1, 2, 3, 4, 5, 6, 7, 8]) {
+      const { data, fromCache } = await instance.get<{ value: string }>('/get', {
+        params: { idx: key },
+        headers: {
+          'x-custom-value': key,
+        },
+      });
+      assert.strictEqual(data.value, key + '');
+      assert.strictEqual(fromCache, true);
+    }
+  });
+});