1npm install suspend-react

This library integrates your async ops into React suspense. Pending- and error-states are handled at the parental level which frees the individual component from that burden and allows for better orchestration. Think of it as async/await for components. Works in all React versions >= 16.6.

1import { Suspense } from 'react'
2import { suspend } from 'suspend-react'
3
4function Post({ id, version }) {
5  const data = suspend(async () => {
6    const res = await fetch(`https://hacker-news.firebaseio.com/${version}/item/${id}.json`)
7    return res.json()    
8  }, [id, version])
9  return (
10    <div>
11      {data.title} by {data.by}
12    </div>
13  )
14}
15
16function App() {
17  return (
18    <Suspense fallback={<div>loading...</div>}>
19      <Post id={1000} version="v0" />
20    </Suspense>
21  )
22}

API

1const suspend = <Keys extends Tuple<unknown>, Fn extends (...keys: Keys) => Promise<unknown>>(
2  fn: Fn | Promise<unknown>,
3  keys?: Keys,
4  config?: Config
5) => Await<ReturnType<Fn>>

1// Function that returns a promise
2const result = suspend((...keys) => anyPromise, keys, config)
3// async function
4const result = suspend(async (...keys) => { /* ... */ }, keys, config)
5// Promise with keys
6const result = suspend(anyPromise, keys, config)
7// Promise itself is the key
8const result = suspend(anyPromise)

suspend yields control back to React and the render-phase is aborted. It will resume once your promise resolves. For this to work you need to wrap it into a <React.Suspense> block, which requires you to set a fallback (can be null).

The dependencies (the 2nd argument) act as cache-keys, use as many as you want. If an entry is already in cache, calling suspend with the same keys will return it immediately without breaking the render-phase. Cache access is similar to useMemo but across the component tree.

The 1st argument has to be a promise, or a function that returns a promise, or an asyn function. It receives the keys as arguments. suspend will return the resolved value, not a promise! This is guaranteed, you do not have to check for validity. Errors will bubble up to the nearest error-boundary.

Config

Both suspend and preload can optionally receive a config object,

Keep-alive

The lifespan prop allows you to invalidate items over time, it defaults to 0 (keep-alive forever). Every read refreshes the timer to ensure that used entries stay valid.

1// Keep cached item alive for one minute without read
2suspend(fn, keys, { lifespan: 60000 })

Equality function

The equal prop customizes per-key validation, it defaults to (a, b) => a === b (reference equality).

1import equal from 'fast-deep-equal'
2
3// Validate keys deeply
4suspend(fn, keys, { equal })

Preloading

1import { preload } from 'suspend-react'
2
3async function fetchFromHN(id, version) {
4  const res = await fetch(`https://hacker-news.firebaseio.com/${version}/item/${id}.json`)
5  return res.json()
6}
7
8preload(fetchFromHN, [1000, 'v0'])

Cache busting

1import { clear } from 'suspend-react'
2
3// Clear all cached entries
4clear()
5// Clear a specific entry
6clear([1000, 'v0'])

Peeking into entries outside of suspense

1import { peek } from 'suspend-react'
2
3// This will either return the value (without suspense!) or undefined
4peek([1000, 'v0'])

Making cache-keys unique

Since suspend operates on a global cache (for now, see React 18), you might be wondering if keys could bleed, and yes they would. To establish cache-safety, create unique or semi-unique appendixes.

1- suspend(fn, [1000, 'v0'])
2+ suspend(fn, [1000, 'v0', 'functionName/fetch'])

If you publish a library that suspends, consider symbols.

1const fetchUUID = Symbol()
2
3export function Foo() {
4  suspend(fn, [1000, 'v0', fetchUUID])

Typescript

Correct types will be inferred automatically.

React 18

Suspense, as is, has been a stable part of React since 16.6, but React will likely add some interesting caching and cache busting APIs that could allow you to define cache boundaries declaratively. Expect these to be work for suspend-react once they come out.

Demos

Fetching posts from hacker-news: codesandbox

Infinite list: codesandbox