Docs for Promise subclasses

[eps1lon]

Turning posts into docs

I.e. how React leverages promise.status. Targeted at Suspense-enabled libraries.

Preview

[github-actions]

Size changes

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

[rickhanlonii]

Can we add some code here for a high-level view of what this looks like?

const dataPromise = {
  then: () => {},
  status: 'fulfilled',
  value: `some data'
}

[eps1lon]

I don't think we want to show how to create a custom thenable.

[sebmarkbage]

Yea while you can use a custom Thenable, it's probably recommended to just use a native Promise for this.

You can make it a sub-class like such:

class FulfilledPromise extends Promise {
  status = 'fulfilled';
  value = null;
  constructor(data) {
     super(resolve => resolve(data));
     this.value = data;
  }
}
const promise = new FulfilledPromise(data);

This makes it more palatable for sticklers that thinks adding expandos to native objects is bad. It shows that the pattern is encouraged by the platform. If it wasn't, then why can I sub-class natives? If can't add fields, what am I supposed to do with those sub-classes?

But in practice when you're not adding any methods to the prototype this is really just the same thing as:

const promise = Promise.resolve(data);
promise.status = 'fulfilled';
promise.value = data;

Which is smaller code and faster, so why not do that? It also doesn't risk getting compiled which would break native subclassing.

So maybe document one stickler version and one faster version (and hint that thenables might be even faster).

[eps1lon]

done

[rickhanlonii]

Can we do something like this instead:

And structure it so that the most relevant code (the promise creation) is what's visible first?

Like this you should see this:

With a Promise subclass

function getUser(id) {
  return {
    status: 'fulfilled',
    value: `User #${id}`,
    then: () => {}
  }
}


function UserDetails() {
  const user = use(getUser());
  return <p>Hello, {user}!</p>;
}

Without a Promise subclass

function getUser(id) {
  return Promise.resolve(`User #${id}`);
}


function UserDetails() {
  const user = use(getUser());
  return <p>Hello, {user}!</p>;
}

[eps1lon]

done

[Ephem]

I like this!

Many examples in the docs that compares approaches like this tend to point out what to look for, like "Note how loading the users shows a loading state", but I don't think that's necessary here.

[Ephem]

I think this is great content and very helpful!

It's a pretty advanced topic though so maybe point out the intended audience early? Maybe lead with:

If you are implementing a Suspense-enabled library, you can help React avoid unnecessarily suspending when you know the promise has already settled, by using status and value or reason fields.

I think "subclass" and "microtask" is likely language that will trip people up, but if it's clear this is an advanced topic I think that's fine.

Maybe be a bit more explicit about the rejected/reason case as well?

Calling use conditionally depending on whether a Promise is settled or not is discouraged. use should be called unconditionally so that React DevTools can show that the Component may suspend on data.

I think this should be its own paragraph as it's a separate point.

[eps1lon]

done

[Ephem]

I think this is good!

Maybe "... if the update was not part of a Transition (e.g. ReactDOM.flushSync())" is too much detail here? At least for me it made the sentence slightly harder to parse and didn't seem that important in this specific context, but not a big deal.

I wondered what it would look like if the docs tried to explain the basics more and noodled on a separate approach, I'm not at all sure this is better or captures everything correctly, so read it as an exploration:

Suggested change

	React will read the `status` field on the Promise to synchronously read the value without having to wait for a microtask. If the Promise is already settled (resolved or rejected), React can read the value immediately without suspending and showing a fallback if the update was not part of a Transition (e.g. [`ReactDOM.flushSync()`](/reference/react-dom/flushSync)).
	React will set the `status` field itself if the passed Promise does not have this field set. Suspense-enabled libraries should set the `status` field on the Promises they create to avoid unnecessary fallbacks.
	In JavaScript, Promise callbacks always run in a "microtask", even if the Promise has already settled. This means that if you call `use(alreadySettledPromise)`, React can not synchronously resolve its values and has to unnecessarily suspend.
	By adding `status: 'fulfilled' | 'rejected'` and either `value` or `reason` to the Promise when it settles, your library makes it possible for React to access these values synchronously and avoid suspending. It is recommended for Suspense-enabled libraries to do this.
	React will set these fields itself if the passed Promise does not have them set.

[rickhanlonii]

I like this, but I also like including examples of when this can happen. But I wouldn't use flush sync for that, I would use examples like "such as when the user clicks the back button, or when they continue interacting with the page while a transition is in progress"

[Ephem]

I like that. The preload case might be another one that's easy to understand and helps explain things.

[Ephem]

I like this!

Many examples in the docs that compares approaches like this tend to point out what to look for, like "Note how loading the users shows a loading state", but I don't think that's necessary here.

[Ephem]

NIT: Is flushSync necessary for this to happen, or is it there to illustrate the difference to a transition clearer?

If it's not necessary, it might distract from the point more than help, at least for me it made me wonder if this was a necessary condition?

I do think it's good to point out this does not happen with transitions though and not sure how to do that differently. 😄

[rickhanlonii]

There's actually a much easier and common way for this to happen:

export default function App() {
  const [userId, setUserId] = useState(null);
  const [userUsable, setUser] = useState(null);
  const [isPending, startTransition] = useTransition();

  return (
    <div>
      <button
        onClick={() => {
          // ⚠️ this startTransition causes a sync update
          // to App to update the `isPending` value
          startTransition(() => {
            setUser(preloadUser(1));
            setUserId(1);
          });
        }}
      >
        Load User #1
      </button>
      {/* ... */}
      <span>{isPending && 'loading...'}</span>
      <Suspense key={userId} fallback={<p>Loading</p>}>
        {/* 
            ⚠️  Without proper memoization, the sync update 
            flows into this boundary, causing it to suspend
            if the data is not available syncronously
        */}
        {userUsable ? (
          <UserDetails userUsable={userUsable} />
        ) : (
          <p>No user selected</p>
        )}
      </Suspense>
    </div>
  );
}

https://codesandbox.io/p/sandbox/ymm9s8?file=%2Fsrc%2FApp.js

[Ephem]

I realize now that you might both trying to show practical examples of how this situation might happen in real code? I was focused on just the practical aspects of what's necessary for it to trigger.

I was focused on the fact that even the first example triggers the suspend with just:

      <button
        onClick={() => {
          setUser(preloadUser(2));
          setUserId(2);
        }}
      >