React Use Promise

Simple and declarative use of Promises in your React components. Observe their state and refresh them in various advanced ways.

Now with built-in support for 🌐 HTTP!

1import { Suspense } from "react";
2import { usePromise, refresh } from "@mittwald/react-use-promise";
3
4// Async loader 👇 function
5const loadNewsItem = async (id) => {
6  const res = await fetch(
7    `https://hacker-news.firebaseio.com/v0/item/${id}.json`,
8  );
9  return res.json();
10};
11
12const NewsItem = ({ id }) => {
13  const news = usePromise(loadNewsItem, [id], {
14    // ✨ Use the async loader 👆 function with its ID-parameter
15    tags: [`news/${id}`],
16    // Use tags 🏷️ with support for "tree structures" 🌳
17  });
18
19  // Do not care about any loading states – just use the result 🤩
20  return (
21    <li>
22      {news.by}: {news.title}
23    </li>
24  );
25};
26
27const App = () => {
28  const reloadAllNews = () => {
29    // ✨ Reload Promises 🔄 by using tags and glob pattern *️⃣
30    refresh({ tag: "news/*" });
31  };
32
33  return (
34    // The Suspense component will render a fallback️
35    // if any child component is in loading state ⏱️
36    <Suspense fallback={<div>Loading...</div>}>
37      <NewsList>
38        <NewsItem id={1000} />
39        <NewsItem id={1001} />
40        <NewsItem id={1002} />
41      </NewsList>
42      <button onClick={reloadAllNews}>Reload news</button>
43    </Suspense>
44  );
45};

Features

• Simple and declarative use of Promises, loading- and error views
• Built-in support to load data with HTTP resources
• Works with data fetching via Next.js server actions
• Auto-refresh after timeout or on window focus
• Type-Safe API
• No "double-loading" when using "same" Promise in different places in your app
• Caching with support for custom tags
• Opt-out Suspense-based loading
• Cache invalidation with glob support
• Observable loading state
• Set up lazy-loading "async resources" with the alternative getAsyncResource-API and pass them as prop to child components
• "Resourceify" any async function
• Fully tested and well-structured TypeScript code-base

Table of Contents

• Installing
• Terminology
• API
  • usePromise
  • getAsyncResource
  • Async resource
  • Options
  • refresh
• Caching
  • Challenges concerning Caching
  • Resource store
  • Creating unique storage keys
  • Using explicit loader IDs
• Tags
  • Hierarchical Tags
• Refreshing resources
• HTTP Resources
  • Request config
  • Default request config
  • Caching and refreshing of HTTP Resources
  • API
• Lazy loading with Async Resources
• Defining loading views
• Opt-Out Suspense
• Opt-Out Loading
• Error handling
• Best practices
• Migration guides

Installing

With npm:

1$ npm install @mittwald/react-use-promise

With Yarn:

1$ yarn add @mittwald/react-use-promise

Terminology

(Async) resource

An async resource (or just resource) represents something that has to be loaded asynchronously. Asynchronous loading involves different states, like "loading" or "loading is done", that should be reflected in the UI. Basically async resources encapsulating Promises and equipping them with relevant features like observing the Promises state or caching the result.

Async loader (function)

The async loader function is simply a function returning a Promise and thus acts as the basic input for async resources.

API

usePromise

Get the result of a Promise by passing an async loader with the relevant loader parameters and an optional configuration to the usePromise hook.

usePromise(asyncLoader, loaderParameters, options?)

Returns: the value of the async resource

For possible options see Options section.

1import { usePromise } from "@mittwald/react-use-promise";
2
3// 1. Inline loader function
4const response = usePromise(() => axios("/user/12345"), []);
5
6// 2. Loader function with parameters
7const getUser = (id) => axios(`/user/${id}`);
8const response = usePromise(getUser, [12345]); // 👈 loader parameters as array
9
10// 3. With options
11const response = usePromise(getUser, [12345], {
12  autoRefresh: {
13    seconds: 30,
14  },
15});

getAsyncResource

This is an alternative and more advanced API to the usePromise hook. For details see Lazy Loading with Async Resources. The usePromise hook uses the getAsyncResource-API under the hood and is basically just a shortcut for getAsyncResource(asyncLoader, loaderParameters, options).use().

Get an async resource by passing an async loader with the relevant loader parameters and an optional configuration to the getAsyncResource function.

getAsyncResource(asyncLoader, loaderParameters, options?)

Returns: Async resource

For possible options see Options section.

1import { getAsyncResource } from "@mittwald/react-use-promise";
2
3// 1. Inline loader function
4const userResource = getAsyncResource(() => axios(`/user/123`), []);
5
6// 2. Loader function with parameters
7const getUser = (id) => axios(`/user/${id}`);
8const userResource = getAsyncResource(getUser, [123]);
9
10// 3. With options
11const userResource = getAsyncResource(getUser, [123], {
12  tags: ["api"],
13});
14
15// 4. Usage in factory function
16const getUserResource = (id) => getAsyncResource(getUser, [id]);

Async resource

The async resource returned by getAsyncResource has the following API.

.use(options?)

For possible options see Options section.

Returns: the value of the async resource, or the result object when useSuspense: false (see Opt-out Suspense)

Calling the use method will actually start the loading process and returns the value of the async resource, once it is loaded. Everytime the resource is refreshed, the used value automatically updates itself.

1import getUserResource from "../resources/user";
2
3const Username = ({ id }) => {
4  const user = getUserResource(id).use(); // 👈 using the resource value
5  return <>{user.name}</>;
6};

.refresh()

Calling the refresh method will clear the cached resource value and trigger a reload, if the resource is being used in any mounted component.

1import getScoreResource from "../resources/score";
2
3const Score = ({ matchId }) => {
4  const scoreResource = getScoreResource(matchId);
5  const score = scoreResource.use();
6  const reloadScore = () => scoreResource.refresh(); // 👈 refresh the resource
7
8  return (
9    <ScoreBox>
10      <Score>
11        {score.home} - {score.guest}
12      </Score>
13      <button onClick={reloadScore}>Reload</button>
14    </ScoreBox>
15  );
16};

.watchState()

Returns: "void" | "loading" | "loaded" | "error"

You can watch the resources state by calling the watchState method.

1import getScoreResource from "../resources/score";
2
3const Score = ({ matchId }) => {
4  const scoreResource = getScoreResource(matchId);
5  const scoreResourceState = scoreResource.watchState();
6  const score = scoreResource.use();
7  const scoreIsLoading = scoreResourceState === "loading";
8
9  return (
10    <ScoreBox>
11      <Score>
12        {score.home} - {score.guest}
13      </Score>
14      <LoadingSpinner visible={scoreIsLoading} />
15    </ScoreBox>
16  );
17};

Options

You can configure usePromise and getAsyncResource with the following options:

autoRefresh – only supported by hooks (use*)

Type: Duration like object
Default: undefined

When a duration is configured, the resource will automatically be refreshed in the provided interval. If the same resource has multiple auto-refresh intervals, the shortest interval will be used.

1autoRefresh: {
2  seconds: 30;
3}

refreshOnWindowFocus – only supported by hooks (use*)

Type: boolean
Default: false

Set this option to true, if the resource should automatically be refreshed, if the window is re-focused.

keepValueWhileLoading – only supported by hooks (use*)

Type: boolean
Default: true

If true, the previously loaded value will be returned during refresh is in progress. The loading view will only be triggered during initial load.

If false, the loading view will always be triggered – during initial load and refresh as well.

tags

Type: string[]
Default: undefined

With this option you can assign tags to resources. Tags allow you to be expressive and flexible when accessing resources, e.g. when you need to refresh multiple resources at once.

You can find details about how to use tags in the Tags section.

1tags: ["hackernews", "getRequest"];

loaderId

Type: string
Default: "null"

It is very unlikely that you ever need to use this option, but to get around the "same code" issue (see "Caveats of default storage key generation"), you can set an explicit loader ID, that identifies the loader function.

useSuspense – only supported by hooks (use*)

Type: boolean
Default: true

Set this to false to opt-out Suspense-based loading behavior. See Opt-Out Suspense for more details.

refresh

If you do not have direct access to the resource that should be refreshed, you can use the global refresh method.

refresh()

Refreshes all resources.

1import { refresh } from "@mittwald/react-use-promise";
2
3export const Menu = () => (
4  <Menu>
5    <MenuItem url="/dashboard" />
6    <MenuItem url="/projects" />
7    <MenuItem url="/profile" />
8    <MenuButton onClick={() => refresh()}>Refresh all data</MenuButton>
9  </Menu>
10);

refresh(options)

The refresh method takes an option object to do a more selective refresh.

The following options are supported:

• tag (string): Refreshes all resources matching the given tag. Glob pattern are supported here. See also the Hierarchical Tags section.
• error (true | error): Set this option to true, to refresh all resource with errors. Set this option to an error instance, to refresh all resources with a matching error. See the Error handling section for more details.

resourceify

resourceify creates a factory function for async resources based on given async loader functions.

resourceify(asyncLoader)

Example of how to create factory functions for your async loaders:

1import { resourceify } from "@mittwald/react-use-promise";
2
3const getUser = (id) => axios(`/user/${id}`);
4// Creates a function to get user resources
5const getUserResource = resourceify(getUser);
6// `myUser` is an async resource
7const myUser = getUserResource(["me"], { refresh: { seconds: 30 } });
8myUser.use();
9
10// Factory method for HTTP GET-Requests via Axios
11import axios from "axios";
12export const getHttpResource = resourceify(axios.get);

Caching

Caching the result of async loader functions is essential to make this library work. Without it, components will end-up in an endless render-loop, since the re-render after finished loading will trigger the loader function again.

To break this loop, the result (and even the error) of the loader function is cached inside the resource instance. If a cached result exists, the loader must not be called again and the cached value is used instead.

Challenges concerning Caching

This caching approach comes with two essential issues one has to care about:

• creating unique cache keys to store results
• providing flexible ways of cache invalidation

Resource store

Every time when usePromise resp. getAsyncResource is called, either a new resource is created or an existing resource is taken from the resource store. If a resources has loaded once, it exists in the store and contains the cached result of the async loader function.

It is noticeable that not the raw result is cached in some "result cache" – it is the resource the keeps the cached result which itself is stored in the resource store.

Creating unique storage keys

Basically you do not have to care about storage keys at all, but there are some odd situations where the default storage key generation fails, and produces conflicting keys. If so, you probably might not get the expected resource. When you are experiencing such issues, you better take a look at this section.

Same resource, same storage key

When creating storage keys, the same key should be formed for async resources considered as "same". An async resource is "the same" compared to another resource, if:

• the loader function is the same
• the parameters used to load the resource are the same

Examples:

1const getUser = (id) => axios(`/user/${id}`);
2const getPost = (id) => axios(`/post/${id}`);
3
4// Same storage key 🍎🍎
5const response1 = usePromise(getUser, [12345]);
6const response2 = usePromise(getUser, [12345]);
7
8// Same storage key 🍐🍐
9const response3 = usePromise(() => getUser(12345), []);
10const response4 = usePromise(() => getUser(12345), []);
11
12// Different storage keys 🍎🍋
13const response5 = usePromise(getUser, [12345]);
14const response6 = usePromise(getUser, [56789]);
15
16// Different storage keys 🍎🍉
17const response7 = usePromise(getUser, [12345]);
18const response8 = usePromise(getPost, [12345]);
19
20// Different storage keys 🍎🌶️
21const response9 = usePromise(() => getUser(12345), []);
22const response10 = usePromise(() => getUser(12344 + 1), []);

Caveats of default storage key generation

In some odd situations the default storage key generation fails and may generate conflicting keys. To evaluate these situations, you should know some details about the default behaviour, which is basically implemented like this:

1import { hash } from "object-code";
2
3const storageKeyObject = {
4  loaderFunction,
5  parameters,
6};
7
8const storageKey = hash(storageKeyObject);

As you can see, the implementation heavily relies on the object-code library, which

is a blazing fast hash code generator that supports every possible javascript value.

When it comes to "hashing" a function (in this case the async loader function), object-code uses toString() to get the function code and uses it for further hashing. This is the point where problems may arise. When two function using the same code, they must not necessarily behave the same. Think of functions using variables from their parent scope (🤯).

The following example may result in inconsistencies. (But only if users and posts share same the IDs.)

1// File Username.jsx
2import repo from "./user";
3
4const loadUserById = (id) => repo.loadById(id);
5// same code 👆, but different repo 😧
6
7export const Username = ({ id }) => {
8  const user = usePromise(loadUserById, [id]);
9  //👆 may be a cached post
10  return <>{user.name}</>;
11};
12
13// File PostTitle.jsx
14import repo from "./post";
15
16const loadPostById = (id) => repo.loadById(id);
17// same code 👆, but different repo 😧
18
19export const PostTitle = ({ id }) => {
20  const post = usePromise(loadPostById, [id]);
21  //👆 may be a cached user
22  return <>{post.title}</>;
23};

Using explicit loader IDs

It is very unlikely that you ever need to use this option, but to get around the "same code" issue demonstrated above, you can set explicit loader IDs in the options object.

This example shows how to set explicit loader IDs:

1// ...
2const post = usePromise(loadPostById, [id], {
3  loaderId: "loadPostById", // explicit loader ID 😮‍💨
4});
5// ...

Tags

You can assign tags to resources. A tag is simply a string that classifies the resource. In advanced scenarios you might want to assign multiple tags to one resource, expressing the resource matches different classifications.

Using relevant tags creates the possibility to be very expressive and flexible when it comes to accessing multiple resources at once, e.g. when you need to refresh them.

For example, you might use tags to refresh some specific resources, when a backend event occurs.

1// File components/Chat.jsx
2import { usePromise } from "@mittwald/react-use-promise";
3
4const Chat = ({ chatId }) => {
5  const messages = usePromise(loadChatMessages, [chatId], {
6    tags: [`chat/${chatId}`],
7  });
8
9  return (
10    <div>
11      {messages.map((msg) => (
12        <ChatMessage message={msg} key={msg.id} />
13      ))}
14    </div>
15  );
16};
17
18// File setup.js
19import { refresh } from "@mittwald/react-use-promise";
20
21backendEventListener.on("chatUpdated", (chatId) => {
22  refresh({
23    tag: `chat/${chatId}`,
24  });
25});

Hierarchical Tags

Tags are supporting a tree structure, compared to paths in filesystems or URLs (e.g. chat/12345/messages). This creates the possibility to structure your resources into hierarchical classes. Combined with glob support in cache invalidation, you can invalidate resources matching a certain level in the tree.

1import { refresh } from "@mittwald/react-use-promise";
2
3refresh({
4  tag: `chat/12345/**/*`,
5});
6// Matches everything for the chat 12345
7// - chat/12345/messages/1
8// - chat/12345/messages/2
9// - chat/12345/metaData
10
11refresh({
12  tag: `chat/12345/messages/*`,
13});
14// Matches all messages for the chat 12345
15// - chat/12345/messages/1
16// - chat/12345/messages/2

Refreshing resources

If a resource has a cached result, the async loader function must not be called again and the cached value is used instead. To invalidate the cached value you can call the refresh() method on the resource or use the global refresh() method. As a result the async loader function will automatically be called again and a component update is triggered when the result is available.

Refreshing resources that are not used in any mounted component, will suspend the reload until the resource is actually used the next time.

You might also use the auto-refresh mechanisms after timeout or refocus window.

1import { refresh } from "@mittwald/react-use-promise";

🌐 HTTP Resources

A major use case of this library might be to load data from some HTTP-API. This is exactly why a preconfigured HTTP resource is included in this package. The simplest way is to use the useHttpData() method to GET data from a given URL.

1import { useHttpData } from "@mittwald/react-use-promise/http";
2
3const NewsItem = ({ id }) => {
4  const news = useHttpData(
5    `https://hacker-news.firebaseio.com/v0/item/${id}.json`,
6  );
7
8  return (
9    <li>
10      {news.by}: {news.title}
11    </li>
12  );
13};

Important: As this feature requires the axios package you need to include it in your dependencies!

1yarn add axios

Request config

Under the hood the popular HTTP client Axios is used to perform the request. To make all Axios config options available to you, the complete config object can be passed as the second parameter to all HTTP functions.

1const videoGames = useHttpData<Article[]>(`/articles`, {
2  params: {
3    catagory: "video-games",
4  },
5});

Default request config

To set the default config for each request (e.g the baseURL or an Authorization header) you can use the axios.defaults object.

1import axios from "axios";
2
3axios.defaults.baseURL = "https://api.foo.org/v2";

Caching and refreshing of HTTP Resources

HTTP Resources are cached by the identity of the request config – meaning, different request configs result in different HTTP Resources.

Cache tags added to HTTP Resources:

• http/method/(HTTP METHOD)
• http/uri/(REQUEST URI)

This lets you refresh HTTP Resources with a certain path.

1import { refresh } from "@mittwald/react-use-promise";
2
3function refreshArticles() {
4  refresh({
5    tag: "http/uri/**/articles",
6  });
7}

HTTP API

useHttpData(url, requestConfig?, usePromiseOptions?)

Fetches data from a given URL with an optional request configuration.

Returns: the parsed body data of the response

url

The URL to perform the request on

requestConfig?

The Axios request config

usePromiseOptions?

For possible options see Options section.

useHttp(url, requestConfig?, usePromiseOptions?)

Get the response from a given URL with an optional request configuration.

Returns: an Axios response object

url

The URL to perform the request on

requestConfig?

The Axios request config

usePromiseOptions?

For possible options see Options section.

getHttpResource(url, requestConfig?, usePromiseOptions?)

Creates an Async Resource that performs an HTTP request as the loader function.

Returns: an Axios response object

url

The URL to perform the request on

requestConfig?

The Axios request config

usePromiseOptions?

For possible options see Options section.

😴 Lazy loading with Async Resources

When constructing your React app, you might get to the point, where you must decide whether to

• load something from your API and pass the result into some child component,
• or the child component should load the data itself by some ID from its props.

Since loading async resources involves different loading states, it is a good advice, to react on these state changes, as deep as possible in the component tree, to avoid needless re-renderings of parent components.

💅 Presentational vs. 📦 Container Components

The components deep in the tree are usually some small components, like the <Avatar /> component showing an avatar image. These kind of components do have a clear focus on the visual representation and should not be polluted by some loading state handling. They are often referred to as Presentational Components. They can be developed as "standalone" and showcased in Storybooks, without the need of any API.

When the time has come to bring your Presentational Components to life, you can "wrap" the component in a container that "connects" it with real data. This is the job of Container Components. They care about loading data and compose Presentational Components to display the data.

Example Presentational Component:

1// Props needed for presentation
2interface Props {
3  imageUrl?: string;
4  size?: number;
5}
6
7const Avatar: FC<Props> = ({ imageUrl, size }) => {
8  return <Image round url={imageUrl} size={size} />;
9};

Example Container Component:

1interface Props {
2  // ID is needed to load the user
3  userId: string;
4  // optional presentational props are possible
5  size?: number;
6}
7
8const UserAvatar: FC<Props> = ({ userId, size }) => {
9  const profile = usePromise(api.loadUserProfile, [userId]);
10  return <Avatar imageUrl={profile.avatarUrl} size={size} />;
11};

Async Resources as prop

As an alternative to the user ID, you might pass an Async User Resource as prop to your Container Component. This makes the component more flexible, because it is not tied to the actual loading method.

For instance if user profiles can be loaded via multiple API methods, the <UserAvatar /> component can still be used without any changes.

It is noticeable that creating Async Resources in any parent component does not trigger the loading process. Therefore, the .use() method can be used in the child components, where the data is actually needed.

Alternative Container Component with lazy loading:

1// ...
2import { AsyncResource, getAsyncResource } from "@mittwald/react-use-promise";
3
4interface Props {
5  // Async User Resource passed as prop
6  user: AsyncResource<UserData>;
7  size?: number;
8}
9
10const UserAvatar: FC<Props> = ({ user, size }) => {
11  // .use() 🔔 triggers loading when needed
12  const profile = user.use();
13  return <Avatar imageUrl={profile.avatarUrl} size={size} />;
14};
15
16const UserProfileMenu: FC = () => {
17  // 😴 Creating the Async Resource does not trigger loading
18  const myProfile = getAsyncResource(api.loadMyUserProfile, []);
19
20  return (
21    <Menu>
22      <MenuHeader>
23        <UserAvatar user={myProfile} size={128} />
24      </MenuHeader>
25      {/* menu items*/}
26    </Menu>
27  );
28};

Defining loading views

When using @mittwald/react-use-promise (or other Suspense-based approaches) you have to define a loading boundary (Reacts <Suspense /> component) to display the loading view. Loading boundaries are quite similar to error boundaries. They "catch" active loading processes in any child component and render a fallback instead. The benefits of this pattern are:

• No pollution of handling loading states over and over again in your components
• Definition of loading views, where you need them in the component tree
• Flexible level of loading views: Sometimes it is less distracting to use a single loading view for a larger section of your app, but sometimes small pieces of async data should not keep off parts of your app from rendering.
• Declarative and easy to understand

Example of how to define loading views:

1const App = () => (
2  <Suspense fallback={<FullScreenLoadingSpinner />}>
3    {/* ... */}
4    <MainLayout>
5      <Suspense fallback={<MainMenuLoadingSkeleton />}>
6        <MainMenu />
7      </Suspense>
8      <Suspense fallback={<MainContentLoadingSkeleton />}>
9        <MainContent />
10      </Suspense>
11    </MainLayout>
12    {/* ... */}
13  </Suspense>
14);

Gotchas when defining "built-in" loading views

When you are using .use() or usePromise() in your component, it can not define its own loading boundary – at least not for directly used Async Resources.

In this example the fallback component will not be shown:

1const UserAvatar = ({ userResource, size }) => {
2  const user = userResource.use();
3  // 👆 any code below this line will not be executed 🙅 until the async loader is done.
4  const loadingView = <AvatarSkeleton size={size} />;
5  return (
6    <Suspense fallback={loadingView}>
7      {/* This fallback 👆 is not rendered for the used resource from above. 😢 */}
8      <Avatar imageUrl={user.avatarUrl} size={size} />
9    </Suspense>
10  );
11};

The following approaches can help you to solve this issue:

• Split up your component into two separate components – one private with the regular rendering, and another one wrapping it with a loading boundary while forwarding props to it.

1const Component = ({ userResource, size }) => {
2  const user = userResource.use();
3  return <Avatar imageUrl={user.avatarUrl} size={size} />;
4};
5
6export const UserAvatar = (props) => {
7  const loadingView = <AvatarSkeleton size={props.size} />;
8
9  return (
10    <Suspense fallback={loadingView}>
11      <Component {...props} />
12    </Suspense>
13  );
14};

• Opt-out Suspense-based loading behavior.

1const UserAvatar = ({ userResource, size }) => {
2  const user = userResource.use({ useSuspense: false });
3
4  // `user` is an object with `isSet` and `value` properties
5  if (!user.isSet) {
6    return <AvatarSkeleton size={size} />;
7  }
8
9  // `value` only exists when `isSet === true`
10  return <Avatar imageUrl={user.value.avatarUrl} size={size} />;
11};

• Use a Higher Order Component (HOC) that enhances your regular implementation with a loading boundary. This HOC could optionally add an error boundary.

1const UserAvatar = withLoadingBoundary(({ userResource, size }) => {
2  const user = userResource.use();
3  return <Avatar imageUrl={user.avatarUrl} size={size} />;
4}, AvatarSkeleton);

• Use a render component where you access the resource:

1const UserAvatar = ({ userResource, size }) => {
2  const loadingView = <AvatarSkeleton size={size} />;
3  return (
4    <Suspense fallback={loadingView}>
5      <Render>
6        {() => {
7          const user = userResource.use();
8          return <Avatar imageUrl={user.avatarUrl} size={size} />;
9        }}
10      </Render>
11    </Suspense>
12  );
13};

Opt-Out Suspense

When you want to react explicitly on the loading-state, the suspense-based loading behavior is a little bit obstructive, e.g. when you want to define components with built-in loading views.

You can opt-out Suspense by setting the useSuspense option to false. When Suspense is disabled, calling .use() resp. usePromise() will not trigger any <Suspense /> component. Instead, a result object is returned, containing loading information and the eventual value.

Example of how the opt-out behaves:

1const message = usePromise(loadMessage, ["12345"], { useSuspense: false });
2
3if (!message.hasValue) {
4  return <LoadingView />;
5}
6
7return (
8  <MessageView message={message.value} activitySpinner={message.isLoading} />
9);

Return object with disabled Suspense

The object returned by .use() resp. usePromise() has the following properties, when Suspense is disabled.

• isLoading: Is true when the resource is loading or reloading. false otherwise.
• hasValue: Is true when a resource value is available, including the "old" value when reloading. false otherwise.
• value: Contains the resource value. Is only available if hasValue is true.
• maybeValue: Contains the resource value, when the resource has loaded. undefined otherwise.

Examples of result objects:

1// Loading the first time or reloading with keepValueWhileLoading disabled
2({
3  isLoading: true,
4  maybeValue: undefined,
5  hasValue: false,
6});
7
8// When value has loaded
9({
10  isLoading: false,
11  maybeValue: "Foo",
12  value: "Foo",
13  hasValue: true,
14});
15
16// When value is reloading
17({
18  isLoading: true,
19  maybeValue: "Foo",
20  value: "Foo",
21  hasValue: true,
22});

Opt-Out Loading

You probably know that you should not call hooks conditionally. But what if the loader parameters you want to use e.g. in usePromise are optional properties, and the loader function requires them? In this case just use null as parameters and loading is disabled!

😈 Bad:

1const Username = ({ id }) => {
2  if (!id) {
3    return null;
4  }
5  // 💥 This will throw a React error because `usePromise` is called conditionally!
6  const user = usePromise(loadUseProfile, [id]);
7  return <>{user.name}</>;
8};

😇 Good:

1const Username = ({ id }) => {
2  // When required loader parameters can be undefined: use null 👇
3  const user = usePromise(loadUseProfile, id ? [id] : null);
4  // ⚠️ In this case, `user` can also be `undefined`!
5  return <>{user ? user.name : "Unknown"}</>;
6};

Error handling

Errors that occur in any async loader function can be handled with regular error boundaries. With only one exception. When you have implemented a retry-render-mechanism in your error fallback view, the erroneous resource has to be refreshed as well before re-rendering.

When you use the popular react-error-boundary package, you can utilize its onReset property to refresh all erroneous resources, while resetting the error view.

Example of refreshing erroneous resources on reset:

1// ...
2import { refresh } from "@mittwald/react-use-promise";
3import { ErrorBoundary } from "react-error-boundary";
4
5const App = () => (
6  <MainLayout>
7    <MainMenu />
8    <ErrorBoundary
9      fallback={<MainContentErrorFallback />}
10      onReset={() => {
11        refresh({ error: true });
12      }}
13    >
14      <Suspense fallback={<MainContentLoadingSkeleton />}>
15        <MainContent />
16      </Suspense>
17    </ErrorBoundary>
18  </MainLayout>
19);

Best practices

• Use async resources as deep in the component tree as possible (see Lazy loading with Async Resources).
• In larger applications use factory methods for your async resources. The resourceify function helps you to quickly set up your factory methods.
• Add tags to your resources for a nuanced refreshing. You can even listen on backend-events (maybe pushed via a socket-connection) to invalidate the resources used in your session.
• Use models for a coherent interaction with your business models. This is a good practice in general, when your app has to deal with a large business model.

1// File resources/user.ts
2import { getUserProfile } from "../resources/user";
3import { resourceify } from "@mittwald/react-use-promise";
4
5export const getUserProfile = resourceify(apiClient.loadUserProfile);
6
7// File models/UserProfile.ts
8import { getUserProfile } from "../resources/user";
9// ...
10
11export class UserProfile {
12  public readonly id: string;
13  public readonly firstName: string;
14  public readonly lastName: string;
15
16  public constructor(data: UserProfileApiData) {
17    this.id = data.id;
18    this.firstName = data.firstName;
19    this.lastName = data.lastName;
20  }
21
22  public static useLoadById(id: string): UserProfile {
23    const data = getUserProfile([id]).use();
24    return new UserProfile(data);
25  }
26
27  public getFullName(): string {
28    return `${this.firstName} ${this.lastName}`;
29  }
30
31  public async updateName(firstName: string, lastName: string): Promise<void> {
32    await apiClient.updateProfile({
33      firstName,
34      lastName,
35    });
36  }
37}
38
39// File components/UserProfileName.tsx
40import { UserProfile } from "../models/UserProfile";
41
42export const UserProfileName: FC<{ id: string }> = (props) => {
43  const user = UserProfile.useLoadById(props.id);
44  return <>{user.getFullName()}</>;
45};

Migration guides

V1 to V2

• For more naming consistency the .watch() method of the Async Resource has changed to .use(). Replace all usages of watch() with use().