Add experimental Suspense support

[ghengeveld]

Description

This adds very basic and experimental support for Suspense. By passing the suspense flag, React Async will throw a promise while data is loading, which can be picked up by Suspense to render a fallback UI. This is similar to the <IfPending> component, but differs in two major ways:

• <Suspense> should be an ancestor of your Async component, instead of a descendant. It can be anywhere up in the component hierarchy.
• You can have a single <Suspense> wrap multiple Async components, in which case it will render the fallback UI until all promises are settled.

Fixes #30

Breaking changes

Due to its experimental nature, we may make breaking changes to this feature even in minor or patch releases, until Suspense for data fetching is officially released. Until then, this is marked experimental.

Usage example

const AsyncUser = ({ id }) => {
  const { data, error } = useAsync({ id, promiseFn: loadUser, suspense: true })
  return error ? error.message : data || null
}

const App = () => (
  <Suspense fallback={<>Loading...</>}>
    <AsyncUser id={1} />
  <Suspense>
)

Checklist

Make sure you check all the boxes. You can omit items that are not applicable.

• Implementation for both <Async> and useAsync()
• Added / updated the unit tests
• Added / updated the documentation
• Updated the PropTypes
• Updated the TypeScript type definitions

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 65b54b1:

Sandbox	Source
quizzical-ritchie-ojqcq	Configuration

[codecov]

Codecov Report

Merging #153 into next will increase coverage by 0.01%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##             next     #153      +/-   ##
==========================================
+ Coverage   98.95%   98.96%   +0.01%     
==========================================
  Files           8        8              
  Lines         382      386       +4     
  Branches      143      145       +2     
==========================================
+ Hits          378      382       +4     
  Misses          4        4

Impacted Files	Coverage Δ
packages/react-async/src/propTypes.js	100% <ø> (ø)	⬆️
packages/react-async/src/Async.js	100% <100%> (ø)	⬆️
packages/react-async/src/useAsync.js	99.12% <100%> (+0.01%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 11f8996...65b54b1. Read the comment docs.

[Kaltsoon]

Great work @ghengeveld, I (and likely many others) have been looking forward to this!

Regarding the cache discussion, would it possible to somehow resolve the data synchronously without triggering suspense and causing rerendering? This would allow the use of any synchronous caching solution.

This might not be the best API, but for the sake of an example case:

const useTodo = todoId => {
  const todoClient = useTodoClient();
  const cache = useCache();

  const {  data, ...rest } = useAsync({
    suspend: true, // could also be used without suspense
    promiseFn: todoClient.getById,
    fn: ({ id }) => cache.get(`todo.${id}`),
    id: todoId,
    watch: todoId,
  });

  return { todo: data, ...rest };
};

Optional fn argument would introduce a way to resolve data synchronously and it should be the primary way to resolve the data (secondary, would be to use the good old promiseFn). This way no additional renders are required in case the fn function can resolve the data (it returns something else than undefined).

If this can be done another way, without introducing a new argument I would gladly hear about it.

[ghengeveld]

@Kaltsoon Good idea. It's not only related to Suspense though, so could you please open a new issue? We can discuss the details there, but you should know I want React Async to be batteries-included, so passing it a react-cache resource is too specific. I'd rather have it create such a resource internally, eventually.