Added useAsyncState and useAsyncWatcher hooks;

DigitalBrainJS · DigitalBrainJS · commit 861b2a4d11f1 · 2021-05-17T17:29:38.000+03:00
diff --git a/README.md b/README.md
@@ -318,6 +318,66 @@ export default function TestComponent(props) {
 }
 ````
 
+### useAsyncState
+
+A simple enhancement of the useState hook for use inside async routines. 
+The only difference, the setter function returns a promise, that will be resolved with the current raw state value.
+If no arguments provided, it will return the current raw state value without changing the state.
+It's not guaranteed that the resolved state is the final computed state value.
+
+````javascript
+export default function TestComponent7(props) {
+
+  const [counter, setCounter] = useAsyncState(0);
+
+  const [fn, cancel, pending, done, result, err] = useAsyncCallback(function* (value) {
+    return (yield cpAxios(`https://rickandmortyapi.com/api/character/${value}`)).data;
+  }, {states: true})
+
+  return (
+    <div className="component">
+      <div>{pending ? "loading..." : (done ? err ? err.toString() : JSON.stringify(result, null, 2) : "")}</div>
+      <button onClick={async()=>{
+        const updatedValue= await setCounter((counter)=> counter + 1);
+        await fn(updatedValue); // pass the state value as an argument
+      }}>Inc</button>
+      {<button onClick={cancel} disabled={!pending}>Cancel async effect</button>}
+    </div>
+  );
+}
+````
+
+### useAsyncWatcher
+
+This hook is a promisified abstraction on top of the `useEffect` hook. The hook returns the watcher function that resolves
+its promise when one of the watched dependencies have changed.
+
+````javascript
+export default function TestComponent7(props) {
+  const [value, setValue] = useState(0);
+
+  const [fn, cancel, pending, done, result, err] = useAsyncCallback(function* () {
+    console.log('inside callback the value is:', value);
+    return (yield cpAxios(`https://rickandmortyapi.com/api/character/${value}`)).data;
+  }, {states: true, deps: [value]})
+
+  const callbackWatcher = useAsyncWatcher(fn);
+
+  return (
+    <div className="component">
+      <div className="caption">useAsyncWatcher demo:</div>
+      <div>{pending ? "loading..." : (done ? err ? err.toString() : JSON.stringify(result, null, 2) : "")}</div>
+      <input value={value} type="number" onChange={async ({target}) => {
+        setValue(target.value * 1);
+        const [fn]= await callbackWatcher();
+        await fn();
+      }}/>
+      {<button onClick={cancel} disabled={!pending}>Cancel async effect</button>}
+    </div>
+  );
+}
+````
+
 To learn more about available features, see the c-promise2 [documentation](https://www.npmjs.com/package/c-promise2).
 
 ### Wiki
@@ -352,7 +412,7 @@ Generator context (`this`) refers to the CPromise instance.
 - `error: object` - refers to the error object. This var is always set when an error occurs.
 - `canceled:boolean` - is set to true if the function has been failed with a `CanceledError`.
 
-All these vars are defined on the returned `cancelFn` function and can be alternative reached through
+All these vars defined on the returned `cancelFn` function and can be alternative reached through
 the iterator interface in the following order: 
 ````javascript
 const [cancelFn, done, result, error, canceled]= useAsyncEffect(/*code*/);
@@ -376,16 +436,31 @@ Generator context (`this`) and the first argument (if `options.scopeArg` is set)
 
 #### Available state vars:
 - `pending: boolean` - the function is in the pending state
-- `done: boolean` - the function execution is completed (with success or failure)
+- `done: boolean` - the function execution completed (with success or failure)
 - `result: any` - refers to the resolved function result
-- `error: object` - refers to the error object. This var is always set when an error occurs.
+- `error: object` - refers to the error object. This var always set when an error occurs.
 - `canceled:boolean` - is set to true if the function has been failed with a `CanceledError`.
 
-All these vars are defined on the decorated function and can be alternative reached through
+All these vars defined on the decorated function and can be alternative reached through
 the iterator interface in the following order: 
 ````javascript
-const [decoratedFn, cancelFn, pending, done, result, error, canceled]= useAsyncCallback(/*code*/);
+const [decoratedFn, cancel, pending, done, result, error, canceled]= useAsyncCallback(/*code*/);
 ````
+### useAsyncState([initialValue]): ([value: any, accessor: function])
+#### arguments
+- `initialValue`
+#### returns
+Iterable of:
+- `value: any` - current state value
+- `accessor:(newValue)=>Promise<rawStateValue:any>` - promisified setter function that can be used
+ as a getter if called without arguments
+
+### useAsyncWatcher([...valuesToWatch]): watcherFn
+#### arguments
+- `...valuesToWatch: any` - any values to watch that will be passed to the internal effect hook
+#### returns
+- `watcherFn: ([grabPrevValue= false]): Promise<[newValue, [prevValue]]>` - if the hook is watching one value
+- `watcherFn: ([grabPrevValue= false]): Promise<[...[newValue, [prevValue]]]>` - if the hook is watching multiple values
 
 ## Related projects
 - [c-promise2](https://www.npmjs.com/package/c-promise2) - promise with cancellation, decorators, timeouts, progress capturing, pause and user signals support
diff --git a/lib/use-async-effect.js b/lib/use-async-effect.js
@@ -138,14 +138,14 @@ const useAsyncEffect = (generator, options) => {
 const argsToPromiseMap = new Map();
 
 /**
- * @typedef {function} UseAsyncCallbackDecoratedFn
- * @param {CPromise} scope
+ * @typedef {Function} UseAsyncCallbackDecoratedFn
+ * @param {CPromise} [scope]
  * @property {CancelFn} cancel
- * @returns {function|*}
+ * @returns {*}
  *//**
- * @typedef {function} UseAsyncCallbackDecoratedFn
+ * @typedef {Function} UseAsyncCallbackDecoratedFn
  * @property {CancelFn} cancel
- * @returns {function|*}
+ * @returns {*}
  */
 
 /**
@@ -166,7 +166,7 @@ const useAsyncCallback = (generator, options) => {
         throw TypeError('options must be an object or array');
     }
 
-    const initialState= {
+    const initialState = {
         done: false,
         result: undefined,
         error: undefined,
@@ -179,7 +179,8 @@ const useAsyncCallback = (generator, options) => {
         queue: [],
         pending: 0,
         args: null,
-        state: initialState
+        state: initialState,
+        callback: null
     });
 
     let {
@@ -188,9 +189,9 @@ const useAsyncCallback = (generator, options) => {
         cancelPrevious = false,
         threads,
         queueSize = -1,
-        scopeArg= false,
-        states= false,
-        catchErrors= false
+        scopeArg = false,
+        states = false,
+        catchErrors = false
     } = options && Array.isArray(options) ? {deps: options} : options || {};
 
     if (threads === undefined) {
@@ -205,28 +206,28 @@ const useAsyncCallback = (generator, options) => {
         }
     }
 
-    if (queueSize!==-1 && (!Number.isFinite(queueSize) || queueSize < -1)) {
+    if (queueSize !== -1 && (!Number.isFinite(queueSize) || queueSize < -1)) {
         throw Error('queueSize must be a finite number >=-1');
     }
 
-    const [state, setState]= states? useState(initialState) : [];
+    const [state, setState] = states ? useState(initialState) : [];
 
     const setDeepState = (newState) => {
         if (isEqualObjects(current.state, newState)) return;
         setState(newState);
         current.state = newState;
     }
 
-    const singleThreaded= threads === 1;
+    const singleThreaded = threads === 1;
 
-    const callback = useMemo(()=>{
-        const cancel= (reason) => {
+    const callback = useMemo(() => {
+        const cancel = (reason) => {
             const _reason = isEvent(reason) ? undefined : reason;
             current.promises.forEach(promise => promise.cancel(_reason));
             current.promises.length = 0;
         };
 
-        const fn= (...args) => {
+        const fn = (...args) => {
             const {promises, queue} = current;
             let n;
 
@@ -252,10 +253,10 @@ const useAsyncCallback = (generator, options) => {
                 let started;
 
                 let promise = new CPromise(resolve => {
-                    const start= ()=> {
+                    const start = () => {
                         current.pending++;
 
-                        started= true;
+                        started = true;
 
                         if (states && singleThreaded) {
                             setDeepState({
@@ -277,22 +278,22 @@ const useAsyncCallback = (generator, options) => {
                     start();
                 }).weight(0)
                   .then(resolveGenerator)
-                  [catchErrors? 'done': 'finally']((value, isRejected) => {
+                  [catchErrors ? 'done' : 'finally']((value, isRejected) => {
                     started && current.pending--;
                     removeElement(promises, promise);
                     combine && argsToPromiseMap.delete(promise);
                     queue.length && queue.shift()();
-                    const canceled= !!(isRejected && CanceledError.isCanceledError(value));
+                    const canceled = !!(isRejected && CanceledError.isCanceledError(value));
 
-                    if(canceled && (value.code === E_REASON_UNMOUNTED || value.code === E_REASON_RESTART)){
+                    if (canceled && (value.code === E_REASON_UNMOUNTED || value.code === E_REASON_RESTART)) {
                         return;
                     }
 
                     states && singleThreaded && setDeepState({
                         pending: false,
                         done: true,
-                        error: isRejected? value : undefined,
-                        result: isRejected? undefined : value,
+                        error: isRejected ? value : undefined,
+                        result: isRejected ? undefined : value,
                         canceled
                     });
                 }).weight(0).aggregate();
@@ -304,7 +305,7 @@ const useAsyncCallback = (generator, options) => {
                 return promise;
             }
 
-            const promise = resolveGenerator()[catchErrors? 'done' : 'finally'](() => {
+            const promise = resolveGenerator()[catchErrors ? 'done' : 'finally'](() => {
                 removeElement(promises, promise);
                 combine && argsToPromiseMap.delete(promise);
             }).weight(0).aggregate();
@@ -318,7 +319,9 @@ const useAsyncCallback = (generator, options) => {
             return promise;
         }
 
-        fn.cancel= cancel;
+        fn.cancel = cancel;
+
+        current.callback= fn;
 
         return fn;
     }, deps);
@@ -348,10 +351,74 @@ const useAsyncCallback = (generator, options) => {
 
     return callback;
 }
+/**
+ * useAsyncState hook whose setter returns a promise
+ * @param {*} [initialValue]
+ * @returns {[any, function(*=, boolean=): (Promise<*>|undefined)]}
+ */
+const useAsyncState = (initialValue) => {
+    const [value, setter] = useState(initialValue);
+
+    return [
+        value,
+        /**
+         * state async accessor
+         * @param {*} [newValue]
+         * @returns {Promise<*>|undefined}
+         */
+        function (newValue) {
+            return new Promise(resolve => {
+                setter((currentValue) => {
+                    if (arguments.length) {
+                        currentValue = typeof newValue === 'function' ? newValue(currentValue) : newValue;
+                    }
+                    resolve(currentValue);
+                    return currentValue;
+                })
+            });
+        }
+    ]
+}
+
+const useAsyncWatcher = (...value) => {
+    const ref = useRef({
+        callbacks: [],
+        oldValue: value
+    });
+
+    const multiple= value.length > 1;
+
+    useEffect(() => {
+        const {current} = ref;
+        const data = multiple ? value.map((value, index) => [value, current.oldValue[index]]) :
+          [value[0], current.oldValue[0]];
+        current.callbacks.forEach(cb => cb(data));
+        current.callbacks = [];
+        current.oldValue = value;
+    }, value);
+
+    /**
+     * @param {Boolean} [grabPrevValue]
+     * @returns {Promise}
+     */
+    return (grabPrevValue) => {
+        return new Promise((resolve) => {
+            ref.current.callbacks.push(entry => {
+                if (multiple) {
+                    resolve(grabPrevValue ? entry : entry.map(values => values[0]))
+                }
+
+                resolve(grabPrevValue ? entry : entry[0]);
+            });
+        });
+    }
+}
 
 module.exports = {
     useAsyncEffect,
     useAsyncCallback,
+    useAsyncState,
+    useAsyncWatcher,
     CanceledError,
     E_REASON_UNMOUNTED,
     E_REASON_RESTART
diff --git a/playground/src/App.js b/playground/src/App.js
@@ -5,6 +5,8 @@ import TestComponent3 from "./TestComponent3";
 import TestComponent4 from "./TestComponent4";
 import TestComponent5 from "./TestComponent5";
 import TestComponent6 from "./TestComponent6";
+import TestComponent7 from "./TestComponent7";
+import TestComponent8 from "./TestComponent8";
 
 export default class App extends React.Component {
   constructor(props) {
@@ -69,6 +71,8 @@ export default class App extends React.Component {
         <TestComponent4 url={this.state.url} timeout={this.state.timeout}></TestComponent4>
         <TestComponent5 url={this.state.url} timeout={this.state.timeout}></TestComponent5>
         <TestComponent6 url={this.state.url} timeout={this.state.timeout}></TestComponent6>
+        <TestComponent7 url={this.state.url} timeout={this.state.timeout}></TestComponent7>
+        <TestComponent8 url={this.state.url} timeout={this.state.timeout}></TestComponent8>
         <button className="btn btn-danger" onClick={this.onClick}>
           Remount component
         </button>
diff --git a/playground/src/TestComponent7.js b/playground/src/TestComponent7.js
@@ -0,0 +1,28 @@
+import React from "react";
+import {
+  useAsyncCallback,
+  useAsyncState
+} from "../../lib/use-async-effect";
+import cpAxios from "cp-axios";
+
+export default function TestComponent7(props) {
+
+  const [counter, setCounter] = useAsyncState(0);
+
+  const [fn, cancel, pending, done, result, err] = useAsyncCallback(function* (value) {
+    console.log('inside callback value is:', value);
+    return (yield cpAxios(`https://rickandmortyapi.com/api/character/${value}`)).data;
+  }, {states: true})
+
+  return (
+    <div className="component">
+      <div className="caption">useAsyncState demo:</div>
+      <div>{pending ? "loading..." : (done ? err ? err.toString() : JSON.stringify(result, null, 2) : "")}</div>
+      <button onClick={async()=>{
+        const updatedValue= await setCounter((counter)=> counter + 1);
+        await fn(updatedValue);
+      }}>Inc</button>
+      {<button onClick={cancel} disabled={!pending}>Cancel async effect</button>}
+    </div>
+  );
+}
diff --git a/playground/src/TestComponent8.js b/playground/src/TestComponent8.js
diff --git a/test/src/index.js b/test/src/index.js
