@modern-js/main-doc 0.0.0-nightly-20250506160336 → 0.0.0-nightly-20250508160349

package/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

package/docs/en/guides/basic-features/deploy.mdx

@@ -136,13 +136,14 @@ Full-stack projects refer to projects that use Custom Web Server, SSR or BFF. Th
 :::info
 1. Currently, Modern.js does not support deployment on Netlify Edge Functions. We will support it in future versions.
 2. You can refer to the [deployment project example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-ssr).
+
 :::
 
 
 ### Monorepo
 
 :::info
-The following guide is mainly for full-stack projects, for pure CSR projects, just follow [Pure Frontend Project](#Pure Frontend Project) to deploy.
+The following guide is mainly for full-stack projects, for pure CSR projects, just follow [Pure Frontend Project](#pure-front-end-project-1) to deploy.
 :::
 
 For Monorepo projects, in addition to building our current project, you also need to build other sub-projects in the repository that the current project depends on.
@@ -330,6 +331,7 @@ For branch deployment, follow these steps:
 :::info
 1. Running `MODERNJS_DEPLOY=ghPages modern deploy` will build the production output for GitHub in the .output directory.
 2. You can refer to the [project](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)
+
 :::
 
 For GitHub Actions deployment, select Settings > Pages > Source > GitHub Actions, and add a workflow file to the project. You can refer to the [example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr).

package/docs/en/guides/get-started/quick-start.mdx

@@ -148,7 +148,7 @@ info    Starting production server...
   > Network:  http://192.168.0.1:8080/
 ```
 
-Open `http://localhost:8000/` in the browser, and the content should be consistent with that of `pnpm run dev`.
+Open `http://localhost:8080/` in the browser, and the content should be consistent with that of `pnpm run dev`.
 
 ## Deployment
 

package/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` 回调对以下场景非常有用：
 - 监控缓存性能

package/package.json

@@ -15,14 +15,14 @@
     "modern",
     "modern.js"
   ],
-  "version": "0.0.0-nightly-20250506160336",
+  "version": "0.0.0-nightly-20250508160349",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.4.1",
-    "@modern-js/sandpack-react": "0.0.0-nightly-20250506160336"
+    "@modern-js/sandpack-react": "0.0.0-nightly-20250508160349"
   },
   "devDependencies": {
     "@rspress/shared": "1.43.11",