@postinumero/use-async

Create a suspending hook from an async function, an async generator or a function that returns an async iterator.

• Server-side rendering
• recall function for re-executing the function and rerendering related components from anywhere

Examples

Get data using axios

1import { Suspense } from 'react';
2import { create } from '@postinumero/use-async';
3import axios from 'axios';
4
5const [useAxios] = create(axios);
6
7function Todo({ id }) {
8  const { data } = useAxios(`https://jsonplaceholder.typicode.com/todos/${id}`);
9
10  return <pre>{JSON.stringify(data, null, 2)}</pre>;
11}
12
13function App() {
14  return (
15    <Suspense fallback="Loading...">
16      <Todo id="1" />
17    </Suspense>
18  );
19}

Render timestamps with setInterval

1import { Suspense } from 'react';
2import { create } from '@postinumero/use-async';
3import { Repeater } from '@repeaterjs/repeater';
4
5const [useTimestamp] = create(
6  () =>
7    new Repeater(async (push, stop) => {
8      push(Date.now());
9      const interval = setInterval(() => push(Date.now()), 1000);
10      await stop;
11      clearInterval(interval);
12    })
13);
14
15function Timestamp() {
16  return <div>Timestamp: {useTimestamp()}</div>;
17}
18
19function App() {
20  return (
21    <Suspense fallback="Loading...">
22      <Timestamp />
23    </Suspense>
24  );
25}

API

create(fn[, config])

For creating shortcut functions of the rest of the API, without needing to pass fn and config each time.

Params

• fn: AsyncFunction
• config: Config (optional)

Returns

An array of functions [useAsync, recall, useAsyncSafe]. Each of the returned function take just the ...args as its arguments.

useAsync(fn[, config[, args]])

Params

• fn: AsyncFunction
• config: Config (optional)
• args: arguments[] for fn (optional)

Returns

Resolved value of fn(...args).

Throws

A thrown exception from fn or a promise for React Suspense.

useAsyncSafe(fn[, config[, args]])

Params

• fn: AsyncFunction
• config: Config (optional)
• args: arguments[] for fn (optional)

Returns

An array [error, value], where error is either null or a thrown exception from fn(...args), and value is resolved value of fn(...args).

Throws

Promise for React Suspense.

recall(fn[, config[, args]]) (async)

If there are components currently mounted using any of the hooks and the same arguments (fn, config, args), fn(...args) gets called. When fn resolves, components will rerender with the new value.

Params

• fn: AsyncFunction
• config: Config (optional)
• args: arguments[] for fn (optional)

Returns

Resolves with undefined, when fn(...args) resolves.

Config

Prop	Example	Default value	Description
id	"axios"	undefined	Cache values using id as key instead of fn. Required in SSR.

Server-side Rendering

1. Use createSSRCache to get SSRCacheProvider and ssrData
2. Wrawp server-side <App> with <SSRCacheProvider>
3. Use react-ssr-prepass to handle suspsense
4. Get initial SSR data using ssrData(). ssrData accepts a map function, which is called for each data entry with 2 arguments: data, { id, args }.
5. Place the data in a <script> before the application

1import { /* nothing, */ createSSRCache } from '@postinumero/use-async';
2import ssrPrepass from 'react-ssr-prepass';
3
4//...
5
6const { ssrData, SSRCacheProvider } = createSSRCache();
7
8const element = (
9  <SSRCacheProvider>
10    <App />
11  </SSRCacheProvider>
12);
13await ssrPrepass(element);
14
15const app = ReactDOMServer.renderToString(element);
16
17res.send(
18  html.replace(
19    '<div id="root"></div>',
20    `<script>${ssrData(([error, response]) =>
21      // error ? nothing :
22      [
23        error,
24        response && {
25          data: response.data,
26          headers: response.headers,
27          status: response.status,
28        },
29      ]
30    )}</script><div id="root">${app}</div>`
31  )
32);

Not ready for Suspense?

Import from @postinumero/use-async/loading-state to use the { isLoading, data, error } style API. Example:

1import { create } from '@postinumero/use-async/loading-state';
2import axios from 'axios';
3
4const [, , useAxiosSafe] = create(axios);
5
6function User({ id }) {
7  const { isLoading, data, error } = useAxiosSafe(`/api/users/${id}`);
8
9  if (isLoading) {
10    return 'Loading...';
11  }
12
13  return <div>First name: {data.data.first_name}</div>;
14}