From 92f898b36065b0fe93e05a9219dac21fe8ed3ad3 Mon Sep 17 00:00:00 2001 From: Ultroncn <82553854+Ultroncn@users.noreply.github.com> Date: Tue, 17 Nov 2026 07:13:08 +0000 Subject: [PATCH 1/2] doc: clarify stream forEach concurrency behavior 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: https://github.com/nodejs/node/issues/66106 Signed-off-by: Ultroncn <82553854+Ultroncn@users.noreply.github.com> --- doc/api/stream.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/api/stream.md b/doc/api/stream.md index a676b98923df..efcd48537129 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -2331,11 +2331,18 @@ This method allows iterating a stream. For each chunk in the stream the promise will be `await`ed. This method is different from `for await...of` loops in that it can optionally -process chunks concurrently. In addition, a `forEach` iteration can only be +process chunks concurrently when the `concurrency` option is greater than `1`. +In addition, a `forEach` iteration can only be stopped by having passed a `signal` option and aborting the related `AbortController` while `for await...of` can be stopped with `break` or `return`. In either case the stream will be destroyed. +`forEach` is implemented on top of [`readable.map`][]: with the default +`concurrency` of `1`, chunks are processed strictly one at a time, and the +next chunk is not read from the stream until the promise returned by `fn` for +the previous chunk has settled. Set `concurrency` to a value greater than `1` +to allow up to that many invocations of `fn` to run at the same time. + This method is different from listening to the [`'data'`][] event in that it uses the [`readable`][] event in the underlying machinery and can limit the number of concurrent `fn` calls. From 2e8779991a1a919a1c5081f4d65d18d7f021ee90 Mon Sep 17 00:00:00 2001 From: Ultron <82553854+Ultroncn@users.noreply.github.com> Date: Thu, 19 Nov 2026 11:10:39 +0800 Subject: [PATCH 2/2] doc: clarify when forEach calls the next callback Describe callback sequencing without making assumptions about stream buffering. Assisted-by: Codex Signed-off-by: Ultroncn <82553854+Ultroncn@users.noreply.github.com> --- doc/api/stream.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/api/stream.md b/doc/api/stream.md index efcd48537129..1d24b435a959 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -2338,10 +2338,10 @@ stopped by having passed a `signal` option and aborting the related `return`. In either case the stream will be destroyed. `forEach` is implemented on top of [`readable.map`][]: with the default -`concurrency` of `1`, chunks are processed strictly one at a time, and the -next chunk is not read from the stream until the promise returned by `fn` for -the previous chunk has settled. Set `concurrency` to a value greater than `1` -to allow up to that many invocations of `fn` to run at the same time. +`concurrency` of `1`, `forEach` waits for the promise returned by `fn` +to settle before calling `fn` for the next chunk. Set `concurrency` to a value +greater than `1` to allow up to that many invocations of `fn` to run at the same +time. This method is different from listening to the [`'data'`][] event in that it uses the [`readable`][] event in the underlying machinery and can limit the