@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

package/docs/en/apis/app/runtime/model/handle-effect.mdx

@@ -1,107 +0,0 @@
----
-sidebar_position: 7
-title: handleEffect
----
-# handleEffect
-
-import ReduckTip from "@site-docs-en/components/reduck-tip"
-
-<ReduckTip />
-
-An asynchronous function type Effect usually has three states that need to be processed: in request, request successful, and request failed. The way to handle these states is to write the Action functions (pending, fulfilled, rejected).
-
-With the help of the `handleEffect` API, we can generate default Action functions to handle different results at each stage of an asynchronous request. The structure of the State returned by the Action generated by `handleEffect` is as follows:
-
-```ts
-interface State {
-  result: any; // result of fulfilled state
-  pending: boolean; // request is pending
-  error: string; // request error message
-}
-```
-
-## Function Signature
-
-```ts
-interface EffectActions {
-  pending: Action;
-  fulfilled: Action;
-  rejected: Action;
-}
-
-interface Config {
-  ns?: string;
-  result?: string | false;
-  error?: string | false;
-  pending?: string | false;
-  combineMode?: 'merge' | 'replace';
-  omitResultNamespace?: boolean;
-}
-
-function handleEffect(config: Config): EffectActions;
-```
-
-### Input
-
-- `ns`: the default returned State structure is flat, By setting this parameter, the returned State can be mounted under the field named by the `ns`. For example, if `ns` is set to `"data"`, the returned structure is:
-
-```ts
-interface State {
-  data: {
-    pending: boolean;
-    result: any;
-    error: string;
-  };
-}
-```
-
-- `result`: the default value is "result". This parameter corresponds to the field name that stores the fulfilled state results. For example, set `result` to `"items"`, the returned State structure is:
-
-```ts
-interface State {
-  items: any; // Default result -> items
-  pending: boolean;
-  error: string;
-}
-```
-
-if `result` is `false`, then returned State has no `result`:
-
-```ts
-interface State {
-  pending: boolean;
-  error: string;
-}
-```
-
-- `pending`: the default value is `"pending"`. Change the name of the `pending` field in the returned State. Usage is the same as `result`.
-
-- `error`: the default value is `"error"`. Change the name of the `error` field in the returned State. Usage is the same as `result`.
-
-- `combineMode`: the default value is `"merge"`. Get fulfilled state results. There are two ways to deal with it (The data types that can be automatically processed here are also limited to simple object or array types):
-
-  - `"merge"`: the previous data is merged with the current data. the data is an array type, operation is similar to `[].concat(lastData, currentData)`. the data is an object, operation is similar to `{...lastData, ...curData}`.
-  - `"replace"`: the current data directly replaces the previous data.
-
-- `omitResultNamespace`: the default value is `false`. When the result is an object type, you want to mount the result directly on the State of the Model, rather than on "result", you can set it to true. For example:
-
-```ts
-// the result: {user: 'xx', email: 'xx'},
-// config handleEffect({ omitResultNamespace: true })
-// get State like follows:
-{
-  user: 'xx',
-  email: 'xx',
-  pending: false,
-  error: null,
-}
-```
-
-### Return Type
-
-Objects are processed by actions in pending, fulfilled, and rejected states.
-
-:::info More
-[Manage Effect](/guides/topic-detail/model/manage-effects).
-
-:::

package/docs/en/apis/app/runtime/model/model_.mdx

@@ -1,198 +0,0 @@
----
-sidebar_position: 1
-title: model
----
-# model
-
-import ReduckTip from "@site-docs-en/components/reduck-tip"
-
-<ReduckTip />
-
-:::tip
-The original type of Reduck is complex. The following type definition shows the simplified type information. For the original type, see [**model**](https://github.com/web-infra-dev/reduck/blob/main/packages/store/src/model/model.ts).
-
-:::
-
-## model
-
-Create a Model for managing application state.
-
-`function model(name: string): { define: function }`
-
-- name: `string`, the unique id of the Model created.
-
-```ts title="example"
-model('foo');
-```
-
-## define
-
-Used to define the detailed structure of the Model, supporting passing in an object type or function type parameter.
-
-### Object Type
-
-`function define(modelDesc: ModelDesc): Model;`
-
-- modelDesc: `ModelDesc`, definition of Model structure, includes `state`、`computed`、`actions`、`effects` etc. props.
-
-```tsx title="example"
-const fooModel = model('foo').define({
-  state: 'foo',
-  computed: {
-    cFoo: state => `c${state}`,
-  },
-  actions: {
-    setState: (state, value) => {
-      return value;
-    },
-  },
-  effects: {
-    loadState: async () => {
-      // get state from remote
-    },
-  },
-});
-```
-
-### Function Type
-
-`function define((context: Context, utils: Utils) => ModelDesc): Model;`
-
-- `context`: Reduck Context, can get underlying `store` object. `store` support all Redux Store [API](https://redux.js.org/api/store), also mounts the `use` method for consuming the Model, and the `unmount` method for unmounting the Model.
-- utils: commonly used tool like `use`、`onMount`. `use` is the same as `store.use`, `onMount` is the hook function after the Model is mounted.
-
-```ts
-interface Utils {
-  use: UseModel;
-  onMount: OnMountHook;
-}
-
-interface Context {
-  store: ReduxStore & {
-    use: UseModel;
-    unmount: (model: Model) => void;
-  };
-}
-```
-
-For example, through `use`, you can get the `state` and `actions` of the Model itself and other Models.
-
-```tsx title="example"
-const fooModel = model('foo').define(() => {
-  return {
-    state: 'foo',
-    actions: {
-      setState: (state, value) => {
-        return value;
-      },
-    },
-  };
-});
-
-const barModel = model('bar').define((_, { use }) => {
-  return {
-    state: 'bar',
-    effects: {
-      syncFoo() {
-        const [state, actions] = use(fooModel);
-        actions.setState(state);
-      },
-    },
-  };
-});
-```
-
-### Input
-
-#### ModelDesc.state
-
-Define the state of the Model. Technically, any type of **State** is supported, but in practice it is recommended to use a JSON serializable type.
-
-```ts
-interface ModelDesc {
-  state: any;
-}
-```
-
-#### ModelDesc.actions
-
-Define the Actions of the Model. The function type of Actions is:
-
-```ts
-interface ModelDesc {
-  actions: {
-    [actionKey: string]: (state: State, payload: any) => State | void;
-  };
-}
-```
-
-Reduck internally integrates [immer](https://github.com/immerjs/immer), which can directly return the original `state`. When the Action has no explicit return value, Reduck internally returns a modified new State object.
-
-#### ModelDesc.computed
-
-Defines the derived state of the Model. The definition of derived state supports two types:
-
-1. Depends only on the state of the Model itself
-
-```ts
-interface ModelDesc {
-  computed: {
-    [computedKey: string]: (state: State) => any;
-  };
-}
-```
-
-2. Depends on the state of other Models
-
-```ts
-interface ModelDesc {
-  computed: {
-    [computedKey: string]: [
-      ...models: Model[],
-      (state: State, ...args: ModelState[]) => any,
-    ];
-  };
-}
-```
-
-```ts title="example"
-const fooModel = model('foo').define({
-  state: 'foo',
-});
-
-const barModel = model('bar').define({
-  state: 'bar',
-  computed: {
-    combineFoo: [fooModel, (state, fooState) => state + fooState],
-  },
-});
-```
-
-#### ModelDesc.effects
-
-Defines the Effects of the Model. The function types defined in Effects are:
-
-```ts
-interface ModelDesc {
-  effects: {
-    [effectKey: string]: (...args: any[]) => any;
-  };
-}
-```
-
-```ts title="example"
-const fooModel = model('foo').define((context, { use }) => ({
-  state: 'foo',
-  effects: {
-    persist() {
-      const [state] = use(fooModel);
-      localStorage.setItem('state', state);
-    },
-  },
-}));
-```
-
-:::info More
-[Define Model](/guides/topic-detail/model/define-model).
-
-:::

package/docs/en/apis/app/runtime/model/use-local-model.mdx

@@ -1,29 +0,0 @@
----
-sidebar_position: 4
-title: useLocalModel
----
-# useLocalModel
-
-import ReduckTip from "@site-docs-en/components/reduck-tip"
-
-<ReduckTip />
-
-To use the State in the Model as a local state, the effect is similar to React's `useState`. `useLocalModel` API same as `useModel`. For detail, see [`useModel`](./use-model.mdx).
-
-## Example
-
-```tsx
-function Container() {
-  const [state, actions] = useLocalModel(modelA);
-  const [state1, actions1] = useLocalModel(modelA);
-
-  // ...
-}
-```
-
-`modelA` was loaded twice with useLocalModel above, because useLocalModel consumes local state, so state and state1 are also completely isolated.
-
-:::info More
-[Use Model](/guides/topic-detail/model/use-model).
-
-:::

package/docs/en/apis/app/runtime/model/use-model.mdx

@@ -1,89 +0,0 @@
----
-sidebar_position: 2
-title: useModel
----
-# useModel
-
-import ReduckTip from "@site-docs-en/components/reduck-tip"
-
-<ReduckTip />
-
-:::tip
-The original type of Reduck is complex. The following type definition shows the simplified type information. For the original type, see [**model**](https://github.com/web-infra-dev/reduck/blob/main/packages/store/src/model/model.ts).
-
-:::
-
-## Function Signature
-
-```ts
-function useModel(
-  models: Models[],
-  stateSelector?: StateSelector,
-  actionSelector?: ActionSelector,
-): [state, actions, subscribe];
-function useModel(
-  ...models: Models[],
-  stateSelector?: (...args: State[]) => any,
-  actionSelector?: (...args: Actions[]) => any,
-): [state, actions, subscribe];
-```
-
-### Input
-
-- models: Array of Model objects, which can be passed in as an array type parameter, or all Models can be passed in as parameters one by one.
-- stateSelector: Optional parameters, used to filter State calculations. The first n parameters are the States corresponding to n Models, and the returned data is used as the first element of the `useModel` return value array.
-- actionSelector: Optional parameters, used to filter Action calculations. The first n parameters are the States corresponding to n Models, and the returned data is used as the second element of the `useModel` return value array.
-
-### Return Value
-
-Returns an array with each value:
-
-- state: return value of `stateSelector`. if there is no `stateSelector`, will combine all incoming Model States(including derived states) and return them. If there is an attribute of the same name in the State of different Models, the following State will override the previous State. when `state` changes, the component call `useModel` will re-render.
-- actions: return value of `actionSelector`. if there is no `actionSelector`, will combine all incoming Model Action(including Effect) and return them. If there is an attribute of the same name in the Action of different Models, the following Action will override the previous Action.
-- subscribe: A function that subscribes to State changes. This function is called when the State of any Model passed in changes.
-
-## Example
-
-### Basic
-
-```tsx
-import todoModel from 'models/todo';
-import filterModel from 'models/filter';
-
-function Test(props) {
-  const [state, actions] = useModel([todoModel, filterModel]);
-  actions.add(); // call todoModel add action
-  actions.setVisibleStatus(); // call filterModel filterModel action
-
-  state.items; // get todoModel state items
-  state.visibleStatus; // get filterModel state visibleStatus
-}
-```
-
-### Selector Usage
-
-```js
-function Test(props) {
-  const [state, actions] = useModel(
-    [todoModel, filterModel],
-    (todoState, filterState) => ({
-      items: todoState.items,
-      visibleStatus: `${props.prefix}-${filterState.visibleStatus}`,
-    }),
-    (todoActions, filterActions) => ({
-      ...todoActions,
-      ...filterActions,
-    }),
-  );
-  actions.add(); // call todoModel add action
-  actions.setVisibleStatus(); // call filterModel filterModel action
-
-  state.items; // get todoModel state items
-  state.visibleStatus; // get filterModel state visibleStatus
-}
-```
-
-:::info More
-[use Model](/guides/topic-detail/model/use-model).
-
-:::

package/docs/en/apis/app/runtime/model/use-static-model.mdx

@@ -1,51 +0,0 @@
----
-sidebar_position: 3
-title: useStaticModel
----
-# useStaticModel
-
-import ReduckTip from "@site-docs-en/components/reduck-tip"
-
-<ReduckTip />
-
-If want to consume a Model in the form of React Hook in the component, and can get the current latest state at any time, but you don't want the Model state to be updated, which will cause the component to be re-rendered, we can use `useStaticModel`.
-
-`useStaticModel` API is same as `useModel`.For detail, see [`useModel`](./use-model.mdx).
-
-To ensure that the latest state is always available, be careful not to deconstruct the returned `state`.
-
-```tsx
-function App() {
-  // ❌ Do not deconstruct state, but can deconstruct actions.
-  const [{ username }, { logout }] = useStaticModel(userModel);
-
-  // ✅ True Usage.
-  const [state, { logout }] = useStaticModel(userModel);
-
-  useEffect(() => {
-    state.username;
-  }, []);
-}
-```
-
-## Example
-
-The following `App` component consumes the `userModel` state, but does not use it directly in JSX. It can be found that changes in the `userModel` state do not necessarily cause the component to re-render. This situation can be optimized using `useStaticModel`.
-
-```tsx
-function App() {
-  const [state] = useStaticModel(userModel);
-
-  useEffect(() => {
-    // Statistical UV Data
-    send('pageview', { user: state.user });
-  }, [state]);
-
-  return <div>Hello</div>;
-}
-```
-
-:::info More
-[Use Model](/guides/topic-detail/model/use-model).
-
-:::

package/docs/en/apis/app/runtime/model/use-store.mdx

@@ -1,26 +0,0 @@
----
-sidebar_position: 9
-title: useStore
----
-# useStore
-
-import ReduckTip from "@site-docs-en/components/reduck-tip"
-
-<ReduckTip />
-
-`useStore` Used to get the store shared by the current component tree.
-
-## Function Signature
-
-```ts
-function useStore(): ReduckStore;
-```
-
-### Return Type
-
-- ReduckStore: Reduck Store, type refer to the return type of [createStore](./create-store.mdx).
-
-:::info More
-[Use Model](/guides/topic-detail/model/use-model).
-
-:::

package/docs/en/apis/app/runtime/ssr/pre-render.mdx

@@ -1,96 +0,0 @@
----
-title: PreRender
----
-# PreRender
-
-A Helmet-like HOC without content implements SPA routing-level caching, manner without additional configuration.
-
-## Usage
-
-```tsx
-import { PreRender } from '@modern-js/runtime/ssr';
-
-export default () => (
-  <>
-    <PreRender interval={5} />
-  </>
-);
-```
-
-## Function Signature
-
-The `PreRender` provides a set of configuration for controlling caching rules, expiration times, caching algorithms, and more.
-
-```tsx
-type Props {
-  interval: number;
-  staleLimit: number;
-  level: number;
-  include: { header?: string[], query?: string[] };
-  matches: { header?: Record<string, any>, query?: Record<string, any> }
-}
-
-function PreRender(props: Props): React.Component
-```
-
-### Input
-
-- `interval`: set the time the cache keep fresh, seconds. During this time, the cache will be used directly and not invoke asynchronous rendering.
-- `staleLimit`: sets the time when the cache is completely expired, seconds.During this time, The cache can be returned and asynchronous rendering will be invoke, otherwise must wait for the re-rendered result.
-- `level`: sets the calculation rule level for the cache identity, usually used with `includes` and `matches`. The default value is `0`.
-
-```bash
-0: pathname
-1: pathname + querystring
-2: pathname + headers
-3: pathname + querystring + headers
-```
-
-- `includes`: sets the content that needs to be included in the cache identifier, used when the `level` is not `0`. The default value is `null`.
-- `matches`: sets the rewriting rule for the value of query or header in cache identity, usually used in cache category, supports regular expressions. The default value is `null`.
-
-## Example
-
-```tsx
-import { PreRender } from '@modern-js/runtime/ssr';
-
-export default function App() {
-  return (
-    <>
-      <PreRender interval={10} />
-      <div>Hello Modern</div>
-    </>
-  );
-}
-```
-
-The following example shows how to add the parameters in the query and header into the cache identifier calculation:
-
-```tsx
-/* calculate cache identifier using channel in query and language in header */
-<PreRender
-  interval={10}
-  level={2}
-  includes={{
-    query: ['channel'],
-    header: ['language'],
-  }}
-/>
-```
-
-The following example shows how not to let the test channel affect the online cache:
-
-```tsx
-/* rewrite the channel value starting with test_ in the query as "testChannel", otherwise rewrite it as "otherChannel" */
-<PreRender interval={10} level={2} includes={{
-  query: ["channel"],
-  header: ["language"]
-}} matches={{
-  query: {
-    channel: {
-      "testChannel", "^test_",
-      "otherChannel", ".*"
-    }
-  }
-}} />
-```