DEV Community: Andrei

Fetching resources in a React Suspense world

Andrei — Sat, 25 Apr 2020 22:09:41 +0000

In my previous article, I talked about how we can implement a data fetching pattern that we can use today with React Suspense.

But Suspense is not just about fetching data in a declarative way, but about fetching resources in general, including data. We saw how we can wrap api functions with the useAsyncResource hook, but what about other resources like images, sound files, and scripts?

Well, let's try to build that.

Building with what we have

Our custom useAsyncResource hook from my previous article is already doing enough, and we saw how flexible it is, being able to work with any function that returns a Promise.

Not sure what useAsyncResource is? Check it out on GitHub: https://github.com/andreiduca/use-async-resource

const fetchUser = id => fetch(`/path/to/user/${id}`).then(r => .json());

// in AppComponent.jsx
const [userDataReader] = useAsyncResource(fetchUser, 1);

// pass `userDataReader` to a "suspendable" child component

This looks simple enough when working with data fetching, because, well, fetch will make an api call, then return the response from the server, response that we read and display in our JSX. But what about images for example? How can we "read" the image "response" from the server?

Well, we don't. And we don't actually need to!

Preloading images

See, when displaying images in HTML, we have an img tag with an src attribute. Nothing more declarative than that! As soon as the browser sees that src tag, it will start downloading the image, displaying it progressively as its data comes through the wire. The image then becomes a resource of the page and, in most cases, the browser caches it. When the image is needed later, the browser will serve it immediately, not needing to download all its data again.

So what we really want in our case is actually to not render any img tag until we have the image already downloaded in the browser's cache. We want to display the image all at once, showing a loader until we have it in full. All we need to do is tell the browser to download the image (our resource) in the background, then tell us when that's done, so we can safely render our img tag.

Luckily, we don't need to actually render an img tag into the DOM to start downloading an image. We can do it in memory:

// create an img tag in memory
const img = document.createElement('img');

// attach a function to the `onload` handler
img.onload = () => {
  console.load("Image was downloaded!");
}

// as soon as we set the src attribute
// the browser will start downloading that image
img.src = '/some/path/to/an/image.jpg';

Turning it into a Promise

This is fine how it is, but we need a Promise. Actually, a function that returns a Promise. Let's create one:

function imageResource(filePath) {
  return new Promise((resolve) => {
    const img = document.createElement('img');

    img.onload = () => resolve(filePath);
    img.src = filePath;
  });
}

Nothing more simple than that. We now have a... function, that returns a... Promise, that just resolves with the input (the file path) when it finishes. A function, that returns a Promise, that resolves with a string. Just like we were doing with our api functions all along.

Using it with our hook

By now you probably guessed that this will immediately work with our custom useAsyncResource hook:

// in a UserComponent.jsx
const user = props.userReader();

// initialize the image "data reader"
const [userImageReader] = useAsyncResource(imageResource, user.profilePic);

return (
  <article>
    <React.Suspense fallback={<SomeImgPlaceholder />}>
      <ProfilePhoto resource={userImageReader} />
    </React.Suspense>
    <h1>{user.name}</h1>
    <h2>{user.bio}</h2>
  </article>
);

// in ProfilePhoto.jsx
const imageSrc = props.resource();

return <img src={imageSrc} />;

And that's it. The user image won't be rendered at all until the browser downloads it in the background.

A better user experience

But there will still be a flash of content here: the user name and bio will show for a brief moment along an image placeholder, then the actual image will show on the page. Wouldn't it be nice if we didn't show the entire user component until both the user data AND the image are downloaded, so we avoid a flash of content?

Well, remember that our custom hook caches the resources. So calling useAsyncResource(imageResource, someFilePath) multiple times won't trigger multiple identical api calls.

In our case, we're safe to remove the nested Suspense boundary and just render the profile photo alongside the other user info. The outer Suspense boundary that wraps the entire user object will try to render the user component until it doesn't throw anymore. This will call useAsyncResource multiple times for our user.profilePic file resource. But we don't care, because the first call will cache it, then all subsequent calls will use the first cached version.

So what we end up with is the simpler (and more user friendly) version:

function App() {
  // initialize the user data reader
  // immediately start fetching the user with id `someId`
  const [userDataReader] = useAsyncResource(fetchUser, someId);

  return (
    // pass the data reader to the user component
    // rendering an entire fallback until we have all we need
    <React.Suspense fallback={<><ImgFallback /><UserNameFallback /></>}>
      <User userReader={userDataReader} />
    </React.Suspense>
  );
}

function User(props) {
  // get the user data
  const user = props.userReader();

  // initialize the image "data reader" with the url for the profile pic
  // subsequent initializations will use the cached version anyways
  const [userImageReader] = useAsyncResource(imageResource, user.profilePic);

  // try rendering the profile image with the other user data
  // this will throw if the image was not downloaded yet
  return (
    <article>
      <ProfilePhoto resource={userImageReader} />
      <h1>{user.name}</h1>
      <h2>{user.bio}</h2>
    </div>
  );
}

function ProfilePhoto(props) {
  const imageSrc = props.resource();
  return <img src={imageSrc} />;
}

You can't get more declarative than that!

Images vs. scripts

Unlike an image, a script resource cannot be simply loaded in the background just by setting the src attribute. Instead, we will have to add the script tag to our DOM. But we can still hook into the onload handler to know when the script was loaded on our page.

function scriptResource(filePath: string) {
  return new Promise<string>((resolve) => {
    const scriptTag = document.createElement('script');
    scriptTag.onload = () => {
      resolve(filePath);
    };

    scriptTag.src = filePath;

    // appending the tag to the boody will start downloading the script
    document.getElementsByTagName('body')[0].appendChild(scriptTag);
  });
}

Using this scriptResource helper becomes just as easy:

const [jq] = useAsyncResource(scriptResource, 'https://code.jquery.com/jquery-3.4.1.slim.min.js');

return (
  <AsyncResourceContent fallback="jQuery loading...">
    <JQComponent jQueryResource={jq} />
  </AsyncResourceContent>
);

// and in JQComponent.tsx
const jQ = props.jQueryResource();
console.log('jQuery version:', window.jQuery.fn.jquery);

// jQuery should be available and you can do something with it

Notice we don't do anything with the const jQ, but we still need to call props.jQueryResource() so it can throw, rendering our fallback until the library is loaded on the page.

Of course, this is a contrived example. But it illustrates how you can dynamically load a 3rd party library before accessing anything from it.

Conclusion

As we showed in the previous article, adopting React Suspense can make your code simpler to write, read, and understand. It helps you avoid common traps that the async world can set for you, and lets you focus only on writing your stateful UI. And bringing images (or any other resources for that matter) into the mix shouldn't be any harder than that.

Practical data fetching with React Suspense that you can use today

Andrei — Fri, 17 Apr 2020 23:14:36 +0000

It's the hottest topic these days in the React community, and everybody gets either super excited or completely confused when the word "Suspense" is thrown around.

In this article, I'm not going to cover all the details of what the heck is up with this Suspense thing, as this has been discussed and explained numerous times, and the official docs are very explicit about the topic. Instead, I will show you how you can start using it today in your React projects.

TLDR?

yarn add use-async-resource

so you can

import { useAsyncResource } from 'use-async-resource';

// a simple api function that fetches a user
const fetchUser = (id: number) => fetch(`.../get/user/by/${id}`).then(res => res.json());

function App() {
  // 👉 initialize the data reader and start fetching the user immediately
  const [userReader, getNewUser] = useAsyncResource(fetchUser, 1);

  return (
    <>
      <ErrorBoundary>
        <React.Suspense fallback="user is loading...">
          <User userReader={userReader} /* 👈 pass it to a suspendable child component */ />
        </React.Suspense>
      </ErrorBoundary>
      <button onClick={() => getNewUser(2)}>Get user with id 2</button>
      {/* clicking the button 👆 will start fetching a new user */}
    </>
  );
}

function User({ userReader }) {
  const userData = userReader(); // 😎 just call the data reader function to get the user object

  return <div>{userData.name}</div>;
}

Of course there's more to it, so read on to find out.

"But I thought it's experimental and we shouldn't use it yet"

Concurrent mode is experimental! Suspense for lazy-loaded components, and even simple data fetching, works today. The React.Suspense component has been shipped since React 16.6, even before hooks!

All the other fancy things, like SuspenseList, useTransition, useDeferredValue, priority-based rendering etc are not officially out. But we're not covering them here. We're just trying to get started with the simple data fetching patterns, so when all these new things will be released, we can just improve our apps with them, building on top of the solutions that do work today.

So what is Suspense again?

In short, it's a pattern that allows React to suspend the rendering of a component until some condition is met. In most cases, until some data is fetched from the server. The component is "suspended" if, instead of returning some JSX like it's supposed to, it throws a promise. This allows React to render other parts of your app without your component being "ready".

Fetching data from a server is always an asynchronous action. At the same time, the data a component needs in order to render should be available as a simple synchronous read.

Of course, the whole Suspense thing is much more than that, but this is enough to get you started.

In code, it's a move from this:

function User(props) {
  const [user, setUser] = useState();
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState();

  useEffect(() => {
    setLoading(true);
    fetchUser(props.id)
      .then((userResponse) => {
        setUser(userResponse);
        setLoading(false);
      )
      .catch((e) => {
        setError(e);
        setLoading(false);
      );
  }, [props.id]);

  if (loading) return <div>loading...</div>;
  if (error) return <div>something happened :(</div>;

  return <div>{user.name}</div>;
}

function App() {
  return <User id={someIdFromSomewhere} />;
}

to this:

function User(props) {
  const user = props.userReader();

  return <div>{user.name}</div>;
}

function App() {
  const userReader = initializeUserReader(someIdFromSomewhere);

  return (
    <ErrorBoundary error="something went wrong with the user :(">
      <React.Suspense fallback="loading...">
        <User userReader={userReader} />
      </React.Suspense>
    </ErrorBoundary>
  );
}

Some details were omitted for simplicity.

If you haven't figured it out yet, userReader is just a synchronous function that, when called, returns the user object. What is not immediately clear is that it also throws a promise if the data is not ready. The React.Suspense boundary will catch this and will render the fallback until the component can be safely rendered. Calling userReader can also throw an error if the async request failed, which is handled by the ErrorBoundary wrapper. At the same time, initializeUserReader will kick off the async call immediately.

This is the most basic example, and the docs get into way more detail about the concepts behind this approach, its benefits, and further examples about managing the flow of data in your app.

Ok, so how do we turn async calls into sync data reads?

First of all, the simplest way to get some async data is to have a function that returns a Promise, which ultimately resolves with your data; for simplicity, let's call such functions "api functions":

const fetchUser = id => fetch(`path/to/user/get/${id}`);

Here, we're using fetch, but the Promise can be anything you like. We can even mock it with a random timeout:

const fetchUser = id =>
  new Promise((resolve) => {
    setTimeout(() => resolve({ id, name: 'John' }), Math.random() * 2000);
  });

Meanwhile, our component wants a function that just returns synchronous data; for consistency, let's call this a "data reader function":

const getUser = () => ({ id: 1, name: 'John' });

But in a Suspense world, we need a bit more than that: we also need to start fetching that data from somewhere, as well as throw the Promise if it's not resolved yet, or throw the error if the request failed. We will need to generate the data reader function, and we'll encapsulate the fetching and throwing logic.

The simplest (and most naive) implementation would look something like this:

const initializeUserReader = (id) => {
  // keep data in a local variable so we can synchronously request it later
  let data;
  // keep track of progress and errors
  let status = 'init';
  let error;

  // call the api function immediately, starting fetching
  const fetchingUser = fetchUser(id)
    .then((user) => {
      data = user;
      status = 'done';
    })
    .catch((e) => {
      error = e;
      status = 'error';
    });

  // this is the data reader function that will return the data,
  // or throw if it's not ready or has errored
  return () => {
    if (status === 'init') {
      throw fetchingUser;
    } else if (status === 'error') {
      throw error;
    }

    return data;
  }
};

If you've been reading other articles or even the official docs, you probably are familiar with this "special" pattern. It's nothing special about it, really: you immediately start fetching the data, then you return a function that, when called, will give you the data if the async call is ready, or throw the promise if it's not (or an error if it failed).

That's exactly what we've been using in our previous example:

// in AppComponent
const userReader = initializeUserReader(someIdFromSomewhere);

return (
  // ...
  <React.Suspense fallback="loading...">
    <User userReader={userReader} />
  </React.Suspense>
);

// in UserComponent
const user = props.userReader();

return <div>{user.name}</div>;

In the parent, we initialize the data reader, meaning we're triggering the api call immediately. We get back that "special" function which the child component can call to access the data, throwing if not ready.

"But this is not practical enough..."

Yes, and if you've been reading anything about Suspense, this is also not new. It's just an example to illustrate a pattern. So how do we turn it into something we can actually use?

First of all, it's not correct. You probably spotted by now that, if the App component updates for any other reason, the data reader gets re-initialized. So even if an api call is already in progress, if the App component re-renders, it will trigger another api call. We can solve this by keeping our generated data reader function in a local state:

// in AppComponent
const [userReader] = useState(() => initializeUserReader(someId));

Next, we will probably need to fetch new data based on a new user id. Again, the setter function from useState can help us:

const [userReader, updateReader] = useState(() => initializeUserReader(someId));

const btnClickCallback = useCallback((newUserId) => {
  updateReader(() => initializeUserReader(newUserId));
}, []);

return (
  // ...
  <button onClick={() => btnClickCallback(1)}>
    get user with id 1
  </button>
);

It looks better, but we're starting to see a lot of repetitions. Plus, it's hardcoded for our fetchUser api function. We need something more generic.

Let's change the initializer to accept an api function, any. We will also need to pass all the parameters the api function might need, if any.

const initializeDataReader = (apiFn, ...parameters) => {
  // ...

  const fetcingPromise = apiFn(...parameters)
    .then(/* ... */)
    // ...

  // ...
};

Our initializer now works with ANY api function which accepts ANY number of parameters (or even none). Everything else remains unchanged.

const [userReader, updateUserReader] = useState(() => initializeDataReader(fetchUser, userId));
const [postsReader, updatePostsReader] = useState(() => initializeDataReader(fetchPostByTags, 'react', 'suspense', 'data', 'fetching'));

const getNewUser = useCallback((newUserId) => {
  updateUserReader(() => initializeDataReader(fetchUser, newUserId));
}, []);

const getNewPosts = useCallback((...tags) => {
  updatePostsReader(() => initializeDataReader(fetchPostByTags, ...tags));
}, []);

But we're still facing the repetition problem when we need to fetch new data because we always need to pass the api function to the initializer. Time for a custom hook!

const useAsyncResource = (apiFunction, ...parameters) => {
  const [dataReader, updateDataReader] = useState(() => initializeDataReader(apiFunction, ...parameters));

  const updater = useCallback((...newParameters) => {
    updateDataReader(() => initializeDataReader(apiFunction, ...newParameters));
  }, [apiFunction]);

  return [dataReader, updater];
};

Here, we've encapsulated the logic of initializing both the data reader and the updater function. Now, when we need to fetch new data, we will never have to specify the api function again. We also return them as a tuple (a pair), so we can name them whatever we want when we use them:

const [userReader, refreshUserReader] = useAsyncResource(fetchUser, userId);

const onBtnClick = useCallback((newId) => {
  refreshUserReader(newId);
}, []);

Again, everything else remains unchanged: we still pass the generated data reader function to the "suspendable" component that will call it in order to access the data, and we wrap that component in a Suspense boundary.

Taking it further

Our custom useAsyncResource hook is simple enough, yet it works for most use cases. But it also needs other features that have proven useful in practice. So let's try to implement them next.

Lazy initialization

In some cases, we don't want to start fetching the data immediately, but rather we need to wait for a user's action. We might want to lazily initialize the data reader.

Let's modify our custom hook so that when it gets the api function as the only argument, we won't start fetching the data, and the data reader function will return undefined (just like an unassigned variable). We can then use the updater function to start fetching data on demand, just like before.

const [userReader, refreshUserReader] = useAsyncResource(fetchUser);

const btnClick = useCallback((userId) => {
  refreshUserReader(userId);
}, []);

// calling userReader() now would return `undefined`, unless a button is clicked

This might work for api functions that take arguments, but now how do we eagerly initialize a data reader for an api function that doesn't take any arguments? Well, as a convention, let's specify that in order to eagerly initialize such functions, the custom hook will expect an empty array as a second argument (just like React hooks!).

// this api function doesn't take any arguments
const fetchLatestPosts = () => fetch('path/to/latest/posts');

// eagerly initialized data reader, will start fetching immediately
const [latestPosts, refreshLatestPosts] = useAsyncResource(fetchLatestPosts, []);


// lazily initialized, won't start fetching until the button is clicked
const [latestPosts, getLatestPosts] = useAsyncResource(fetchLatestPosts);

const startFetchingLatestsPosts = useCallback(() => {
  // this will kick off the api call
  getLatestPosts();
}, []);

return (
  <button onClick={startFetchingLatestsPosts}>
    get latest posts
  </button>
);

In short, passing the api function params to the hook will kick off the api call immediately; otherwise, it won't. All cases would work on the same principle:

// lazily initialized data readers
const [userReader, refreshUserReader] = useAsyncResource(fetchUser);
const [latestPosts, getLatestPosts] = useAsyncResource(fetchLatestPosts);

// eagerly initialized data readers
const [userReader, refreshUserReader] = useAsyncResource(fetchUser, userId);
const [latestPosts, refreshLatestPosts] = useAsyncResource(fetchLatestPosts, []);

Implementing this will require some changes to our custom hook:

const useAsyncResource = (apiFunction, ...parameters) => {
  // initially defined data reader
  const [dataReader, updateDataReader] = useState(() => {
    // lazy initialization, when no parameters are passed
    if (!parameters.length) {
      // we return an empty data reader function
      return () => undefined;
    }

    // eager initialization for api functions that don't accept arguments
    if (
      // check that the api function doesn't take any arguments
      !apiFunction.length
      // but the user passed an empty array as the only parameter
      && parameters.length === 1
      && Array.isArray(parameters[0])
      && parameters[0].length === 0
    ) {
      return initializeDataReader(apiFunction);
    }

    // eager initialization for all other cases
    // (i.e. what we previously had)
    return initializeDataReader(apiFunction, ...parameters);
  });

  // the updater function remains unchaged
  const updater = useCallback((...newParameters) => {
    updateDataReader(() => initializeDataReader(apiFunction, ...newParameters));
  }, [apiFunction]);

  return [dataReader, updater];
};

Transforming the data upon reading

In other cases, the data you get back might be a full response from the server, or a deeply nested object, but your component only needs a small portion from that, or even a completely transformed version of your original data. Wouldn't it be nice if, when reading the data, we can easily transform it somehow?

// transform function
function friendsCounter(userObject) {
  return userObject.friendsList.length;
}

function UserComponent(props) {
  const friendsCount = props.userReader(friendsCounter);

  return <div>Friends: {friendsCount}</div>;
}

We will need to add this functionality to our data reader initializer:

const initializeDataReader = (apiFn, ...parameters) => {
  // ...

  return (modifier) => {
    if (status === 'init') // ...
      // ... throwing like before

    return typeof modifier === 'function'
      // apply a transformation if it exists
      ? modifier(data)
      // otherwise, return the unchanged data
      : data;
  }
};

What about TypeScript?

If you use TypeScript in your project, you might want to have this custom hook fully typed. You'd expect the data reader function to return the correct type of the data your original api function was returning as a Promise. Well, this is where things can get complicated. But let's try...

First, we know we are working with many types, so let's define them in advance to make everything more readable.

// a typical api function: takes an arbitrary number of arguments of type A
// and returns a Promise which resolves with a specific response type of R
type ApiFn<R, A extends any[] = []> = (...args: A) => Promise<R>;

// an updater function: has a similar signature with the original api function,
// but doesn't return anything because it only triggers new api calls
type UpdaterFn<A extends any[] = []> = (...args: A) => void;

// a simple data reader function: just returns the response type R
type DataFn<R> = () => R;
// a lazy data reader function: might also return `undefined`
type LazyDataFn<R> = () => (R | undefined);

// we know we can also transform the data with a modifier function
// which takes as only argument the response type R and returns a different type M
type ModifierFn<R, M = any> = (response: R) => M;

// therefore, our data reader functions might behave differently
// when we pass a modifier function, returning the modified type M
type ModifiedDataFn<R> = <M>(modifier: ModifierFn<R, M>) => M;
type LazyModifiedDataFn<R> = <M>(modifier: ModifierFn<R, M>) => (M | undefined);

// finally, our actual eager and lazy implementations will use
// both versions (with and without a modifier function),
// so we need overloaded types that will satisfy them simultaneously
type DataOrModifiedFn<R> = DataFn<R> & ModifiedDataFn<R>;
type LazyDataOrModifiedFn<R> = LazyDataFn<R> & LazyModifiedDataFn<R>;

That was a lot, but we covered all the types that we're going to use:

we start from a simple api function ApiFn<R, A ...> and we'll want to end up with a simple data reader function DataFn<R>;
this data reader function my return undefined if it's lazily initialized, so we'll also use LazyDataFn<R>;
our custom hook will correctly return one or the other based on how we initialize it, so we'll need to keep them separate;
the data reader function can accept an optional modifier function as a parameter, in which case it will return a modified type instead of the original data type (therefore ModifiedDataFn<R> or LazyModifiedDataFn<R>); without it, it should just return the data type;
to satisfy both these conditions (with or without the modifier function), we'll actually use DataOrModifiedFn<R> and LazyDataOrModifiedFn<R> respectively;
we also get back an updater function UpdaterFn<R, A ...>, with a similar definition as the original api function.

Let's start with the initializer. We know we're going to have two types of api functions: with arguments, and without arguments. We also know that the initializer will always kick off the api call, meaning the data reader is always eagerly generated. We also know that the returned data reader can have an optional modifier function passed to it.

// overload for wrapping an apiFunction without params:
// it only takes the api function as an argument
// it returns a data reader with an optional modifier function
function initializeDataReader<ResponseType>(
  apiFn: ApiFn<ResponseType>,
): DataOrModifiedFn<ResponseType>;

// overload for wrapping an apiFunction with params:
// it takes the api function and all its expected arguments
// also returns a data reader with an optional modifier function
function initializeDataReader<ResponseType, ArgTypes extends any[]>(
  apiFn: ApiFn<ResponseType, ArgTypes>,
  ...parameters: ArgTypes
): DataOrModifiedFn<ResponseType>;

// implementation that covers the above overloads
function initializeDataReader<ResponseType, ArgTypes extends any[] = []>(
  apiFn: ApiFn<ResponseType, ArgTypes>,
  ...parameters: ArgTypes
) {
  type AsyncStatus = 'init' | 'done' | 'error';

  let data: ResponseType;
  let status: AsyncStatus = 'init';
  let error: any;

  const fetcingPromise = apiFn(...parameters)
    .then((response) => {
      data = response;
      status = 'done';
    })
    .catch((e) => {
      error = e;
      status = 'error';
    });

  // overload for a simple data reader that just returns the data
  function dataReaderFn(): ResponseType;
  // overload for a data reader with a modifier function
  function dataReaderFn<M>(modifier: ModifierFn<ResponseType, M>): M;
  // implementation to satisfy both overloads
  function dataReaderFn<M>(modifier?: ModifierFn<ResponseType, M>) {
    if (status === 'init') {
      throw fetcingPromise;
    } else if (status === 'error') {
      throw error;
    }

    return typeof modifier === "function"
      ? modifier(data) as M
      : data as ResponseType;
  }

  return dataReaderFn;
}

Pretty complex, but it will get the job done.

Now let's continue typing the custom hook. We know there are 3 use cases, so we'll need 3 overloads: lazy initializing, eager initializing for api functions without arguments, and eager initializing for api functions with arguments.

// overload for a lazy initializer:
// the only param passed is the api function that will be wrapped
// the returned data reader LazyDataOrModifiedFn<ResponseType> is "lazy",
//   meaning it can return `undefined` if the api call hasn't started
// the returned updater function UpdaterFn<ArgTypes>
//   can take any number of arguments, just like the wrapped api function
function useAsyncResource<ResponseType, ArgTypes extends any[]>(
  apiFunction: ApiFn<ResponseType, ArgTypes>,
): [LazyDataOrModifiedFn<ResponseType>, UpdaterFn<ArgTypes>];

// overload for an eager initializer for an api function without params:
// the second param must be `[]` to indicate we want to start the api call immediately
// the returned data reader DataOrModifiedFn<ResponseType> is "eager",
//   meaning it will always return the ResponseType
//   (or a modified version of it, if requested)
// the returned updater function doesn't take any arguments,
//   just like the wrapped api function
function useAsyncResource<ResponseType>(
  apiFunction: ApiFn<ResponseType>,
  eagerLoading: never[], // the type of an empty array `[]` is `never[]`
): [DataOrModifiedFn<ResponseType>, UpdaterFn];

// overload for an eager initializer for an api function with params
// the returned data reader is "eager", meaning it will return the ResponseType
//   (or a modified version of it, if requested)
// the returned updater function can take any number of arguments,
//   just like the wrapped api function
function useAsyncResource<ResponseType, ArgTypes extends any[]>(
  apiFunction: ApiFn<ResponseType, ArgTypes>,
  ...parameters: ArgTypes
): [DataOrModifiedFn<ResponseType>, UpdaterFn<ArgTypes>];

And the implementation that satisfies all 3 overloads:

function useAsyncResource<ResponseType, ArgTypes extends any[]>(
  apiFunction: ApiFn<ResponseType> | ApiFn<ResponseType, ArgTypes>,
  ...parameters: ArgTypes
) {
  // initially defined data reader
  const [dataReader, updateDataReader] = useState(() => {
    // lazy initialization, when no parameters are passed
    if (!parameters.length) {
      // we return an empty data reader function
      return (() => undefined) as LazyDataOrModifiedFn<ResponseType>;
    }

    // eager initialization for api functions that don't accept arguments
    if (
      // ... check for empty array param
    ) {
      return initializeDataReader(apiFunction as ApiFn<ResponseType>);
    }

    // eager initialization for all other cases
    return initializeDataReader(apiFunction as ApiFn<ResponseType, ArgTypes >, ...parameters);
  });

  // the updater function
  const updater = useCallback((...newParameters: ArgTypes) => {
    updateDataReader(() =>
      initializeDataReader(apiFunction as ApiFn<ResponseType, ArgTypes >, ...newParameters)
    );
  }, [apiFunction]);

  return [dataReader, updater];
};

Now our custom hook should be fully typed and we can take advantage of all the benefits TypeScript gives us:

interface User {
  id: number;
  name: string;
  email: string;
}

const fetchUser = (id: number): Promise<User> => fetch(`path/to/user/${id}`);


function AppComponent() {
  const [userReader, updateUserReader] = useAsyncResource(fetchUser, someIdFromSomewhere);
  // `userReader` is automatically a function that returns an object of type `User`
  // `updateUserReader` is automatically a function that takes a single argument of type number

  return (
    // ...
    <React.Suspense fallback="loading...">
      <UserComponent userReader={userReader} />
    </React.Suspense>
  );
}

function UserComponent(props) {
  // `user` is automatically an object of type User
  const user = props.userReader();

  // your IDE will happily provide full autocomplete for this object
  return <div>{user.name}</div>;
}

Note how all types are inferred: we don't need to manually specify them all over the place, as long as the api function has its types defined.

Trying to call updateUserReader with other parameter types will trigger a type error. TS will also complain if we pass the wrong parameters to useAsyncResource.

// TS will complain about this
const [userReader, updateUserReader] = useAsyncResource(fetchUser, 'some', true, 'params');

// and this
updateUserReader('wrong', 'params');

However, if we don't pass any arguments to the hook other than the api function, the data reader will be lazily initialized:

function AppComponent() {
  const [userReader, updateUserReader] = useAsyncResource(fetchUser);
  // `userReader` is a function that returns `undefined` or an object of type `User`
  // `updateUserReader` is still a function that takes a single argument of type number

  const getNewUser = useCallback((newUserId: number) => {
    updateUserReader(newUserId);
  }, []);

  return (
    // ...
    <button onClick={() => getNewUser(1)}>
      load user with id 1
    </button>
    <React.Suspense fallback="loading...">
      <UserComponent userReader={userReader} />
    </React.Suspense>
  );
}

function UserComponent(props) {
  // here, `user` is `undefined` unless the button is clicked
  const user = props.userReader();

  // we need to add a type guard to get autocomplete further down
  if (!user) {
    return null;
  }

  // now autocomplete works again for the User type object
  return <div>{user.name}</div>;
}

Using the data reader with a modifier function also works as expected:

// a pure function that transforms the data of type User
function getUserDisplayName(userObj: User) {
  return userObj.firstName + ' ' + userObj.lastName;
}

function UserComponent(props) {
  // `userName` is automatically typed as string
  const userName = props.userReader(getUserDisplayName);

  return <div>Name: {userName}</div>;
}

Resource caching

There's one more thing our custom hook is missing: resource caching. Subsequent calls with the same parameters for the same api function should return the same resource, and not trigger new, identical api calls. But we'd also like the power to clear cached results if we really wanted to re-fetch a resource.

In a very simple implementation, we would use a Map with a hash function for the api function and the params as the key, and the data reader function as the value. We can go a bit further and create separate Map lists for each api function, so it's easier to control the caches.

const caches = new Map();

export function resourceCache<R, A extends any[]>(
  apiFn: ApiFn<R, A>,
  ...params: A | never[]
) {
  // if there is no Map list defined for our api function, create one
  if (!caches.has(apiFn)) {
    caches.set(apiFn, new Map());
  }

  // get the Map list of caches for this api function only
  const apiCache: Map<string, DataOrModifiedFn<R>> = caches.get(apiFn);

  // "hash" the parameters into a unique key*
  const pKey = JSON.stringify(params);

  // return some methods that let us control our cache
  return {
    get() {
      return apiCache.get(pKey);
    },
    set(data: DataOrModifiedFn<R>) {
      return apiCache.set(pKey, data);
    },
    delete() {
      return apiCache.delete(pKey);
    },
    clear() {
      return apiCache.clear();
    }
  };
}

Note: we're using a naive "hashing" method here by converting the parameters to a simple JSON string. In a real scenario, you would want something more sophisticated, like object-hash.

Now we can just use this in our data reader initializer:

function initializeDataReader(apiFn, ...parameters) {
  // check if we have a cached data reader and return it instead
  const cache = resourceCache(apiFn, ...parameters);
  const cachedResource = cache.get();

  if (cachedResource) {
    return cachedResource;
  }

  // otherwise continue creating it
  type AsyncStatus = 'init' | 'done' | 'error';
  // ...

  function dataReaderFn(modifier) {
    // ...
  }

  // cache the newly generated data reader function
  cache.set(dataReaderFn);

  return dataReaderFn;
}

That's it! Now our resource is cached, so if we request it multiple times, we'll get the same data reader function.

If we want to clear a cache so we can re-fetch a specific piece of data, we can manually do so using the helper function we just created:

const [latestPosts, getPosts] = useAsyncResource(fetchLatestPosts, []);

const refreshLatestPosts = useCallback(() => {
  // clear the cache so we force a new api call
  resourceCache(fetchLatestPosts).clear();
  // refresh the data reader
  getPosts();
}, []);

return (
  // ...
  <button onClick={refreshLatestPosts}>get fresh posts</button>
  // ...
);

In this case, we're clearing the entire cache for the fetchLatestPosts api function. But you can also pass parameters to the helper function, so you only delete the cache for those specific ones:

const [user, getUser] = useAsyncResource(fetchUser, id);

const refreshUserProfile = useCallback(() => {
  // only clear cache for user data reader for that id
  resourceCache(fetchUser, id).delete();
  // get new user data
  getUser(id);
}, [id]);

Future-proofing

We said in the beginning that the shiny new stuff is still in the works, but we'd like to take advantage of them once they're officially released.

So is our implementation compatible with what's coming next? Well, yes. Let's quickly look at some.

Enabling Concurrent Mode

First, we need to opt into making (the experimental version of) React work in concurrent mode:

const rootElement = document.getElementById("root");

ReactDOM.createRoot(rootElement).render(<App />);
// instead of the traditional ReactDOM.render(<App />, rootElement)

SuspenseList

This helps us coordinate many components that can suspend by orchestrating the order in which these components are revealed to the user.

<React.SuspenseList revealOrder="forwards">
  <React.Suspense fallback={<div>...user</div>}>
    <User userReader={userReader} />
  </React.Suspense>
  <React.Suspense fallback={<div>...posts</div>}>
    <LatestPosts postsReader={postsReader} />
  </React.Suspense>
</React.SuspenseList>

In this example, if the posts load faster, React still waits for the user data to be fetched before rendering anything.

useTransition

This delays the rendering of a child component being suspended, rendering with old data until the new data is fetched. In other words, it prevents the Suspense boundary from rendering the loading indicator while the suspendable component is waiting for the new data.

const [user, getUser] = useAsyncResource(fetchUser, 1);
const [startLoadingUser, isUserLoading] = useTransition({ timeoutMs: 1000 });

const getRandomUser = useCallback(() => {
  startLoadingUser(() => {
    getUser(Math.ceil(Math.random() * 1000));
  });
}, []);

return (
  // ...
  <button onClick={getRandomUser} disabled={isUserLoading}>get random user</button>
  <React.Suspense fallback={<div>...loading user</div>}>
    <User userReader={userReader} />
  </React.Suspense>
);

Here, the ...loading user message is not displayed while a new random user is being fetched, but the button is disabled. If fetching the new user data takes longer than 1 second, then the loading indicator is shown again.

Conclusion

With a little bit of work, we managed to make ourselves a nice wrapper for api functions that works in a Suspense world. More importantly, we can start using this today!

In fact, we already use it in production at OpenTable, in our Restaurant product. We started playing around with this at the beginning of 2020, and we now have refactored a small part of our application to use this technique. Compared to previous patterns we were using (like Redux-Observables), this one brings some key advantages that I'd like to point out.

It's simpler to write, read and understand

Treating data like it's available synchronously makes the biggest difference in the world, because your UI can fully be declarative. And that's what React is all about!

Not to mention the engineering time saved by shaving off the entire boilerplate that Redux and Redux-Observables were requiring. We can now write code much faster and more confident, bringing projects to life in record time.

It's "cancellable"

Although not technically (you can't prevent a fetch or a Promise to fulfill), as soon as you instantiate a new data reader, the old one is discarded. So stale or out of order updates just don't happen anymore!

This used to bring a lot of headaches to the team with traditional approaches. Then, after adopting Redux-Observables, we had to write A LOT of boilerplate: registering epics, listening for incoming actions, switch-mapping and calling the api (thus canceling any previously triggered one), finally dispatching another action that would update our redux store.

It's nothing new

All the Redux + Observables code was living in external files too, so it would make understanding the logic of a single component way harder. Not to mention the learning curve associated with all this. Junior engineers would waste precious time reading cryptic code and intricate logic, instead of focusing on building product features.

Instead, now we just update the data reader by calling the updater function! And that's just plain old JavaScript.

In closing, I'd like to leave you with this thread about "Why Suspense matters" so much. Ultimately, I think the beauty of the entire thing is in its simplicity.