Merge pull request #7 from filefoxper/3.2.5

add API useAgentSelector and useAgentMethods

Author: filefoxper

.eslintignore

@@ -0,0 +1,6 @@
+.eslintrc.js
+test/
+jest.config.js
+babel.config.js
+index.js
+webpack.config.js

.eslintrc.js

@@ -0,0 +1,50 @@
+module.exports = {
+    env: {
+        "browser": true,
+        "es6": true
+    },
+    extends: [
+        'airbnb',
+        'plugin:@typescript-eslint/recommended',
+        // 'plugin:@typescript-eslint/recommended-requiring-type-checking'
+    ],
+    globals: {
+        "Atomics": "readonly",
+        "SharedArrayBuffer": "readonly",
+        "self": "readonly"
+    },
+    parserOptions: {
+        "ecmaVersion": 2021,
+        "sourceType": 'module',
+        tsconfigRootDir: '.',
+        project: ['./tsconfig.json'],
+    },
+    plugins: ['@typescript-eslint'],
+    settings: {
+        'import/resolver': {
+            'typescript': {},
+
+        }
+    },
+    rules: {
+        "import/extensions": "off",
+        "no-param-reassign": "off",
+        "@typescript-eslint/no-explicit-any":"off",
+        "@typescript-eslint/no-unused-vars": ["off"],
+        'react/jsx-filename-extension': ["off", { 'extensions': ['.js', '.jsx', '.ts', '.tsx'] }],
+        'react/jsx-props-no-spreading':'off',
+        'import/prefer-default-export':'off',
+        'max-classes-per-file':'off',
+        'no-plusplus':["error",{allowForLoopAfterthoughts:true}],
+        'react/require-default-props':'off',
+        'camelcase':'off',
+        "no-use-before-define": "off",
+        "@typescript-eslint/no-use-before-define": ["error", { "functions": false, "classes": true }],
+        'react/no-did-update-set-state':'warn',
+        "no-shadow":["warn"],
+        'class-methods-use-this':'off',
+        'jsx-a11y/no-static-element-interactions':'off',
+        'jsx-a11y/click-events-have-key-events':'off',
+        '@typescript-eslint/no-empty-function':'off'
+    }
+};

CHANGE_LOG.md

@@ -6,4 +6,8 @@
 这时`useAgent`只支持`agent-reducer@1.*`特性，
 而`useAgentReducer`方法因不受全局影响，依然只支持`agent-reducer@3.*`。
 
-[update] 重新增加被去除的`use-agent-reducer@1.*`方法：useBranch,useParent作为废弃方法。
+[update] 重新增加被去除的`use-agent-reducer@1.*`方法：useBranch,useParent作为废弃方法。
+
+## v3.2.5 2021-04-10
+
+[new] add API `useAgentSelector` and `useAgentMethods`

docs/README.md

@@ -8,9 +8,9 @@
 
 # use-agent-reducer
 
-This is a powerful `react hook` library for managing component state changes. It is designed for replacing reducer tools in `react hook` ecosystem. You can manage the major component state change logistic with it by a class or object model pattern.
+This is a powerful `react hook` library for managing state changes. It is designed for replacing reducer tools in `react hook` ecosystem. You can design a state change logistic by setting a model with class or object pattern.
 
-The core dependency of this library is [agent-reducer](https://www.npmjs.com/package/agent-reducer), you can read its [document](https://github.com/filefoxper/agent-reducer/blob/master/documents/en/index.md) for a preview about what `use-agent-reducer` can do. But, we suggest you follow our [document](/introduction) and learn how to use it first.
+The core dependency of this library is [agent-reducer](https://github.com/filefoxper/agent-reducer/blob/master/documents/en/index.md), you can read its document for a preview about what `use-agent-reducer` can do. But, we suggest you follow our [document](/introduction) and learn how to use it first.
 
 * [Introduction](introduction.md)
 * [Tutorial](/tutorial.md)

docs/_sidebar.md

@@ -2,4 +2,5 @@
 * [Introduction](introduction.md)
 * [Tutorial](/tutorial.md)
 * [Guides](/guides.md)
-* [API Reference](/api.md)
+* [API Reference](/api.md)
+* [Change Logs](/changes.md)

docs/api.md

@@ -12,7 +12,7 @@ function useAgentReducer<T extends OriginAgent<S>, S>(
 ): T
 ```
 
-* originAgent - the model class or object.
+* entry - the model class or object.
 * middleWareOrEnv - it is an optional param, if you want to use `MiddleWare`, it can be a `MiddleWare`, if you want to set running env without `MiddleWare`, it can be an env config.
 * env - if you want to set both `MiddleWare` and running env, you can set an env config here.
 
@@ -41,19 +41,53 @@ function useMiddleWare<T extends OriginAgent<S>, S>(
 
 You can see how to use it [here](/tutorial?id=use-middleware).
 
-## useAgent
+## useAgentSelector
+
+This api function is a react hook, it can be used to extract data from a sharing model state. And only the extracted data change can cause its consumer (react component) rerender.
+
+```typescript
+export function useAgentSelector<T extends OriginAgent<S>, S, R>(
+  entry: T,
+  mapStateCallback: (state: T['state']) => R,
+): R
+```
+
+* entry - the model instance object.
+* mapStateCallback - a callback function for extracting data from model state.
+  
+This function returns data extracted from a model state directly.
+
+## useAgentMethods
+
+This api function is a react hook for calling a model methods. It never causes its consumer (react component) rerendering.
+
+```typescript
+export function useAgentMethods<T extends OriginAgent<S>, S>(
+  entry: T,
+  middleWareOrEnv?: MiddleWare | RunEnv,
+  env?: Omit<RunEnv, 'legacy'>,
+): Omit<T, 'state'>
+```
+
+* entry - the model instance object.
+* middleWareOrEnv - it is an optional param, if you want to use `MiddleWare`, it can be a `MiddleWare`, if you want to set running env without `MiddleWare`, it can be an env config.
+* env - if you want to set both `MiddleWare` and running env, you can set an env config here.
+
+This function returns a model like instance which has an empty state property. It only provides model methods.
+
+## ~~useAgent~~
 
 (not recommend)
 
 This api function is an old version abount [useAgentReducer](/api?id=useagentreducer), it is kept for supporting the old features of [agent-reducer](https://www.npmjs.com/package/agent-reducer). And we do not recommend to use it.
 
-## useBranch
+## ~~useBranch~~
 
 (not recommend)
 
 This api function is an old version abount [useMiddleWare](/api?id=usemiddleware). And we do not recommend to use it.
 
-## useMiddleActions
+## ~~useMiddleActions~~
 
 (not recommend)
 
@@ -71,7 +105,7 @@ function useMiddleActions<T extends OriginAgent<S>, P extends MiddleActions<T, S
 * middleActions - a instance of class extends MiddleActions
 * otherParams - start an `Agent` object, and rest with MiddleWares
 
-## AgentProvider
+## ~~AgentProvider~~
 
 (not recommend)
 
@@ -88,7 +122,7 @@ interface Props{
 * value - the `Agent` object for sharing in `AgentProvider` children.
 * children - react nodes
 
-## useAgentContext
+## ~~useAgentContext~~
 
 (not recommend)
 
@@ -100,7 +134,7 @@ This is a react hook function, it picks `Agent` from a nearest [AgentProvider](/
 function useAgentContext<T extends OriginAgent>(): T
 ```
 
-## useParent
+## ~~useParent~~
 
 (not recommend)
 

docs/guides.md

@@ -207,3 +207,42 @@ describe("set run env",()=>{
 
 Be careful in `env.strict`, you'd better not set it to be `false`. For it will make the state difference between `Agent` and your reducer tool.
 
+## model sharing optimization
+
+By using `model sharing`, we can share state updating between different components. But this feature brings problem too, that causes model sharing consumers( react components ) always render together, no matter if the state change is necessary for urrent consumer. From `use-agent-reducer@3.2.5`, we provide some new API functions for resolving this problem. You can use API function `useAgentSelector` to extract data from a model state which is truly used in component. And also, you can extract methods from a sharing model by using another API `useAgentMethods`.
+
+API `useAgentSelector` extracts data from a state, and only the extracted data change can cause its consumer (react component) rerender.  
+
+```typescript
+import {weakSharing} from 'agent-reducer';
+import {useAgentSelector} from 'use-agent-reducer';
+
+// model sharing reference
+const sharingRef = weakSharing(()=> Model);
+
+......
+
+// use a sharing model, 
+// and extract data from state by a state mapping function.
+// Only the extracted data change can cause its consumer rerender.
+const renderNeeds = useAgentSelector(sharingRef.current, (state)=> state.renderNeeds);
+```
+
+API `useAgentMethods` only provides methods from a model like instance, it never causes a rerender.
+
+```typescript
+import {weakSharing, MiddleWarePresets} from 'agent-reducer';
+import {useAgentMethods} from 'use-agent-reducer';
+
+// model sharing reference
+const sharingRef = weakSharing(()=> Model);
+
+......
+
+// use a sharing model,
+// get a model like instance, which omits the state property.
+// It is used for providing methods from sharing model,
+// and it never causes a rerender.
+const {fetchState} = useAgentMethods(sharingRef.current, MiddleWarePresets.takePromiseResolve());
+```
+

docs/introduction.md

@@ -1,20 +1,20 @@
 # Introduction
 
-The primary work of this tool is using a `state producible model` to generate a `state changeable agent`. The agent changes state according to what the model produces out. So, [Model](/introduction?id=model) and [Agent](/introduction?id=agent) are very important in this document.
+The primary work of this tool is generating a `state changeable agent` from its `state producible model`. An agent changes state according to what its model produces out. So, [Model](/introduction?id=model) and [Agent](/introduction?id=agent) are very important concepts in this document.
 
-## motivation
+## Motivation
 
-The core library [agent-reducer](https://www.npmjs.com/package/agent-reducer) is a powerful independent tool for managing state changes. But it can not work in `react` directly, so we designed this library to connect `agent-reducer` with `react hooks`. 
+The core library [agent-reducer](https://www.npmjs.com/package/agent-reducer) is a powerful independent tool for managing state changes. But it can not work in `react` system directly, so we designed this library to connect `agent-reducer` with `react hooks`. 
 
 ## Concept
 
-There are two concepts we have mentioned above, `Model` and `Agent`. And we will explain the details about these concepts in this section.
+There are two concepts we have mentioned above, `Model` and `Agent`. They will  be explained in this section.
 
 #### Model
 
-`Model` is a class or an object which describes what kind of data you want to maintian and how to produce new one. We can describe the maintainable data with a property name `state`, and prepare some state producing methods in `Model`. In `agent-reducer`, concept `Model` has another name `OriginAgent`, but here, we call it `Model`.
+`Model` is a class or an object which describes what kind of data you want to maintian and how to produce a new one. You can describe a maintainable data with property name `state` in `Model`, and prepare some state producible methods beside. In `agent-reducer`, concept `Model` has another name `OriginAgent`, but here, we call it `Model`.
 
-1. Property `state` stores the data you want to maintian, it can be any type. Do not modify `state` manual, it is very important.
+1. Property `state` stores the data you want to maintian, it can be any type. Do not modify `state` manually, this may causes some problems.
 2. `method` is a function for producing a new `state`. You can consider what returns from a `method` as a new state.
 
 This is a `Model` example:
@@ -24,7 +24,7 @@ import {OriginAgent} from 'agent-reducer';
 
 // model
 class CountAgent implements OriginAgent<number> {
-    // with a initial state
+    // set a initial state
     state = 0;
 
     // use arrow function to produce a new state
@@ -51,9 +51,9 @@ class CountAgent implements OriginAgent<number> {
 
 #### Agent
 
-`Agent` is a Proxy object, it provides a latest state and methods for changing state. You can create an `Agent` object by using api useAgentReducer. A class model is always transformed into a instance object first by this api, then to be proxied as an `Agent` object. 
+`Agent` is a Proxy object, it provides a newest state and some methods base on the same name methods in its `Model` for changing state. You can create an `Agent` object by using api useAgentReducer with a `Model`. 
 
-The state of `Agent` object always keeps equal with its model state.
+The state of `Agent` object always keeps equal with its `Model` state.
 
 ```typescript
 import {OriginAgent} from 'agent-reducer';
@@ -90,11 +90,11 @@ The `use-agent-reducer` package lives in [npm](https://www.npmjs.com/get-npm). T
 ```
 npm i use-agent-reducer
 ```
-You'd better add `agent-reducer` into your package.json dependencies too. When  you are installing package `use-agent-reducer`, a `agent-reducer` package is always brought into your dependencies, but this can not resolve the problem: when you are developing with `use-agent-reducer`, you can not find `agent-reducer` helper easily. 
+You'd better add `agent-reducer` into your package.json dependencies too. When  you are installing package `use-agent-reducer`, a `agent-reducer` package is always brought into your `node_modules` directory, but this is not helpful for using `agent-reducer` API. 
 
 ## Getting started
 
-This section describes how to create a model, and how to call `agent-reducer` for help. After reading this section, you can master the basic usage of `use-agent-reducer`. 
+This section describes how to create a model, and how to call `agent-reducer` API for help. After reading this section, you can master the basic usage of `use-agent-reducer`. 
 
 #### create model
 

docs/zh/_sidebar.md

@@ -2,4 +2,5 @@
 * [介绍](/zh/introduction.md)
 * [教程](/zh/tutorial.md)
 * [引导](/zh/guides.md)
-* [API 文档](/zh/api.md)
+* [API 文档](/zh/api.md)
+* [更新日志](/zh/changes.md)

docs/zh/api.md

@@ -12,7 +12,7 @@ function useAgentReducer<T extends OriginAgent<S>, S>(
 ): T
 ```
 
-* originAgent - 模型，可以是 class 也可以是 object 。
+* entry - 模型，可以是 class 也可以是 object 。
 * middleWareOrEnv - 可选参数，如果想要设置 MiddleWare ，就传入 MiddleWare ，如果不想使用 MiddleWare ，想要配置运行环境参数，则传入环境配置。
 * env - 可选参数，如果想同时使用 MiddleWare 和 环境配置，请通过该参数传入环境配置。
 
@@ -41,19 +41,53 @@ function useMiddleWare<T extends OriginAgent<S>, S>(
 
 [使用案例](/zh/tutorial?id=use-middleware).
 
-## useAgent
+## useAgentSelector
+
+这是一个 react hook 方法，可用于提取被共享模型 state 中的部分数据，若被提取数据保持不变，则不会触发组件渲染。
+
+```typescript
+export function useAgentSelector<T extends OriginAgent<S>, S, R>(
+  entry: T,
+  mapStateCallback: (state: T['state']) => R,
+): R
+```
+
+* entry - 模型实例 object 。
+* mapStateCallback - state 提取方法，用于提取当前模型实例 state 的部分数据，如果被提取数据保持不变则不会触发组件渲染。
+  
+该方法返回值即为被提取数据。
+
+## useAgentMethods
+
+这是一个 react hook 方法，可用于提取被共享模型中的方法，该 hook 本身不会触发当前使用组件渲染。
+
+```typescript
+export function useAgentMethods<T extends OriginAgent<S>, S>(
+  entry: T,
+  middleWareOrEnv?: MiddleWare | RunEnv,
+  env?: Omit<RunEnv, 'legacy'>,
+): Omit<T, 'state'>
+```
+
+* entry - 模型实例 object 。
+* middleWareOrEnv - 可选参数，如果想要设置 MiddleWare ，就传入 MiddleWare ，如果不想使用 MiddleWare ，想要配置运行环境参数，则传入环境配置。
+* env - 可选参数，如果想同时使用 MiddleWare 和 环境配置，请通过该参数传入环境配置。
+
+该方法返回值为忽略了 state 数据的模型实例。
+
+## ~~useAgent~~
 
 (不推荐)
 
 当前 API 接口为老版本的 [useAgentReducer](/zh/api?id=useagentreducer)。
 
-## useBranch
+## ~~useBranch~~
 
 (不推荐)
 
 当前 API 接口为老版本的 [useMiddleWare](/zh/api?id=usemiddleware)。
 
-## useMiddleActions
+## ~~useMiddleActions~~
 
 (不推荐)
 
@@ -69,7 +103,7 @@ function useMiddleActions<T extends OriginAgent<S>, P extends MiddleActions<T, S
 * middleActions - 继承 MiddleActions 的 class
 * middleWare - MiddleWares
 
-## AgentProvider
+## ~~AgentProvider~~
 
 (不推荐)
 
@@ -86,7 +120,7 @@ interface Props{
 * value - `Agent` 代理对象，用于 children 共享。
 * children - react 组件
 
-## useAgentContext
+## ~~useAgentContext~~
 
 (不推荐)
 
@@ -98,7 +132,7 @@ interface Props{
 function useAgentContext<T extends OriginAgent>(): T
 ```
 
-## useParent
+## ~~useParent~~
 
 (不推荐)