@modern-js/main-doc 0.0.0-nightly-20250302160335 → 0.0.0-nightly-20250303160335

package/docs/en/guides/basic-features/data/_meta.json

@@ -1 +1 @@
-["data-fetch", "data-write"]
+["data-fetch", "data-write", "data-cache"]

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

@@ -0,0 +1,169 @@
+---
+title: Data Caching
+sidebar_position: 4
+---
+# Data Caching
+
+The `cache` function allows you to cache the results of data fetching or computation.
+
+## Basic Usage
+
+```ts
+import { cache } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(fetchUserData);
+
+const loader = async () => {
+  const user = await getUser(user); // When the parameters of the function changes, the function will be re-executed
+  return {
+    user,
+  };
+};
+```
+
+
+### Parameters
+
+- `fn`: The data fetching or computation function to be cached
+- `options` (optional): Cache configuration
+  - `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
+
+The type of the `options` parameter is as follows:
+
+```ts
+interface CacheOptions {
+  tag?: string | string[];
+  maxAge?: number;
+  revalidate?: number;
+}
+```
+
+
+### Return Value
+
+The `cache` function returns a new function with caching capabilities. Multiple calls to this function will not re-execute the `fn` function.
+
+## Usage Scope
+
+Unlike React's [cache](https://react.dev/reference/react/cache) function which can only be used in server components,
+EdenX's `cache` function can be used in any frontend or server-side code.
+
+## Detailed Usage
+
+### 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.
+
+:::info
+Without the `options` parameter, it can be considered a replacement for React's [`cache`](https://react.dev/reference/react/cache) function and can be used in any server-side code (such as in data loaders of SSR projects), not limited to server components.
+:::
+
+```ts
+import { cache } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(fetchUserData);
+
+const loader = async () => {
+  const user = await getUser();
+  return {
+    user,
+  };
+};
+```
+
+
+### With `options` Parameter
+
+#### `maxAge` Parameter
+
+After each computation, the framework records the time when the cache is written.
+When the function is called again, it checks if the cache has expired based on the `maxAge` parameter.
+If expired, the `fn` function is re-executed; otherwise, the cached data is returned.
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+
+const getDashboardStats = cache(
+  async () => {
+    return await fetchComplexStatistics();
+  },
+  {
+    maxAge: CacheTime.MINUTE * 2,  // Calling this function within 2 minutes will return cached data
+  }
+);
+```
+
+
+#### `revalidate` Parameter
+
+The `revalidate` parameter sets a time window for revalidating the cache after it expires. It can be used together with the `maxAge` parameter, similar to HTTP Cache-Control's stale-while-revalidate mode.
+
+In the following example, within the 2-minute period before the cache expires, calls to `getDashboardStats` will return cached data. If the cache has expired (between 2 and 3 minutes), requests will first return the old data, then refresh the data in the background and update the cache.
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+
+const getDashboardStats = cache(
+  async () => {
+    return await fetchComplexStatistics();
+  },
+  {
+    maxAge: CacheTime.MINUTE * 2,
+    revalidate: CacheTime.MINUTE * 1,
+  }
+);
+```
+
+
+#### `tag` Parameter
+
+The `tag` parameter identifies the cache with a tag, which can be a string or an array of strings.
+You can invalidate caches based on this tag, and multiple cache functions can use the same tag.
+
+```ts
+import { cache, revalidateTag } from '@modern-js/runtime/cache';
+
+const getDashboardStats = cache(
+  async () => {
+    return await fetchDashboardStats();
+  },
+  {
+    tag: 'dashboard',
+  }
+);
+
+const getComplexStatistics = cache(
+  async () => {
+    return await fetchComplexStatistics();
+  },
+  {
+    tag: 'dashboard',
+  }
+);
+
+revalidateTag('dashboard-stats'); // Invalidates the cache for both getDashboardStats and getComplexStatistics functions
+```
+
+
+### 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.
+
+:::info
+Considering that the results of `cache` function caching are not large, they are currently stored in memory by default.
+:::
+
+You can specify the storage limit using the `configureCache` function:
+
+```ts
+import { configureCache, CacheSize } from '@modern-js/runtime/cache';
+
+configureCache({
+  maxSize: CacheSize.MB * 10, // 10MB
+});
+```

package/docs/zh/guides/basic-features/data/_meta.json

@@ -1 +1 @@
-["data-fetch", "data-write"]
+["data-fetch", "data-write", "data-cache"]

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

@@ -0,0 +1,162 @@
+---
+title: 数据缓存
+sidebar_position: 4
+---
+# 数据缓存
+
+`cache` 函数可以让你缓存数据获取或计算的结果。
+
+## 基本用法
+
+```ts
+import { cache } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(fetchUserData);
+
+const loader = async () => {
+  const user = await getUser(user); // 函数入参发生变化时，函数会重新执行
+  return {
+    user,
+  };
+};
+```
+
+### 参数
+
+- `fn`: 需要缓存的数据获取或计算的函数
+- `options`（可选）: 缓存配置
+  - `tag`: 用于标识缓存的标签，可以基于这个标签使缓存失效
+  - `maxAge`: 缓存的有效期 (毫秒)
+  - `revalidate`: 重新验证缓存的时间窗口（毫秒），与 HTTP Cache-Control 的 stale-while-revalidate 功能一致
+
+`options` 参数的类型如下：
+
+```ts
+interface CacheOptions {
+  tag?: string | string[];
+  maxAge?: number;
+  revalidate?: number;
+}
+```
+
+### 返回值
+
+`cache` 函数会返回一个新的函数，该函数有缓存的能力，多次调用该函数，不会重复执行 `fn` 函数。
+
+## 使用范围
+
+与 react 的 [cache](https://react.dev/reference/react/cache) 函数只能在 server component 组件中使用不同，
+EdenX 提供的 `cache` 函数可以在任意的前端或服务端的代码中使用。
+
+## 详细用法
+
+### 无 `options` 参数
+
+当无 `options` 参数传入时，主要可以用于 SSR 项目，缓存的生命周期是单次 ssr 渲染的请求，如可以在多个 data loader 中调用同一个 cachedFn 时，不会重复执行 cachedFn 函数。这样可以在不同的 data loader 中共享数据，同时避免重复的请求，EdenX 会在每次收到服务端请求时，重新执行 `fn` 函数。
+
+:::info
+无 `options` 参数时，可以看作是 react [`cache`](https://react.dev/reference/react/cache) 函数的替代品，可以在任意服务端代码中使用（比如可以在 SSR 项目的 data loader 中），不局限于 server component。
+:::
+
+
+```ts
+import { cache } from '@modern-js/runtime/cache';
+import { fetchUserData } from './api';
+
+const getUser = cache(fetchUserData);
+
+const loader = async () => {
+  const user = await getUser();
+  return {
+    user,
+  };
+};
+```
+
+### 有 `options` 参数
+
+#### `maxAge` 参数
+
+每次计算完成后，框架会记录写入缓存的时间，当再次调用该函数时，会根据 `maxAge` 参数判断缓存是否过期，如果过期，则重新执行 `fn` 函数，否则返回缓存的数据。
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+
+const getDashboardStats = cache(
+  async () => {
+    return await fetchComplexStatistics();
+  },
+  {
+    maxAge: CacheTime.MINUTE * 2,  // 在 2 分钟内调用该函数会返回缓存的数据
+  }
+);
+```
+
+#### `revalidate` 参数
+
+`revalidate` 参数用于设置缓存过期后，重新验证缓存的时间窗口，可以和 `maxAge` 参数一起使用，类似与 HTTP Cache-Control 的 stale-while-revalidate 模式。
+
+
+如以下示例，在缓存未过期的 2分钟内，如果调用 `getDashboardStats` 函数，会返回缓存的数据，如果缓存过期，2分到3分钟内，收到的请求会先返回旧数据，然后后台会重新请求数据，并更新缓存。
+
+```ts
+import { cache, CacheTime } from '@modern-js/runtime/cache';
+
+const getDashboardStats = cache(
+  async () => {
+    return await fetchComplexStatistics();
+  },
+  {
+    maxAge: CacheTime.MINUTE * 2,
+    revalidate: CacheTime.MINUTE * 1,
+  }
+);
+```
+
+#### `tag` 参数
+
+`tag` 参数用于标识缓存的标签，可以传入一个字符串或字符串数组，可以基于这个标签使缓存失效，多个缓存函数可以使用一个标签。
+
+```ts
+import { cache, revalidateTag } from '@modern-js/runtime/cache';
+
+const getDashboardStats = cache(
+  async () => {
+    return await fetchDashboardStats();
+  },
+  {
+    tag: 'dashboard',
+  }
+);
+
+const getComplexStatistics = cache(
+  async () => {
+    return await fetchComplexStatistics();
+  },
+  {
+    tag: 'dashboard',
+  }
+);
+
+revalidateTag('dashboard-stats'); // 会使 getDashboardStats 函数和 getComplexStatistics 函数的缓存都失效
+```
+
+
+### 存储
+
+目前不管是客户端还是服务端，缓存都存储在内存中，默认情况下所有缓存函数共享的存储上限是 1GB，当达到存储上限后，使用 LRU 算法移除旧的缓存。
+
+:::info
+考虑到 `cache` 函数缓存的结果内容不会很大，所以目前默认都存储在内存中
+:::
+
+可以通过 `configureCache` 函数指定缓存的存储上限：
+
+```ts
+import { configureCache, CacheSize } from '@modern-js/runtime/cache';
+
+configureCache({
+  maxSize: CacheSize.MB * 10, // 10MB
+});
+```

package/package.json

@@ -15,14 +15,14 @@
     "modern",
     "modern.js"
   ],
-  "version": "0.0.0-nightly-20250302160335",
+  "version": "0.0.0-nightly-20250303160335",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "0.0.0-nightly-20250302160335"
+    "@modern-js/sandpack-react": "0.0.0-nightly-20250303160335"
   },
   "devDependencies": {
     "@rspress/shared": "1.42.0",