react-suspense-fetch

A low-level library for React Suspense for Data Fetching

Introduction

React 18 comes with Suspense (sort of), but Suspense for Data Fetching is left for data frameworks. The goal of this library is to provide a thin API to allow Suspense For Data Fetching without richer frameworks.

Project status: Waiting more feedbacks before finalizing the API.

Install

npm install react-suspense-fetch

Usage

import React, { Suspense, useState, useTransition } from 'react';
import { createRoot } from 'react-dom/client';

import { createFetchStore } from 'react-suspense-fetch';

// 1️⃣
// Create a store with an async function.
// The async function can take one input argument.
// The input value becomes the "key" of cache.
// By default, keys are compared with strict equal `===`.
const store = createFetchStore(async (userId) => {
  const res = await fetch(`https://reqres.in/api/users/${userId}?delay=3`);
  const data = await res.json();
  return data;
});

// 2️⃣
// Prefetch data for the initial data.
// We should prefetch data before getting the result.
// In this example, it's done at module level, which might not be ideal.
// Some initialization function would be a good place.
// We could do it in render function of a component close to root in the tree.
store.prefetch('1');

// 3️⃣
// When updating, wrap with startTransition to lower the priority.
const DisplayData = ({ result, update }) => {
  const [isPending, startTransition] = useTransition();
  const onClick = () => {
    startTransition(() => {
      update('2');
    });
  };
  return (
    <div>
      <div>First Name: {result.data.first_name}</div>
      <button type="button" onClick={onClick}>Refetch user 2</button>
      {isPending && 'Pending...'}
    </div>
  );
};

// 4️⃣
// We should prefetch new data in an event handler.
const Main = () => {
  const [id, setId] = useState('1');
  const result = store.get(id);
  const update = (nextId) => {
    store.prefetch(nextId);
    setId(nextId);
  };
  return <DisplayData result={result} update={update} />;
};

// 5️⃣
// Suspense boundary is required somewhere in the tree.
// We can have many Suspense components at different levels.
const App = () => (
  <Suspense fallback={<span>Loading...</span>}>
    <Main />
  </Suspense>
);

createRoot(document.getElementById('app')).render(<App />);

API

FetchStore

fetch store

prefetch will start fetching. get will return a result or throw a promise when a result is not ready. preset will set a result without fetching. evict will remove a result. abort will cancel fetching.

There are three cache types:

WeakMap: input has to be an object in this case
Map: you need to call evict to remove from cache
Map with areEqual: you can specify a custom comparator

Type: {prefetch: function (input: Input): void, get: function (input: Input, option: GetOptions): Result, preset: function (input: Input, result: Result): void, evict: function (input: Input): void, abort: function (input: Input): void}

Properties

prefetch function (input: Input): void
get function (input: Input, option: GetOptions): Result
preset function (input: Input, result: Result): void
evict function (input: Input): void
abort function (input: Input): void

createFetchStore

create fetch store

Parameters

fetchFunc FetchFunc<Result, Input>
cacheType CacheType<Input>?
presets Iterable<any>?

Examples

import { createFetchStore } from 'react-suspense-fetch';

const fetchFunc = async (userId) => (await fetch(`https://reqres.in/api/users/${userId}?delay=3`)).json();
const store = createFetchStore(fetchFunc);
store.prefetch('1');

Examples

The examples folder contains working examples. You can run one of them with

PORT=8080 npm run examples:01_minimal

and open http://localhost:8080 in your web browser.

You can also try them in codesandbox.io: 01 02 03 04 05 06 07

Blogs

Diving Into React Suspense Render-as-You-Fetch for REST APIs