Commit 22fd89feab8 for nodejs
commit 22fd89feab8f92e336c6488b3910a3cbf7b80f21
Author: James M Snell <jasnell@gmail.com>
Date: Wed Oct 7 10:47:03 2026 +0000
stream: apply stream/iter stateful transforms without async generators
Every stateful (generator) transform in an async pipeline added two
async generators of stream/iter's own to every batch, besides the
transform's: one to append the null flush signal to its source, and one
to read and normalize its output. Validated transforms, such as
compression, added one.
Write both out by hand. The source of the transform passes reads to the
pipeline with one reaction each, then yields null once, and passes
return() and throw() on as yield* does. The output is read with one
reaction per item, and normalized as before; outputs that are not async
iterables are still read by an async generator, as for await reads them.
The transform is still called on the first pull.
For 16-byte chunks one per batch, iterating pull() with one stateful
transform is 23-31% faster, and with three 36-45% faster; compression
is unchanged.
Assisted-by: OpenCode
Signed-off-by: James M Snell <jasnell@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/66504
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
diff --git a/lib/internal/streams/iter/pull.js b/lib/internal/streams/iter/pull.js
index 9dca617e7f5..2cc643eafb2 100644
--- a/lib/internal/streams/iter/pull.js
+++ b/lib/internal/streams/iter/pull.js
@@ -972,22 +972,98 @@ function applyFusedStatelessAsyncTransforms(source, run, abort) {
}
/**
- * Append a null flush signal after the source is exhausted.
- * @yields {Uint8Array[]}
- */
-/**
- * Append a null flush signal after the source is exhausted.
- * @yields {Uint8Array[]}
+ * The source of a stateful transform: what an async generator doing
+ * `yield* source; yield null;` would yield, written out by hand, as it is
+ * read for every batch. Reads are passed to
+ * the source's iterator, with one reaction each; once it is done, null is
+ * yielded once, as the flush signal. return() and throw() are passed on as
+ * yield* does.
+ * @param {AsyncIterable<Uint8Array[]>} source
+ * @returns {AsyncIterator<Uint8Array[]|null>}
*/
-async function* withFlushAsync(source) {
- yield* source;
- yield null;
+function createFlushSource(source) {
+ let iterator = null;
+ // Whether the source is done, and the flush signal yielded; then the
+ // source is ended.
+ let sourceDone = false;
+ let done = false;
+
+ function onResult(result) {
+ if ((typeof result !== 'object' && typeof result !== 'function') ||
+ result === null) {
+ done = true;
+ throw new ERR_INVALID_RETURN_VALUE(
+ 'an object', 'iterator.next()', result);
+ }
+ if (result.done) {
+ sourceDone = true;
+ return new IterResult(false, null);
+ }
+ return new IterResult(false, result.value);
+ }
+
+ function onError(error) {
+ done = true;
+ throw error;
+ }
+
+ return ObjectSetPrototypeOf({
+ next() {
+ if (done || sourceDone) {
+ done = true;
+ return PromiseResolve(new IterResult(true, undefined));
+ }
+ try {
+ iterator ??= source[SymbolAsyncIterator]();
+ return PromisePrototypeThen(PromiseResolve(iterator.next()),
+ onResult, onError);
+ } catch (error) {
+ done = true;
+ return PromiseReject(error);
+ }
+ },
+ return(value) {
+ const result = new IterResult(true, value);
+ if (done || sourceDone || iterator === null) {
+ done = true;
+ return PromiseResolve(result);
+ }
+ done = true;
+ return PromisePrototypeThen(closeAsyncIterator(iterator, false),
+ () => result);
+ },
+ throw(error) {
+ if (done || sourceDone || iterator === null) {
+ done = true;
+ return PromiseReject(error);
+ }
+ try {
+ const throwMethod = iterator.throw;
+ if (throwMethod === undefined || throwMethod === null) {
+ // As yield*: close the source, then throw a TypeError.
+ done = true;
+ return PromisePrototypeThen(closeAsyncIterator(iterator, false),
+ () => {
+ throw new ERR_INVALID_STATE.TypeError(
+ 'The iterator does not provide ' +
+ 'a \'throw\' method');
+ });
+ }
+ return PromisePrototypeThen(
+ PromiseResolve(FunctionPrototypeCall(throwMethod, iterator, error)),
+ onResult, onError);
+ } catch (thrown) {
+ done = true;
+ return PromiseReject(thrown);
+ }
+ },
+ [SymbolAsyncIterator]() { return this; },
+ }, null);
}
-async function* applyStatefulAsyncTransform(
- source, transform, receiver, options) {
- const output = FunctionPrototypeCall(
- transform, receiver, withFlushAsync(source), options);
+// Iterate the output of a stateful transform as for await does, for outputs
+// that are not async iterables: see createStatefulTransformIterator().
+async function* yieldStatefulOutput(output) {
for await (const item of output) {
if (item === null) continue;
// Fast path: item is already a Uint8Array[] batch (e.g. compression transforms)
@@ -1014,24 +1090,133 @@ async function* applyStatefulAsyncTransform(
}
/**
- * Fast path for validated stateful transforms (e.g. compression).
- * Skips withFlushAsync (transform handles done internally) and
- * skips isUint8ArrayBatch validation (transform guarantees valid output).
- * @yields {Uint8Array[]}
+ * A stateful transform applied to `source`: what an async generator doing
+ * `for await (const item of output)` over the transform's output would
+ * yield, written out by hand, as it runs for every batch. The transform is
+ * called on the first next(), with createFlushSource(source), or with
+ * `source` itself for a validated transform (e.g. compression), whose
+ * output needs no normalization. An output that is not an async iterable
+ * is read by the async generator instead (yieldStatefulOutput()).
+ * @param {AsyncIterable<Uint8Array[]>} source
+ * @param {Function} transform
+ * @param {object} receiver
+ * @param {TransformOptions} options
+ * @param {PipelineAbort} abort
+ * @param {boolean} validated
+ * @returns {AsyncIterator<Uint8Array[]>}
*/
-async function* applyValidatedStatefulAsyncTransform(
- source, transform, receiver, options, abort) {
- const output = FunctionPrototypeCall(
- transform, receiver, source, options);
- for await (const batch of output) {
- if (batch.length > 0) {
- yield batch;
+function createStatefulTransformIterator(
+ source, transform, receiver, options, abort, validated) {
+ let state = kStart;
+ let iterator;
+ let nextMethod;
+
+ function pull() {
+ return PromisePrototypeThen(
+ PromiseResolve(FunctionPrototypeCall(nextMethod, iterator)),
+ onItem, onError);
+ }
+
+ function onItem(result) {
+ if ((typeof result !== 'object' && typeof result !== 'function') ||
+ result === null) {
+ state = kDone;
+ throw new ERR_INVALID_RETURN_VALUE(
+ 'an object', 'iterator.next()', result);
+ }
+ if (result.done) {
+ state = kDone;
+ // Without the flush signal there is no extra read to give the
+ // pipeline a chance to see an abort.
+ if (validated) abort.throwIfAborted();
+ return new IterResult(true, undefined);
+ }
+ const item = result.value;
+ if (validated) {
+ return item.length > 0 ? new IterResult(false, item) : pull();
+ }
+ if (item === null) return pull();
+ if (isUint8ArrayBatch(item)) {
+ return item.length > 0 ? new IterResult(false, item) : pull();
+ }
+ if (isUint8Array(item)) return new IterResult(false, [item]);
+ // Slow path: flatten arbitrary transform yield. An error doing so
+ // closes the output, as for await does when its body throws.
+ return PromisePrototypeThen(flattenItem(item), (batch) => {
+ return batch.length > 0 ? new IterResult(false, batch) : pull();
+ }, (error) => {
+ state = kDone;
+ return PromisePrototypeThen(closeAsyncIterator(iterator, true), () => {
+ throw error;
+ });
+ });
+ }
+
+ async function flattenItem(item) {
+ const batch = [];
+ for await (const chunk of flattenTransformYieldAsync(item)) {
+ batch[batch.length] = chunk;
}
+ return batch;
}
- // Check abort after the transform completes - without the
- // withFlushAsync wrapper there is no extra yield to give
- // the outer pipeline a chance to see the abort.
- abort.throwIfAborted();
+
+ function onError(error) {
+ state = kDone;
+ throw error;
+ }
+
+ return ObjectSetPrototypeOf({
+ next() {
+ if (state === kDone) {
+ return PromiseResolve(new IterResult(true, undefined));
+ }
+ if (state === kStart) {
+ state = kActive;
+ try {
+ const output = FunctionPrototypeCall(
+ transform, receiver,
+ validated ? source : createFlushSource(source), options);
+ if (output != null &&
+ typeof output[SymbolAsyncIterator] === 'function') {
+ iterator = output[SymbolAsyncIterator]();
+ } else {
+ // Iterated as for await would: sync iterables, and errors.
+ iterator = yieldStatefulOutput(output);
+ }
+ nextMethod = iterator.next;
+ } catch (error) {
+ state = kDone;
+ return PromiseReject(error);
+ }
+ }
+ try {
+ return pull();
+ } catch (error) {
+ state = kDone;
+ return PromiseReject(error);
+ }
+ },
+ return(value) {
+ const result = new IterResult(true, value);
+ if (state !== kActive) {
+ state = kDone;
+ return PromiseResolve(result);
+ }
+ state = kDone;
+ return PromisePrototypeThen(closeAsyncIterator(iterator, false),
+ () => result);
+ },
+ throw(error) {
+ if (state !== kActive) {
+ state = kDone;
+ return PromiseReject(error);
+ }
+ state = kDone;
+ return PromisePrototypeThen(closeAsyncIterator(iterator, true),
+ () => { throw error; });
+ },
+ [SymbolAsyncIterator]() { return this; },
+ }, null);
}
/**
@@ -1131,13 +1316,9 @@ function createAsyncTransformLayers(normalized, transforms, abort) {
statelessRun = [];
}
const opts = new TransformOptions(abort);
- if (transform[kValidatedTransform]) {
- current = applyValidatedStatefulAsyncTransform(
- current, transform.transform, transform.receiver, opts, abort);
- } else {
- current = applyStatefulAsyncTransform(
- current, transform.transform, transform.receiver, opts);
- }
+ current = createStatefulTransformIterator(
+ current, transform.transform, transform.receiver, opts, abort,
+ transform[kValidatedTransform] === true);
} else {
ArrayPrototypePush(statelessRun, transform);
}
diff --git a/test/parallel/test-stream-iter-pull-async.js b/test/parallel/test-stream-iter-pull-async.js
index c8293257712..53480cb653d 100644
--- a/test/parallel/test-stream-iter-pull-async.js
+++ b/test/parallel/test-stream-iter-pull-async.js
@@ -4,6 +4,7 @@
const common = require('../common');
const assert = require('assert');
const {
+ array,
broadcast,
dump,
from,
@@ -428,6 +429,63 @@ async function testPullSignalListenerRemoved() {
await assert.rejects(iter.next(), { name: 'AbortError' });
}
+// Stateful transforms: called on the first pull, with a source that ends
+// with one null flush signal; their output is normalized; stopping early
+// closes the output and the source.
+async function testStatefulTransformProtocol() {
+ const log = [];
+ const stateful = {
+ async *transform(source) {
+ log.push('called');
+ try {
+ for await (const batch of source) {
+ log.push(batch === null ? 'flush' : `batch ${batch[0][0]}`);
+ if (batch === null) {
+ yield 'end';
+ } else {
+ yield batch;
+ yield batch[0];
+ yield null;
+ yield [];
+ }
+ }
+ } finally {
+ log.push('output closed');
+ }
+ },
+ };
+ const iterable = pull(createLoggedSource(log, [1, 2]), stateful);
+ assert.deepStrictEqual(log, []);
+ const chunks = await array(iterable);
+ assert.deepStrictEqual(chunks.map((chunk) => chunk[0]), [1, 1, 2, 2, 101]);
+ assert.deepStrictEqual(log, [
+ 'called', 'next 0', 'batch 1', 'next 1', 'batch 2', 'next 2', 'flush',
+ 'output closed',
+ ]);
+
+ log.length = 0;
+ const iterator = pull(createLoggedSource(log, [1, 2, 3]),
+ stateful)[Symbol.asyncIterator]();
+ assert.strictEqual((await iterator.next()).value[0][0], 1);
+ assert.strictEqual((await iterator.return()).done, true);
+ assert.deepStrictEqual(log, [
+ 'called', 'next 0', 'batch 1', 'return', 'output closed',
+ ]);
+ assert.strictEqual((await iterator.next()).done, true);
+
+ // Outputs that are sync iterables are read as for await reads them.
+ const syncOutput = { transform: () => [[Uint8Array.of(7)], 'x'] };
+ assert.deepStrictEqual((await array(pull(from('a'), syncOutput))).map(
+ (chunk) => chunk[0]), [7, 120]);
+
+ // Errors from the transform reject the pull.
+ const failing = {
+ // eslint-disable-next-line require-yield
+ async *transform() { throw new Error('stateful failed'); },
+ };
+ await assert.rejects(array(pull(from('a'), failing)), /stateful failed/);
+}
+
// Pull consumer break (return()) cleans up transform signal
async function testPullConsumerBreakCleanup() {
let signalAborted = false;
@@ -884,6 +942,7 @@ async function testTransformReturnClosesOutputAndSource() {
testPullSignalAbortWhileTransformPending(),
testPullSignalAbortWhileIdleClosesSource(),
testPullSignalListenerRemoved(),
+ testStatefulTransformProtocol(),
testTransformOptionsSignalAssignable(),
testTransformErrorClosesSource(),
testTransformSourceErrorDoesNotCloseSource(),