Commit 6db0cfca0dc for nodejs

commit 6db0cfca0dc33c3eb02af258bea3be3d8f4b1a0b
Author: James M Snell <jasnell@gmail.com>
Date:   Wed Oct 7 02:45:17 2026 +0000

    stream: create stream/iter transform signals and options lazily

    A pull() pipeline with transforms creates an AbortController for the
    signal passed to its transforms, and each call of a stateless transform
    is passed a new options object holding it. Most transforms never read
    the signal, and a new options object for every call allocates on every
    batch unless the call is inlined.

    Keep the abort state of a pipeline in a PipelineAbort, which creates the
    AbortController when the signal is first read, already aborted with the
    same reason if the pipeline has been aborted; nothing can have listened
    to the signal before, so this cannot be told apart from a signal created
    with the pipeline. Code in the pipeline checks the abort state instead
    of reading the signal.

    Give each transform of a pipeline one options object, passed to every
    call of a stateless transform. A transform still cannot change the
    options another transform sees. `signal` is an accessor until it is
    first read or assigned, after which it is a data property.

    This departs from the specification, where TransformCallbackOptions is
    a dictionary, converted to a new object with a `signal` data property
    for every call.

    Calling four stateless transforms that do not read the signal over a
    sync source of 16-byte chunks, one per batch, is about 4% faster, and
    about 9% faster when the transforms are not inlined.

    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/doc/api/stream_iter.md b/doc/api/stream_iter.md
index b8fac507cba..5cc71c47c90 100644
--- a/doc/api/stream_iter.md
+++ b/doc/api/stream_iter.md
@@ -144,10 +144,13 @@ Both forms receive an `options` parameter with the following property:
   can check `signal.aborted` or listen for the `'abort'` event to perform
   early cleanup.

-In `pull()`, stateless transforms receive a new `options` object for every
-call, and stateful transforms one for the pipeline, so a transform can modify
-its `options` without affecting other transforms. The object does not inherit
-from `Object.prototype`. Transforms passed to [`pullSync()`][] receive no
+Each transform of a pipeline receives its own `options` object, the same one
+for every call of a stateless transform, so a transform can modify its
+`options` without affecting other transforms. The object does not inherit
+from `Object.prototype`. The signal is created when `options.signal` is
+first read, so a pipeline whose transforms never read it does not create one;
+until then, `signal` is an accessor property. It is the same signal for every
+transform of the pipeline. Transforms passed to [`pullSync()`][] receive no
 `options`.

 The flush signal (`null`) is sent after the source ends, giving transforms
diff --git a/lib/internal/streams/iter/pull.js b/lib/internal/streams/iter/pull.js
index 31bd3acf26a..1cb0276fc87 100644
--- a/lib/internal/streams/iter/pull.js
+++ b/lib/internal/streams/iter/pull.js
@@ -58,6 +58,7 @@ const {

 const {
   IterResult,
+  PipelineAbort,
   kActive,
   kDone,
   kNullOnceOption,
@@ -581,19 +582,53 @@ function* createSyncPipeline(source, transforms) {
 // Async Pipeline Implementation
 // =============================================================================

-// The options object passed to async transforms. Stateless transforms get a
-// new one for every call, so it is constructed rather than created as a
-// `{ __proto__: null, signal }` literal (a dictionary-mode object). The
-// prototype is frozen and has no %Object.prototype% in its chain, and the
-// non-enumerable `constructor` lets util.inspect() print the options as
-// `TransformOptions { signal }`.
-function TransformOptions(signal) {
-  this.signal = signal;
+// The options object passed to an async transform: one for each transform of
+// a pipeline, passed to every call of a stateless transform. Its `signal` is
+// the pipeline's signal, created by `abort` when first read (see
+// PipelineAbort): until then it is an accessor, which replaces itself with a
+// data property holding the signal. The prototype is frozen and has no
+// %Object.prototype% in its chain, and the non-enumerable `constructor` lets
+// util.inspect() print the options as `TransformOptions { signal }`.
+function TransformOptions(abort) {
+  ObjectDefineProperty(this, 'signal', {
+    __proto__: null,
+    configurable: true,
+    enumerable: true,
+    get() {
+      const signal = abort.signal;
+      ObjectDefineProperty(this, 'signal', {
+        __proto__: null,
+        configurable: true,
+        enumerable: true,
+        value: signal,
+        writable: true,
+      });
+      return signal;
+    },
+    set(value) {
+      ObjectDefineProperty(this, 'signal', {
+        __proto__: null,
+        configurable: true,
+        enumerable: true,
+        value,
+        writable: true,
+      });
+    },
+  });
 }
 TransformOptions.prototype = ObjectFreeze(ObjectDefineProperty(
   { __proto__: null }, 'constructor',
   { __proto__: null, value: TransformOptions }));

+// The options for each function of a fused run of stateless transforms.
+function createRunOptions(run, abort) {
+  const options = [];
+  for (let i = 0; i < run.length; i++) {
+    options[i] = new TransformOptions(abort);
+  }
+  return options;
+}
+
 /**
  * Close an async iterator as for await does: for a throw completion
  * (`quiet`), wait for it but ignore errors; otherwise reject on errors and
@@ -650,13 +685,13 @@ async function* yieldFusedStatelessOutput(current) {
  * @param {Array<Function>} run
  * @param {number} index
  * @param {any} result - The result of `run[index]`
- * @param {AbortSignal} signal
+ * @param {TransformOptions[]} runOptions - The options of each function
  * @yields {Uint8Array[]}
  */
-async function* continueFusedStatelessBatch(run, index, result, signal) {
+async function* continueFusedStatelessBatch(run, index, result, runOptions) {
   let current;
   for (let i = index; i < run.length; i++) {
-    if (i !== index) result = run[i](current, new TransformOptions(signal));
+    if (i !== index) result = run[i](current, runOptions[i]);
     if (isPromise(result)) result = await result;
     if (result === null) return;
     if (i === run.length - 1) {
@@ -680,24 +715,24 @@ async function* continueFusedStatelessBatch(run, index, result, signal) {
  * flush each transform after all upstream data, including data emitted by
  * earlier flushes, has been processed by that transform.
  * @param {Array<Function>} run
- * @param {AbortSignal} signal
+ * @param {TransformOptions[]} runOptions - The options of each function
  * @yields {Uint8Array[]}
  */
-async function* flushFusedStatelessAsyncTransforms(run, signal) {
+async function* flushFusedStatelessAsyncTransforms(run, runOptions) {
   let pending = [];
   for (let i = 0; i < run.length; i++) {
     const next = [];
     for (let j = 0; j < pending.length; j++) {
       const pendingResult = appendTransformResultAsync(
         next,
-        run[i](pending[j], new TransformOptions(signal)));
+        run[i](pending[j], runOptions[i]));
       if (pendingResult !== undefined) {
         await pendingResult;
       }
     }
     const flushResult = appendTransformResultAsync(
       next,
-      run[i](null, new TransformOptions(signal)));
+      run[i](null, runOptions[i]));
     if (flushResult !== undefined) {
       await flushResult;
     }
@@ -731,15 +766,14 @@ const kDelegated = Symbol('kDelegated');
  *   if any, and close the source unless it has ended; return() propagates
  *   errors from closing it, throw() ignores them.
  *
- * INVARIANT: This function accepts a signal, NOT a pre-built options object.
- * A fresh TransformOptions object is created for each
- * transform invocation to prevent cross-transform mutation.
+ * Each function of the run is passed its own options object on every call.
  * @param {AsyncIterable<Uint8Array[]>} source
  * @param {Array<Function>} run - Array of stateless transform functions
- * @param {AbortSignal} signal - The pipeline's abort signal
+ * @param {PipelineAbort} abort - The pipeline's abort state
  * @returns {AsyncIterator<Uint8Array[]>}
  */
-function applyFusedStatelessAsyncTransforms(source, run, signal) {
+function applyFusedStatelessAsyncTransforms(source, run, abort) {
+  const runOptions = createRunOptions(run, abort);
   let state = kStart;
   let iterator;
   let nextMethod;
@@ -792,9 +826,9 @@ function applyFusedStatelessAsyncTransforms(source, run, signal) {
   function applyBatch(chunks) {
     let current = chunks;
     for (let i = 0; i < run.length; i++) {
-      const result = run[i](current, new TransformOptions(signal));
+      const result = run[i](current, runOptions[i]);
       if (isPromise(result)) {
-        delegate = continueFusedStatelessBatch(run, i, result, signal);
+        delegate = continueFusedStatelessBatch(run, i, result, runOptions);
         return kDelegated;
       }
       if (result === null) return null;
@@ -804,7 +838,7 @@ function applyFusedStatelessAsyncTransforms(source, run, signal) {
       }
       current = normalizeTransformResultFast(result);
       if (current === undefined) {
-        delegate = continueFusedStatelessBatch(run, i, result, signal);
+        delegate = continueFusedStatelessBatch(run, i, result, runOptions);
         return kDelegated;
       }
       if (current === null) return null;
@@ -832,7 +866,7 @@ function applyFusedStatelessAsyncTransforms(source, run, signal) {
       }
       if (result.done) {
         sourceDone = true;
-        delegate = flushFusedStatelessAsyncTransforms(run, signal);
+        delegate = flushFusedStatelessAsyncTransforms(run, runOptions);
         return pullDelegate();
       }
       value = result.value;
@@ -988,7 +1022,7 @@ async function* applyStatefulAsyncTransform(
  * @yields {Uint8Array[]}
  */
 async function* applyValidatedStatefulAsyncTransform(
-  source, transform, receiver, options) {
+  source, transform, receiver, options, abort) {
   const output = FunctionPrototypeCall(
     transform, receiver, source, options);
   for await (const batch of output) {
@@ -999,7 +1033,7 @@ async function* applyValidatedStatefulAsyncTransform(
   // 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.
-  options.signal?.throwIfAborted();
+  abort.throwIfAborted();
 }

 /**
@@ -1076,22 +1110,17 @@ async function* yieldFrom(source) {
  * Build the chain of transform layers of a pipeline.
  * @param {AsyncIterable<Uint8Array[]>} normalized
  * @param {Array} transforms
- * @param {AbortSignal} transformSignal
+ * @param {PipelineAbort} abort - The pipeline's abort state
  * @returns {AsyncIterable<Uint8Array[]>}
  */
-function createAsyncTransformLayers(normalized, transforms, transformSignal) {
+function createAsyncTransformLayers(normalized, transforms, abort) {
   // Apply transforms - fuse consecutive stateless transforms into a single
   // layer to avoid unnecessary async ticks.
   //
-  // INVARIANT: Each transform invocation MUST receive its own fresh options
-  // object (new TransformOptions(signal)). Transforms may mutate the options
-  // object, so sharing a single object across invocations would allow one
-  // transform to corrupt the options seen by another. The signal is shared
-  // across calls (mutations to it are acceptable), but the containing options
-  // object must be unique per call. This is enforced inside
-  // applyFusedStatelessAsyncTransforms and applyStatefulAsyncTransform, which
-  // accept the signal directly and create the options object per invocation.
-  // DO NOT pass a pre-built options object.
+  // Each transform gets its own options object, created here once and passed
+  // to every call of the transform: transforms may mutate the options
+  // object, and must not be able to change the options another transform
+  // sees.
   let current = normalized;
   let statelessRun = [];

@@ -1101,13 +1130,13 @@ function createAsyncTransformLayers(normalized, transforms, transformSignal) {
       // Flush any accumulated stateless run before the stateful transform
       if (statelessRun.length > 0) {
         current = applyFusedStatelessAsyncTransforms(current, statelessRun,
-                                                     transformSignal);
+                                                     abort);
         statelessRun = [];
       }
-      const opts = new TransformOptions(transformSignal);
+      const opts = new TransformOptions(abort);
       if (transform[kValidatedTransform]) {
         current = applyValidatedStatefulAsyncTransform(
-          current, transform.transform, transform.receiver, opts);
+          current, transform.transform, transform.receiver, opts, abort);
       } else {
         current = applyStatefulAsyncTransform(
           current, transform.transform, transform.receiver, opts);
@@ -1119,7 +1148,7 @@ function createAsyncTransformLayers(normalized, transforms, transformSignal) {
   // Flush remaining stateless run
   if (statelessRun.length > 0) {
     current = applyFusedStatelessAsyncTransforms(current, statelessRun,
-                                                 transformSignal);
+                                                 abort);
   }
   return current;
 }
@@ -1130,9 +1159,9 @@ function createAsyncTransformLayers(normalized, transforms, transformSignal) {
  * layer for every batch (see applyFusedStatelessAsyncTransforms()).
  *
  * When started by the first next(), it checks `signal`, then creates the
- * controller whose signal the transforms get, aborted when `signal` aborts.
- * Each batch, and the end, is passed on only if the transforms' signal has
- * not been aborted. If the pipeline fails, the transforms' signal is aborted
+ * abort state whose signal the transforms get, aborted when `signal` aborts.
+ * Each batch, and the end, is passed on only if the pipeline has not been
+ * aborted. If the pipeline fails, the transforms' signal is aborted
  * with the error; if it is stopped early by return() or throw(), the
  * transforms are closed and their signal is aborted.
  * @param {AsyncIterable<Uint8Array[]>} source
@@ -1142,7 +1171,7 @@ function createAsyncTransformLayers(normalized, transforms, transformSignal) {
  */
 function createAsyncTransformPipeline(source, transforms, signal) {
   let state = kStart;
-  let controller;
+  let abort;
   let abortHandler;
   let completed = false;
   let iterator;
@@ -1151,10 +1180,10 @@ function createAsyncTransformPipeline(source, transforms, signal) {

   // What an async generator would do in its `finally` block.
   function cleanup() {
-    if (!completed && !controller.signal.aborted) {
+    if (!completed && !abort.aborted) {
       // Consumer stopped early or return() was called.
       // If a transform listener throws here, let it propagate.
-      controller.abort(lazyDOMException('Aborted', 'AbortError'));
+      abort.abort(lazyDOMException('Aborted', 'AbortError'));
     }
     // Clean up user signal listener to prevent holding controller alive
     if (signal && abortHandler) {
@@ -1182,9 +1211,7 @@ function createAsyncTransformPipeline(source, transforms, signal) {
     state = kDone;
     try {
       try {
-        if (!controller.signal.aborted) {
-          abortSignal(controller.signal, error);
-        }
+        abort.abort(error);
       } finally {
         cleanup();
       }
@@ -1206,7 +1233,7 @@ function createAsyncTransformPipeline(source, transforms, signal) {
         // A transform can abort while completing without producing a final
         // batch, for example when an async flush resolves to null. In that
         // case there is no batch with which to observe the abort.
-        controller.signal.throwIfAborted();
+        abort.throwIfAborted();
         completed = true;
         return complete(new IterResult(true, undefined));
       }
@@ -1214,9 +1241,8 @@ function createAsyncTransformPipeline(source, transforms, signal) {
     } catch (error) {
       return fail(error);
     }
-    try {
-      controller.signal.throwIfAborted();
-    } catch (error) {
+    if (abort.aborted) {
+      const error = abort.reason;
       // Like for await when its body throws: close the transforms first.
       return PromisePrototypeThen(
         closeAsyncIterator(iterator, true), () => fail(error));
@@ -1249,17 +1275,16 @@ function createAsyncTransformPipeline(source, transforms, signal) {
       }
       state = kActive;
       const normalized = yieldAbortable(source, signal);
-      // Create internal controller for transform cancellation.
-      controller = new AbortController();
+      abort = new PipelineAbort();
       if (signal) {
         abortHandler = () => {
-          abortSignal(controller.signal, signal.reason);
+          abort.abort(signal.reason);
         };
         signal.addEventListener('abort', abortHandler, kNullOnceOption);
       }
       try {
         const current = createAsyncTransformLayers(
-          normalized, transforms, controller.signal);
+          normalized, transforms, abort);
         iterator = current[SymbolAsyncIterator]();
         nextMethod = iterator.next;
       } catch (error) {
diff --git a/lib/internal/streams/iter/utils.js b/lib/internal/streams/iter/utils.js
index 6b40f5a2903..b4eb5e9c662 100644
--- a/lib/internal/streams/iter/utils.js
+++ b/lib/internal/streams/iter/utils.js
@@ -37,6 +37,10 @@ const {

 const { isSharedArrayBuffer, isUint8Array } = require('internal/util/types');
 const { kWeakHandler } = require('internal/event_target');
+const {
+  AbortController,
+  abortSignal,
+} = require('internal/abort_controller');
 const { RingBuffer } = require('internal/streams/iter/ringbuffer');

 const {
@@ -110,6 +114,50 @@ function onSignalAbort(signal, handler) {
   }
 }

+/**
+ * The abort state of a pipeline: what the AbortController of a pipeline in
+ * the specification holds, without creating an AbortController unless its
+ * signal is used. Most transforms never read the signal passed to them, so
+ * most pipelines never need one. When the signal is first read, it is
+ * created aborted with the same reason if the pipeline has been aborted:
+ * nothing can have listened to it before, so this cannot be told apart from
+ * a signal created with the pipeline. Code inside the pipeline checks
+ * `aborted` instead of reading the signal.
+ */
+class PipelineAbort {
+  aborted = false;
+  reason = undefined;
+  #controller = null;
+
+  get signal() {
+    let controller = this.#controller;
+    if (controller === null) {
+      controller = this.#controller = new AbortController();
+      if (this.aborted) abortSignal(controller.signal, this.reason);
+    }
+    return controller.signal;
+  }
+
+  /**
+   * Abort the pipeline with `reason`, if it is not aborted already. Abort
+   * listeners on the signal, if it has been created, run synchronously, and
+   * errors they throw propagate.
+   * @param {any} reason
+   */
+  abort(reason) {
+    if (this.aborted) return;
+    this.aborted = true;
+    this.reason = reason;
+    if (this.#controller !== null) {
+      abortSignal(this.#controller.signal, reason);
+    }
+  }
+
+  throwIfAborted() {
+    if (this.aborted) throw this.reason;
+  }
+}
+
 /**
  * Wrap an async source so each pending read is abort-aware.
  * @param {AsyncIterable<Uint8Array[]>} source - The source to read from.
@@ -942,6 +990,7 @@ module.exports = {
   kStart,
   PendingRequest,
   PendingWrite,
+  PipelineAbort,
   kMultiConsumerDefaultBudget,
   kNullOnceOption,
   kPushDefaultBudget,
diff --git a/test/parallel/test-stream-iter-pull-async.js b/test/parallel/test-stream-iter-pull-async.js
index 308e3a0ebb9..4c1bc0a7a14 100644
--- a/test/parallel/test-stream-iter-pull-async.js
+++ b/test/parallel/test-stream-iter-pull-async.js
@@ -553,7 +553,7 @@ async function testPipeToStringSource() {
   assert.strictEqual(data, 'hello-pipe');
 }

-// INVARIANT: Each transform invocation receives its own options object.
+// Each transform receives its own options object.
 // A transform that mutates options must not affect subsequent transforms.
 async function testTransformOptionsNotShared() {
   const seen = [];
@@ -575,41 +575,97 @@ async function testTransformOptionsNotShared() {
   assert.strictEqual(seen[1].mutated, undefined);
 }

-// Stateless transforms get a new options object for every call, and stateful
-// transforms one for the pipeline. The options object has only `signal`, does
+// Each transform of a pipeline gets its own options object, passed to every
+// call of a stateless transform. The options object has only `signal`, does
 // not inherit from Object.prototype, and its prototype is frozen, so that a
-// transform cannot pass state to others through it.
+// transform cannot pass state to others through it. The signal is the same
+// for every transform and every call.
 async function testTransformOptionsShape() {
   const seen = [];
+  const statelessSeen = [];
+  let statefulOptions;
   const stateless = (chunks, options) => {
     seen.push(options);
+    statelessSeen.push(options);
     return chunks;
   };
   const stateful = {
     async* transform(source, options) {
       seen.push(options);
+      statefulOptions = options;
       for await (const chunks of source) yield chunks;
     },
   };
   const ac = new AbortController();
   await text(pull(from(['a', 'b']), stateless, stateful,
                   { signal: ac.signal }));
-  // Stateless: one call per batch plus the flush call.
+  // Stateless: one call per batch plus the flush call; stateful: one call.
+  assert.strictEqual(statelessSeen.length, 3);
+  assert.strictEqual(new Set(statelessSeen).size, 1);
   assert.strictEqual(seen.length, 4);
-  assert.strictEqual(new Set(seen).size, seen.length);
+  assert.notStrictEqual(statefulOptions, statelessSeen[0]);
   for (const options of seen) {
     assert.strictEqual(options instanceof Object, false);
     assert.deepStrictEqual(Object.keys(options), ['signal']);
     assert.ok(options.signal instanceof AbortSignal);
+    assert.strictEqual(options.signal, seen[0].signal);
     assert.strictEqual(Object.isFrozen(Object.getPrototypeOf(options)), true);
     assert.match(inspect(options), /^TransformOptions \{ signal: /);
   }
-  assert.strictEqual(Object.getPrototypeOf(seen[0]),
-                     Object.getPrototypeOf(seen[3]));
+  assert.strictEqual(Object.getPrototypeOf(statefulOptions),
+                     Object.getPrototypeOf(statelessSeen[0]));
   assert.throws(() => { Object.getPrototypeOf(seen[0]).leak = true; },
                 TypeError);
 }

+// `options.signal` can be assigned, as a data property could, whether or
+// not it has been read.
+async function testTransformOptionsSignalAssignable() {
+  const seen = [];
+  let calls = 0;
+  const transform = (chunks, options) => {
+    seen.push(options.signal);
+    options.signal = ++calls;
+    return chunks;
+  };
+  const unread = (chunks, options) => {
+    options.signal = 'unread';
+    seen.push(options.signal);
+    return chunks;
+  };
+  await text(pull(from(['a', 'b']), transform, unread));
+  assert.ok(seen[0] instanceof AbortSignal);
+  assert.deepStrictEqual(seen.slice(1), ['unread', 1, 'unread', 2, 'unread']);
+}
+
+// The transforms' signal is the pipeline's: first read after the pipeline
+// has been aborted, it is already aborted with the same reason, and read
+// before, it is aborted when the pipeline is.
+async function testTransformSignalReadAfterAbort() {
+  const reason = new Error('stop');
+  let options;
+  const transform = (chunks, opts) => {
+    options = opts;
+    throw reason;
+  };
+  await assert.rejects(text(pull(from('a'), transform)), reason);
+  assert.strictEqual(options.signal.aborted, true);
+  assert.strictEqual(options.signal.reason, reason);
+  assert.strictEqual(options.signal, options.signal);
+
+  const ac = new AbortController();
+  let signal;
+  const iterator = pull(from(['a', 'b']), (chunks, opts) => {
+    signal ??= opts.signal;
+    return chunks;
+  }, { signal: ac.signal })[Symbol.asyncIterator]();
+  await iterator.next();
+  assert.strictEqual(signal.aborted, false);
+  ac.abort(reason);
+  assert.strictEqual(signal.aborted, true);
+  assert.strictEqual(signal.reason, reason);
+}
+
 // Run the uncaughtException test sequentially (it installs a global handler
 // that would interfere with concurrent tests).
 // Transform pipelines read and close the source like an async generator
@@ -760,6 +816,8 @@ async function testTransformReturnClosesOutputAndSource() {
     testPipeToStringSource(),
     testTransformOptionsNotShared(),
     testTransformOptionsShape(),
+    testTransformSignalReadAfterAbort(),
+    testTransformOptionsSignalAssignable(),
     testTransformErrorClosesSource(),
     testTransformSourceErrorDoesNotCloseSource(),
     testPipeToTransformsStoppedEarly(),