Improved useAsyncCallback queue logic;

Fixed a bug with missing stage change that should be generated by the `useAsyncCallback` when deps changed;
Added a Demo App to the playground to discover `useAsyncCallback` options set;

Author: DigitalBrainJS

README.md

@@ -5,12 +5,79 @@
 [![Stars](https://badgen.net/github/stars/DigitalBrainJS/use-async-effect)](https://github.com/DigitalBrainJS/use-async-effect/stargazers)
 
 ## useAsyncEffect2 :snowflake:
-This library provides `useAsyncEffect` and `useAsyncCallback` React hooks that make possible to cancel async code
-inside it and unsubscribe the internal routines if needed (request, timers etc.).
-These hooks are very useful for data fetching, since you don't have to worry about request
-cancellation when components unmounts. So just forget about `isMounted` flag and `AbortController`, 
-which were used to protect your components from React leak warning, these hooks do that for you automatically.
-Writing cancellable async code becomes easy.
+
+This library provides asynchronous versions of the `useEffect` and` useCallback` React hooks that can cancel
+asynchronous code inside it due to timeouts, user requests, or automatically when a component is unmounted or some
+dependency has changed.
+
+The library is designed to make it as easy as possible to use complex and composite asynchronous routines 
+in React components. It works on top of a [custom cancellable promise](https://www.npmjs.com/package/c-promise2),
+simplifying the solution to many common challenges with asynchronous code. Can be composed with cancellable version of `Axios`
+([cp-axios](https://www.npmjs.com/package/cp-axios)) and `fetch API` ([cp-fetch](https://www.npmjs.com/package/cp-fetch))
+to get auto cancellable React async effects/callbacks with network requests.
+
+### Quick start
+
+1. You have to use the generator syntax instead of ECMA async functions, basically by replacing `await` with `yield`
+ and  `async()=>{}` or `async function()` with `function*`:
+ 
+    ````javascript
+    // plain React useEffect hook
+    useEffect(()=>{
+      (async()=>{
+        await somePromiseHandle;
+      })();
+    }, [])
+    // useAsyncEffect React hook
+    useAsyncEffect(function*(){
+      yield somePromiseHandle;
+    }, [])
+    ````
+
+1. It's recommended to use [`CPromise`](https://www.npmjs.com/package/c-promise2) instead of the native Promise to make
+ the promise chain deeply cancellable, at least if you're going to change the component state inside it.
+
+    ````javascript
+    import { CPromise } from "c-promise2";
+    
+    const MyComponent= ()=>{
+        const [text, setText]= useState('');
+        
+        useAsyncEffect(function*(){
+          yield CPromise.delay(1000);
+          setText('Hello!');
+        });
+    }
+    ````
+
+1. Don't catch (or just rethrow caught) `CanceledError` errors with `E_REASON_UNMOUNTED` 
+reason inside your code before making any stage change:
+
+    ````javascript
+    import {
+      useAsyncEffect,
+      E_REASON_UNMOUNTED,
+      CanceledError
+    } from "use-async-effect2";
+    import cpAxios from "cp-axios";
+    
+    const MyComponent= ()=>{
+        const [text, setText]= useState('');
+        
+        useAsyncEffect(function*(){
+          try{
+              const json= (yield cpAxios('http://localhost/')).data;
+              setText(`Data: ${JSON.stringify(json)}`);
+          }catch(err){
+              // just rethrow the CanceledError error if it has E_REASON_UNMOUNTED reason
+              CanceledError.rethrow(err, E_REASON_UNMOUNTED);
+              // otherwise work with it somehow
+              setText(`Failed: ${err.toString}`);
+          } 
+        });
+    }
+    ````
+
 ## Installation :hammer:
 - Install for node.js using npm/yarn:
 
@@ -37,9 +104,9 @@ When used in conjunction with other libraries from CPromise ecosystem,
 such as [cp-fetch](https://www.npmjs.com/package/cp-fetch) and [cp-axios](https://www.npmjs.com/package/cp-axios),
 you get a powerful tool for building asynchronous logic of React components.
 
-`useAsyncEffect` & `useAsyncCallback` hooks make cancelable async functions from generators,
-providing the ability to cancel async sequence in any stage in automatically way, when the related component unmounting.
-It's totally the same as async functions, but with cancellation- you need use 'yield' instead of 'await'. That's all.
+## Examples
+
+### useAsyncEffect
 
 A tiny `useAsyncEffect` demo with JSON fetching using internal states: 
 
@@ -84,6 +151,60 @@ function JSONViewer(props) {
 ````
 Notice: the related network request will be aborted, when unmounting.
 
+An example with a timeout & error handling ([Live demo](https://codesandbox.io/s/async-effect-demo1-vho29?file=/src/TestComponent.js)):
+````jsx
+import React, { useState } from "react";
+import { useAsyncEffect, E_REASON_UNMOUNTED, CanceledError} from "use-async-effect2";
+import cpFetch from "cp-fetch";
+
+export default function TestComponent(props) {
+  const [text, setText] = useState("");
+  const [isPending, setIsPending] = useState(true);
+
+  const cancel = useAsyncEffect(
+    function* ({ onCancel }) {
+      console.log("mount");
+
+      this.timeout(props.timeout);
+
+      onCancel(() => console.log("scope canceled"));
+
+      try {
+        setText("fetching...");
+        const response = yield cpFetch(props.url);
+        const json = yield response.json();
+        setIsPending(false);
+        setText(`Success: ${JSON.stringify(json)}`);
+      } catch (err) {
+        CanceledError.rethrow(err, E_REASON_UNMOUNTED); //passthrough for UNMOUNTED rejection
+        setIsPending(false);
+        setText(`Failed: ${err}`);
+      }
+
+      return () => {
+        console.log("unmount");
+      };
+    },
+    [props.url]
+  );
+
+  return (
+    <div className="component">
+      <div className="caption">useAsyncEffect demo:</div>
+      <div>{text}</div>
+      <button onClick={cancel} disabled={!isPending}>
+        Cancel request
+      </button>
+    </div>
+  );
+}
+````
+
+### useAsyncCallback
+
+Here's a [Demo App](https://codesandbox.io/s/use-async-callback-demo-app-yyic4?file=/src/TestComponent.js) to play with
+`asyncCallback` and learn about its options.
+
 Live search for character from the `rickandmorty` universe using `rickandmortyapi.com`:
 
 [Live demo](https://codesandbox.io/s/use-async-effect-axios-rickmorty-search-ui-sd2mv?file=/src/TestComponent.js)
@@ -136,54 +257,6 @@ export default function TestComponent(props) {
 This code handles the cancellation of the previous search sequence (including aborting the request) and
 canceling the sequence when the component is unmounted to avoid the React leak warning.
 
-An example with a timeout & error handling ([Live demo](https://codesandbox.io/s/async-effect-demo1-vho29?file=/src/TestComponent.js)):
-````jsx
-import React, { useState } from "react";
-import { useAsyncEffect, E_REASON_UNMOUNTED, CanceledError} from "use-async-effect2";
-import cpFetch from "cp-fetch";
-
-export default function TestComponent(props) {
-  const [text, setText] = useState("");
-  const [isPending, setIsPending] = useState(true);
-
-  const cancel = useAsyncEffect(
-    function* ({ onCancel }) {
-      console.log("mount");
-
-      this.timeout(props.timeout);
-
-      onCancel(() => console.log("scope canceled"));
-
-      try {
-        setText("fetching...");
-        const response = yield cpFetch(props.url);
-        const json = yield response.json();
-        setIsPending(false);
-        setText(`Success: ${JSON.stringify(json)}`);
-      } catch (err) {
-        CanceledError.rethrow(err, E_REASON_UNMOUNTED); //passthrough for UNMOUNTED rejection
-        setIsPending(false);
-        setText(`Failed: ${err}`);
-      }
-
-      return () => {
-        console.log("unmount");
-      };
-    },
-    [props.url]
-  );
-
-  return (
-    <div className="component">
-      <div className="caption">useAsyncEffect demo:</div>
-      <div>{text}</div>
-      <button onClick={cancel} disabled={!isPending}>
-        Cancel request
-      </button>
-    </div>
-  );
-}
-````
 `useAsyncCallback` example: fetch with progress capturing & cancellation 
  ([Live demo](https://codesandbox.io/s/use-async-callback-axios-catch-ui-l30h5?file=/src/TestComponent.js)):
 ````javascript
@@ -293,15 +366,15 @@ Generator context (`this`) and the first argument (if `options.scopeArg` is set)
 - `deps?: any[] | UseAsyncCallbackOptions` - effect dependencies
 #### UseAsyncCallbackOptions:
 - `deps: any[]` - effect dependencies 
-- `combine:boolean` - subscribe to the result of the async function already 
-running with the same arguments or run a new one. 
+- `combine:boolean` - subscribe to the result of the async function already running with the same arguments instead
+ of running a new one. 
 - `cancelPrevious:boolean` - cancel the previous pending async function before running a new one. 
-- `threads: number=0` - set concurrency limit for simultaneous calls. `0` mean unlimited.
+- `threads: number=0` - set concurrency limit for simultaneous calls. `0` means unlimited.
 - `queueSize: number=0` - set max queue size.
 - `scopeArg: boolean=false` - pass `CPromise` scope to the generator function as the first argument.
 - `states: boolean=false` - enable state changing. The function must be single threaded to use the states.
 
-#### Available states vars:
+#### Available state vars:
 - `pending: boolean` - the function is in the pending state
 - `done: boolean` - the function execution is completed (with success or failure)
 - `result: any` - refers to the resolved function result

lib/use-async-effect.js

@@ -4,11 +4,9 @@ const isEqualObjects = require('is-equal-objects/dist/is-equal-objects.cjs');
 
 const {E_REASON_QUEUE_OVERFLOW, E_REASON_RESTART} = CanceledError.registerErrors({
     E_REASON_QUEUE_OVERFLOW: 'overflow',
-    E_REASON_RESTART: 'restarted',
+    E_REASON_RESTART: 'restarted'
 })
 
-const {hasOwnProperty}= Object.prototype;
-
 const isGeneratorFn = (thing) => typeof thing === 'function' &&
     thing.constructor &&
     thing.constructor.name === 'GeneratorFunction';
@@ -128,6 +126,7 @@ const useAsyncEffect = (generator, options) => {
         });
 
         return () => {
+            ref.current.isMounted= false;
             cancel(E_REASON_UNMOUNTED);
             cb && cb();
         }
@@ -170,29 +169,34 @@ const useAsyncCallback = (generator, options) => {
         promises: [],
         queue: [],
         pending: 0,
-        args: null
+        args: null,
+        mounted: true
     });
 
     let {
         deps = [],
         combine = false,
         cancelPrevious = false,
-        threads = 0,
-        queueSize = 0,
+        threads,
+        queueSize = -1,
         scopeArg= false,
         states= false
     } = options && Array.isArray(options) ? {deps: options} : options || {};
 
-    if (cancelPrevious && (threads || queueSize)) {
-        throw Error('cancelPrevious cannot be used in conjunction with threads or queueSize options');
-    }
+    if (threads === undefined) {
+        threads = cancelPrevious || states ? 1 : 0;
+    } else {
+        if (cancelPrevious && threads !== -1) {
+            throw Error('can not activate function multithreading when cancelPrevious is set');
+        }
 
-    if (threads && (!Number.isFinite(queueSize) || threads < 0)) {
-        throw Error('threads must be a positive number');
+        if (!Number.isFinite(threads) || threads < 0) {
+            throw Error('threads must be a positive number');
+        }
     }
 
-    if (queueSize && (!Number.isFinite(queueSize) || queueSize < 0)) {
-        throw Error('queueSize must be a positive number');
+    if (queueSize!==-1 && (!Number.isFinite(queueSize) || queueSize < -1)) {
+        throw Error('queueSize must be a finite number >=-1');
     }
 
     const [state, setState]= states? useState({
@@ -203,12 +207,7 @@ const useAsyncCallback = (generator, options) => {
         pending: false
     }) : [];
 
-    if(cancelPrevious){
-        threads= 1;
-        queueSize= 0;
-    }
-
-    const singleThreaded= threads === 1 && !combine;
+    const singleThreaded= threads === 1;
 
     const callback = useCallback((...args) => {
         const {promises, queue} = current;
@@ -219,20 +218,24 @@ const useAsyncCallback = (generator, options) => {
             while (n-- > 0) {
                 promise = promises[n];
                 if (argsToPromiseMap.has(promise) && isEqualObjects(argsToPromiseMap.get(promise), args)) {
+                    if (cancelPrevious) {
+                        promise.cancel(E_REASON_RESTART);
+                        break;
+                    }
                     return CPromise.resolve(promise);
                 }
             }
         }
 
-        if (queueSize && (queueSize - promises.length) <= 0) {
+        if (queueSize !== -1 && (queueSize - promises.length - current.pending) <= 0) {
             return CPromise.reject(CanceledError.from(E_REASON_QUEUE_OVERFLOW))
         }
 
         const resolveGenerator = () => CPromise.run(generator, {args, resolveSignatures: true, scopeArg});
 
-        cancelPrevious && cancel(E_REASON_RESTART);
+        cancelPrevious && !combine && cancel(E_REASON_RESTART);
 
-        if (threads) {
+        if (threads || queueSize!==-1) {
             const promise = new CPromise(resolve => {
                 if (current.pending === threads) {
                     return queue.push(() => {
@@ -260,11 +263,7 @@ const useAsyncCallback = (generator, options) => {
 
                     const canceled= !!(isRejected && CanceledError.isCanceledError(value));
 
-                    if( canceled && value.code===E_REASON_UNMOUNTED){
-                        return;
-                    }
-
-                    if(states && singleThreaded){
+                    if(states && singleThreaded && current.mounted){
                         setState({
                             done: true,
                             pending: false,
@@ -326,6 +325,12 @@ const useAsyncCallback = (generator, options) => {
         return () => cancel(E_REASON_UNMOUNTED);
     }, deps);
 
+    if (states) {
+        useEffect(() => () => {
+            current.mounted = false;
+        }, []);
+    }
+
     callback.cancel = cancel;
 
     return callback;