Added scopeArg option for useAsyncCallback hook;

Added `skipFirst` option for `useAsyncEffect` hook;
Updated README.md;
Updated dependencies;

Author: DigitalBrainJS

CHANGELOG.md

@@ -1,32 +1,55 @@
-# Change Log
-All notable changes to this project will be documented in this file.
+### Changelog
 
-The format is based on [Keep a Changelog](http://keepachangelog.com/)
-and this project adheres to [Semantic Versioning](http://semver.org/).
+All notable changes to this project will be documented in this file. Dates are displayed in UTC.
 
-## [0.4.0] - 2021-01-11
+Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
-### Added 
-- `queueSize` option for `useAsyncEffect`;
+#### [v0.4.0](https://github.com/DigitalBrainJS/use-async-effect/compare/v0.4.0...v0.4.0)
 
-### Updated
-- reworked `cancelPrevious` and `combine` logic;
+#### [v0.4.0](https://github.com/DigitalBrainJS/use-async-effect/compare/v0.3.0...v0.4.0)
 
-## [0.3.0] - 2021-01-07
+> 11 January 2021
 
-### Fixed
-- Bug with `useAsyncEffect` user cancellation;
+- Added `queueSize` option for `useAsyncEffect`; [`0436e46`](https://github.com/DigitalBrainJS/use-async-effect/commit/0436e46fc55309ccf5965221ba6389356e1b2259)
 
-## [0.2.0] - 2021-01-06
+#### [v0.3.0](https://github.com/DigitalBrainJS/use-async-effect/compare/v0.2.1...v0.3.0)
 
-### Added 
-- `useAsyncCallback` hook
-- typings
+> 7 January 2021
 
-### Updated
-- `useAsyncEffect` now returns a cancel function directly instead of an array with it.
+- Fixed bug with useAsyncEffect user cancellation; [`3ccd038`](https://github.com/DigitalBrainJS/use-async-effect/commit/3ccd03813d0b7e01132118de660f2b030967389e)
 
-## [0.1.0] - 2021-01-04
+#### [v0.2.1](https://github.com/DigitalBrainJS/use-async-effect/compare/v0.2.0...v0.2.1)
 
-### Added
-- initial version
+> 6 January 2021
+
+- Fixed demo links in the README.md; [`1cb5f11`](https://github.com/DigitalBrainJS/use-async-effect/commit/1cb5f11a5dc035d2755b8638b9844d726521f481)
+- Added typings config to the package.json; [`481afc8`](https://github.com/DigitalBrainJS/use-async-effect/commit/481afc81612fe7c01b516cb11b9b8f084d63d3b1)
+
+#### [v0.2.0](https://github.com/DigitalBrainJS/use-async-effect/compare/v0.1.2...v0.2.0)
+
+> 6 January 2021
+
+- Added useAsyncCallback hook; [`baca6a7`](https://github.com/DigitalBrainJS/use-async-effect/commit/baca6a73792cf47262f3a21eade60600ba8cf877)
+- spellcheck; [`34c70ea`](https://github.com/DigitalBrainJS/use-async-effect/commit/34c70ea037f9e592a3d1f039948bf588e68dac6c)
+
+#### [v0.1.2](https://github.com/DigitalBrainJS/use-async-effect/compare/v0.1.1...v0.1.2)
+
+> 5 January 2021
+
+- Added console.error for catch handler; [`df9b78f`](https://github.com/DigitalBrainJS/use-async-effect/commit/df9b78fa77a0a823436d96f7a14c80bcbe972fdc)
+
+#### [v0.1.1](https://github.com/DigitalBrainJS/use-async-effect/compare/v0.1.0...v0.1.1)
+
+> 5 January 2021
+
+- Refactored package.json; [`3a7253a`](https://github.com/DigitalBrainJS/use-async-effect/commit/3a7253a9726f4f65acc0164838f226c81ff2ca8f)
+- Added prepublishOnly & postversion scripts; [`40ebb4d`](https://github.com/DigitalBrainJS/use-async-effect/commit/40ebb4d0c20834121645b16bcedeb4f719092df3)
+- Renamed package; [`a0d6894`](https://github.com/DigitalBrainJS/use-async-effect/commit/a0d68945bc10c165a93aea0271a10a01b651c15c)
+
+#### v0.1.0
+
+> 5 January 2021
+
+- Initial commit [`5529feb`](https://github.com/DigitalBrainJS/use-async-effect/commit/5529febb3c24fb3d6f1dccc1bd210e9f6e88bf26)
+- Improved README.md; [`a0a7144`](https://github.com/DigitalBrainJS/use-async-effect/commit/a0a7144ef707085e879f828d49620761227dba0b)
+- Refactored; [`590756c`](https://github.com/DigitalBrainJS/use-async-effect/commit/590756c6dbd7053200c8c46a49bd9bb1d76716b1)

README.md

@@ -5,32 +5,43 @@
 [![Stars](https://badgen.net/github/stars/DigitalBrainJS/use-async-effect)](https://github.com/DigitalBrainJS/use-async-effect/stargazers)
 
 ## useAsyncEffect2 :snowflake:
-The library provides a React hook with ability to automatically cancel asynchronous code inside it.
-It just makes it easier to write cancelable asynchronous code that doesn't cause 
-the following React issue when unmounting, if your asynchronous tasks that change state are pending:
+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.
+## Installation :hammer:
+- Install for node.js using npm/yarn:
+
+```bash
+$ npm install use-async-effect2
+```
+
+```bash
+$ yarn add use-async-effect2
+```
+
+## Why
+Every asynchronous procedure in your component that changes its state must properly handle the unmount event
+and stop execution in some way before attempting to change the state of the unmounted component, otherwise
+you will get the well-known React leakage warning:
 ````
 Warning: Can't perform a React state update on an unmounted component. 
 This is an no-op, but it indicates a memory leak in your application. 
 To fix, cancel all subscriptions and asynchronous task in "a useEffect cleanup function".
 ````
+
 It uses [c-promise2](https://www.npmjs.com/package/c-promise2) to make it work. 
-When it used in conjunction with other libraries from CPromise ecosystem,
+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 for your React components.
-You just have to use `generators` instead of an async function to make your code cancellable, 
-but basically, that just means you will have to use `yield` instead of `await` keyword.
-## Installation :hammer:
-- Install for node.js using npm/yarn:
 
-```bash
-$ npm install use-async-effect2 c-promise2
-```
+`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.
 
-```bash
-$ yarn add use-async-effect2 c-promise2
-```
-## Usage example
-Minimal example with json request [Live demo](https://codesandbox.io/s/friendly-murdock-wxq8u?file=/src/TestComponent.js)
+JSON fetching using `useAsyncEffect` [Live demo](https://codesandbox.io/s/friendly-murdock-wxq8u?file=/src/TestComponent.js)
 ````jsx
 import React from "react";
 import {useState} from "react";
@@ -41,16 +52,45 @@ function JSONViewer(props) {
     const [text, setText] = useState("");
 
     useAsyncEffect(function* () {
-            setText("fetching...");
-            const response = yield cpFetch(props.url);
+            setText("fetching..."); 
+            const response = yield cpFetch(props.url); // will throw a CanceledError if component get unmounted
             const json = yield response.json();
             setText(`Success: ${JSON.stringify(json)}`);
     }, [props.url]);
 
     return <div>{text}</div>;
 }
 ````
-Example with a timeout & error handling ([Live demo](https://codesandbox.io/s/async-effect-demo1-vho29?file=/src/TestComponent.js)):
+Notice: the related network request will be aborted, when unmounting.
+
+It can be even easier with the [axios wrapper](https://www.npmjs.com/package/cp-axios) ([Demo](https://codesandbox.io/s/use-async-effect-axios-tiny-lsbpv?file=/src/TestComponent.js)):
+````javascript
+import React, { useState } from "react";
+import { useAsyncEffect } from "use-async-effect2";
+import cpAxios from "cp-axios";
+
+export default function TestComponent(props) {
+  const [text, setText] = useState("");
+
+  const cancel = useAsyncEffect(
+    function* () {
+      const response = yield cpAxios(props.url);
+      setText(JSON.stringify(response.data));
+    },
+    [props.url]
+  );
+
+  return (
+    <div className="component">
+      <div className="caption">useAsyncEffect demo:</div>
+      <div>{text}</div>
+      <button onClick={cancel}>Cancel request</button>
+    </div>
+  );
+}
+````
+
+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 } from "use-async-effect2";
@@ -59,8 +99,10 @@ import cpFetch from "cp-fetch";
 
 export default function TestComponent(props) {
   const [text, setText] = useState("");
+  const [isPending, setIsPending] = useState(true);
 
-  const cancel = useAsyncEffect(function* ({ onCancel }) {
+  const cancel = useAsyncEffect(
+    function* ({ onCancel }) {
       console.log("mount");
 
       this.timeout(props.timeout);
@@ -71,9 +113,11 @@ export default function TestComponent(props) {
         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
+        CanceledError.rethrow(err, E_REASON_UNMOUNTED); //passthrough for UNMOUNTED rejection
+        setIsPending(false);
         setText(`Failed: ${err}`);
       }
 
@@ -88,56 +132,71 @@ export default function TestComponent(props) {
     <div className="component">
       <div className="caption">useAsyncEffect demo:</div>
       <div>{text}</div>
-      <button onClick={cancel}>Abort</button>
+      <button onClick={cancel} disabled={!isPending}>
+        Cancel request
+      </button>
     </div>
   );
 }
 ````
-useAsyncCallback example ([Live demo](https://codesandbox.io/s/use-async-callback-bzpek?file=/src/TestComponent.js)):
+`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
-import React from "react";
-import { useState } from "react";
-import { useAsyncCallback, E_REASON_UNMOUNTED } from "../../lib/use-async-effect";
+import React, { useState } from "react";
+import { useAsyncCallback, E_REASON_UNMOUNTED } from "use-async-effect2";
 import { CPromise, CanceledError } from "c-promise2";
+import cpAxios from "cp-axios";
+import { ProgressBar } from "react-bootstrap";
 
-export default function TestComponent2() {
-    const [text, setText] = useState("");
+export default function TestComponent(props) {
+  const [text, setText] = useState("");
+  const [progress, setProgress] = useState(0);
+  const [isFetching, setIsFetching] = useState(false);
 
-    const asyncRoutine = useAsyncCallback(
-        function* (a, b) {
-            setText(`Stage1`);
-            yield CPromise.delay(1000);
-            setText(`Stage2`);
-            yield CPromise.delay(1000);
-            setText(`Stage3`);
-            yield CPromise.delay(1000);
-            setText(`Done`);
-            return Math.random();
-        },
-        { cancelPrevious: true }
-    );
-
-    const onClick = () => {
-        asyncRoutine(123, 456).then(
-            (value) => {
-                setText(`Result: ${value}`);
-            },
-            (err) => {
-                console.warn(err);
-                CanceledError.rethrow(E_REASON_UNMOUNTED);
-                setText(`Fail: ${err}`);
-            }
-        );
-    };
-
-    return (
-        <div className="component">
-            <div className="caption">useAsyncCallback demo:</div>
-            <button onClick={onClick}>Run async job</button>
-            <div>{text}</div>
-            <button onClick={() => asyncRoutine.cancel()}>Abort</button>
-        </div>
-    );
+  const fetchUrl = useAsyncCallback(
+    function* (options) {
+      try {
+        setIsFetching(true);
+        this.innerWeight(3); // for progress calculation
+        this.progress(setProgress);
+        setText("fetching...");
+        const response = yield cpAxios(options).timeout(props.timeout);
+        yield CPromise.delay(500); // just for fun
+        yield CPromise.delay(500); // just for fun
+        setText(JSON.stringify(response.data));
+        setIsFetching(false);
+      } catch (err) {
+        CanceledError.rethrow(err, E_REASON_UNMOUNTED);
+        setText(err.toString());
+        setIsFetching(false);
+      }
+    },
+    [props.url]
+  );
+
+  return (
+    <div className="component">
+      <div className="caption">useAsyncEffect demo:</div>
+      <div>{isFetching ? <ProgressBar now={progress * 100} /> : text}</div>
+      {!isFetching ? (
+        <button
+          className="btn btn-success"
+          onClick={() => fetchUrl(props.url)}
+          disabled={isFetching}
+        >
+          Fetch data
+        </button>
+      ) : (
+        <button
+          className="btn btn-warning"
+          onClick={() => fetchUrl.cancel()}
+          disabled={!isFetching}
+        >
+          Cancel request
+        </button>
+      )}
+    </div>
+  );
 }
 ````
 
@@ -150,25 +209,32 @@ just use the codesandbox [demo](https://codesandbox.io/s/async-effect-demo1-vho2
 
 ## API
 
-### useAsyncEffect(generatorFn, deps?): (cancel():boolean)
+### useAsyncEffect(generatorFn, deps?: []): (cancel():boolean)
+### useAsyncEffect(generatorFn, options?: object): (cancel():boolean)
 A React hook based on [`useEffect`](https://reactjs.org/docs/hooks-effect.html), that resolves passed generator as asynchronous function. 
 The asynchronous generator sequence and its promise of the result will be canceled if 
-the effect cleanup process is started before it completes.
+the effect cleanup process started before it completes.
 The generator can return a cleanup function similar to the `useEffect` hook. 
-- `generatorFn(...userArgs, scope: CPromise)` : `GeneratorFunction` - generator to resolve as an async function. 
-The last argument passed to this function and `this` refer to the CPromise instance.
-- `deps?: any[]` - effect dependencies 
+- `generatorFn(scope: CPromise)` : `GeneratorFunction` - generator to resolve as an async function. 
+Generator context (`this`) refers to the CPromise instance.
+- `deps?: any[]` - effect dependencies
+- `options.deps?: any[]` - skip the first render
+- `options.skipFirst?: boolean` - skip first render
 
-### useAsyncCallback(generatorFn, deps?): CPromiseAsyncFunction
+### useAsyncCallback(generatorFn, deps?: []): CPromiseAsyncFunction
 ### useAsyncCallback(generatorFn, options?: object): CPromiseAsyncFunction
 This hook makes an async callback that can be automatically canceled on unmount or by user request.
+- `generatorFn([scope: CPromise], ...userArguments)` : `GeneratorFunction` - generator to resolve as an async function. 
+Generator context (`this`) and the first argument (if `options.scopeArg` is set) refer to the CPromise instance.
+
 #### options:
 - `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. 
 - `cancelPrevious:boolean` - cancel the previous pending async function before running a new one. 
 - `concurrency: number=0` - set concurrency limit for simultaneous calls. `0` mean unlimited.
 - `queueSize: number=0` - set max queue size.
+- `scopeArg: boolean=false` - pass CPromise scope to the generator function as the first argument.
 
 ## Related projects
 - [c-promise2](https://www.npmjs.com/package/c-promise2) - promise with cancellation, decorators, timeouts, progress capturing, pause and user signals support