Skip to content

doc: clarify stream forEach concurrency behavior - #67537

Open
Ultroncn wants to merge 2 commits into
nodejs:mainfrom
Ultroncn:doc/stream-foreach-concurrency
Open

Ultroncn wants to merge 2 commits into
nodejs:mainfrom
Ultroncn:doc/stream-foreach-concurrency

Conversation

@Ultroncn

Copy link
Copy Markdown
Contributor

Fixes: #66106

Hi! The readable.forEach() docs say the method "can optionally process chunks concurrently", but with the default concurrency of 1 that does not happen: forEach is implemented on top of readable.map (lib/internal/streams/operators.js), and the map pump pauses reading until the previous fn promise has settled, so chunks are processed strictly one at a time unless concurrency is set above 1.

This PR clarifies that in the docs:

  • the "process chunks concurrently" sentence now says this applies when concurrency is greater than 1;
  • a short paragraph explains the default sequential behavior and how to opt into concurrency.

Docs-only change, no code or tests affected. I checked the implementation and the existing test-stream-forEach.js tests before writing this; happy to adjust the wording if reviewers prefer a different phrasing.

forEach is implemented on top of readable.map. With the default
concurrency of 1, chunks are processed strictly one at a time: the
next chunk is not read until the previous fn call has settled, so
the method only processes chunks concurrently when concurrency is
greater than 1. Document this so users do not expect concurrent
processing with the default options.

Fixes: nodejs#66106
Signed-off-by: Ultroncn <82553854+Ultroncn@users.noreply.github.com>
@nodejs-github-bot nodejs-github-bot added doc Issues and PRs related to Node.js documentation. stream Issues and PRs related to Node.js streams. labels Nov 17, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Caution

AgentScan found account activity patterns that may be consistent with automation. This is a heuristic, not proof that this pull request was opened by an agent or violates policy. AI-assisted contributions are permitted, but automated tooling must not open pull requests without advance approval, and contributors must personally understand, test, verify, and take responsibility for every submitted change. See the AgentScan analysis, AI use policy, and automation policy for additional context.

Describe callback sequencing without making assumptions about stream
buffering.

Assisted-by: Codex
Signed-off-by: Ultroncn <82553854+Ultroncn@users.noreply.github.com>
@Ultroncn

Copy link
Copy Markdown
Contributor Author

Thanks for catching this. On Node.js v24.18.0, two more chunks were already buffered while the first callback was pending. I’ve updated the paragraph to describe when forEach calls fn for the next chunk.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agentscan:automated-account doc Issues and PRs related to Node.js documentation. stream Issues and PRs related to Node.js streams.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Stream.prototype.forEach will block in first promise in queue before read more chunk

2 participants