Setup gitbook.

.gitbook.yaml

@@ -0,0 +1,5 @@
+root: ./gitbook/
+
+structure:
+  readme: introduction.md
+  summary: _summary.md

gitbook/1.introduction.md

@@ -0,0 +1,32 @@
+# Introduction
+
+React Async is a utility belt for declarative promise resolution and data fetching. It makes it easy to handle
+asynchronous UI states, without assumptions about the shape of your data or the type of request. React Async consists of
+a React component and several hooks. You can use it with `fetch`, Axios or other data fetching libraries, even GraphQL.
+
+## Rationale
+
+React Async is different in that it tries to resolve data as close as possible to where it will be used, while using
+declarative syntax, using just JSX and native promises. This is in contrast to systems like Redux where you would
+configure any data fetching or updates on a higher (application global) level, using a special construct
+(actions/reducers).
+
+React Async works well even in larger applications with multiple or nested data dependencies. It encourages loading
+data on-demand and in parallel at component level instead of in bulk at the route/page level. It's entirely decoupled
+from your routes, so it works well in complex applications that have a dynamic routing model or don't use routes at all.
+
+React Async is promise-based, so you can resolve anything you want, not just `fetch` requests.
+
+## Concurrent React and Suspense
+
+The React team is currently working on a large rewrite called [Concurrent React], previously known as "Async React".
+Part of this rewrite is Suspense, which is a generic way for components to suspend rendering while they load data from
+a cache. It can render a fallback UI while loading data, much like `<Async.Pending>`.
+
+React Async has no direct relation to Concurrent React. They are conceptually close, but not the same. React Async is
+meant to make dealing with asynchronous business logic easier. Concurrent React will make those features have less
+impact on performance and usability. When Suspense lands, React Async will make full use of Suspense features. In fact,
+you can already **start using React Async right now**, and in a later update, you'll **get Suspense features for free**.
+In fact, React Async already has experimental support for Suspense, by passing the `suspense` option.
+
+[concurrent react]: https://github.com/sw-yx/fresh-concurrent-react/blob/master/Intro.md#introduction-what-is-concurrent-react

gitbook/2.installation.md

@@ -0,0 +1,49 @@
+# Getting started
+
+You can install `react-async` from npm:
+
+```
+npm install --save react-async
+```
+
+Or if you're using Yarn:
+
+```
+yarn add react-async
+```
+
+> This package requires `react` as a peer dependency. Please make sure to install that as well.
+> If you want to use the `useAsync` hook, you'll need `react@16.8.0` or later.
+
+## Upgrading
+
+### Upgrade to v8
+
+All standalone helper components were renamed to avoid import naming collision.
+
+- `<Initial>` was renamed to `<IfInitial>`.
+- `<Pending>` was renamed to `<IfPending>`.
+- `<Fulfilled>` was renamed to `<IfFulfilled>`.
+- `<Rejected>` was renamed to `<IfRejected`.
+- `<Settled>` was renamed to `<IfSettled>`.
+
+> A [codemod](https://github.com/async-library/react-async/tree/master/codemods) is available to automate the upgrade.
+
+The return type for `run` was changed from `Promise` to `undefined`. You should now use the `promise` prop instead. This
+is a manual upgrade. See [`promise`](#promise-1) for details.
+
+### Upgrade to v6
+
+- `<Async.Pending>` was renamed to `<Async.Initial>`.
+- Some of the other helpers were also renamed, but the old ones remain as alias.
+- Don't forget to deal with any custom instances of `<Async>` when upgrading.
+
+> A [codemod](https://github.com/async-library/react-async/tree/master/codemods) is available to automate the upgrade.
+
+### Upgrade to v4
+
+- `deferFn` now receives an `args` array as the first argument, instead of arguments to `run` being spread at the front
+  of the arguments list. This enables better interop with TypeScript. You can use destructuring to keep using your
+  existing variables.
+- The shorthand version of `useAsync` now takes the `options` object as optional second argument. This used to be
+  `initialValue`, but was undocumented and inflexible.

gitbook/3.usage.md

@@ -0,0 +1,205 @@
+# Usage
+
+React Async offers three primary APIs: the `useAsync` hook, the `<Async>` component and the `createInstance`
+factory function. Each has its unique benefits and downsides.
+
+## As a hook
+
+The `useAsync` hook (available [from React v16.8.0](https://reactjs.org/hooks)) offers direct access to React Async's
+core functionality from within your own function components:
+
+```jsx
+import { useAsync } from "react-async"
+
+const loadCustomer = async ({ customerId }, { signal }) => {
+  const res = await fetch(`/api/customers/${customerId}`, { signal })
+  if (!res.ok) throw new Error(res)
+  return res.json()
+}
+
+const MyComponent = () => {
+  const { data, error, isPending } = useAsync({ promiseFn: loadCustomer, customerId: 1 })
+  if (isPending) 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
+}
+```
+
+> Using [helper components](#with-helper-components) can greatly improve readability of your render functions by not
+> having to write all those conditional returns.
+
+Or using the shorthand version:
+
+```jsx
+const MyComponent = () => {
+  const { data, error, isPending } = useAsync(loadCustomer, options)
+  // ...
+}
+```
+
+### With `useFetch`
+
+Because fetch is so commonly used with `useAsync`, there's a dedicated `useFetch` hook for it:
+
+```jsx
+import { useFetch } from "react-async"
+
+const MyComponent = () => {
+  const headers = { Accept: "application/json" }
+  const { data, error, isPending, run } = useFetch("/api/example", { headers }, options)
+  // This will setup a promiseFn with a fetch request and JSON deserialization.
+
+  // you can later call `run` with an optional callback argument to
+  // last-minute modify the `init` parameter that is passed to `fetch`
+  function clickHandler() {
+    run(init => ({
+      ...init,
+      headers: {
+        ...init.headers,
+        authentication: "...",
+      },
+    }))
+  }
+
+  // alternatively, you can also just use an object that will be spread over `init`.
+  // please note that this is not deep-merged, so you might override properties present in the
+  // original `init` parameter
+  function clickHandler2() {
+    run({ body: JSON.stringify(formValues) })
+  }
+}
+```
+
+`useFetch` takes the same arguments as [fetch] itself, as well as `options` to the underlying `useAsync` hook. The
+`options` object takes two special boolean properties: `defer` and `json`. These can be used to switch between
+`deferFn` and `promiseFn`, and enable JSON parsing. By default `useFetch` automatically uses `promiseFn` or `deferFn`
+based on the request method (`deferFn` for POST / PUT / PATCH / DELETE) and handles JSON parsing if the `Accept` header
+is set to `"application/json"`.
+
+[fetch]: https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch
+
+## As a component
+
+The classic interface to React Async. Simply use `<Async>` directly in your JSX component tree, leveraging the render
+props pattern:
+
+```jsx
+import Async from "react-async"
+
+// 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={loadCustomer} customerId={1}>
+    {({ data, error, isPending }) => {
+      if (isPending) 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
+    }}
+  </Async>
+)
+```
+
+> Using [helper components](#with-helper-components) can greatly improve readability of your render functions by not
+> having to write all those conditional returns.
+
+## As a factory
+
+You can also create your own component instances, allowing you to preconfigure them with options such as default
+`onResolve` and `onReject` callbacks.
+
+```jsx
+import { createInstance } from "react-async"
+
+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={1}>
+    <AsyncCustomer.Fulfilled>{customer => `Hello ${customer.name}`}</AsyncCustomer.Fulfilled>
+  </AsyncCustomer>
+)
+```
+
+## With helper components
+
+Several [helper components](#helper-components) are available to improve legibility. They can be used with `useAsync`
+by passing in the state, or with `<Async>` by using Context. Each of these components simply enables or disables
+rendering of its children based on the current state.
+
+```jsx
+import { useAsync, IfPending, IfFulfilled, IfRejected } from "react-async"
+
+const loadCustomer = async ({ customerId }, { signal }) => {
+  // ...
+}
+
+const MyComponent = () => {
+  const state = useAsync({ promiseFn: loadCustomer, customerId: 1 })
+  return (
+    <>
+      <IfPending state={state}>Loading...</IfPending>
+      <IfRejected state={state}>{error => `Something went wrong: ${error.message}`}</IfRejected>
+      <IfFulfilled state={state}>
+        {data => (
+          <div>
+            <strong>Loaded some data:</strong>
+            <pre>{JSON.stringify(data, null, 2)}</pre>
+          </div>
+        )}
+      </IfFulfilled>
+    </>
+  )
+}
+```
+
+### As compounds to `<Async>`
+
+Each of the helper components are also available as static properties of `<Async>`. In this case you won't have to pass
+the state object, instead it will be automatically provided through Context.
+
+```jsx
+import Async 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 = () => (
+  <Async promiseFn={loadCustomer} customerId={1}>
+    <Async.Pending>Loading...</Async.Pending>
+    <Async.Fulfilled>
+      {data => (
+        <div>
+          <strong>Loaded some data:</strong>
+          <pre>{JSON.stringify(data, null, 2)}</pre>
+        </div>
+      )}
+    </Async.Fulfilled>
+    <Async.Rejected>{error => `Something went wrong: ${error.message}`}</Async.Rejected>
+  </Async>
+)
+```