Merge pull request #16 from ghengeveld/abortcontroller

Add AbortController to enable fetch cancelation (closes #15)

Author: ghengeveld

README.md

@@ -36,19 +36,18 @@ ultimate flexibility as well as the new Context API for ease of use. Makes it ea
 without assumptions about the shape of your data or the type of request.
 
 - Zero dependencies
-- Works with any (native) promise
+- Works with any (native) Promise and the Fetch API
 - Choose between Render Props, Context-based helper components or the `useAsync` hook
 - Provides convenient `isLoading`, `startedAt` and `finishedAt` metadata
 - Provides `cancel` and `reload` actions
 - Automatic re-run using `watch` prop
 - Accepts `onResolve` and `onReject` callbacks
+- Supports [abortable fetch] by providing an AbortController
 - Supports optimistic updates using `setData`
 - Supports server-side rendering through `initialValue`
 - Works well in React Native too!
 
-> Versions 1.x and 2.x of `react-async` on npm are from a different project abandoned years ago. The original author was
-> kind enough to transfer ownership so the `react-async` package name could be repurposed. The first version of
-> React Async is v3.0.0.
+[abortable fetch]: https://developers.google.com/web/updates/2017/09/abortable-fetch
 
 ## Rationale
 
@@ -84,46 +83,19 @@ npm install --save react-async
 
 ## Usage
 
-As a hook with `useAsync`:
-
-```js
-import { useAsync } from "react-async"
-
-const loadJson = () => fetch("/some/url").then(res => res.json())
-
-const MyComponent = () => {
-  const { data, error, isLoading } = useAsync({ promiseFn: loadJson })
-  if (isLoading) return "Loading..."
-  if (error) return `Something went wrong: ${error.message}`
-  if (data)
-    return (
-      <div>
-        <strong>Loaded some data:</strong>
-        <pre>{JSON.stringify(data, null, 2)}</pre>
-      </div>
-    )
-  return null
-}
-```
-
-Or using the shorthand version:
-
-```js
-const MyComponent = () => {
-  const { data, error, isLoading } = useAsync(loadJson)
-  // ...
-}
-```
-
-Using render props for ultimate flexibility:
+Using render props for flexibility:
 
 ```js
 import Async from "react-async"
 
-const loadJson = () => fetch("/some/url").then(res => res.json())
+// Your promiseFn receives all props from Async and an AbortController instance
+const loadCustomer = ({ customerId }, { signal }) =>
+  fetch(`/api/customers/${customerId}`, { signal })
+    .then(res => (res.ok ? res : Promise.reject(res)))
+    .then(res => res.json())
 
 const MyComponent = () => (
-  <Async promiseFn={loadJson}>
+  <Async promiseFn={loadCustomer} customerId={1}>
     {({ data, error, isLoading }) => {
       if (isLoading) return "Loading..."
       if (error) return `Something went wrong: ${error.message}`
@@ -145,10 +117,13 @@ Using helper components (don't have to be direct children) for ease of use:
 ```js
 import Async from "react-async"
 
-const loadJson = () => fetch("/some/url").then(res => res.json())
+const loadCustomer = ({ customerId }, { signal }) =>
+  fetch(`/api/customers/${customerId}`, { signal })
+    .then(res => (res.ok ? res : Promise.reject(res)))
+    .then(res => res.json())
 
 const MyComponent = () => (
-  <Async promiseFn={loadJson}>
+  <Async promiseFn={loadCustomer} customerId={1}>
     <Async.Loading>Loading...</Async.Loading>
     <Async.Resolved>
       {data => (
@@ -168,28 +143,67 @@ Creating a custom instance of Async, bound to a specific promiseFn:
 ```js
 import { createInstance } from "react-async"
 
-const loadCustomer = ({ customerId }) => fetch(`/api/customers/${customerId}`).then(...)
+const loadCustomer = ({ customerId }, { signal }) =>
+  fetch(`/api/customers/${customerId}`, { signal })
+    .then(res => (res.ok ? res : Promise.reject(res)))
+    .then(res => res.json())
 
 // createInstance takes a defaultProps object and a displayName (both optional)
 const AsyncCustomer = createInstance({ promiseFn: loadCustomer }, "AsyncCustomer")
 
 const MyComponent = () => (
-  <AsyncCustomer customerId="123">
+  <AsyncCustomer customerId={1}>
     <AsyncCustomer.Resolved>{customer => `Hello ${customer.name}`}</AsyncCustomer.Resolved>
   </AsyncCustomer>
 )
 ```
 
-Similarly, this allows you to set default `onResolve` and `onReject` callbacks.
+> Similarly, this allows you to set default `onResolve` and `onReject` callbacks.
+
+As a hook with `useAsync` (currently [only in React v16.7.0-alpha](https://reactjs.org/hooks)):
+
+```js
+import { useAsync } from "react-async"
+
+const loadCustomer = ({ customerId }, { signal }) =>
+  fetch(`/api/customers/${customerId}`, { signal })
+    .then(res => (res.ok ? res : Promise.reject(res)))
+    .then(res => res.json())
+
+const MyComponent = () => {
+  const { data, error, isLoading } = useAsync({ promiseFn: loadCustomer, customerId: 1 })
+  if (isLoading) return "Loading..."
+  if (error) return `Something went wrong: ${error.message}`
+  if (data)
+    return (
+      <div>
+        <strong>Loaded some data:</strong>
+        <pre>{JSON.stringify(data, null, 2)}</pre>
+      </div>
+    )
+  return null
+}
+```
+
+Or using the shorthand version:
+
+```js
+const MyComponent = () => {
+  const { data, error, isLoading } = useAsync(loadCustomer)
+  // ...
+}
+```
+
+The shorthand version does not support passing additional props.
 
 ## API
 
 ### Props
 
 `<Async>` takes the following properties:
 
-- `promiseFn` {() => Promise} A function that returns a promise; invoked in `componentDidMount` and `componentDidUpdate`; receives props (object) as argument
-- `deferFn` {() => Promise} A function that returns a promise; invoked only by calling `run`, with arguments being passed through, as well as props (object) as final argument
+- `promiseFn` {(props, controller) => Promise} A function that returns a promise; invoked in `componentDidMount` and `componentDidUpdate`; receives component props (object) and AbortController instance as arguments
+- `deferFn` {(...args, props, controller) => Promise} A function that returns a promise; invoked only by calling `run`, with arguments being passed through, as well as component props (object) and AbortController as final arguments
 - `watch` {any} Watches this property through `componentDidUpdate` and re-runs the `promiseFn` when the value changes (`oldValue !== newValue`)
 - `initialValue` {any} initial state for `data` or `error` (if instance of Error); useful for server-side rendering
 - `onResolve` {Function} Callback function invoked when a promise resolves, receives data as argument
@@ -217,12 +231,12 @@ Similarly, this allows you to set default `onResolve` and `onReject` callbacks.
 - `setData` {Function} sets `data` to the passed value, unsets `error` and cancels any pending promise
 - `setError` {Function} sets `error` to the passed value and cancels any pending promise
 
-### `useState`
+### `useAsync`
 
-The `useState` hook accepts an object with the same props as `<Async>`. Alternatively you can use the shorthand syntax:
+The `useAsync` hook accepts an object with the same props as `<Async>`. Alternatively you can use the shorthand syntax:
 
 ```js
-useState(promiseFn, initialValue)
+useAsync(promiseFn, initialValue)
 ```
 
 ## Examples
@@ -424,4 +438,6 @@ Renders only while the deferred promise is still pending (not yet run).
 
 ## Acknowledgements
 
-Many thanks to Andrey Popp for handing over ownership of `react-async` on npm.
+Versions 1.x and 2.x of `react-async` on npm are from a different project abandoned years ago. The original author was
+kind enough to transfer ownership so the `react-async` package name could be repurposed. The first version of
+React Async is v3.0.0. Many thanks to Andrey Popp for handing over ownership of `react-async` on npm.

examples/with-abortcontroller/.env

@@ -0,0 +1 @@
+SKIP_PREFLIGHT_CHECK=true

examples/with-abortcontroller/README.md

@@ -0,0 +1,5 @@
+[![Deploy to now](https://deploy.now.sh/static/button.svg)](https://deploy.now.sh/?repo=https://github.com/ghengeveld/react-async/tree/master/examples/basic-fetch)
+
+# Basic fetch with React Async
+
+This demonstrates a very simple HTTP GET using `fetch`, wrapped with React Async.

examples/with-abortcontroller/now.json

@@ -0,0 +1,9 @@
+{
+  "version": 2,
+  "builds": [{ "src": "package.json", "use": "@now/static-build" }],
+  "routes": [
+    { "src": "^/static/(.*)", "dest": "/static/$1" },
+    { "src": "^/favicon.ico", "dest": "/favicon.ico" },
+    { "src": "^/(.*)", "dest": "/index.html" }
+  ]
+}

examples/with-abortcontroller/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "basic-fetch",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+    "react": "16.7.0-alpha.2",
+    "react-async": "latest",
+    "react-dom": "16.7.0-alpha.2",
+    "react-scripts": "2.1.2"
+  },
+  "scripts": {
+    "start": "react-scripts start",
+    "build": "react-scripts build",
+    "now-build": "npm run build && mv build dist"
+  },
+  "eslintConfig": {
+    "extends": "react-app"
+  },
+  "browserslist": [
+    ">0.2%",
+    "not dead",
+    "not ie <= 11",
+    "not op_mini all"
+  ]
+}

examples/with-abortcontroller/public/favicon.ico

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
+    <meta name="theme-color" content="#000000" />
+    <title>React App</title>
+  </head>
+  <body>
+    <noscript> You need to enable JavaScript to run this app. </noscript>
+    <div id="root"></div>
+  </body>
+</html>

examples/with-abortcontroller/public/index.html

@@ -0,0 +1,20 @@
+body {
+  margin: 20px;
+  padding: 0;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Oxygen", "Ubuntu",
+    "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+button {
+  background: none;
+  color: palevioletred;
+  border: 2px solid palevioletred;
+  border-radius: 5px;
+  padding: 10px 20px;
+  font-size: 0.9em;
+  font-weight: bold;
+  outline: 0;
+  text-transform: uppercase;
+}

examples/with-abortcontroller/src/index.css

@@ -0,0 +1,25 @@
+import React from "react"
+import { useAsync } from "react-async"
+import ReactDOM from "react-dom"
+import "./index.css"
+
+const download = (event, props, controller) =>
+  fetch(`https://reqres.in/api/users/1?delay=3`, { signal: controller.signal })
+    .then(res => (res.ok ? res : Promise.reject(res)))
+    .then(res => res.json())
+
+const App = () => {
+  const { run, cancel, isLoading } = useAsync({ deferFn: download })
+  return (
+    <>
+      {isLoading ? <button onClick={cancel}>cancel</button> : <button onClick={run}>start</button>}
+      {isLoading ? (
+        <p>Loading...</p>
+      ) : (
+        <p>Inspect network traffic to see requests being canceled.</p>
+      )}
+    </>
+  )
+}
+
+ReactDOM.render(<App />, document.getElementById("root"))

examples/with-abortcontroller/src/index.js

@@ -14,6 +14,7 @@ export const createInstance = (defaultProps = {}, displayName = "Async") => {
     constructor(props) {
       super(props)
 
+      this.start = this.start.bind(this)
       this.load = this.load.bind(this)
       this.run = this.run.bind(this)
       this.cancel = this.cancel.bind(this)
@@ -30,6 +31,7 @@ export const createInstance = (defaultProps = {}, displayName = "Async") => {
       this.mounted = false
       this.counter = 0
       this.args = []
+      this.abortController = { abort: () => {} }
       this.state = {
         initialValue,
         data: initialData,
@@ -56,8 +58,8 @@ export const createInstance = (defaultProps = {}, displayName = "Async") => {
     componentDidUpdate(prevProps) {
       if (prevProps.watch !== this.props.watch) this.load()
       if (prevProps.promiseFn !== this.props.promiseFn) {
-        this.cancel()
         if (this.props.promiseFn) this.load()
+        else this.cancel()
       }
     }
 
@@ -66,28 +68,39 @@ export const createInstance = (defaultProps = {}, displayName = "Async") => {
       this.mounted = false
     }
 
+    start() {
+      if ("AbortController" in window) {
+        this.abortController.abort()
+        this.abortController = new window.AbortController()
+      }
+      this.counter++
+      this.setState({ isLoading: true, startedAt: new Date(), finishedAt: undefined })
+    }
+
     load() {
       const promiseFn = this.props.promiseFn || defaultProps.promiseFn
       if (!promiseFn) return
-      this.counter++
-      this.setState({ isLoading: true, startedAt: new Date(), finishedAt: undefined })
-      return promiseFn(this.props).then(this.onResolve(this.counter), this.onReject(this.counter))
+      this.start()
+      return promiseFn(this.props, this.abortController).then(
+        this.onResolve(this.counter),
+        this.onReject(this.counter)
+      )
     }
 
     run(...args) {
       const deferFn = this.props.deferFn || defaultProps.deferFn
       if (!deferFn) return
-      this.counter++
       this.args = args
-      this.setState({ isLoading: true, startedAt: new Date(), finishedAt: undefined })
-      return deferFn(...args, this.props).then(
+      this.start()
+      return deferFn(...args, this.props, this.abortController).then(
         this.onResolve(this.counter),
         this.onReject(this.counter)
       )
     }
 
     cancel() {
       this.counter++
+      this.abortController.abort()
       this.setState({ isLoading: false, startedAt: undefined })
     }