GitBook: [next] 7 pages modified

ghengeveld · gitbook-bot · commit a0567e7c91b5 · 2019-10-05T19:15:22.000Z
diff --git a/gitbook/_summary.md b/gitbook/_summary.md
@@ -1,8 +1,9 @@
-# Summary
+# Table of contents
+
+* [Introduction](introduction.md)
+* [Getting started](installation.md)
+* [Usage](usage.md)
+* [API](api.md)
+* [Helper components](helpers.md)
+* [DevTools](devtools.md)
 
-- [Introduction](introduction.md)
-- [Getting started](installation.md)
-- [Usage](usage.md)
-- [API](api.md)
-- [Helper components](helpers.md)
-- [DevTools](devtools.md)
diff --git a/gitbook/api.md b/gitbook/api.md
diff --git a/gitbook/devtools.md b/gitbook/devtools.md
@@ -1,15 +1,14 @@
 # DevTools
 
-React Async comes with a separate DevTools package which helps you Debug and develop your asynchronous application
-states. You can install it from npm:
+React Async comes with a separate DevTools package which helps you Debug and develop your asynchronous application states. You can install it from npm:
 
-```
+```text
 npm install --save react-async-devtools
 ```
 
 Or if you're using Yarn:
 
-```
+```text
 yarn add react-async-devtools
 ```
 
@@ -25,3 +24,4 @@ export const Root = () => (
   </>
 )
 ```
+
diff --git a/gitbook/helpers.md b/gitbook/helpers.md
@@ -1,17 +1,17 @@
 # Helper components
 
-React Async provides several helper components that make your JSX more declarative and less cluttered.
-They don't have to be direct children of `<Async>` and you can use the same component several times.
+React Async provides several helper components that make your JSX more declarative and less cluttered. They don't have to be direct children of `<Async>` and you can use the same component several times.
 
 ## `<IfInitial>` / `<Async.Initial>`
 
 Renders only while the deferred promise is still waiting to be run, or you have not provided any promise.
 
 ### Props
 
-- `children` `function(state: Object): Node | Node` Render function or React Node.
-- `state` `object` Async state object (return value of `useAsync()`).
-- `persist` `boolean` Show until we have data, even while loading or when an error occurred. By default it hides as soon
+* `children` `function(state: Object): Node | Node` Render function or React Node.
+* `state` `object` Async state object \(return value of `useAsync()`\).
+* `persist` `boolean` Show until we have data, even while loading or when an error occurred. By default it hides as soon
+
   as the promise starts loading.
 
 ### Examples
@@ -49,15 +49,15 @@ return (
 
 ## `<IfPending>` / `<Async.Pending>`
 
-This component renders only while the promise is pending (loading / unsettled).
+This component renders only while the promise is pending \(loading / unsettled\).
 
 Alias: `<Async.Loading>`
 
 ### Props
 
-- `children` `function(state: Object): Node | Node` Render function or React Node.
-- `state` `object` Async state object (return value of `useAsync()`).
-- `initial` `boolean` Show only on initial load (when `data` is `undefined`).
+* `children` `function(state: Object): Node | Node` Render function or React Node.
+* `state` `object` Async state object \(return value of `useAsync()`\).
+* `initial` `boolean` Show only on initial load \(when `data` is `undefined`\).
 
 ### Examples
 
@@ -82,15 +82,15 @@ return (
 
 ## `<IfFulfilled>` / `<Async.Fulfilled>`
 
-This component renders only when the promise is fulfilled (resolved to a value, could be `undefined`).
+This component renders only when the promise is fulfilled \(resolved to a value, could be `undefined`\).
 
 Alias: `<Async.Resolved>`
 
 ### Props
 
-- `children` `function(data: any, state: Object): Node | Node` Render function or React Node.
-- `state` `object` Async state object (return value of `useAsync()`).
-- `persist` `boolean` Show old data while loading new data. By default it hides as soon as a new promise starts.
+* `children` `function(data: any, state: Object): Node | Node` Render function or React Node.
+* `state` `object` Async state object \(return value of `useAsync()`\).
+* `persist` `boolean` Show old data while loading new data. By default it hides as soon as a new promise starts.
 
 ### Examples
 
@@ -119,6 +119,7 @@ This component renders only when the promise is rejected.
 
 ### Props
 
-- `children` `function(error: Error, state: Object): Node | Node` Render function or React Node.
-- `state` `object` Async state object (return value of `useAsync()`).
-- `persist` `boolean` Show old error while loading new data. By default it hides as soon as a new promise starts.
+* `children` `function(error: Error, state: Object): Node | Node` Render function or React Node.
+* `state` `object` Async state object \(return value of `useAsync()`\).
+* `persist` `boolean` Show old error while loading new data. By default it hides as soon as a new promise starts.
+
diff --git a/gitbook/installation.md b/gitbook/installation.md
@@ -2,48 +2,51 @@
 
 You can install `react-async` from npm:
 
-```
+```text
 npm install --save react-async
 ```
 
 Or if you're using Yarn:
 
-```
+```text
 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.
+> 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>`.
+* `<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.
+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`](installation.md#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.
+* `<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
+* `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
+
+* The shorthand version of `useAsync` now takes the `options` object as optional second argument. This used to be
+
   `initialValue`, but was undocumented and inflexible.
+
diff --git a/gitbook/introduction.md b/gitbook/introduction.md
@@ -1,32 +1,18 @@
 # 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.
+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 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 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>`.
+The React team is currently working on a large rewrite called [Concurrent React](https://github.com/sw-yx/fresh-concurrent-react/blob/master/Intro.md#introduction-what-is-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.
+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
diff --git a/gitbook/usage.md b/gitbook/usage.md
@@ -1,12 +1,10 @@
 # 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.
+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:
+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"
@@ -32,8 +30,7 @@ const MyComponent = () => {
 }
 ```
 
-> Using [helper components](#with-helper-components) can greatly improve readability of your render functions by not
-> having to write all those conditional returns.
+> Using [helper components](usage.md#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:
 
@@ -77,18 +74,11 @@ const MyComponent = () => {
 }
 ```
 
-`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
+`useFetch` takes the same arguments as [fetch](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/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"`.
 
 ## As a component
 
-The classic interface to React Async. Simply use `<Async>` directly in your JSX component tree, leveraging the render
-props pattern:
+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"
@@ -117,13 +107,11 @@ const MyComponent = () => (
 )
 ```
 
-> Using [helper components](#with-helper-components) can greatly improve readability of your render functions by not
-> having to write all those conditional returns.
+> Using [helper components](usage.md#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.
+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"
@@ -145,9 +133,7 @@ const MyComponent = () => (
 
 ## 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.
+Several [helper components](usage.md#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"
@@ -177,8 +163,7 @@ const MyComponent = () => {
 
 ### 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.
+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"
@@ -203,3 +188,4 @@ const MyComponent = () => (
   </Async>
 )
 ```
+
