@modern-js/main-doc 2.1.0 → 2.3.0

package/en/guides/topic-detail/model/manage-effects.mdx

@@ -0,0 +1,260 @@
+---
+sidebar_position: 5
+title: 副作用管理
+---
+# 副作用管理
+
+Model 中的 Action 必须是一个纯函数，执行过程中不会产生任何副作用。但在真实的业务中，我们会遇到很多副作用场景，如：请求 HTTP 接口获取状态数据，或者在更新状态的同时修改 localStorage、发送事件等。在 Reduck 中，是通过 Model 的 Effects 函数管理副作用的。
+
+## 副作用对 State 修改
+
+副作用修改 State，最常见的场景就是请求 HTTP 接口，更新状态数据。
+
+我们以一个简单的 `todoModel` 为例。其有一个 `load` 的副作用函数，请求远端的 TODO 列表，请求成功之后更新 `state.items` 字段。
+
+```ts
+const todoModel = model('todo').define({
+  state: {
+    items: [],
+    loading: false,
+    error: null,
+  },
+  actions: {
+    load: {
+      pending(state) {
+        state.loading = true;
+      },
+      fulfilled(state, items) {
+        state.items = items;
+        state.loading = false;
+      },
+      rejected(state, error) {
+        state.error = error;
+        state.loading = false;
+      },
+    },
+  },
+  effects: {
+    // Promise 副作用
+    async load() {
+      return new Promise(resolve => {
+        setTimeout(() => resolve(['Learn Modern.js']), 2000);
+      });
+    },
+  },
+});
+```
+
+副作用函数统一定义在 `effects` 字段下。这里我们写了一个 `load` 函数，它返回一个 Promise，Promise 执行成功后，返回 TODO 列表 `["Lerna Modern.js"]`。
+
+副作用函数需要和 actions 配合使用，才能完成状态的修改。因此，我们在 `actions` 中定义了一个 `load`（命名需要和 `effects` 下的副作用函数的名字保持一致）对象，包含 `pending`、`fulfilled`、`rejected` 3 个 action，分别是对副作用函数 `load` 返回的 `Promise` 的三种状态（ pending、fulfilled、rejected ）的处理：
+
+- `pending`：接收当前状态 `state` 作为参数，新的状态中 `loading` 设为 `true`。
+- `fulfilled`：接收当前状态 `state` 和 Promise fulfilled 状态的值 `items` 为参数，新的状态中 `items` 等于参数 `items`、`loading` 设为 `false`。
+- `rejected`：接收当前状态 `state` 和 Promise rejected 状态的错误 `error` 为参数，新的状态中 `error` 等于参数 `error`、`loading` 设为 `false`。
+
+组件中如何调用 effects 函数呢？ effects 函数会被合并到 actions 对象上，因此可以通过 actions 对象调用 effects 函数，如下所示：
+
+```ts
+function Todo() {
+  const [state, actions] = useModel(todoModel);
+
+  useEffect(() => {
+    // 调用 effects 函数
+    actions.load();
+  }, []);
+
+  if (state.loading) {
+    return <div>loading....</div>;
+  }
+
+  return (
+    <div>
+      <div>
+        {state.items.map((item, index) => (
+          <div key={index}>{item}</div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+上面的示例中， `pending`、`fulfilled`、`rejected` 3 个 action，对于用于获取数据的 HTTP 请求场景下，一般都是需要的。Reduck 提供了一个工具函数 `handleEffect`，用于简化这种场景下的 action 创建。
+
+`handleEffect` 约定这种副作用场景下， Model 的 State 结构包含 `result`、`error`、`pending` 3 个字段，初始值为：
+
+```ts
+{
+  result: null,
+  error: null,
+  pending: false，
+}
+```
+
+调用 `handleEffect` 会返回如下数据结构:
+
+```ts
+{
+  pending() { // ... },
+  fulfilled() { // ... },
+  rejected() { // ... }
+}
+```
+
+这个数据结构和我们在 `actions` 下的 `load` 对象的数据结构是相同的。`handleEffect` 返回的对象，其实就是对应了 Effects 函数需要的 3 个 action。
+
+利用 `handleEffect`，改写 `todoModel`：
+
+```ts
+const todoModel = model('todo').define({
+  state: {
+    items: [],
+    loading: false,
+    error: null,
+  },
+  actions: {
+    load: handleEffect({ result: 'items' }),
+  },
+  effects: {
+    // Promise 副作用
+    async load() {
+      return new Promise(resolve => {
+        setTimeout(() => resolve(['Learn Modern.js']), 2000);
+      });
+    },
+  },
+});
+```
+
+`handleEffect` 接收的参数对象，将 `result` 设置为 `item`。因为 `todoModel` 的 state，使用 `items` 作为 key 保存 todo 列表数据，而不是使用 `handleEffect` 默认的 `result` 作为 key，所以这里需要进行配置。
+
+明显可见，通过 `handleEffect` 实现的 `todoModel` 比之前的实现有了很大精简。
+
+如果不希望 pending、fulfilled、rejected 3 种状态都被 `handleEffect` 自动处理，例如 fulfilled 需要手动处理较复杂的数据类型，但是 pending、rejected 依旧想进行自动化处理，可以参考如下写法：
+
+```ts
+  actions: {
+    load: {
+      ...handleEffect(),
+      fulfilled(state, payload) {
+        // 手动处理
+      },
+    },
+  },
+```
+
+:::info 补充信息
+`handleEffect` [API](/apis/app/runtime/model/handle-effect)。
+
+:::
+
+Effects 函数中，也支持手动调用 Actions，例如：
+
+```ts
+const todoModel = model('todo').define((context, utils) => ({
+  state: {
+    items: [],
+    loading: false,
+    error: null,
+  },
+  actions: {
+    pending(state) {
+      state.loading = true;
+    },
+    fulfilled(state, items) {
+      state.items = items;
+      state.loading = false;
+    },
+  },
+  effects: {
+    async load() {
+      // 通过 utils.use 获取当前 Model 对象的 actions
+      const [, actions] = utils.use(todoModel);
+      // 手动调用 action
+      actions.pending();
+
+      return new Promise(resolve => {
+        setTimeout(() => {
+          const items = ['Learn Modern.js'];
+          // 手动调用 action
+          actions.fulfilled(items);
+          resolve(items);
+        }, 2000);
+      });
+    },
+  },
+}));
+```
+
+:::info 注
+可以使用 `use` 函数加载其它 Model（包括 Model 自身），实现 [Model 间通信](/guides/topic-detail/model/model-communicate)。
+
+:::
+
+## 副作用不影响 state
+
+有些场景下，我们只需要读取 State，执行相关副作用逻辑，副作用不会修改 State。
+
+例如，存储某些 State 到 `localStorage`：
+
+```ts
+const fooModel = model('foo').define((context, utils) => ({
+  state: {
+    value: 'foo',
+  },
+  effects: {
+    setLocalStorage(key) {
+      const [state] = utils.use(fooModel);
+      localStorage.set(key, state.value);
+      return 'success';
+    },
+  },
+}));
+```
+
+或者是向服务端发送数据：
+
+```ts
+const fooModel = model('foo').define({
+  state: {
+    value: 'foo',
+  },
+  effects: {
+    async sendData(data) {
+      const res = await fetch('url', {
+        method: 'POST',
+        body: data,
+      });
+      return res.json();
+    },
+  },
+});
+```
+
+## 副作用函数返回值
+
+有时候，我们希望能根据副作用函数的执行结果，直接执行后续逻辑。这时候，就需要使用 Effects 函数的返回。
+
+例如，当点击发送按钮，发送数据成功后，立即关闭当前的弹窗；如果失败，显示错误信息。我们可以通过如下代码实现：
+
+```ts
+// 代码仅做示意，不能执行
+// 组件内部 发送按钮 的响应函数
+const handleClick = async () => {
+  // sendData 返回代表状态的字符串
+  const result = await actions.sendData('some data');
+  if (result === 'success') {
+    // 关闭弹窗
+    closeModal();
+  } else {
+    // 显示错误
+    showError(result);
+  }
+};
+```
+
+:::info 补充信息
+[示例代码](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/effects)
+
+:::

package/en/guides/topic-detail/model/model-communicate.mdx

@@ -0,0 +1,220 @@
+---
+sidebar_position: 7
+title: Model 通信
+---
+# Model 通信
+
+Model 通信，既指不同 Model 间的通信，也指同一个 Model 内部 Effects、Actions 之间的通信。
+
+## Model 间通信
+
+Model 之间不是孤立的，是可以进行通信的。主要分为两种场景：
+
+1. 在 Model 中访问其它 Model 的 State 和 Actions。
+2. 在 Model 中监听其它 Model 变化。
+
+这里将 [快速上手](/guides/topic-detail/model/quick-start) 一节的简单计数器应用改造成一个可设置步频的计数器应用。可以通过设置步频，从而影响每次计数器增加的幅度。
+
+我们抽象出两个 Model，分别为 `stepModel`（步频）、`counterModel`（计数器）：
+
+```ts
+import { model } from '@modern-js/runtime/model';
+
+const stepModel = model('step').define({
+  state: 1,
+});
+
+const counterModel = model('count').define((context, { use, onMount }) => {
+  const [, , subscribeStep] = use(stepModel);
+
+  onMount(() => {
+    return subscribeStep(() => {
+      console.log(
+        `Subscribe in counterModel: stepModel change to ${use(stepModel)[0]}`,
+      );
+    });
+  });
+
+  return {
+    state: {
+      value: 1,
+    },
+    actions: {
+      add(state) {
+        const step = use(stepModel)[0];
+        state.value += step;
+      },
+    },
+  };
+});
+
+export { stepModel, counterModel };
+```
+
+`stepModel` 只声明一个 `state`，初始值为 1。
+
+`counterModel` 通过 `use` 函数加载 `stepModel`，拿到返回的 `subscribeStep` 函数，用来监听 `stepModel` 状态的变更。 `onMount` 是 Model 挂载完成后的钩子函数，`counterModel` 挂载完成后开始订阅 `stepModel` 状态的变更，打印出 `stepModel` 的最新值。
+
+`counterModel` 通过 `use` 函数访问 `stepModel`，在 `add` 里可以获取到当前 `stepModel` 的值（步频），以此值来做自增。
+
+:::caution 注意
+当需要访问其他 Model 的 State 时，必须要在当前 Actions 或 Effects 函数（本例中对应 `add` 函数 ）真正执行的阶段调用 `use`，以保证获取的 State 是最新值。因此，我们虽然在 `define` 的回调函数中也调用了 `use(stepModel)`，但是我们并没有解构 `stepModel` 的 `state` 值，因为 `define` 的回调函数是在 Model 的挂载阶段执行的，这个时候获取到的 `stepModel` 的 `state` 可能和 `add` 执行时获取到的值是不同的。
+
+:::
+
+修改 **App.tsx**
+
+```tsx
+import { useModel } from '@modern-js/runtime/model';
+import { counterModel, stepModel } from './models/count';
+
+function Counter() {
+  const [state, actions] = useModel(counterModel);
+  const [step, stepActions] = useModel(stepModel);
+
+  return (
+    <div>
+      <div>step: {step}</div>
+      <button onClick={() => stepActions.setState(step + 1)}>add step</button>
+      <div>counter: {state.value}</div>
+      <button onClick={() => actions.add()}>add counter</button>
+    </div>
+  );
+}
+
+export default function App() {
+  return <Counter />;
+}
+```
+
+:::info 补充信息
+Modern.js 默认开启 [自动生成 actions](./auto-actions.md)，所以 `stepModel` 中虽然没有手动定义 Actions，但可以使用自动生成的 `setState`。
+
+:::
+
+- 点击 **add step** 增加步频。
+- 点击 **add counter** 触发计数器增加。
+
+最终效果如下：
+
+![communicate-models](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/models-communicate.gif)
+
+:::info 补充信息
+- 本节完整的[示例代码](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/models-communication)。
+- 相关 API 的更多介绍，请参考：[model](/apis/app/runtime/model/model_#函数类型)。
+
+:::
+
+前面 `counterModel` 的例子，我们是在 Actions 的函数内部调用 `use` 获取其他 Model 对象的。如果只需要调用其它 Model 的 Actions，因为 Actions 都是函数，不存在值过期问题，所以也可以在 `define` 的回调函数中调用 `use` 获取 Model 的 Actions。例如：
+
+```ts
+const barModel = model('bar').define({
+  // 省略
+});
+
+const fooModel = model('foo').define((context, utils) => {
+  // 获取 barModel 的 actions
+  const [, actions] = utils.use(barModel);
+  return {
+    // 省略 state、actions
+    effects: {
+      async loadA() {
+        // 省略副作用逻辑
+        // 调用 barModel 的 action
+        barModel.actionA();
+      },
+      async loadB() {
+        // 省略副作用逻辑
+        // 调用 barModel 的 action
+        barModel.actionB();
+      },
+    },
+  };
+});
+```
+
+这样，我们不需要在 `loadA`、`loadB` 中重复获取 `barModel` 对象，简化了代码逻辑。
+
+## Model 内通信
+
+Model 内通信，也主要分为两种场景：
+
+1. Effects 函数调用自身 Model 的 Actions 函数、或其他 Effects 函数。
+2. Actions 函数调用自身 Model 的 其他 Actions 函数。
+
+在 [副作用管理](/guides/topic-detail/model/manage-effects) 一节，我们演示过 Effects 函数如何调用 Actions 函数。
+
+这里我们再来举一个例子：
+
+```ts
+const fooModel = model('foo').define((context, { use, onMount }) => ({
+  state: {
+    a: '',
+    b: '',
+  },
+  actions: {
+    setA(state, payload) {
+      state.a = payload;
+    },
+    setB(state, payload) {
+      state.a = payload;
+    },
+  },
+  effects: {
+    async loadA() {
+      // 通过 use 获取当前 Model 的 actions
+      const [, actions] = use(fooModel);
+      const res = await mockFetchA();
+      actions.setA(res);
+    },
+    async loadB() {
+      // 通过 use 获取当前 Model 的 actions
+      const [, actions] = use(fooModel);
+      const res = await mockFetchB();
+      actions.setB(res);
+    },
+  },
+}));
+```
+
+这个例子中，`fooModel` 的两个 Effects 函数，需要调用自身的 Actions 函数。这里我们在每个 Effects 函数中，都调用了一次 `use`，为什么不能像 Model 间通信的例子中，在 `define` 的回调函数中，统一调用 `use` 获取 Model 自身的 Actions 呢？这是因为调用 `use` 获取 Model 时，会先检查这个 Model 是否已经挂载，如果还没有挂载，会先执行挂载逻辑，而 `define` 的回调函数又是在 Model 的挂载阶段执行的，这样一来，在挂载阶段调用 `use` 获取 Model 自身，会出现死循环（代码实际执行过程会抛出错误）。所以，**一定不能在 `define` 的回调函数中，调用 `use` 获取 Model 自身对象。**
+
+不过，我们可以利用 `onMount` 这个钩子函数，在 Model 挂载完成后，再通过 `use` 获取 Model 自身对象：
+
+```ts
+const fooModel = model('foo').define((context, { use, onMount }) => {
+  let actions;
+
+  onMount(() => {
+    // fooModel 挂载完成后，通过 use 获取当前 Model 的 actions
+    [, actions] = use(fooModel);
+  });
+
+  return {
+    state: {
+      a: '',
+      b: '',
+    },
+    actions: {
+      setA(state, payload) {
+        state.a = payload;
+      },
+      setB(state, payload) {
+        state.a = payload;
+      },
+    },
+    effects: {
+      async loadA() {
+        const res = await mockFetchA();
+        actions.setA(res);
+      },
+      async loadB() {
+        const res = await mockFetchB();
+        actions.setB(res);
+      },
+    },
+  };
+});
+```
+
+这样，我们也可以实现代码的简化。

package/en/guides/topic-detail/model/performance.mdx

@@ -0,0 +1,171 @@
+---
+sidebar_position: 8
+title: 性能优化
+---
+# 性能优化
+
+Reduck 内部已经做了大量性能优化工作，一般情况下不需要考虑性能问题。不过当对性能比较敏感、或者遇到了性能问题，可以考虑从以下 3 个方面，进行更有针对性的性能优化。
+
+## Model 拆分
+
+当 `useModel` 返回 Model 对象的完整 State 时，State 任意部分的变化都会导致调用了 `useModel` 的组件重新渲染。
+
+例如：
+
+```ts
+const fooModel = model('foo').define({
+  state: {
+    a: '',
+    b: '',
+  },
+  actions: {
+    setA(state, payload) {
+      state.a = payload;
+    },
+    setB(state, payload) {
+      state.b = payload;
+    },
+  },
+});
+
+function ComponentA() {
+  const [state] = useModel(fooModel);
+
+  return <div>{state.a}</div>;
+}
+```
+
+组件 `ComponentA` 虽然只需要使用 `a` 状态，但当 `b` 状态发送变化时， `ComponentA` 仍然会重新渲染。这种情况，我们可以考虑把 `fooModel` 拆分，`a`、`b` 分别由不同的 Model 负责管理：
+
+```ts
+const fooModel = model('foo').define({
+  state: {
+    a: '',
+  },
+  actions: {
+    setA(state, payload) {
+      state.a = payload;
+    },
+  },
+});
+
+const barModel = model('bar').define({
+  state: {
+    b: '',
+  },
+  actions: {
+    setB(state, payload) {
+      state.b = payload;
+    },
+  },
+});
+```
+
+## 状态筛选
+
+`useModel` 支持传入 selector 函数，对返回给组件的 State 和 Actions 做筛选。我们可以通过 selector 函数，确保返回给组件的 State 是组件直接需要使用的，从而保证组件不会因为其他无关状态的变化而重新渲染。
+
+对于上面同样的例子，我们采用 selector 函数进行性能优化，代码如下：
+
+```ts
+const fooModel = model('foo').define({
+  state: {
+    a: '',
+    b: '',
+  },
+  actions: {
+    setA(state, payload) {
+      state.a = payload;
+    },
+    setB(state, payload) {
+      state.b = payload;
+    },
+  },
+});
+
+function ComponentA() {
+  // 通过传入 selector 函数，只返回 a 状态给组件
+  const [stateA] = useModel(fooModel, state => state.a);
+
+  return <div>{stateA}</div>;
+}
+```
+
+## 衍生状态缓存
+
+当 Model 存在 `computed` 时，每次调用`useModel` 都会执行 `computed` 函数。
+
+考虑如下代码：
+
+```ts
+const barModel = model('bar').define({
+  state: {
+    value: 'bar',
+  },
+  computed: {
+    combineA: [
+      fooModel, // fooModel 定义同上
+      (state, fooState) => {
+        return state + fooState.a;
+      },
+    ],
+  },
+  actions: {
+    setValue(state, payload) {
+      state.value = payload;
+    },
+  },
+});
+
+function ComponentB() {
+  const [state, actions] = useModel(fooModel);
+  const [{ combineA }] = useModel(barModel);
+  // 省略
+}
+```
+
+`barModel` 的衍生状态 `combineA` 依赖 `barModel` 自身状态 和 `fooModel` 的状态 `a`，但是即使是 `fooModel` 的状态 `b` 发生了变化，组件重新渲染时， `combineA` （更准确的说法是 `combineA` 的最后一个函数类型的元素 ）依然会被调用执行。
+
+一般情况下，`computed` 函数中的逻辑都是非常轻量的，但当 `computed` 函数逻辑比较复杂时，我们可以考虑对计算逻辑做缓存。例如，我们使用 [reselect](https://github.com/reduxjs/reselect) 对 `barModel` 的 `combineA` 做缓存：
+
+```ts
+import 'createSelector' from 'reselect';
+
+// 创建缓存函数
+const selectCombineA = createSelector(
+  (state) => state.bar.value,
+  (state) => state.foo.a,
+  (barState, fooState) => {
+    return barState + fooState;
+  }
+);
+
+const barModel = model("bar").define({
+  state: {
+    value: "bar",
+  },
+  computed: {
+    combineA: [
+      fooModel,
+      (state, fooState) => {
+        return selectCombineA({
+          foo: fooState,
+          bar: state,
+        });
+      },
+    ],
+  },
+  actions: {
+    setValue(state, payload) {
+      state.value = payload;
+    },
+  },
+});
+```
+
+我们创建缓存函数 `createSelector`，仅当 `barModel` 的状态发生改变或 `fooModel` 的 `a` 状态发生改变时，才会重新计算 `combineA` 的值。
+
+:::info 补充信息
+本节完整的[示例代码](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/performance-optimization)
+
+:::