add equalityFn and shallowEqual

Author: wangyi

.eslintignore

@@ -1,4 +1,5 @@
 .eslintrc.js
+example/
 test/
 jest.config.js
 babel.config.js

docs/api.md

@@ -49,11 +49,13 @@ This api function is a react hook, it can be used to extract data from a sharing
 export function useAgentSelector<T extends OriginAgent<S>, S, R>(
   entry: T,
   mapStateCallback: (state: T['state']) => R,
+  equalityFn?:(prev: R, current: R) => boolean,
 ): R
 ```
 
 * entry - the model instance object.
-* mapStateCallback - a callback function for extracting data from model state.
+* mapStateCallback - a callback function for extracting data from model state. The callback param state is a current model state.
+* equalityFn - optional param, a callback function to compare the previous extracted data with the current one. If this function returns `true`, `useAgentSelector` do not make its consumer (react component) rerender, no matter if the extracted data changes. Param `prev` is the previous extracted data, and param `current` is the current one.
 
 This function returns data extracted from a model state directly.
 
@@ -75,6 +77,19 @@ export function useAgentMethods<T extends OriginAgent<S>, S>(
 
 This function returns a model like instance which has an empty state property. It only provides model methods.
 
+## shallowEqual
+
+This api function is a shortcut `equalityFn` callback for using api [useAgentSelector](/api?id=useagentselector). It compares `prev` extracted data and `current` extracted data with a shallow `key-value` equality comparator.
+
+```typescript
+function shallowEqual<R>(prev:R, current:R):boolean
+```
+
+* prev - one data for comparing with another.
+* current - one data for comparing with another.
+
+It returns a `boolean` value. If the two params are equal, it returns `true`, otherwise it returns `false`. 
+
 ## ~~useAgent~~
 
 (not recommend)

docs/changes.md

@@ -1,4 +1,9 @@
 ## v3.2.5 2021-04-10
 
 * [new] add API [useAgentSelector](/api?id=useagentselector) for optimizing the model sharing.
-* [new] add API [useAgentMethods](/api?id=useagentmethods) for optimizing the model sharing.
+* [new] add API [useAgentMethods](/api?id=useagentmethods) for optimizing the model sharing.
+
+## v3.2.7 2021-04-11
+
+* [update] API [useAgentSelector](/api?id=useagentselector) add a new param `equalityFn` for comparing current extracted data with the previous one, and then deside if its consumer (react component) should be rerendered.
+* [new] add API [shallowEqual](/api?id=shallowequal) for a shallow comparing with two data.

docs/guides.md

@@ -211,11 +211,12 @@ Be careful in `env.strict`, you'd better not set it to be `false`. For it will m
 
 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.  
+API [useAgentSelector](/api?id=useagentselector) extracts data from a state, and only the extracted data change may cause its consumer (react component) rerender. You can also use `equalityFn` to show if the consumer should rerender with a new extracted data.
+The `shallowEqual` is a simple `equalityFn`, you can use it directly.
 
 ```typescript
 import {weakSharing} from 'agent-reducer';
-import {useAgentSelector} from 'use-agent-reducer';
+import {useAgentSelector,shallowEqual} from 'use-agent-reducer';
 
 // model sharing reference
 const sharingRef = weakSharing(()=> Model);
@@ -226,9 +227,24 @@ const sharingRef = weakSharing(()=> 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);
+
+// tell `useAgentSelector` to rerender consumer (component),
+// while equalityFn returns false.
+// The param `prev` is the previous extracted data, 
+// and `current` is the current extracted data
+function equalityFn<R>(prev:R, current:R):boolean{
+    // `shallowEqual` compares the `key-values` 
+    // between `prev` and `current`, 
+    // if all of them are equal, it returns true.
+    // This function only compares data own properties.
+    // You can also use `shallowEqual` directly to `useAgentSelector`.
+    return shallowEqual(prev, current);
+}
+
+const renderNeeds = useAgentSelector(sharingRef.current, ({renderNeeds})=> renderNeeds,equalityFn);
 ```
 
-API `useAgentMethods` only provides methods from a model like instance, it never causes a rerender.
+API [useAgentMethods](/api?id=useagentmethods) only provides methods from a model like instance, it never causes a rerender.
 
 ```typescript
 import {weakSharing, MiddleWarePresets} from 'agent-reducer';

docs/tutorial.md

@@ -682,7 +682,7 @@ check [sourceCode](https://github.com/filefoxper/use-agent-reducer/blob/master/e
 model:
 
 ```typescript
-import {middleWare, MiddleWarePresets, MiddleWares, OriginAgent} from "agent-reducer";
+iimport {middleWare, MiddleWarePresets, MiddleWares, OriginAgent} from "agent-reducer";
 import {FetchParams, PriorLevel, SearchParams, State, Todo} from "@/type";
 import {fetchTodoList, fetchTodoListWithDelay} from "@/service";
 
@@ -727,9 +727,8 @@ export default class SimpleTodoList implements OriginAgent<State> {
     private async fetchDataSource(searchParams: SearchParams, currentPage: number, pageSize: number): Promise<State> {
         const fetchParams = {...searchParams, currentPage, pageSize};
         const {content: dataSource, total} = await fetchTodoList(fetchParams);
-        // we do not copy searchParams here,
-        // we can use new feature of 'agent-reducer@3.2.0' to update state synchronously in component.
-        return {searchParams, dataSource, currentPage, pageSize, total};
+        // Copy searchParams here
+        return {searchParams:{...searchParams}, dataSource, currentPage, pageSize, total};
     }
 
     // this method should works with a page navigation
@@ -752,8 +751,8 @@ export default class SimpleTodoList implements OriginAgent<State> {
 page:
 
 ```typescript
-import React, {memo, useCallback, useEffect, useState} from 'react';
-import {RunEnv, useAgentReducer, useMiddleWare} from "use-agent-reducer";
+import React, {memo, useCallback, useEffect} from 'react';
+import {RunEnv, useAgentReducer, useMiddleWare, useAgentMethods, useAgentSelector} from "use-agent-reducer";
 import SimpleTodoList, {SearchParamsModel} from "./model";
 import {ContentInput, PageContent, PriorLevelSelect, SearchContent} from "@/components";
 import {Button, Pagination, Table} from "antd";
@@ -766,20 +765,30 @@ import {MiddleWarePresets, weakSharing} from "agent-reducer";
 // shares state updating with each other.
 // the model created by `agent-reducer` API `weakSharing`,
 // often be reset back, if there is no living `Agent` built on it.
-const searchParamsModel = weakSharing(()=>SearchParamsModel);
+const searchParamsModel = weakSharing(() => SearchParamsModel);
 
-const simpleTodoList = weakSharing(()=>SimpleTodoList);
+const simpleTodoList = weakSharing(() => SimpleTodoList);
 
 const SearchParamComponent = memo(() => {
 
-    const {state, changeSearchContent, changeSearchPriorLevel} = useAgentReducer(searchParamsModel.current);
+    const {state, changeSearchContent, changeSearchPriorLevel, feedback} = useAgentReducer(searchParamsModel.current);
 
     // `Agent` bases on object simpleTodoList,
     // If we use class `SimpleTodoList` as a model,
     // `useAgentReducer` should create a private model object inside,
     // and then, no state updating can be shared now.
     // So, model sharing only works on 'Agents' base on a same model object.
-    const {search} = useAgentReducer(simpleTodoList.current);
+    // API `useAgentMethods` can optimize our component,
+    // it never leads its consumer (component) rerender.
+    const {search} = useAgentMethods(simpleTodoList.current);
+
+    // API `useAgentSelector` can optimize our component,
+    // it only leads its consumer (component) rerender, when the extracted data changes.
+    const searchParams = useAgentSelector(simpleTodoList.current, ({searchParams}) => searchParams);
+
+    useEffect(() => {
+        feedback(searchParams);
+    }, [searchParams]);
 
     const handleSubmit = useCallback(async () => {
         // submit current searchParams with model object `simpleTodoList`
@@ -799,8 +808,6 @@ const SearchParamComponent = memo(() => {
 
 export default function NewFeatures() {
 
-    const {feedback} = useAgentReducer(searchParamsModel.current);
-
     // `Agent` bases on model `simpleTodoList`
     const agent = useAgentReducer(simpleTodoList.current);
 
@@ -818,7 +825,6 @@ export default function NewFeatures() {
     // handle page change
     const handleChangePage = useCallback(async (currentPage: number, pageSize: number = 10) => {
         // feedback searchParams with model object `searchParamsModel`.
-        feedback(state.searchParams);
         await changePageLatest(currentPage, pageSize);
     }, [state]);
 
@@ -846,6 +852,6 @@ export default function NewFeatures() {
 }
 ```
 
-`Agents` base on a same model object can update state synchronously. Using this feature of `agent-reducer` can make your code more simple.
+`Agents` base on a same model object can update state synchronously. Using this feature of `agent-reducer` can make your code more simple. And use API [useAgentSelector](/api?id=useagentselector) and [useAgentMethods](/api?id=useagentmethods) can make your component render more less with `agent-reducer` model sharing.
 
 You can do more things to make a search page model better.

docs/zh/api.md

@@ -49,11 +49,13 @@ function useMiddleWare<T extends OriginAgent<S>, S>(
 export function useAgentSelector<T extends OriginAgent<S>, S, R>(
   entry: T,
   mapStateCallback: (state: T['state']) => R,
+  equalityFn?:(prev: R, current: R) => boolean,
 ): R
 ```
 
 * entry - 模型实例 object 。
 * mapStateCallback - state 提取方法，用于提取当前模型实例 state 的部分数据，如果被提取数据保持不变则不会触发组件渲染。
+* equalityFn - 可选，用于对比 mapStateCallback 在模型 state 改变前后产生的数据，如果该函数返回 `true`，则 `useAgentSelector` 忽略 mapStateCallback 提取值的变化状况，不触发组件渲染。
 
 该方法返回值即为被提取数据。
 
@@ -75,6 +77,19 @@ export function useAgentMethods<T extends OriginAgent<S>, S>(
 
 该方法返回值为忽略了 state 数据的模型实例。
 
+## shallowEqual
+
+该方法可对两个数据进行浅对比，并判断两个数据是否等价。可用作[useAgentSelector](/zh/api?id=useagentselector)的`equalityFn`回调参数。
+
+```typescript
+function shallowEqual<R>(prev:R, current:R):boolean
+```
+
+* prev - 对比数据之一.
+* current - 对比数据之一.
+
+如果浅对比等价则返回 `true` ，否则返回 `false` 。
+
 ## ~~useAgent~~
 
 (不推荐)

docs/zh/changes.md

@@ -1,4 +1,9 @@
 ## v3.2.5 2021-04-10
 
 * [新增] 添加 API [useAgentSelector](/zh/api?id=useagentselector)， 用于优化模型共享的组件性能。
-* [新增] 添加 API [useAgentMethods](/zh/api?id=useagentmethods)， 用于优化模型共享的组件性能。
+* [新增] 添加 API [useAgentMethods](/zh/api?id=useagentmethods)， 用于优化模型共享的组件性能。
+
+## v3.2.7 2021-04-11
+
+* [更新] API [useAgentSelector](/zh/api?id=useagentselector) 增加提取数据等价对比功能，进一步优化性能。
+* [新增] 添加 API [shallowEqual](/zh/api?id=shallowequal)，用于快速浅对比两个数据是否等价。

docs/zh/guides.md

@@ -203,11 +203,11 @@ describe("设置运行环境 RunEnv",()=>{
 
 通过使用 `agent-reducer` 的模型共享特性，我们可以很容易地在不同组件间同步渲染数据，但这也给我们的组件带来了一定的负担，因为只要模型 state 有变更，无论变更数据是否对当前组件有用，必然会引起渲染行为，这不是我们愿意看到的。自 `use-agent-reducer@3.2.5` 起，我们提供了相关的性能优化接口：`useAgentSelector` 、 `useAgentMethods`。
 
-API 接口 `useAgentSelector` ，可用于提取当前组件需要的部分数据，如果该部分数据没有发生改变，则不会触发当前组件的渲染。
+API 接口 [useAgentSelector](/zh/api?id=useagentselector)  ，可用于提取当前组件需要的部分数据，如果该部分数据没有发生改变，则不会触发当前组件的渲染。通过使用 `equalityFn` 对前后两次 state 提取数据进行对比，可进一步优化渲染性能，若对比返回值为 `true` ，则忽略提取数据的改变状况，不触发当前组件的渲染。
 
 ```typescript
 import {weakSharing} from 'agent-reducer';
-import {useAgentSelector} from 'use-agent-reducer';
+import {useAgentSelector, shallowEqual} from 'use-agent-reducer';
 
 // 共享模型引用
 const sharingRef = weakSharing(()=> Model);
@@ -217,9 +217,18 @@ const sharingRef = weakSharing(()=> Model);
 // 使用共享模型实例，通过 callback 从 state 中提取当前组件需的要数据，
 // 如果提取数据保持不变，则不会触发组件渲染
 const renderNeeds = useAgentSelector(sharingRef.current, (state)=> state.renderNeeds);
+
+// 提取数据对比器，若返回 true ，则不触发组件渲染
+function equalityFn<R>(prev:R, current:R):boolean{
+    // 浅对比 API，方便使用者，
+    // 可直接用在 useAgentSelector 上
+    return shallowEqual(prev, current);
+}
+
+const renderNeeds = useAgentSelector(sharingRef.current, (state)=> state.renderNeeds,equalityFn);
 ```
 
-API 接口 `useAgentMethods` ， 不会触发当前组件渲染，该接口只提供了当前组件需要使用的模型方法。
+API 接口 [useAgentMethods](/zh/api?id=useagentmethods) ， 不会触发当前组件渲染，该接口只提供了当前组件需要使用的模型方法。
 
 ```typescript
 import {weakSharing, MiddleWarePresets} from 'agent-reducer';

example/package.json

@@ -19,8 +19,8 @@
     "moment": "^2.24.0",
     "classnames": "^2.2.6",
     "babel-polyfill": "^6.26.0",
-    "agent-reducer": "3.2.6",
-    "use-agent-reducer": "3.2.3"
+    "agent-reducer": "3.2.7",
+    "use-agent-reducer": "3.2.5"
   },
   "devDependencies": {
     "@babel/core": "7.2.2",

example/src/newFeatures/index.tsx

@@ -1,5 +1,5 @@
-import React, {memo, useCallback, useEffect, useState} from 'react';
-import {RunEnv, useAgentReducer, useMiddleWare} from "use-agent-reducer";
+import React, {memo, useCallback, useEffect} from 'react';
+import {RunEnv, useAgentReducer, useMiddleWare, useAgentMethods, useAgentSelector} from "use-agent-reducer";
 import SimpleTodoList, {SearchParamsModel} from "./model";
 import {ContentInput, PageContent, PriorLevelSelect, SearchContent} from "@/components";
 import {Button, Pagination, Table} from "antd";
@@ -12,20 +12,30 @@ import {MiddleWarePresets, weakSharing} from "agent-reducer";
 // shares state updating with each other.
 // the model created by `agent-reducer` API `weakSharing`,
 // often be reset back, if there is no living `Agent` built on it.
-const searchParamsModel = weakSharing(()=>SearchParamsModel);
+const searchParamsModel = weakSharing(() => SearchParamsModel);
 
-const simpleTodoList = weakSharing(()=>SimpleTodoList);
+const simpleTodoList = weakSharing(() => SimpleTodoList);
 
 const SearchParamComponent = memo(() => {
 
-    const {state, changeSearchContent, changeSearchPriorLevel} = useAgentReducer(searchParamsModel.current);
+    const {state, changeSearchContent, changeSearchPriorLevel, feedback} = useAgentReducer(searchParamsModel.current);
 
     // `Agent` bases on object simpleTodoList,
     // If we use class `SimpleTodoList` as a model,
     // `useAgentReducer` should create a private model object inside,
     // and then, no state updating can be shared now.
     // So, model sharing only works on 'Agents' base on a same model object.
-    const {search} = useAgentReducer(simpleTodoList.current);
+    // API `useAgentMethods` can optimize our component,
+    // it never leads its consumer (component) rerender.
+    const {search} = useAgentMethods(simpleTodoList.current);
+
+    // API `useAgentSelector` can optimize our component,
+    // it only leads its consumer (component) rerender, when the extracted data changes.
+    const searchParams = useAgentSelector(simpleTodoList.current, ({searchParams}) => searchParams);
+
+    useEffect(() => {
+        feedback(searchParams);
+    }, [searchParams]);
 
     const handleSubmit = useCallback(async () => {
         // submit current searchParams with model object `simpleTodoList`
@@ -45,8 +55,6 @@ const SearchParamComponent = memo(() => {
 
 export default function NewFeatures() {
 
-    const {feedback} = useAgentReducer(searchParamsModel.current);
-
     // `Agent` bases on model `simpleTodoList`
     const agent = useAgentReducer(simpleTodoList.current);
 
@@ -64,7 +72,6 @@ export default function NewFeatures() {
     // handle page change
     const handleChangePage = useCallback(async (currentPage: number, pageSize: number = 10) => {
         // feedback searchParams with model object `searchParamsModel`.
-        feedback(state.searchParams);
         await changePageLatest(currentPage, pageSize);
     }, [state]);