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 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