fix: add Streamable.from to avoid eager promises

[migueloller]

What/Why?

Our Streamable pattern relies on passing promises as props to RSCs and client components. For RSCs, it "pushes down" data fetching so that Next.js will mark particular components as dynamic when using PPR. For client components, it streams the data to the client while triggering a Suspense boundary.

For the former case, we were getting the following error:

Unhandled Rejection: Error: Route /[locale]/category/[slug] needs to bail out of prerendering at this point because it used `await searchParams`, `searchParams.then`, or similar. React throws this special object to indicate where. It should not be caught by your own try/catch. Learn more: https://nextjs.org/docs/messages/ppr-caught-error
    at P (.next/server/chunks/5884.js:1:42808)
    at Object.get (.next/server/chunks/4019.js:4:32956)
    at <unknown> (.next/server/app/[locale]/(default)/(faceted)/category/[slug]/page.js:42:741) {
  ‘$$typeof’: Symbol(react.postpone)
}
Node.js process exited with exit status: 128. The logs above can help with debugging the issue.

We believe the reason for this is that promises are eager, not lazy. This means that if we call an async function on an RSC, it will start executing even if the RSC that we pass the promise to hasn't rendered yet. In particular, if the execution calls cookies(), await searchParams or other dynamic APIs which throw, it results in the error above.

This PR introduces Streamable.from which abstracts the idea of a "lazy promise", deferring execution until the first .then call. It uses Streamable.from anywhere we were calling an async function without await to avoid the unhandled rejection.

Something particular about Streamable.from is that it allows us to refer to values via closure directly in the RSC, removing the need for creating async functions when using the streamable pattern. This PR purposefully keeps this out of scope and I plan to address this in a future PR.

Furthermore, the implementation of Streamable.from is a simple wrapper around p-lazy. In a future PR, I intend to remove the dependency on p-lazy and have a custom implementation for lazy promises.

This PR is pre-work for the move to PPR + dynamicIO to better optimize caching and performance of Catalyst.

Testing

CleanShot.2025-03-24.at.17.52.10.mp4

[linear]

ENG-7914 Apply PPR and `dynamicIO` patterns from PDP to rest of app

[changeset-bot]

⚠️ No Changeset found

Latest commit: b8732362cee4e340ed998cba3c38b760ded0a181

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
catalyst-canary	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Mar 25, 2025 2:37pm

4 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
catalyst	⬜️ Ignored (Inspect)			Mar 25, 2025 2:37pm
catalyst-au	⬜️ Ignored (Inspect)	Visit Preview		Mar 25, 2025 2:37pm
catalyst-soul	⬜️ Ignored (Inspect)	Visit Preview		Mar 25, 2025 2:37pm
catalyst-uk	⬜️ Ignored (Inspect)	Visit Preview		Mar 25, 2025 2:37pm

[fikrikarim]

Looks great!

[fikrikarim]

Should we automatically wrap every Streamable.all promise with Streamable.from?

[migueloller]

I found myself wondering if we needed Streamable.all if we had Streamable.from and I think the answer is "yes" given that they have different goals. Streamable.all will combine multiple streamables and keep that stable so that we don't get infinite suspensions in the client side. There's a question of whether we want to be doing that at all, though. I'm wondering if we should remove Streamable.all. Because we shouldn't be creating new streamables in client components, just how we shouldn't be creating promises in client components and because on the server we can use Streamable.from

That being said, you might have a point here about Streamable.all potentially eagerly executing both of these promises. I'll look into it.

[migueloller]

Ok, so I tested it and Streamable.all does trigger the executor, which is problematic.

Also, I remembered that the reason we added Streamable.all was because we wanted to be able to use VIBES components that were "shared" components with Makeswift, which would execute in a client environment.

I'm going to have to re-think Streamable.all but I will do this in a separate PR. cc: @agurtovoy

[github-actions]

⚡️🏠 Lighthouse report

Lighthouse ran against https://catalyst-canary-mx1yj5yh7-bigcommerce-platform.vercel.app

🖥️ Desktop

We ran Lighthouse against the changes on a desktop and produced this report. Here's the summary:

Category	Score
🟢 Performance	99
🟢 Accessibility	92
🟠 Best practices	78
🟠 SEO	82

📱 Mobile

We ran Lighthouse against the changes on a mobile and produced this report. Here's the summary:

Category	Score
🟠 Performance	84
🟢 Accessibility	92
🟠 Best practices	78
🟠 SEO	85