@modern-js/main-doc 2.68.1 → 2.68.2

package/docs/en/guides/basic-features/data/data-cache.mdx

@@ -74,7 +74,7 @@ EdenX's `cache` function can be used in any frontend or server-side code.
 
 ## Detailed Usage
 
-### Without `options` Parameter
+### Without options Parameter
 
 When no `options` parameter is provided, it's primarily useful in SSR projects, the cache lifecycle is limited to a single SSR rendering request. For example, when the same cachedFn is called in multiple data loaders, the cachedFn function won't be executed repeatedly. This allows data sharing between different data loaders while avoiding duplicate requests. EdenX will re-execute the `fn` function with each server request.
 
@@ -97,7 +97,7 @@ const loader = async () => {
 ```
 
 
-### With `options` Parameter
+### With options Parameter
 
 #### `maxAge` Parameter
 
@@ -166,13 +166,15 @@ const getComplexStatistics = cache(
   }
 );
 
-revalidateTag('dashboard'); // Invalidates the cache for both getDashboardStats and getComplexStatistics functions
+await revalidateTag('dashboard-stats'); // Invalidates the cache for both getDashboardStats and getComplexStatistics functions
 ```
 
 
 #### `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:
+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.
+
+Its return value becomes part of the final cache key, but the key is still combined with a unique function identifier, making the cache **function-scoped**.
 
 ```ts
 import { cache, CacheTime } from '@modern-js/runtime/cache';
@@ -238,7 +240,9 @@ 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:
+The `customKey` parameter is used to **fully customize** the cache key. It is a function that receives an object with the following properties and returns a string as the cache key.
+
+Its return value **directly becomes** the final cache key, **overriding** the default combination of a function identifier and parameter-based key. This allows you to create **globally unique** keys and share cache across different functions.
 
 - `params`: Array of arguments passed to the cached function
 - `fn`: Reference to the original function being cached
@@ -247,16 +251,15 @@ The `customKey` parameter is used to customize the cache key. It is a function t
 :::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
+1. The function's input parameters change
+2. The maxAge condition is no longer satisfied
+3. 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`.
+By default, the framework generates a stable function ID based on the function's string representation and combines it with the generated parameter key. `customKey` can be used when you need complete control over the cache key generation, especially useful for sharing cache across different function instances. If you just need to customize how parameters are converted to cache keys, 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.
+This is very useful in some scenarios, such as when you want to share cache across different function instances or when you need predictable cache keys for external cache management.
 
 ```ts
 import { cache } from '@modern-js/runtime/cache';
@@ -287,21 +290,26 @@ const getUserB = cache(
   }
 );
 
-// You can also use Symbol as a cache key (usually used to share cache within the same application)
-const USER_CACHE_KEY = Symbol('user-cache');
+// Now you can share cache across different function implementations
+await getUserA(123); // Fetches data and caches with key "user-123"
+await getUserB(123); // Cache hit, returns cached data
+
+// You can utilize the generatedKey parameter to modify the default key
 const getUserC = cache(
   fetchUserData,
   {
-    maxAge: CacheTime.MINUTE * 5,
-    customKey: () => USER_CACHE_KEY,
+    customKey: ({ generatedKey }) => `prefix-${generatedKey}`,
   }
 );
 
-// You can utilize the generatedKey parameter to modify the default key
+// For predictable cache keys that can be managed externally
 const getUserD = cache(
-  fetchUserData,
+  async (userId: string) => {
+    return await fetchUserData(userId);
+  },
   {
-    customKey: ({ generatedKey }) => `prefix-${generatedKey}`,
+    maxAge: CacheTime.MINUTE * 5,
+    customKey: ({ params }) => `app:user:${params[0]}`,
   }
 );
 ```
@@ -370,6 +378,8 @@ The `onCache` callback is useful for:
 
 ### Storage
 
+#### Default Storage
+
 Currently, both client and server caches are stored in memory.
 The default storage limit for all cached functions is 1GB. When this limit is reached, the oldest cache is removed using an LRU algorithm.
 
@@ -386,3 +396,132 @@ configureCache({
   maxSize: CacheSize.MB * 10, // 10MB
 });
 ```
+
+#### Custom Storage Container
+
+In addition to the default memory storage, you can use custom storage containers such as Redis, file systems, databases, etc. This enables cache sharing across processes and servers.
+
+##### Container Interface
+
+Custom storage containers need to implement the `Container` interface:
+
+```ts
+interface Container {
+  get: (key: string) => Promise<string | undefined | null>;
+  set: (key: string, value: string, options?: { ttl?: number }) => Promise<any>;
+  has: (key: string) => Promise<boolean>;
+  delete: (key: string) => Promise<boolean>;
+  clear: () => Promise<void>;
+}
+```
+
+##### Basic Usage
+
+```ts
+import { configureCache } from '@modern-js/runtime/cache';
+
+// Use custom storage container
+configureCache({
+  container: customContainer,
+});
+```
+
+##### Using `customKey` to Ensure Cache Key Stability
+
+:::note
+
+When using custom storage containers (such as Redis), **it's recommended to configure `customKey`** to ensure cache key stability. This ensures:
+
+1. **Cross-process sharing**: Different server instances can share the same cache
+2. **Cache validity after application restart**: Cache remains valid after restarting the application
+3. **Cache persistence after code deployment**: Cache for the same logic remains effective after code updates
+
+:::
+
+The default cache key generation mechanism is based on function references, which may not be stable enough in distributed environments. It's recommended to use `customKey` to provide stable cache keys:
+
+```ts
+import { cache, configureCache } from '@modern-js/runtime/cache';
+
+// Configure Redis container
+configureCache({
+  container: redisContainer,
+});
+
+// Recommended: Use customKey to ensure key stability
+const getUser = cache(
+  async (userId: string) => {
+    return await fetchUserData(userId);
+  },
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    // Use stable identifiers related to the cached function as cache keys
+    customKey: () => `fetchUserData`,
+  }
+);
+```
+
+##### Redis Storage Example
+
+Here's an example of using Redis as a storage backend:
+
+```ts
+import { Redis } from 'ioredis';
+import { Container, configureCache } from '@modern-js/runtime/cache';
+
+class RedisContainer implements Container {
+  private client: Redis;
+
+  constructor(client: Redis) {
+    this.client = client;
+  }
+
+  async get(key: string): Promise<string | null> {
+    const value = await this.redis.get(key);
+    return value ? JSON.parse(value) : null;
+  }
+
+  async set(
+    key: string,
+    value: string,
+    options?: { ttl?: number },
+  ): Promise<'OK'> {
+    if (options?.ttl) {
+      return this.client.set(key, JSON.stringify(value), 'EX', options.ttl);
+    }
+    return this.client.set(key, JSON.stringify(value));
+  }
+
+  async has(key: string): Promise<boolean> {
+    const result = await this.client.exists(key);
+    return result === 1;
+  }
+
+  async delete(key: string): Promise<boolean> {
+    const result = await this.client.del(key);
+    return result > 0;
+  }
+
+  async clear(): Promise<void> {
+    // Be cautious with this in production. It will clear the entire Redis database.
+    // A more robust implementation might use a key prefix and delete keys matching that prefix.
+    await this.client.flushdb();
+  }
+}
+
+// Configure Redis storage
+const redisClient = new Redis({
+  host: 'localhost',
+  port: 6379,
+});
+
+configureCache({
+  container: new RedisContainer(redisClient),
+});
+```
+
+##### Important Notes
+
+1. **Serialization**: All cached data will be serialized to strings for storage. The container only needs to handle string get/set operations.
+
+2. **TTL Support**: If your storage backend supports TTL (Time To Live), you can use the `options.ttl` parameter in the `set` method (in seconds).

package/docs/zh/guides/basic-features/data/data-cache.mdx

@@ -159,12 +159,14 @@ const getComplexStatistics = cache(
   }
 );
 
-revalidateTag('dashboard'); // 会使 getDashboardStats 函数和 getComplexStatistics 函数的缓存都失效
+await revalidateTag('dashboard-stats'); // 会使 getDashboardStats 函数和 getComplexStatistics 函数的缓存都失效
 ```
 
 #### `getKey` 参数
 
-`getKey` 参数用于自定义缓存键的生成方式，例如你可能只需要依赖函数参数的一部分来区分缓存。它是一个函数，接收与原始函数相同的参数，返回一个字符串作为缓存键：
+`getKey` 参数用于**简化**缓存键的生成方式，例如你可能只需要依赖函数参数的一部分来区分缓存。它是一个函数，接收与原始函数相同的参数，返回一个字符串。
+
+它的返回值会作为参数部分参与最终缓存键的生成，但最终的键仍然会包含函数的唯一标识，因此缓存是**函数级别**的。
 
 ```ts
 import { cache, CacheTime } from '@modern-js/runtime/cache';
@@ -216,7 +218,9 @@ const getUser = cache(
 
 #### `customKey` 参数
 
-`customKey` 参数用于定制缓存的键，它是一个函数，接收一个包含以下属性的对象，返回值必须是字符串或 Symbol 类型，将作为缓存的键：
+`customKey` 参数用于**完全定制**缓存的键，它是一个函数，接收一个包含以下属性的对象，返回值必须是字符串类型。
+
+它的返回值将**直接**作为最终的缓存键，**覆盖**了默认的函数标识和参数组合。这允许你创建**全局唯一**的缓存键，从而实现跨函数共享缓存。
 
 - `params`：调用缓存函数时传入的参数数组
 - `fn`：原始被缓存的函数引用
@@ -225,16 +229,15 @@ const getUser = cache(
 :::info
 
 一般在以下场景，缓存会失效：
-1. 缓存的函数引用发生变化
-2. 函数的入参发生变化
-3. 不满足 maxAge
-4. 调用了 `revalidateTag`
+1. 函数的入参发生变化
+2. 不满足 maxAge 条件
+3. 调用了 `revalidateTag`
 
-`customKey` 可以用在函数引用不同，但希望共享缓存的场景，如果只是自定义缓存键，推荐使用 `getKey`
+默认情况下，框架会基于函数的字符串表示生成稳定的函数 ID，并与生成的参数键组合。`customKey` 可以用于完全控制缓存键的生成，特别适用于在不同函数实例间共享缓存。如果只是需要自定义参数如何转换为缓存键，推荐使用 `getKey`。
 
 :::
 
-这在某些场景下非常有用，比如当函数引用发生变化时，但你希望仍然返回缓存的数据。
+这在某些场景下非常有用，比如当你希望在不同函数实例间共享缓存，或者需要可预测的缓存键用于外部缓存管理时。
 
 ```ts
 import { cache } from '@modern-js/runtime/cache';
@@ -264,26 +267,26 @@ const getUserB = cache(
   }
 );
 
-// 即使 getUserA 和 getUserB 是不同的函数引用，但由于它们的 customKey 返回相同的值
-// 所以当调用参数相同时，它们会共享缓存
-const dataA = await getUserA(1);
-const dataB = await getUserB(1); // 这里会命中缓存，不会再次发起请求
+// 现在你可以在不同的函数实现间共享缓存
+await getUserA(123); // 获取数据并使用键 "user-123" 缓存
+await getUserB(123); // 缓存命中，返回缓存的数据
 
-// 也可以使用 Symbol 作为缓存键（通常用于共享同一个应用内的缓存）
-const USER_CACHE_KEY = Symbol('user-cache');
+// 可以利用 generatedKey 参数在默认键的基础上进行修改
 const getUserC = cache(
   fetchUserData,
   {
-    maxAge: CacheTime.MINUTE * 5,
-    customKey: () => USER_CACHE_KEY,
+    customKey: ({ generatedKey }) => `prefix-${generatedKey}`,
   }
 );
 
-// 可以利用 generatedKey 参数在默认键的基础上进行修改
+// 用于可预测的缓存键，便于外部管理
 const getUserD = cache(
-  fetchUserData,
+  async (userId: string) => {
+    return await fetchUserData(userId);
+  },
   {
-    customKey: ({ generatedKey }) => `prefix-${generatedKey}`,
+    maxAge: CacheTime.MINUTE * 5,
+    customKey: ({ params }) => `app:user:${params[0]}`,
   }
 );
 ```
@@ -352,6 +355,8 @@ await getUser(2); // 缓存未命中
 
 ### 存储
 
+#### 默认存储
+
 目前不管是客户端还是服务端，缓存都存储在内存中，默认情况下所有缓存函数共享的存储上限是 1GB，当达到存储上限后，使用 LRU 算法移除旧的缓存。
 
 :::info
@@ -368,3 +373,130 @@ configureCache({
 });
 ```
 
+#### 自定义存储器
+
+除了默认的内存存储，你还可以使用自定义的存储容器，例如 Redis、文件系统、数据库等。这样可以实现跨进程、跨服务器的缓存共享。
+
+##### Container 接口
+
+自定义存储容器需要实现 `Container` 接口：
+
+```ts
+interface Container {
+  get: (key: string) => Promise<string | undefined | null>;
+  set: (key: string, value: string, options?: { ttl?: number }) => Promise<any>;
+  has: (key: string) => Promise<boolean>;
+  delete: (key: string) => Promise<boolean>;
+  clear: () => Promise<void>;
+}
+```
+
+##### 基本使用
+
+```ts
+import { configureCache } from '@modern-js/runtime/cache';
+
+// 使用自定义存储容器
+configureCache({
+  container: customContainer,
+});
+```
+
+##### 使用 `customKey` 确保缓存键稳定性
+
+:::warning 重要建议
+当使用自定义存储容器（如 Redis）时，**建议配置 `customKey`** 来确保缓存键的稳定性。这样可以确保：
+
+1. **跨进程共享**：不同服务器实例能够共享相同的缓存
+2. **应用重启后缓存有效**：重启应用后仍能命中之前的缓存
+3. **代码部署后缓存保持**：代码更新后相同逻辑的缓存仍然有效
+:::
+
+默认的缓存键生成机制基于函数引用，在分布式环境中可能不够稳定。建议使用 `customKey` 提供稳定的缓存键：
+
+```ts
+import { cache, configureCache } from '@modern-js/runtime/cache';
+
+// 配置 Redis 容器
+configureCache({
+  container: redisContainer,
+});
+
+// 推荐：使用 customKey 确保键的稳定性
+const getUser = cache(
+  async (userId: string) => {
+    return await fetchUserData(userId);
+  },
+  {
+    maxAge: CacheTime.MINUTE * 5,
+    // 使用被缓存函数相关的稳定标识符作为缓存键
+    customKey: () => `fetchUserData`,
+  }
+);
+```
+
+##### Redis 存储示例
+
+以下是一个使用 Redis 作为存储后端的示例：
+
+```ts
+import { Redis } from 'ioredis';
+import { Container, configureCache } from '@modern-js/runtime/cache';
+
+class RedisContainer implements Container {
+  private client: Redis;
+
+  constructor(client: Redis) {
+    this.client = client;
+  }
+
+  async get(key: string): Promise<string | null> {
+    const value = await this.redis.get(key);
+    return value ? JSON.parse(value) : null;
+  }
+
+  async set(
+    key: string,
+    value: string,
+    options?: { ttl?: number },
+  ): Promise<'OK'> {
+    if (options?.ttl) {
+      return this.client.set(key, JSON.stringify(value), 'EX', options.ttl);
+    }
+    return this.client.set(key, JSON.stringify(value));
+  }
+
+  async has(key: string): Promise<boolean> {
+    const result = await this.client.exists(key);
+    return result === 1;
+  }
+
+  async delete(key: string): Promise<boolean> {
+    const result = await this.client.del(key);
+    return result > 0;
+  }
+
+  async clear(): Promise<void> {
+    // 注意：在生产环境中要谨慎使用，这会清空整个 Redis 数据库
+    // 更好的实现方式是使用键前缀，然后删除匹配该前缀的所有键
+    await this.client.flushdb();
+  }
+}
+
+// 配置 Redis 存储
+const redisClient = new Redis({
+  host: 'localhost',
+  port: 6379,
+});
+
+configureCache({
+  container: new RedisContainer(redisClient),
+});
+```
+
+##### 注意事项
+
+1. **序列化**：所有的缓存数据都会被序列化为字符串存储，容器只需要处理字符串的存取操作。
+
+2. **TTL 支持**：如果你的存储后端支持 TTL（生存时间），可以在 `set` 方法中使用 `options.ttl` 参数（单位为秒）。
+

package/package.json

@@ -15,14 +15,14 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.68.1",
+  "version": "2.68.2",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.4.1",
-    "@modern-js/sandpack-react": "2.68.1"
+    "@modern-js/sandpack-react": "2.68.2"
   },
   "devDependencies": {
     "@rsbuild/plugin-sass": "1.3.3",