发布3.1.0

Author: wangyi

README.md

@@ -183,15 +183,32 @@ OriginAgent : class | new class();
 
 MiddleWare : 见 agent-reducer
 
-env : {strict?:boolean}
+env : {strict?:boolean,legacy?:boolean}
 
 const agent = useAgent(OriginAgent, MiddleWare? | env?, env?);
 ```
-`env`参数，我们只开放了strict，如果希望在处理之后，渲染之前立即改变`this.state`可以把它设置为`false`。
+`env`参数，如果希望在处理之后，渲染之前立即改变`this.state`可以把`env.strict`设置为`false`;
+如果希望使用 1.* 版本的`agent-reducer`，可以将`env.legacy`设置为`true`，
+也可以使用`agent-reducer`的`globalConfig`进行全局设置。
 
 关于其他参数含义可参考：[agent-reducer](https://www.npmjs.com/package/agent-reducer)
 
-2 . useMiddleActions ( >=2.0.0 3.0.0:接口更改 )
+2 . useAgentReducer ( >=3.1.0 )
+
+用来创建一个稳定的agent对象，可用于代替`useState`、`useReducer`，用法与`useAgent`一样，
+但使用的`agent-reducer`版本锁死在 3.* 版本，不受全局环境影响，`env.legacy`对该方法不生效。
+
+```
+OriginAgent : class | new class();
+
+MiddleWare : 见 agent-reducer
+
+env : {strict?:boolean}
+
+const agent = useAgentReducer(OriginAgent, MiddleWare? | env?, env?);
+```
+
+3 . useMiddleActions ( >=2.0.0 3.0.0:接口更改 )
 
 配合`useAgent`使用，用于管理调用`agent`，用于异步请求后`dispatch`或做其他任何事情。
 
@@ -208,7 +225,7 @@ const middles = useMiddleActions(Middles,agent?,...MiddleWare|LifecycleMiddleWar
 ```
 关于参数含义可参考：[agent-reducer](https://www.npmjs.com/package/agent-reducer)
 
-3 . useMiddleWare ( >=2.0.0 )
+4 . useMiddleWare ( >=2.0.0 ) ~~useBranch ( <2.0.0 )~~
 
 复制`agent`，获得一个拥有可控生命周期的`agent`，有点类似git的分支概念，复制版与原版`agent`的非方法属性完全同步。
 可通过附加`MiddleWare`或`LifecycleMiddleWare`控制复制版`agent`的特性。
@@ -220,7 +237,7 @@ const branch=useMiddleWare(agent, MiddleWare | LifecycleMiddleWare);
 ```
 关于参数含义和`LifecycleMiddleWares`可参考：[agent-reducer](https://www.npmjs.com/package/agent-reducer)
 
-4 . AgentProvider
+5 . AgentProvider
 
 `use-agent-reducer`提供的一个`react` Context.Provider组件，可为当前范围内所有需要使用已有`agent`的子组件提供Context便利。
 
@@ -235,7 +252,7 @@ return (
 ```
 `useMiddleActions`和对应的模型可以在任何地方直接引用 ( import )，所以就不为其设定provider了。
 
-5 . useAgentContext ( >=2.0.0 ) ~~useParent ( <2.0.0 )~~
+6 . useAgentContext ( >=2.0.0 ) ~~useParent ( <2.0.0 )~~
 
 配合`AgentProvider`使用，直接读取最近一层AgentProvider传入的agent对象。
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-agent-reducer",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "main": "./index.js",
   "author": "Jimmy.Harding",
   "description": "the purpose of this project is make useReducer classify",
@@ -31,10 +31,10 @@
   "peerDependencies": {
     "react": ">=16.8.0",
     "react-dom": ">=16.8.0",
-    "agent-reducer": "^3.0.0"
+    "agent-reducer": "^3.1.0"
   },
   "dependencies": {
-    "agent-reducer": "^3.0.0"
+    "agent-reducer": "^3.1.1"
   },
   "devDependencies": {
     "@babel/core": "7.2.2",

src/index.ts

@@ -49,10 +49,11 @@ class AgentShipping {
 const AgentContext = React.createContext<AgentShipping | null>(null);
 
 export type RunEnv = {
-    strict?: boolean
+    strict?: boolean,
+    legacy?:boolean
 };
 
-export function useAgent<T extends OriginAgent<S>,S>(entry: T | { new(): T }, middleWareOrEnv?: MiddleWare | RunEnv, env?: RunEnv): T {
+export function useAgentReducer<T extends OriginAgent<S>, S>(entry: T | { new(): T }, middleWareOrEnv?: MiddleWare | RunEnv, env?: Omit<RunEnv,'legacy'>): T {
 
     const runEnv = typeof middleWareOrEnv !== 'function' ? middleWareOrEnv : env;
 
@@ -61,6 +62,7 @@ export function useAgent<T extends OriginAgent<S>,S>(entry: T | { new(): T }, mi
     let {current: reducer} = useRef(createAgentReducer(entry, middleWare, {
         ...runEnv,
         ...env,
+        legacy: false,
         expired: false,
         updateBy: 'manual'
     }));
@@ -78,29 +80,65 @@ export function useAgent<T extends OriginAgent<S>,S>(entry: T | { new(): T }, mi
     return reducer.agent;
 }
 
+export function useAgent<T extends OriginAgent<S>, S>(entry: T | { new(): T }, middleWareOrEnv?: MiddleWare | RunEnv, env?: RunEnv): T {
+
+    const runEnv = typeof middleWareOrEnv !== 'function' ? middleWareOrEnv : env;
+
+    const middleWare = typeof middleWareOrEnv === 'function' ? middleWareOrEnv : undefined;
+
+    let {current: reducer} = useRef(createAgentReducer(entry, middleWare, {
+        ...runEnv,
+        ...env,
+        expired: false,
+        updateBy: 'manual'
+    }));
+
+    const [state, dispatch] = useReducer(reducer, reducer.initialState);
+
+    reducer.update(state, dispatch);
+
+    useEffect(() => {
+        return () => {
+            reducer.env.expired = true;
+        }
+    }, []);
+
+    return reducer.agent;
+
+}
+
 export function useMiddleActions<T extends OriginAgent<S>, P extends MiddleActions<T, S>, S = any>(
     middleActions: { new(agent: T): P },
     agent?: T,
     ...middleWare: (MiddleWare | LifecycleMiddleWare)[]
 ): P {
-    const ref= useRef(useAgentMiddleActions(middleActions,agent,...middleWare) as P);
+    const ref = useRef(useAgentMiddleActions(middleActions, agent, ...middleWare) as P);
     return ref.current;
 }
 
-export function useMiddleWare<T extends OriginAgent<S>,S>(agent: T, middleWare: MiddleWare | LifecycleMiddleWare) {
-    const {current} = useRef(useAgentMiddleWare(agent, middleWare));
+export function useMiddleWare<T extends OriginAgent<S>, S>(agent: T, ...middleWare: (MiddleWare | LifecycleMiddleWare)[]) {
+    const {current} = useRef(useAgentMiddleWare(agent, ...middleWare));
     return current;
 }
 
-export function AgentProvider<T extends OriginAgent<S>,S>({value, children}: { readonly value: T, readonly children?: ReactNodeLike }) {
+/**
+ * @deprecated
+ * @param agent
+ * @param middleWare
+ */
+export function useBranch<T extends OriginAgent<S>, S>(agent: T, middleWare: MiddleWare | LifecycleMiddleWare) {
+    return useMiddleWare(agent, middleWare);
+}
+
+export function AgentProvider<T extends OriginAgent<S>, S>({value, children}: { readonly value: T, readonly children?: ReactNodeLike }) {
     let ref = useRef(new AgentShipping(value));
     useEffect(() => {
         ref.current.update(value);
     }, [value.state]);
     return React.createElement(AgentContext.Provider, {value: ref.current}, children);
 }
 
-export function useAgentContext<T extends OriginAgent>() {
+export function useAgentContext<T extends OriginAgent>():T {
 
     const shipping = useContext(AgentContext);
 
@@ -119,4 +157,11 @@ export function useAgentContext<T extends OriginAgent>() {
     }, [shipping]);
 
     return ref.current as T;
+}
+
+/**
+ * @deprecated
+ */
+export function useParent<T extends OriginAgent>():T {
+    return useAgentContext<T>();
 }

test/spec/basic.spec.tsx

@@ -1,8 +1,24 @@
 import React, {useEffect} from "react";
 import {renderHook, act} from "@testing-library/react-hooks";
 import {render} from "@testing-library/react";
-import {AgentProvider, useAgent, useAgentContext, useMiddleActions, useMiddleWare} from "../../src";
-import { MiddleActions, middleWare, MiddleWarePresets, OriginAgent} from "agent-reducer";
+import {
+    AgentProvider,
+    useAgent,
+    useAgentContext,
+    useAgentReducer,
+    useBranch,
+    useMiddleActions,
+    useMiddleWare
+} from "../../src";
+import {
+    BranchResolvers,
+    clearGlobalConfig,
+    globalConfig,
+    MiddleActions,
+    middleWare,
+    MiddleWarePresets,
+    OriginAgent
+} from "agent-reducer";
 import {ReactNodeLike} from "prop-types";
 
 describe('使用基本的useAgent', () => {
@@ -192,4 +208,84 @@ describe('使用useMiddleWare复制一个专注一种任务模式的agent', () =
         expect(div.innerHTML).toBe('1');
     });
 
+});
+
+describe('使用 3.1.0+ 对 1.* 版的兼容功能',()=>{
+
+    beforeAll(()=>{
+        //在顶级将环境设置为 1.* 模式。
+        globalConfig({env:{legacy:true}});
+    });
+
+    afterAll(()=>{
+        //注意：正式使用时，不要调用该方法
+        clearGlobalConfig();
+    })
+
+    class CountAgent implements OriginAgent<number> {
+
+        state = 0;
+
+        stepUp = (): number => this.state + 1;
+
+        stepDown = (): number => this.state - 1;
+
+        sum = (...counts: number[]): number => this.state + counts.reduce((r, c): number => r + c, 0);
+
+        step = (isUp: boolean) => isUp ? this.stepUp() : this.stepDown();
+
+        doubleDispatchStep(isUp: boolean) {
+            return isUp ? this.stepUp() : this.stepDown();
+        }
+
+        // 在 1.* 中起作用，在 3.1.0+ 中需要使用 MiddleWare 的方法
+        async callingSum(tms: number) {
+            await new Promise((r) => setTimeout(r, tms * 100));
+            return this.sum(tms); // 注意：3.1.0+ 中 this.sum 是个纯粹的方法调用，本身并不会修改 this.state，所以需要 return，否则this.state将变成undefined
+        }
+
+        async callingSumByLegacy(tms: number) {
+            await new Promise((r) => setTimeout(r, tms * 100));
+            this.sum(tms); // 注意：1.* 中因为 this 的层层代理作用，加上 middle-action 作用， this.sum 会修改 this.state，所以不需要 return
+        }
+
+    }
+
+    test('1.* 用法',async ()=>{
+        // useAgent 会收到全局 env.legacy 影响，变成 1.* 支持版本
+        const {result: ar} = renderHook(() => useAgent(CountAgent));
+        const {result: mr} = renderHook(() => useBranch(ar.current, BranchResolvers.takeLatest()));
+        await act(async () => {
+            const first = mr.current.callingSumByLegacy(5);
+            const second = mr.current.callingSumByLegacy(2);
+            await Promise.all([first, second]);
+        });
+        expect(ar.current.state).toBe(2);
+    });
+
+    test('3.* 用法',async ()=>{
+        // useAgentReducer 只支持 3.0.0 以上写法，并忽略全局 env.legacy 设置
+        const {result: ar} = renderHook(() => useAgentReducer(CountAgent));
+        const {result: mr} = renderHook(() => useMiddleWare(ar.current, MiddleWarePresets.takeLatest()));
+        await act(async () => {
+            const first = mr.current.callingSum(5);
+            const second = mr.current.callingSum(2);
+            await Promise.all([first, second]);
+        });
+        expect(ar.current.state).toBe(2);
+    });
+
+    test('3.* 使用 1.* 的写法',async ()=>{
+        // useAgentReducer 只支持 3.0.0 以上写法，并忽略全局 env.legacy 设置
+        const {result: ar} = renderHook(() => useAgentReducer(CountAgent));
+        const {result: mr} = renderHook(() => useMiddleWare(ar.current, MiddleWarePresets.takeLatest()));
+        await act(async () => {
+            const first = mr.current.callingSumByLegacy(5);
+            // 注意：3.1.0+ 中 this.sum 是个纯粹的方法调用，本身并不会修改 this.state，所以需要 return，否则this.state将变成undefined
+            const second = mr.current.callingSumByLegacy(2);
+            await Promise.all([first, second]);
+        });
+        expect(ar.current.state).toBe(undefined);
+    });
+
 });