feat: support getKey for cache funtion (#7102)

Author: yimingjfe

.changeset/dirty-turkeys-crash.md

@@ -0,0 +1,6 @@
+---
+'@modern-js/runtime-utils': patch
+---
+
+feat: support getKey for cache funtion
+feat: 为 cahce 函数支持 getKey

packages/document/main-doc/docs/en/guides/basic-features/data/data-cache.mdx

@@ -12,6 +12,15 @@ X.65.5 and above versions are required
 
 ## Basic Usage
 
+:::note
+
+If you use the `cache` function in BFF, you should import the cache funtion from `@modern-js/server-runtime/cache`
+
+`import { cache } from '@modern-js/server-runtime/cache'`
+
+:::
+
+
 ```ts
 import { cache } from '@modern-js/runtime/cache';
 import { fetchUserData } from './api';
@@ -34,6 +43,7 @@ const loader = async () => {
   - `tag`: Tag to identify the cache, which can be used to invalidate the cache
   - `maxAge`: Cache validity period (milliseconds)
   - `revalidate`: Time window for revalidating the cache (milliseconds), similar to HTTP Cache-Control's stale-while-revalidate functionality
+  - `getKey`: Simplified cache key generation function based on function parameters
   - `customKey`: Custom cache key function
 
 The type of the `options` parameter is as follows:
@@ -43,6 +53,7 @@ interface CacheOptions {
   tag?: string | string[];
   maxAge?: number;
   revalidate?: number;
+  getKey?: <Args extends any[]>(...args: Args) => string;
   customKey?: <Args extends any[]>(options: {
     params: Args;
     fn: (...args: Args) => any;
@@ -159,6 +170,72 @@ revalidateTag('dashboard-stats'); // Invalidates the cache for both getDashboard
 ```
 
 
+#### `getKey` Parameter
+
+The `getKey` parameter simplifies cache key generation, especially useful when you only need to rely on part of the function parameters to differentiate caches. It's a function that receives the same parameters as the original function and returns a string or number as the cache key:
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(
+  async (userId, options) => {
+    // Here options might contain many configurations, but we only want to cache based on userId
+    return await fetchUserData(userId, options);
+  },
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    // Only use the first parameter (userId) as the cache key
+    getKey: (userId, options) => userId,
+  }
+);
+
+// The following two calls will share the cache because getKey only uses userId
+await getUser(123, { language: 'en' });
+await getUser(123, { language: 'fr' }); // Cache hit, won't request again
+
+// Different userId will use different cache
+await getUser(456, { language: 'en' }); // Won't hit cache, will request again
+```
+
+You can also use Modern.js's `generateKey` function together with getKey to generate the cache key:
+
+:::info
+
+The `generateKey` function in Modern.js ensures that a consistent and unique key is generated even if object property orders change, guaranteeing stable caching.
+
+:::
+
+```ts
+import { cache, CacheTime, generateKey } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(
+  async (userId, options) => {
+    return await fetchUserData(userId, options);
+  },
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    getKey: (userId, options) => generateKey(userId),
+  }
+);
+```
+
+Additionally, `getKey` can also return a numeric type as a cache key:
+
+```ts
+const getUserById = cache(
+  fetchUserDataById,
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    // Directly use the numeric ID as the cache key
+    getKey: (id) => id,
+  }
+);
+
+await getUserById(42); // Uses 42 as the cache key
+```
+
 #### `customKey` parameter
 
 The `customKey` parameter is used to customize the cache key. It is a function that receives an object with the following properties and returns a string or Symbol type as the cache key:
@@ -167,6 +244,18 @@ The `customKey` parameter is used to customize the cache key. It is a function t
 - `fn`: Reference to the original function being cached
 - `generatedKey`: Cache key automatically generated by the framework based on input parameters
 
+:::info
+
+Generally, the cache will be invalidated in the following scenarios:
+1. The referenced cached function changes
+2. The function's input parameters change
+3. The maxAge condition is no longer satisfied
+4. The `revalidateTag` method has been called
+
+`customKey` can be used in scenarios where function references are different but shared caching is desired. If it's just for customizing the cache key, it is recommended to use `getKey`.
+
+:::
+
 This is very useful in some scenarios, such as when the function reference changes , but you want to still return the cached data.
 
 ```ts
@@ -271,7 +360,7 @@ The `onCache` callback receives an object with the following properties:
 - `params`: The parameters passed to the cached function
 - `result`: The result data (either from cache or newly computed)
 
-This callback is only invoked when the `options` parameter is provided. When using the cache function without options (for SSR request-scoped caching), the `onCache` callback is not called.
+This callback is only invoked when the `options` parameter is provided. When using the cache function without options, the `onCache` callback is not called.
 
 The `onCache` callback is useful for:
 - Monitoring cache performance

packages/document/main-doc/docs/zh/guides/basic-features/data/data-cache.mdx

@@ -12,6 +12,14 @@ sidebar_position: 4
 
 ## 基本用法
 
+:::note
+
+如果在 BFF 中使用 `cache` 函数，应该从 `@modern-js/server-runtime/cache` 导入相关函数
+
+`import { cache } from '@modern-js/server-runtime/cache'`
+
+:::
+
 ```ts
 import { cache } from '@modern-js/runtime/cache';
 import { fetchUserData } from './api';
@@ -33,6 +41,7 @@ const loader = async () => {
   - `tag`: 用于标识缓存的标签，可以基于这个标签使缓存失效
   - `maxAge`: 缓存的有效期 (毫秒)
   - `revalidate`: 重新验证缓存的时间窗口（毫秒），与 HTTP Cache-Control 的 stale-while-revalidate 功能一致
+  - `getKey`: 简化的缓存键生成函数，根据函数参数生成缓存键
   - `customKey`: 自定义缓存键生成函数，用于在函数引用变化时保持缓存
 
 `options` 参数的类型如下：
@@ -42,6 +51,7 @@ interface CacheOptions {
   tag?: string | string[];
   maxAge?: number;
   revalidate?: number;
+  getKey?: <Args extends any[]>(...args: Args) => string;
   customKey?: <Args extends any[]>(options: {
     params: Args;
     fn: (...args: Args) => any;
@@ -152,6 +162,58 @@ const getComplexStatistics = cache(
 revalidateTag('dashboard-stats'); // 会使 getDashboardStats 函数和 getComplexStatistics 函数的缓存都失效
 ```
 
+#### `getKey` 参数
+
+`getKey` 参数用于自定义缓存键的生成方式，例如你可能只需要依赖函数参数的一部分来区分缓存。它是一个函数，接收与原始函数相同的参数，返回一个字符串作为缓存键：
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(
+  async (userId, options) => {
+    // 这里 options 可能包含很多配置，但我们只想根据 userId 缓存
+    return await fetchUserData(userId, options);
+  },
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    // 只使用第一个参数（userId）作为缓存键
+    getKey: (userId, options) => userId,
+  }
+);
+
+// 下面两次调用会共享缓存，因为 getKey 只使用了 userId
+await getUser(123, { language: 'zh' });
+await getUser(123, { language: 'en' }); // 命中缓存，不会重新请求
+
+// 不同的 userId 会使用不同的缓存
+await getUser(456, { language: 'zh' }); // 不会命中缓存，会重新请求
+```
+
+你也可以使用 Modern.js 提供的 `generateKey` 函数配合 getKey 生成缓存的键：
+
+:::info
+
+Modern.js 中的 `generateKey` 函数确保即使对象属性顺序发生变化，也能生成一致的唯一键值，保证稳定的缓存
+
+:::
+
+```ts
+import { cache, CacheTime, generateKey } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(
+  async (userId, options) => {
+    return await fetchUserData(userId, options);
+  },
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    getKey: (userId, options) => generateKey(userId),
+  }
+);
+```
+
+
 #### `customKey` 参数
 
 `customKey` 参数用于定制缓存的键，它是一个函数，接收一个包含以下属性的对象，返回值必须是字符串或 Symbol 类型，将作为缓存的键：
@@ -160,6 +222,18 @@ revalidateTag('dashboard-stats'); // 会使 getDashboardStats 函数和 getCompl
 - `fn`：原始被缓存的函数引用
 - `generatedKey`：框架基于入参自动生成的原始缓存键
 
+:::info
+
+一般在以下场景，缓存会失效：
+1. 缓存的函数引用发生变化
+2. 函数的入参发生变化
+3. 不满足 maxAge
+4. 调用了 `revalidateTag`
+
+`customKey` 可以用在函数引用不同，但希望共享缓存的场景，如果只是自定义缓存键，推荐使用 `getKey`
+
+:::
+
 这在某些场景下非常有用，比如当函数引用发生变化时，但你希望仍然返回缓存的数据。
 
 ```ts
@@ -268,7 +342,7 @@ await getUser(2); // 缓存未命中
 - `params`: 传递给缓存函数的参数
 - `result`: 结果数据（来自缓存或新计算的）
 
-这个回调只在提供 `options` 参数时被调用。当使用不带选项的缓存函数（用于 SSR 请求范围内的缓存）时，不会调用 `onCache` 回调。
+这个回调只在提供 `options` 参数时被调用。当使用无 options 的缓存函数时，不会调用 `onCache` 回调。
 
 `onCache` 回调对以下场景非常有用：
 - 监控缓存性能

packages/server/server-runtime/package.json

@@ -24,17 +24,29 @@
     ".": {
       "node": {
         "jsnext:source": "./src/index.ts",
-        "types": "./dist/types/index.d.ts",
         "import": "./dist/esm-node/index.js",
         "require": "./dist/cjs/index.js"
       },
+      "types": "./dist/types/index.d.ts",
       "default": "./dist/cjs/index.js"
+    },
+    "./cache": {
+      "node": {
+        "jsnext:source": "./src/cache.ts",
+        "import": "./dist/esm-node/cache.js",
+        "require": "./dist/cjs/cache.js"
+      },
+      "types": "./dist/types/cache.d.ts",
+      "default": "./dist/cjs/cache.js"
     }
   },
   "typesVersions": {
     "*": {
       ".": [
         "./dist/types/index.d.ts"
+      ],
+      "cache": [
+        "./dist/types/cache.d.ts"
       ]
     }
   },
@@ -46,7 +58,8 @@
   },
   "dependencies": {
     "@swc/helpers": "0.5.13",
-    "@modern-js/server-core": "workspace:*"
+    "@modern-js/server-core": "workspace:*",
+    "@modern-js/runtime-utils": "workspace:*"
   },
   "devDependencies": {
     "@scripts/build": "workspace:*",

packages/server/server-runtime/src/cache.ts

@@ -0,0 +1 @@
+export * from '@modern-js/runtime-utils/cache';

packages/toolkit/runtime-utils/src/universal/async_storage.ts

@@ -1,7 +1,20 @@
 // This file is an `async_storage` proxy for browser bundle.
 import type { Storage } from './async_storage.server';
 
+const isBrowser =
+  typeof window !== 'undefined' && typeof window.document !== 'undefined';
+
 export const getAsyncLocalStorage = (): Storage | null => {
-  console.error('You should not get async storage in browser');
-  return null;
+  if (isBrowser) {
+    console.error('You should not get async storage in browser');
+    return null;
+  } else {
+    try {
+      const serverStorage = require('./async_storage.server');
+      return serverStorage.getAsyncLocalStorage();
+    } catch (err) {
+      console.error('Failed to load server async storage', err);
+      return null;
+    }
+  }
 };

packages/toolkit/runtime-utils/src/universal/cache.ts

@@ -29,6 +29,7 @@ interface CacheOptions {
   tag?: string | string[];
   maxAge?: number;
   revalidate?: number;
+  getKey?: <Args extends any[]>(...args: Args) => string;
   customKey?: <Args extends any[]>(options: {
     params: Args;
     fn: (...args: Args) => any;
@@ -38,7 +39,7 @@ interface CacheOptions {
 }
 
 interface CacheConfig {
-  maxSize: number;
+  maxSize?: number;
   unstable_shouldDisable?: ({
     request,
   }: {
@@ -86,7 +87,7 @@ function getLRUCache() {
       Function | string | symbol,
       Map<string, CacheItem<any>>
     >({
-      maxSize: cacheConfig.maxSize,
+      maxSize: cacheConfig.maxSize ?? CacheSize.GB,
       sizeCalculation: (value: Map<string, CacheItem<any>>): number => {
         if (!value.size) {
           return 1;
@@ -171,6 +172,7 @@ export function cache<T extends (...args: any[]) => Promise<any>>(
     revalidate = 0,
     customKey,
     onCache,
+    getKey,
   } = options || {};
   const store = getLRUCache();
 
@@ -187,9 +189,9 @@ export function cache<T extends (...args: any[]) => Promise<any>>(
       if (request) {
         let shouldDisableCaching = false;
         if (cacheConfig.unstable_shouldDisable) {
-          shouldDisableCaching = await Promise.resolve(
-            cacheConfig.unstable_shouldDisable({ request }),
-          );
+          shouldDisableCaching = await cacheConfig.unstable_shouldDisable({
+            request,
+          });
         }
 
         if (shouldDisableCaching) {
@@ -225,7 +227,7 @@ export function cache<T extends (...args: any[]) => Promise<any>>(
         }
       }
     } else if (typeof options !== 'undefined') {
-      const genKey = generateKey(args);
+      const genKey = getKey ? getKey(...args) : generateKey(args);
       const now = Date.now();
 
       const cacheKey = getCacheKey(args, genKey);
@@ -246,9 +248,9 @@ export function cache<T extends (...args: any[]) => Promise<any>>(
         const storage = getAsyncLocalStorage();
         const request = storage?.useContext()?.request;
         if (request) {
-          shouldDisableCaching = await Promise.resolve(
-            cacheConfig.unstable_shouldDisable({ request }),
-          );
+          shouldDisableCaching = await cacheConfig.unstable_shouldDisable({
+            request,
+          });
         }
       }