@modern-js/main-doc 2.7.0 → 2.9.0

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

@@ -0,0 +1,222 @@
+---
+sidebar_position: 7
+title: Model Communication
+---
+
+# Model Communication
+
+Model communication refers to communication between different Models, as well as communication between Effects and Actions within the same Model.
+
+## Communication between Models
+
+Models are not isolated from each other and can communicate with each other. There are mainly two scenarios:
+
+1. Accessing the State and Actions of other Models in the Model.
+2. Listening to changes in other Models in the Model.
+
+Here, we will transform the simple counter application in the [Quick Start](/guides/topic-detail/model/quick-start) section into a counter application that allows you to set the step frequency. By setting the step frequency, you can affect the magnitude of each counter increase.
+
+We abstract two Models, `stepModel` (step frequency) and `counterModel` (counter):
+
+```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` declares only one `state`, with an initial value of 1.
+
+`counterModel` loads `stepModel` with the `use` function, and retrieves the returned `subscribeStep` function to listen for changes to the `stepModel` state. `onMount` is a hook function that is executed after the Model is mounted. `counterModel` begins to subscribe to the state changes of `stepModel` after it has been mounted, and prints out the latest value of `stepModel`.
+
+`counterModel` accesses `stepModel` using the `use` function, and in the `add` function, the current value of `stepModel` (step frequency) can be obtained to perform increments using this value.
+
+:::caution Note
+When you need to access the state of another Model, you must call `use` during the actual execution phase of the current Actions or Effects function (in this example, the `add` function) to ensure that the obtained State is the latest value. Therefore, although we also call `use(stepModel)` in the callback function of `define`, we do not destructure the `state` value of `stepModel` because the callback function of `define` is executed during the mounting phase of the Model, and at this time, the `state` of `stepModel` obtained may be different from the value obtained when `add` is executed.
+:::
+
+Modify 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 Additional Information
+Modern.js has enabled [auto-generate actions](./auto-actions.mdx) by default, so even though there are no Actions defined manually in the `stepModel`, the auto-generated `setState` can still be used.
+
+:::
+
+- Click **add step** to add steps.
+- Click **add counter** to trigger the counter to increase.
+
+The final effect is as follows:
+
+![communicate-models](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/models-communicate.gif)
+
+:::info Additional Information
+- Full example code for this section can be found [here](https://github.com/web-infra-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/models-communication).
+- For more information about the relevant API, please refer to: [model](/apis/app/runtime/model/model_#function-types).
+
+:::
+
+In the previous example of `counterModel`, we called `use` within the Actions function to get other Model objects. If we only need to call Actions of other Models, we can also use `use` to get the Actions of Models in the `define` callback function because Actions are functions and there is no issue of value expiration. For example:
+
+```ts
+const barModel = model('bar').define({
+  // ..
+});
+
+const fooModel = model('foo').define((context, utils) => {
+  // get barModel actions
+  const [, actions] = utils.use(barModel);
+  return {
+    // ...
+    effects: {
+      async loadA() {
+        // ...
+        // invoke barModel action
+        barModel.actionA();
+      },
+      async loadB() {
+        // ...
+        // invoke barModel action
+        barModel.actionB();
+      },
+    },
+  };
+});
+```
+
+Here, we no longer need to repeatedly get the `barModel` object in `loadA` and `loadB`, which simplifies the code logic.
+
+## Communication within a Model
+
+Communication within a Model can also be divided into two main scenarios:
+
+1. Effects functions call the Actions functions of the same Model or other Effects functions.
+2. Actions functions call other Actions functions of the same Model.
+
+In the [Managing Side Effects](/guides/topic-detail/model/manage-effects) section, we demonstrated how Effects functions call Actions functions.
+
+Here we provide another example:
+
+```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() {
+      // get current Model actions
+      const [, actions] = use(fooModel);
+      const res = await mockFetchA();
+      actions.setA(res);
+    },
+    async loadB() {
+      // get current Model actions
+      const [, actions] = use(fooModel);
+      const res = await mockFetchB();
+      actions.setB(res);
+    },
+  },
+}));
+```
+
+In this example, the two Effects functions of `fooModel` need to call their own Actions functions. Here, we have called `use` once in each Effects function. Why can't we use `use` to get the Actions of the Model itself in the `define` callback function, as in the example of Model communication? This is because when calling `use` to get a Model, it first checks whether the Model has been mounted. If it has not been mounted, the mounting logic will be executed first.
+
+The `define` callback function is executed during the mounting phase, so calling `use` to get the Model itself during the mounting phase will result in an infinite loop (which will throw an error in the actual execution process). Therefore, **you must not call `use` in the `define` callback function to get the Model itself**.
+
+However, we can use the `onMount` hook function to get the Model itself through `use` after the Model has been mounted:
+
+```ts
+const fooModel = model('foo').define((context, { use, onMount }) => {
+  let actions;
+
+  onMount(() => {
+    // after fooModel mounted，get 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);
+      },
+    },
+  };
+});
+```
+
+In this way, we can also simplify the code.

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

@@ -0,0 +1,170 @@
+---
+sidebar_position: 8
+title: Performance Optimization
+---
+# Performance Optimization
+
+Reduck has already done a lot of performance optimization work internally, so performance issues generally do not need to be considered. However, when performance is more sensitive, or when encountering performance issues, you can consider more targeted performance optimization from the following three aspects.
+
+## Splitting Models
+
+When `useModel` returns the complete State object of the Model, any change in any part of the State will cause the component that calls `useModel` to be re-rendered.
+
+For example:
+
+```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>;
+}
+```
+
+Although `ComponentA` only needs to use the `a` state, it will still be re-rendered when the `b` state changes. In this case, we can consider splitting `fooModel` into separate Models responsible for managing `a` and `b` respectively:
+
+```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;
+    },
+  },
+});
+```
+
+## State Selection
+
+`useModel` supports passing in a selector function to filter the returned State and Actions for the component. We can use a selector function to ensure that the State returned to the component is what the component needs directly, thus ensuring that the component is not re-rendered due to changes in other unrelated states.
+
+For the same example above, we can use a selector function for performance optimization, the code is as follows:
+
+```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>;
+}
+```
+
+## Derivative State Caching
+
+When a Model has `computed` property, the `computed` function will be executed every time `useModel` is called.
+
+Consider the following code:
+
+```ts
+const barModel = model('bar').define({
+  state: {
+    value: 'bar',
+  },
+  computed: {
+    combineA: [
+      fooModel, // fooModel define as above
+      (state, fooState) => {
+        return state + fooState.a;
+      },
+    ],
+  },
+  actions: {
+    setValue(state, payload) {
+      state.value = payload;
+    },
+  },
+});
+
+function ComponentB() {
+  const [state, actions] = useModel(fooModel);
+  const [{ combineA }] = useModel(barModel);
+  // ...
+}
+```
+Even if the `b` state of `fooModel` changes, the `combineA` function (more precisely, the last function type element of `combineA`) will still be called and executed when the component is re-rendered, although the derivative state `combineA` of `barModel` depends on `barModel` itself and the state `a` of `fooModel`.
+
+In general, the logic in the `computed` function is usually very lightweight, but when the logic in the `computed` function is relatively complex, we can consider caching the calculation logic. For example, we can use [reselect](https://github.com/reduxjs/reselect) to cache `combineA` of `barModel`:
+
+```ts
+import 'createSelector' from 'reselect';
+
+// create cache function
+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;
+    },
+  },
+});
+```
+
+We created a caching function `createSelector`, which only recalculates the value of `combineA` when the state of `barModel` changes or the state `a` of `fooModel` changes.
+
+:::info Additional Information
+You can find the complete example code of this section [here](https://github.com/web-infra-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/performance-optimization).
+:::
+

package/docs/en/guides/topic-detail/model/quick-start.mdx

@@ -0,0 +1,114 @@
+---
+sidebar_position: 1
+title: Quick Start
+---
+# Quick Start
+
+import ReduckMigration from "@site-docs/components/reduck-migration"
+
+<ReduckMigration />
+
+[Reduck](https://github.com/web-infra-dev/reduck) is a state management library developed by the Modern.js team that follows the MVC pattern. Its underlying state storage is based on [Redux](https://redux.js.org/) implementation, while providing a higher level of abstraction and full compatibility with the Redux ecosystem.
+
+The goal of Reduck is to organize the development structure of React applications in the MVC pattern, maintain business logic in the Model layer, decoupling business logic from UI, making it easier for developers to focus on business logic, and reducing duplicated work (boilerplate code) through higher level of abstraction.
+
+In the MVC pattern, Reduck plays the role of M(Model), React UI Component corresponds to V(View), and gets the Model from Reduck and modifies the Model's React Container Component, which corresponds to C(View Controller/Container).
+
+The state management solution of Modern.js is implemented through built-in Reduck. Using Reduck in Modern.js not only eliminates the manual integration process, but also allows all Reduck APIs to be imported and used directly from the Modern.js Runtime package, providing a better consistency experience.
+
+:::info
+1. To use Reduck APIs in Modern.js, you need to set [runtime.state](/configure/app/runtime/state) to enable the state management plugin.
+2. Reduck can also be used separately as a state management library [outside of Modern.js](/guides/topic-detail/model/use-out-of-modernjs).
+
+:::
+
+## Core Concepts
+
+There are only four core concepts in Reduck: Model, State, Actions, and Effects.
+
+Model: Encapsulates the logic and required state of an independent module, consisting of State, Actions, and Effects.
+
+State: The state stored in the Model.
+
+Actions: Pure functions used to modify State, functions must be **Synchronous**.
+
+Effects: Functions with side effects used to modify State, functions can be **Asynchronous**. Effects can call their own Actions and Effects or those of other Models.
+
+The Reduck data flow is shown in the following figure:
+
+![Reduck Data Flow](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/reduck-concept.svg)
+
+## Basic Usage
+
+Next, let's take a simple **Counter** application as an example to demonstrate the basic usage of Reduck.
+
+First, we define a Model named `count`:
+
+```js
+import { model } from '@modern-js/runtime/model';
+
+const countModel = model('count').define({
+  state: {
+    value: 1,
+  },
+});
+
+export default countModel;
+```
+
+We use the API `model` to create `countModel`, which currently only contains the state that stores the counter `value`, that is, value in the code.
+
+We define an action to increase the counter by 1:
+
+```js
+import { model } from '@modern-js/runtime/model';
+
+const countModel = model('count').define({
+  state: {
+    value: 1,
+  },
+  actions: {
+    add(state) {
+      state.value += 1;
+    },
+  },
+});
+
+export default countModel;
+```
+
+In the `add` action, we can directly modify the value of the state and perform the increment operation without treating the state as an immutable object. This is because Reduck integrates [immer](https://github.com/immerjs/immer), which can directly modify the original state object.
+
+Next, we will demonstrate how to use the Model in a component.
+
+Create a new component called `Counter`, and use the `countModel` via the `useModel` API inside the component:
+
+```js
+import { useModel } from '@modern-js/runtime/model';
+import countModel from './models/count';
+
+function Counter() {
+  const [state, actions] = useModel(countModel);
+
+  return (
+    <div>
+      <div>counter: {state.value}</div>
+      <button onClick={() => actions.add()}>add</button>
+    </div>
+  );
+}
+```
+
+`useModel` gets the `state` and `actions` of `countModel`. The component displays the current value of the counter, and clicking the `add` button increments the counter by 1.
+
+:::info
+Due to the simplicity of the example used here, the layering of the MVC pattern is not strictly followed. The `Counter` component acts as both the V and C layers.
+
+:::
+
+The final demonstration effect is as follows:
+
+![countModel](https://lf3-static.bytednsdoc.com/obj/eden-cn/eueh7vhojuh/modern/simple-count-model.gif)
+
+That completes a simple counter application. You can view the complete example code for this section [here](https://github.com/web-infra-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/counter-model).
+

package/docs/en/guides/topic-detail/model/redux-integration.mdx

@@ -0,0 +1,24 @@
+---
+sidebar_position: 11
+title: Ecosystem Integration
+---
+# Redux Ecosystem Integration
+
+Reduck is based on Redux, so you can use libraries from the [Redux ecosystem](https://redux.js.org/introduction/ecosystem) to enhance its functionality. APIs like [`Provider`](/apis/app/runtime/model/Provider), [`createApp`](/apis/app/runtime/model/create-app), and [`createStore`](/apis/app/runtime/model/create-store) allow you to configure the use of [middlewares](https://redux.js.org/understanding/thinking-in-redux/glossary#middleware) and [store enhancers](https://redux.js.org/understanding/thinking-in-redux/glossary#store-enhancer); and using [`createStore`](/apis/app/runtime/model/create-store), you can take complete control over the process of creating the store.
+
+For example, if we want to use the middleware [`redux-logger`](https://github.com/LogRocket/redux-logger), the example code is as follows:
+
+
+```ts
+ReactDOM.render(
+  <Provider config={{ middlewares: [logger] }}>
+    // Set middleware through the config parameter of Provider
+    <App />
+  </Provider>,
+  document.getElementById('root'),
+);
+```
+
+:::caution
+Reduck is built on top of the lower-level Redux API, and abstracts away some of the underlying concepts of Redux, such as Reducers. Reduck allows models to be dynamically mounted, whereas Redux mounts all the necessary state at Store creation time. Due to these implementation differences, some libraries from the Redux ecosystem cannot be used directly in Reduck.
+:::

package/docs/en/guides/topic-detail/model/test-model.mdx

@@ -0,0 +1,45 @@
+---
+sidebar_position: 9
+title: Test Model
+---
+# Test Model
+
+Testing is crucial for the stability of code. Here's an example using the `countModel` from [Quick Start](/guides/topic-detail/model/quick-start) to demonstrate how to perform unit testing on a Model in Modern.js.
+
+To use the testing feature, you need to first enable it. In the project root directory, execute `pnpm run new` and make the following selection:
+
+```bash
+? Please select the operation you want to perform: Enable optional features
+? Enable optional features Enable "Unit Testing / Integration Testing" feature
+```
+
+This will enable testing feature support.
+
+Create a new file called `count.test.ts` with the following code:
+
+```ts
+import { createStore } from '@modern-js/runtime/testing';
+import countModel from './count';
+
+describe('test model', () => {
+  it('count value should plus one after add', () => {
+    const store = createStore();
+    const [state, { add }] = store.use(countModel);
+
+    expect(state).toEqual({ value: 1 });
+
+    add();
+
+    expect(store.use(countModel)[0]).toEqual({ value: 2 });
+  });
+});
+```
+
+:::info
+The [`createStore`](/apis/app/runtime/model/create-store) used here is imported from `@modern-js/runtime/testing`, which internally uses the configuration of [`runtime.state`](/configure/app/runtime/state) to create a `store`.
+
+:::
+
+In the test case, we create a new `store` to mount `countModel`, use `store.use` to get the State and Actions of `countModel`. Then, we call the `add` Action to update the state and assert the updated state value.
+
+Execute the `pnpm run test` command to trigger the execution of the test case.

package/docs/en/guides/topic-detail/model/typescript-best-practice.mdx

@@ -0,0 +1,72 @@
+---
+sidebar_position: 10
+title: TS Best Practices
+---
+# TS Best Practices
+
+Reduck provides excellent support for TypeScript, and in most cases, you can get API type prompts directly without any extra work. In this section, we will provide additional information on other usage scenarios.
+
+## Defining the State Type of the Model
+
+Declaring type information for the State of a Model is a best practice when using Reduck in TypeScript.
+
+```ts
+interface State {
+  data: string;
+}
+
+export const foo = model<State>('foo').define({
+  state: {
+    data: '',
+  },
+  computed: {
+    withSuffix: state => state.data + 'suffix',
+  },
+  actions: {
+    setData: (state, payload: string) => {
+      state.data = payload;
+    },
+  },
+});
+```
+
+When you declare type information for the State of a Model, the `computed` and `actions` of the Model can get the correct type information. In fact, even if we don't define State type information in the example code above, the type information of State can be automatically inferred based on the initial value information of `state`. However, we still recommend that you declare the type information of State when defining a Model because the type information of State inferred based on the initial value information of `state` may be incomplete (missing fields or field type information), and the type information of State cannot be automatically inferred based on the initial value information of `state` when using [Function Type](/apis/app/runtime/model/model_#函数类型) to define the Model.
+
+## Dependent types of Derived State
+
+When the derived state of a Model depends on other Models, you need to manually specify the State of the other Models.
+
+
+```ts
+interface State {
+  data: string;
+}
+
+export const bar = model<State>('bar').define({
+  state: {
+    data: '',
+  },
+  computed: {
+    // 为 fooState 指定类型
+    withFoo: [foo, (state, fooState: FooState) => state.data + fooState.data],
+  },
+});
+```
+
+## Hooks for Getting Model Type Information
+
+Reduck provides a set of utility types for getting Model type information:
+
+- `GetModelState`: Get the type information of the State (including derived state) of the Model.
+- `GetModelActions`: Get the type information of the Actions (including Effects functions) of the Model.
+
+```ts
+export const foo = model<State2>('foo').define({
+  // 省略
+});
+
+// 获取 foo 的 State 类型
+let fooActions: GetModelActions<typeof foo>;
+// 获取 foo 的 Actions 类型
+let fooState: GetModelState<typeof foo>;
+```