Commit 7b656b0d585 for nodejs

commit 7b656b0d585c4aaefa5ce0db9a13ff94950698c0
Author: James M Snell <jasnell@gmail.com>
Date:   Wed Oct 7 12:30:17 2026 +0000

    stream: read stream/iter from() sync sources without a generator

    from() read sync iterable sources with a sync generator doing
    for...of over the source, resumed for every batch. Its next() calls
    went through FunctionPrototypeCall(), which V8 does not inline for the
    next() of a generator.

    Read the source with SyncSourceReader, which does what that generator
    did, written out by hand: it collects single chunks into batches,
    splits oversized batches, flushes before other values, and closes the
    source as for...of does on return(), throw() and cancellation. It
    calls the next() of a generator as the constant
    %GeneratorPrototype%.next, and an own next() method as
    iterator.next(), so that V8 can inline either. Like for...of, it reads
    next() only once.

    Iterating from() over a sync source yielding one-chunk batches is about
    15% faster, and over a generator yielding single chunks about 6-11%
    faster. Piping a sync source to a writer is about 20% faster.

    The microtask that keeps the normalizer busy until the tick after each
    batch, for async generator parity, is the remaining per-batch cost;
    note it.

    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/from.js b/lib/internal/streams/iter/from.js
index 23b7021a649..d32d2353bdc 100644
--- a/lib/internal/streams/iter/from.js
+++ b/lib/internal/streams/iter/from.js
@@ -15,6 +15,8 @@ const {
   DataViewPrototypeGetByteOffset,
   FunctionPrototypeCall,
   ObjectFreeze,
+  ObjectGetOwnPropertyDescriptor,
+  ObjectGetPrototypeOf,
   ObjectSetPrototypeOf,
   PromisePrototypeThen,
   PromiseReject,
@@ -41,6 +43,7 @@ const { lazyDOMException } = require('internal/util');

 const {
   isAnyArrayBuffer,
+  isGeneratorObject,
   isPromise,
   isTypedArray,
   isUint8Array,
@@ -1119,63 +1122,237 @@ function normalizeAsyncSource(source, context) {
 }

 // A value of a sync source that is not a Uint8Array or a Uint8Array[]
-// batch, yielded by readSyncSource() to be normalized asynchronously.
+// batch, returned by SyncSourceReader to be normalized asynchronously.
 function SyncSourceValue(value) {
   this.value = value;
 }
 SyncSourceValue.prototype = ObjectFreeze({ __proto__: null });

 /**
- * Read a sync iterable source for from(): yields Uint8Array[] batches,
+ * Read a sync iterable source for from(): returns Uint8Array[] batches,
  * collecting single Uint8Arrays into batches of up to FROM_BATCH_SIZE
  * chunks, and a SyncSourceValue for any other value, after the chunks
  * collected before it.
- * @param {Iterable} source
- * @param {object} context
- * @yields {Uint8Array[]|SyncSourceValue}
+ *
+ * This is what a sync generator doing `for (const value of source)` would
+ * yield, written out by hand, as it runs for every batch: next(), return()
+ * and throw() behave as that generator's do. The source is closed, as
+ * for...of closes it, when the reader is returned or thrown into while it
+ * is reading the source, or when the normalization is found cancelled;
+ * errors closing it are ignored for throw() and cancellation. An error from
+ * the source's next() or [Symbol.iterator]() ends the reader without
+ * closing the source.
  */
-function* readSyncSource(source, context) {
-  throwIfNormalizationCancelled(context);
-  if (!isSyncIterable(source)) {
-    throw new ERR_INVALID_ARG_TYPE(
-      'source', ['Iterable', 'AsyncIterable'], source);
-  }
-  let batch = [];
-  for (const value of source) {
-    throwIfNormalizationCancelled(context);
-    // Fast path 1: value is already a Uint8Array[] batch
-    if (isUint8ArrayBatch(value)) {
-      // Flush any accumulated batch first
-      if (batch.length > 0) {
-        yield batch;
-        batch = [];
+// %GeneratorPrototype%.next, taken before user code runs.
+const GeneratorPrototypeNext =
+  ObjectGetPrototypeOf(function*() {}).prototype.next;
+
+// How a SyncSourceReader calls the next() of its source's iterator.
+const kNextOwn = 1;
+const kNextGenerator = 2;
+
+// The states of a SyncSourceReader: not started, reading the source, done.
+const kReaderStart = 0;
+const kReaderActive = 1;
+const kReaderDone = 2;
+
+class SyncSourceReader {
+  #source;
+  #context;
+  #iterator = null;
+  #next = null;
+  // kNextGenerator if the source's iterator is a generator whose next() is
+  // %GeneratorPrototype%.next, which is then called as a constant; kNextOwn
+  // if its next() is an own data property, which is then called as
+  // `iterator.next()`; otherwise 0, and #next is called with
+  // FunctionPrototypeCall(). Calls V8 can inline make reading single chunks
+  // faster. (Generators of different generator functions don't share a map,
+  // so for them `iterator.next()` would be a megamorphic load per chunk.)
+  #direct = 0;
+  #state = kReaderStart;
+  // Single Uint8Arrays read and not yet returned.
+  #batch = [];
+  // A value to return on the next call, after the batch returned before it.
+  #pending = undefined;
+  // A batch larger than FROM_BATCH_SIZE being returned in slices, and the
+  // offset of the next slice.
+  #large = null;
+  #offset = 0;
+
+  constructor(source, context) {
+    this.#source = source;
+    this.#context = context;
+  }
+
+  next() {
+    switch (this.#state) {
+      case kReaderDone:
+        return new IterResult(true, undefined);
+      case kReaderStart:
+        this.#start();
+        break;
+    }
+    if (this.#pending !== undefined) {
+      const value = this.#pending;
+      this.#pending = undefined;
+      return new IterResult(false, value);
+    }
+    if (this.#large !== null) return new IterResult(false, this.#nextSlice());
+    // Read into locals: the loop runs for every chunk of the source.
+    const iterator = this.#iterator;
+    const next = this.#next;
+    const direct = this.#direct;
+    const context = this.#context;
+    const batch = this.#batch;
+    for (;;) {
+      let value;
+      try {
+        const result = direct === kNextGenerator ?
+          FunctionPrototypeCall(GeneratorPrototypeNext, iterator) :
+          direct === kNextOwn ? iterator.next() :
+            FunctionPrototypeCall(next, iterator);
+        if ((typeof result !== 'object' && typeof result !== 'function') ||
+            result === null) {
+          throw new ERR_INVALID_RETURN_VALUE(
+            'an object', 'iterator.next()', result);
+        }
+        if (result.done) {
+          this.#state = kReaderDone;
+          if (batch.length > 0) {
+            return new IterResult(false, this.#takeBatch());
+          }
+          return new IterResult(true, undefined);
+        }
+        value = result.value;
+      } catch (error) {
+        this.#state = kReaderDone;
+        throw error;
       }
-      if (value.length <= FROM_BATCH_SIZE) {
-        if (value.length !== 0) yield value;
-      } else {
-        yield* yieldBoundedBatch(value);
+      if (context?.cancelled) {
+        this.#close(true);
+        throw context.reason;
       }
-      continue;
-    }
-    // Fast path 2: value is a single Uint8Array (very common)
-    if (isUint8Array(value)) {
-      batch[batch.length] = value;
-      if (batch.length === FROM_BATCH_SIZE) {
-        yield batch;
-        batch = [];
+      // Fast path 1: value is a single Uint8Array (very common). Checking
+      // ArrayIsArray() first keeps batches from paying for isUint8Array().
+      const isArray = ArrayIsArray(value);
+      if (!isArray && isUint8Array(value)) {
+        batch[batch.length] = value;
+        if (batch.length === FROM_BATCH_SIZE) {
+          return new IterResult(false, this.#takeBatch());
+        }
+        continue;
       }
-      continue;
+      // Fast path 2: value is already a Uint8Array[] batch
+      if (isArray && isUint8ArrayBatch(value)) {
+        if (value.length === 0) {
+          if (batch.length > 0) {
+            return new IterResult(false, this.#takeBatch());
+          }
+          continue;
+        }
+        let ready = value;
+        if (value.length > FROM_BATCH_SIZE) {
+          this.#large = value;
+          this.#offset = 0;
+          ready = undefined;
+        }
+        // Flush any accumulated batch first
+        if (batch.length > 0) {
+          this.#pending = ready;
+          return new IterResult(false, this.#takeBatch());
+        }
+        return new IterResult(false, ready ?? this.#nextSlice());
+      }
+      // Slow path: flush, then have the value normalized
+      const sourceValue = new SyncSourceValue(value);
+      if (batch.length > 0) {
+        this.#pending = sourceValue;
+        return new IterResult(false, this.#takeBatch());
+      }
+      return new IterResult(false, sourceValue);
     }
-    // Slow path: flush, then have the value normalized
-    if (batch.length > 0) {
-      yield batch;
-      batch = [];
+  }
+
+  return() {
+    const state = this.#state;
+    this.#state = kReaderDone;
+    this.#pending = undefined;
+    this.#large = null;
+    if (state === kReaderActive) this.#close(false);
+    return new IterResult(true, undefined);
+  }
+
+  throw(error) {
+    const state = this.#state;
+    this.#state = kReaderDone;
+    this.#pending = undefined;
+    this.#large = null;
+    if (state === kReaderActive) this.#close(true);
+    throw error;
+  }
+
+  #start() {
+    this.#state = kReaderActive;
+    try {
+      throwIfNormalizationCancelled(this.#context);
+      const source = this.#source;
+      if (!isSyncIterable(source)) {
+        throw new ERR_INVALID_ARG_TYPE(
+          'source', ['Iterable', 'AsyncIterable'], source);
+      }
+      const iterator = source[SymbolIterator]();
+      const next = iterator.next;
+      this.#iterator = iterator;
+      this.#next = next;
+      if (isGeneratorObject(iterator) && next === GeneratorPrototypeNext) {
+        this.#direct = kNextGenerator;
+      } else if (typeof iterator === 'object' && iterator !== null) {
+        const descriptor = ObjectGetOwnPropertyDescriptor(iterator, 'next');
+        if (descriptor !== undefined && descriptor.value === next) {
+          this.#direct = kNextOwn;
+        }
+      }
+    } catch (error) {
+      this.#state = kReaderDone;
+      throw error;
     }
-    yield new SyncSourceValue(value);
   }
-  // Yield any remaining batched values
-  if (batch.length > 0) {
-    yield batch;
+
+  #takeBatch() {
+    const batch = this.#batch;
+    this.#batch = [];
+    return batch;
+  }
+
+  #nextSlice() {
+    const large = this.#large;
+    const offset = this.#offset;
+    this.#offset = offset + FROM_BATCH_SIZE;
+    if (this.#offset >= large.length) this.#large = null;
+    return ArrayPrototypeSlice(large, offset, offset + FROM_BATCH_SIZE);
+  }
+
+  // Close the source as for...of does: errors are ignored if `quiet` (an
+  // error is being thrown), and otherwise thrown, as is a result of
+  // return() that is not an object.
+  #close(quiet) {
+    this.#state = kReaderDone;
+    const iterator = this.#iterator;
+    let result;
+    try {
+      const returnMethod = iterator.return;
+      if (returnMethod === undefined || returnMethod === null) return;
+      result = FunctionPrototypeCall(returnMethod, iterator);
+    } catch (error) {
+      if (quiet) return;
+      throw error;
+    }
+    if (!quiet &&
+        ((typeof result !== 'object' && typeof result !== 'function') ||
+         result === null)) {
+      throw new ERR_INVALID_RETURN_VALUE(
+        'an object', 'iterator.return()', result);
+    }
   }
 }

@@ -1184,19 +1361,19 @@ function* readSyncSource(source, context) {
  * Uint8Array, without an async generator layer for every batch (see
  * createAsyncSourceNormalizer()).
  *
- * The source is read by the sync generator readSyncSource(), so for...of
- * reads and closes it, and this iterator only adds the asynchronous
- * normalization of values that need it. Operations on the generator mirror
- * those on the async generator this replaces: return() and throw() are
- * passed to it, after closing the value being normalized, and an error
- * normalizing a value is thrown into it, so that for...of closes the source
- * as for an error in the loop body.
+ * The source is read by a SyncSourceReader, which reads and closes it as
+ * for...of does, and this iterator only adds the asynchronous normalization
+ * of values that need it. Operations on the reader mirror those on the
+ * async generator this replaces: return() and throw() are passed to it,
+ * after closing the value being normalized, and an error normalizing a
+ * value is thrown into it, so that the source is closed as for an error in
+ * the body of a for...of loop.
  * @param {Iterable} source
  * @param {object} context
  * @returns {object} An object with next(), return() and throw().
  */
 function createSyncSourceNormalizer(source, context) {
-  const reader = readSyncSource(source, context);
+  const reader = new SyncSourceReader(source, context);
   let done = false;
   // A normalizeAsyncSourceValue() generator for the value being normalized.
   let valueBatches = null;
@@ -1206,6 +1383,11 @@ function createSyncSourceNormalizer(source, context) {
   // until the tick after a yield or return (both await their operand), so
   // that a next(), return() or throw() made synchronously after this one is
   // queued behind it; do the same.
+  // TODO(@jasnell): This costs a microtask per batch. Running a call made
+  // while the previous one has finished synchronously right away would make
+  // for-await over from(syncSource) about 1.3x faster, at the cost of this
+  // async generator parity for calls made back to back without awaiting
+  // (see testFromSyncSourceQueuesBehindReturn).
   function finish(result) {
     PromisePrototypeThen(kResolvedPromise, release);
     return result;
diff --git a/test/parallel/test-stream-iter-from-async.js b/test/parallel/test-stream-iter-from-async.js
index cfbb46fa9b6..44befd8eb7e 100644
--- a/test/parallel/test-stream-iter-from-async.js
+++ b/test/parallel/test-stream-iter-from-async.js
@@ -724,6 +724,78 @@ async function testFromSyncSourceBatching() {
   ]);
 }

+async function testFromSyncSourceLargeAndEmptyBatches() {
+  // Batches of more than 128 chunks are split, after the chunks collected
+  // before them; empty batches only flush collected chunks. Returning while
+  // a batch is split closes the source, returning after its last batch
+  // does not.
+  const large = Array.from({ length: 300 }, () => new Uint8Array(1));
+  let log = [];
+  let iterator = from(createLoggedSyncSource(log, [
+    Uint8Array.of(1), [], [], large, Uint8Array.of(2),
+  ]))[Symbol.asyncIterator]();
+  for (let i = 0; i < 6; i++) await settle(log, `result ${i}`, iterator.next());
+  assert.deepStrictEqual(log, [
+    'iterator', 'next 0', 'next 1', 'result 0: 1', 'next 2', 'next 3',
+    'result 1: 128', 'result 2: 128', 'result 3: 44', 'next 4', 'next 5',
+    'result 4: 1', 'result 5: done',
+  ]);
+
+  log = [];
+  iterator = from(createLoggedSyncSource(log, [large]))[
+    Symbol.asyncIterator]();
+  await settle(log, 'result', iterator.next());
+  await settle(log, 'return', iterator.return());
+  assert.deepStrictEqual(log, [
+    'iterator', 'next 0', 'result: 128', 'return', 'return: done',
+  ]);
+
+  // A result whose value getter throws ends the iteration without closing
+  // the source.
+  log = [];
+  const source = {
+    [Symbol.iterator]() {
+      return {
+        next() {
+          log.push('next');
+          return { done: false, get value() { throw new Error('getter'); } };
+        },
+        return() {
+          log.push('return');
+          return { done: true };
+        },
+      };
+    },
+  };
+  iterator = from(source)[Symbol.asyncIterator]();
+  await settle(log, 'result 0', iterator.next());
+  await settle(log, 'result 1', iterator.next());
+  assert.deepStrictEqual(log, ['next', 'result 0: getter', 'result 1: done']);
+
+  // The next() method of the source's iterator is read once, as for...of
+  // reads it.
+  let reads = 0;
+  let count = 0;
+  const accessorSource = {
+    [Symbol.iterator]() {
+      return {
+        get next() {
+          reads++;
+          return () => (count < 3 ?
+            { done: false, value: [Uint8Array.of(count++)] } :
+            { done: true, value: undefined });
+        },
+      };
+    },
+  };
+  const chunks = [];
+  for await (const batch of from(accessorSource)) chunks.push(...batch);
+  assert.deepStrictEqual(chunks, [
+    Uint8Array.of(0), Uint8Array.of(1), Uint8Array.of(2),
+  ]);
+  assert.strictEqual(reads, 1);
+}
+
 async function testFromSyncSourceErrors() {
   // An error from the source does not close it.
   let log = [];
@@ -900,6 +972,7 @@ Promise.all([
   testFromReturnAndThrowBeforeStart(),
   testFromReturnAndThrowCloseSource(),
   testFromSyncSourceBatching(),
+  testFromSyncSourceLargeAndEmptyBatches(),
   testFromSyncSourceErrors(),
   testFromSyncSourceReturnAndThrow(),
   testFromSyncSourceQueuesBehindReturn(),