stream: share webstreams async iterator methods

[mcollina]

Round 20 of the webstreams performance work (follows #66230). It targets for await over a short-lived stream, such as iterating a response body once per request.

Async iterator methods on a shared prototype

ReadableStream.prototype.values() built every iterator from an object literal holding next(), return() and a computed [Symbol.asyncIterator]() method, plus closures for the next and return steps. A literal with a computed symbol-key method goes through the runtime on every evaluation, the same cost #66154 removed from pipeTo and tee. That cost close to a microsecond per iterator.

next() and return() now live on a shared ReadableStreamAsyncIterator prototype, which is how WebIDL defines async iterators. Each iterator holds only a private reference to its state, and that state doubles as the iterator's read request. The prototype extends %AsyncIteratorPrototype% and has exactly the next and return properties WPT checks for. This makes the placeholder AsyncIterator object in internal/webstreams/util.js unnecessary. The return steps are no longer an async function either: the cancel path chains the result onto the cancel promise, which settles one microtask later exactly as await did. Microtask timing is unchanged, including the extra hop before the first read.

Observable differences

Both follow WebIDL and match browsers:

• iterators no longer carry own next/return properties (Object.keys(stream.values()) was ['next', 'return'], now []);
• next() and return() return a promise rejected with ERR_INVALID_THIS when called on something that is not a ReadableStream async iterator, for example after const { next } = iterator.

test/parallel/test-whatwg-readablestream-async-iterator-shape.js covers both.

Benchmark

benchmark/webstreams/lifecycle.js gains an async-iterator kind (create a stream, read 4 chunks with for await).

node benchmark/compare.js --runs 20 (lifecycle, readable-async-iterator, readable-read):

                                                             confidence improvement accuracy (*)    (**)   (***)
webstreams/lifecycle.js kind='async-iterator' n=50000               ***     16.22 %       ±4.51%  ±6.10%  ±8.14%
webstreams/lifecycle.js kind='pipe-through' n=50000                         -1.97 %       ±4.39%  ±5.88%  ±7.73%
webstreams/lifecycle.js kind='pipe-to' n=50000                              -3.13 %       ±8.35% ±11.19% ±14.72%
webstreams/lifecycle.js kind='readable' n=50000                             -0.54 %       ±2.96%  ±3.97%  ±5.23%
webstreams/readable-async-iterator.js type='bytes' n=100000                 -2.65 %       ±3.37%  ±4.51%  ±5.94%
webstreams/readable-async-iterator.js type='normal' n=100000                 1.49 %       ±5.42%  ±7.26%  ±9.56%
webstreams/readable-read.js type='byob' n=100000                            -0.91 %       ±2.00%  ±2.69%  ±3.57%
webstreams/readable-read.js type='normal' n=100000                           5.54 %       ±6.24%  ±8.36% ±10.99%

The long-running iterator rows are flat as expected, since the saving is per iterator, not per chunk. With a source that enqueues its chunks in start(), iterator creation is a larger share of the work and a local harness measured +70 %.

A 26-scenario microtask-ordering stress for async iteration logs identically against main. It covers concurrent next() calls, return() with a read pending, slow, rejecting and throwing cancel(), break, errors, preventCancel and byte streams. WPT streams and the webstreams parallel batch are green.

---

AI generated, humanly reviewed.

[nodejs-github-bot]

Review requested:

• @nodejs/performance

[codecov]

Codecov Report

❌ Patch coverage is 94.28571% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.42%. Comparing base (6866129) to head (01fc4d2).
⚠️ Report is 88 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/webstreams/readablestream.js	94.28%	9 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #66392      +/-   ##
==========================================
+ Coverage   90.36%   90.42%   +0.06%     
==========================================
  Files         792      791       -1     
  Lines      275498   275616     +118     
  Branches    52798    52850      +52     
==========================================
+ Hits       248947   249225     +278     
+ Misses      16976    16780     -196     
- Partials     9575     9611      +36     

Files with missing lines	Coverage Δ
lib/internal/webstreams/util.js	97.07% <ø> (-0.05%)	⬇️
lib/internal/webstreams/readablestream.js	98.08% <94.28%> (+0.01%)	⬆️

... and 54 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Renegade334]

This makes the placeholder AsyncIterator object in internal/webstreams/util.js unnecessary.

🙏 this was one of our uglier WPT hacks!

[mcollina]

@Renegade334 ptal

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/78157/

[Renegade334]

LGTM!

[nodejs-github-bot]

Commit Queue failed

This pull request has multiple commits, but no landing policy was selected.

Add commit-queue-squash PRs the Commit Queue should land as one squashed commit. to land it as one commit, or commit-queue-rebase PRs the Commit Queue should land as multiple self-contained commits. to land the commits separately.

The pull request was removed from the Commit Queue and labeled commit-queue-failed PRs whose Commit Queue landing failed and need manual intervention before retrying. . After resolving the failure, remove that label and add commit-queue PRs queued for automated landing through the Commit Queue. to retry.

Full Commit Queue output

�[36m⠋�[39m Loading data for nodejs/node/pull/66392
�[36m⠋�[39m Loading data for nodejs/node/pull/66392
�[36m⠋�[39m Getting collaborator contacts from README of nodejs/node
�[36m⠋�[39m Getting PR from nodejs/node/pull/66392
�[36m⠋�[39m Getting reviews from nodejs/node/pull/66392
�[36m⠋�[39m Getting comments from nodejs/node/pull/66392
�[36m⠋�[39m Getting commits from nodejs/node/pull/66392
✔  Done loading data for nodejs/node/pull/66392
----------------------------------- PR info ------------------------------------
Title      stream: share webstreams async iterator methods (#66392)
Author     Matteo Collina <matteo.collina@gmail.com> (@mcollina)
Branch     mcollina:webstream-perf-round20 -> nodejs:main
Labels     needs-ci, commit-queue, web streams
Commits    2
 - stream: share webstreams async iterator methods
 - stream: add webstreams async iterator toStringTag
Committers 1
 - Matteo Collina <hello@matteocollina.com>
PR-URL: https://github.com/nodejs/node/pull/66392
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/66392
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Tue, 29 Sep 2026 07:50:52 GMT
   ✔  Approvals: 2
   ✔  - Paolo Insogna (@ShogunPanda) (TSC): https://github.com/nodejs/node/pull/66392#pullrequestreview-5399437634
   ✔  - René (@Renegade334): https://github.com/nodejs/node/pull/66392#pullrequestreview-5407911877
   ✔  Last GitHub CI successful
   ℹ  Last Full PR CI on 2026-10-04T07:21:34Z: https://ci.nodejs.org/job/node-test-pull-request/78157/
�[36m⠙�[39m Querying data for job/node-test-pull-request/78157/
�[36m⠙�[39m Querying data for job/node-test-pull-request/78157/
�[36m⠙�[39m Querying API for job/node-test-pull-request/78157/
✔  Build data downloaded
   ✔  Last Jenkins CI successful
--------------------------------------------------------------------------------
   ✔  No git cherry-pick in progress
   ✔  No git am in progress
   ✔  No git rebase in progress
--------------------------------------------------------------------------------
�[36m⠹�[39m Bringing origin/main up to date...
�[36m⠹�[39m Bringing origin/main up to date...
From https://github.com/nodejs/node
 * branch                  main       -> FETCH_HEAD
✔  origin/main is now up-to-date
�[36m⠸�[39m Downloading patch for 66392
�[36m⠸�[39m Downloading patch for 66392
From https://github.com/nodejs/node
 * branch                  refs/pull/66392/merge -> FETCH_HEAD
✔  Fetched commits as 85df70eecc2b..01fc4d288697
--------------------------------------------------------------------------------
[main 8af81c2f97] stream: share webstreams async iterator methods
 Author: Matteo Collina <hello@matteocollina.com>
 Date: Mon Sep 28 09:07:14 2026 +0200
 4 files changed, 226 insertions(+), 158 deletions(-)
 create mode 100644 test/parallel/test-whatwg-readablestream-async-iterator-shape.js
[main 1034919789] stream: add webstreams async iterator toStringTag
 Author: Matteo Collina <hello@matteocollina.com>
 Date: Fri Oct 2 08:21:19 2026 +0200
 2 files changed, 14 insertions(+), 1 deletion(-)
   ✔  Patches applied
There are 2 commits in the PR. Attempting autorebase.
(node:687) [DEP0190] DeprecationWarning: Passing args to a child process with shell option true can lead to security vulnerabilities, as the arguments are not escaped, only concatenated.
(Use `node --trace-deprecation ...` to show where the warning was created)
Rebasing (2/4)
Executing: git node land --amend --yes
--------------------------------- New Message ----------------------------------
stream: share webstreams async iterator methods

ReadableStream.prototype.values() built each iterator from an object
literal with a computed symbol-key method plus five closures. Such a
literal is rebuilt through the runtime on every evaluation, costing
close to a microsecond per iterator, which dominates iterating a
short-lived stream.

Move next() and return() to a shared ReadableStreamAsyncIterator
prototype, as for any WebIDL async iterator, and keep the per-iterator
state in its read request. The prototype chain and property shape are
the ones WPT checks; the placeholder AsyncIterator object in util.js is
no longer needed. As in WebIDL, next() and return() now reject when
called on something that is not a ReadableStream async iterator, and
iterators no longer carry own next/return properties.

Add an async-iterator kind to benchmark/webstreams/lifecycle.js.

webstreams/lifecycle.js kind='async-iterator'   ***  +16.22%

Signed-off-by: Matteo Collina <hello@matteocollina.com>
PR-URL: https://github.com/nodejs/node/pull/66392
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>
--------------------------------------------------------------------------------
[detached HEAD 3e1a11299b] stream: share webstreams async iterator methods
 Author: Matteo Collina <hello@matteocollina.com>
 Date: Mon Sep 28 09:07:14 2026 +0200
 4 files changed, 226 insertions(+), 158 deletions(-)
 create mode 100644 test/parallel/test-whatwg-readablestream-async-iterator-shape.js
Rebasing (3/4)
Rebasing (4/4)
Executing: git node land --amend --yes
--------------------------------- New Message ----------------------------------
stream: add webstreams async iterator toStringTag

WebIDL gives an async iterator prototype the class string
"<interface> AsyncIterator", so ReadableStream iterators now report
'ReadableStream AsyncIterator' through Symbol.toStringTag.

Signed-off-by: Matteo Collina <hello@matteocollina.com>
PR-URL: https://github.com/nodejs/node/pull/66392
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>
--------------------------------------------------------------------------------
[detached HEAD 26c19ec6c7] stream: add webstreams async iterator toStringTag
 Author: Matteo Collina <hello@matteocollina.com>
 Date: Fri Oct 2 08:21:19 2026 +0200
 2 files changed, 14 insertions(+), 1 deletion(-)
Successfully rebased and updated refs/heads/main.
--------------------------------------------------------------------------------
   ℹ  Add `commit-queue-squash` label to land the PR as one commit, or `commit-queue-rebase` to land as separate commits.

View workflow run

[nodejs-github-bot]

Landed in c56cb09