Skip to content

perf: stream a generator's output to the generators that read it - #1238

Open
ovflowd wants to merge 1 commit into
perf/stream-workerfrom
perf/stream-cache
Open

ovflowd wants to merge 1 commit into
perf/stream-workerfrom
perf/stream-cache

Conversation

@ovflowd

@ovflowd ovflowd commented Nov 3, 2026 •

Copy link
Copy Markdown
Member

Description

This PR lets the cache stream a generator's output to the generators that read it, instead of collecting every chunk first. It's the second part of a stack that splits #1205.

Every dependency edge was a full barrier: cache.consume collected all of a generator's chunks before its dependent started, so each stage of a build waited for the whole of the one before it.

  • A generator can set streamsInput: true to get its dependency's output as an async iterable of chunks, read as they're produced. With one thread nothing runs alongside, so it still gets one array, and a dependency that doesn't stream arrives as a single chunk. No generator sets it yet.
  • The cache runs a streamed generator once, with createReplay: any number of readers each read all of its chunks, from the first, while it still runs. Once every reader has started, a chunk is let go as soon as all of them have read it, rather than when the last one is done.
  • docs/creating-generators.md has a new Streaming Input section.

Validation

Added tests for createReplay (every reader gets every chunk in order, a reader that starts late, a chunk let go before a reader read it, a failure), for the cache (one run for streaming and collecting readers, chunks let go only once every reader has read them, a stream read only once, failures before and after the stream is read), and for runGenerators (streaming to a generator that streams its input, and giving it the whole input with one thread). Built on 12 of Node.js's API docs at 1 and 4 threads, the output is byte-identical to main's.

Related Issues

Refs: #1205

Check List

  • I have read the Contributing Guidelines and made commit messages that follow the guideline.
  • I have run node --run test and all tests passed.
  • I have check code formatting with node --run format:check & node --run lint.
  • I've covered new added functionality with unit tests if necessary.

Every dependency edge was a full barrier: the cache collected all of a
generator's chunks before its dependents started, so each stage of a
build waited for the whole of the one before it.

A generator can now set streamsInput: true to receive its dependency's
output as an async iterable of chunks, read as they are produced. With
one thread nothing runs alongside, so it still gets one array, and a
dependency that doesn't stream arrives as a single chunk. Nothing sets
it yet.

The cache runs a streamed generator once, recording its chunks so any
number of readers each read all of them, from the first, while it still
runs. Once every reader has started, it lets go of a chunk as soon as
all of them have read it, rather than holding the output until the last
one is done.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
Assisted-by: Claude Sonnet 5.5 <noreply@anthropic.com>
@vercel

vercel Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
api-docs-tooling Ready Ready Preview Nov 3, 2026 7:35pm UTC

Request Review

@ovflowd
ovflowd added this pull request to stack #1244 November 3, 2026 19:34
@ovflowd ovflowd changed the title perf(core): stream a generator's output to the generators that read it perf: stream a generator's output to the generators that read it Nov 3, 2026
@codecov

codecov Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 99.22822% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.35%. Comparing base (e677946) to head (dc17197).

Files with missing lines Patch % Lines
packages/core/src/__tests__/generators.test.mjs 96.21% 5 Missing ⚠️
packages/core/src/__tests__/caching.test.mjs 99.75% 1 Missing ⚠️
packages/core/src/utils/__tests__/replay.test.mjs 98.83% 1 Missing ⚠️
Additional details and impacted files
@@                  Coverage Diff                   @@
##           perf/stream-worker    #1238      +/-   ##
======================================================
+ Coverage               94.21%   94.35%   +0.14%     
======================================================
  Files                     291      293       +2     
  Lines                   29366    30238     +872     
  Branches                 2985     3076      +91     
======================================================
+ Hits                    27666    28531     +865     
- Misses                   1678     1685       +7     
  Partials                   22       22              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@cloudflare-workers-and-pages

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ dc17197 2026-11-03T19:36:16.433Z View logs ↗

@ovflowd
ovflowd marked this pull request as ready for review November 3, 2026 20:39
@ovflowd
ovflowd requested a review from a team as a code owner November 3, 2026 20:39

This branch was successfully deployed

1 active deployment
Preview – api-docs-tooling — dc171971 Deployed Nov 3, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant