Commit 8fedfbf1bfd for nodejs
commit 8fedfbf1bfdeaa0a870d0242e54f522a6b30f44c
Author: James M Snell <jasnell@gmail.com>
Date: Wed Oct 7 12:54:35 2026 +0000
stream: normalize stream/iter fromSync() inputs without generators
fromSync() returned null-prototype object literals, which V8 creates in
dictionary mode, whose iterators were sync generators: one for values
that need no normalization, and two layers, an outer generator
delegating to normalizeSyncSource(), for iterables, resumed for every
batch.
Use classes, as from() does since the previous commits: SyncBatchSource
for values, the sync counterpart of BatchSource, and SyncSource for
iterables, whose iterator reads the source with the SyncSourceReader of
from() and normalizes other values with normalizeSyncValue(). The
iterators behave as the generators did: iterables can be iterated
again, and return(), throw() and errors normalizing a value close the
source as for...of does. normalizeSyncSource() is no longer used.
Creating a sync stream from a value and reading it is about 18 times
faster. Reading a sync source one chunk per batch with for...of is
about 1.8 times faster, and piping it with pipeToSync() about 1.5 times
faster.
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 0c962b4a8f9..0598859a189 100644
--- a/lib/internal/streams/iter/from.js
+++ b/lib/internal/streams/iter/from.js
@@ -395,60 +395,6 @@ function* yieldBoundedBatch(batch) {
}
}
-/**
- * Normalize a sync streamable source, yielding batches of Uint8Array.
- * @param {Iterable} source
- * @yields {Uint8Array[]}
- */
-function* normalizeSyncSource(source) {
- let batch = [];
-
- for (const value of source) {
- // Fast path 1: value is already a Uint8Array[] batch
- if (isUint8ArrayBatch(value)) {
- if (batch.length > 0) {
- yield batch;
- batch = [];
- }
- if (value.length <= FROM_BATCH_SIZE) {
- if (value.length !== 0) yield value;
- } else {
- yield* yieldBoundedBatch(value);
- }
- 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 = [];
- }
- continue;
- }
- // Slow path: normalize the value
- if (batch.length > 0) {
- yield batch;
- batch = [];
- }
- let valueBatch = [];
- for (const chunk of normalizeSyncValue(value)) {
- valueBatch[valueBatch.length] = chunk;
- if (valueBatch.length === FROM_BATCH_SIZE) {
- yield valueBatch;
- valueBatch = [];
- }
- }
- if (valueBatch.length > 0) {
- yield valueBatch;
- }
- }
-
- if (batch.length > 0) {
- yield batch;
- }
-}
-
function yieldNormalizationAbortable(source, context) {
if (context === undefined) return source;
return {
@@ -1550,6 +1496,173 @@ async function* normalizeAsyncStreamableResult(result, context) {
// Public API: from() and fromSync()
// =============================================================================
+/**
+ * The sync iterator of a SyncBatchSource: what a sync generator yielding
+ * the batches of a BatchIterator would give, written out by hand.
+ */
+class SyncBatchIterator {
+ #batch;
+ #index = 0;
+
+ constructor(batch) {
+ this.#batch = batch;
+ }
+
+ next() {
+ const batch = this.#batch;
+ const index = this.#index;
+ if (index >= batch.length) {
+ this.#index = batch.length;
+ return new IterResult(true, undefined);
+ }
+ if (index === 0 && batch.length <= FROM_BATCH_SIZE) {
+ this.#index = batch.length;
+ return new IterResult(false, batch);
+ }
+ this.#index = index + FROM_BATCH_SIZE;
+ return new IterResult(
+ false, ArrayPrototypeSlice(batch, index, index + FROM_BATCH_SIZE));
+ }
+
+ return(value) {
+ this.#index = this.#batch.length;
+ return new IterResult(true, value);
+ }
+
+ throw(error) {
+ this.#index = this.#batch.length;
+ throw error;
+ }
+
+ [SymbolIterator]() {
+ return this;
+ }
+}
+ObjectSetPrototypeOf(SyncBatchIterator.prototype, null);
+
+/**
+ * A sync iterable yielding the chunks of `batch`, a Uint8Array[], in
+ * batches of at most FROM_BATCH_SIZE chunks, for fromSync() of values that
+ * need no normalization: the sync counterpart of BatchSource.
+ */
+class SyncBatchSource {
+ #batch;
+
+ constructor(batch) {
+ this.#batch = batch;
+ }
+
+ [SymbolIterator]() {
+ return new SyncBatchIterator(this.#batch);
+ }
+}
+ObjectSetPrototypeOf(SyncBatchSource.prototype, null);
+
+/**
+ * The sync iterator of a SyncSource: what a sync generator normalizing the
+ * source with for...of would yield, written out by hand. The source is read by a SyncSourceReader, which
+ * collects single chunks into batches and closes the source as for...of
+ * does; other values are normalized with normalizeSyncValue(), and their
+ * chunks returned in batches of up to FROM_BATCH_SIZE. An error normalizing
+ * a value is thrown into the reader, which closes the source, as for an
+ * error in the body of a for...of loop.
+ */
+class SyncSourceIterator {
+ #reader;
+ // The normalizeSyncValue() generator of the value being normalized.
+ #valueChunks = null;
+
+ constructor(source) {
+ this.#reader = new SyncSourceReader(source, undefined);
+ }
+
+ next() {
+ if (this.#valueChunks !== null) {
+ const batch = this.#readValue();
+ if (batch !== null) return new IterResult(false, batch);
+ }
+ for (;;) {
+ const result = this.#reader.next();
+ if (result.done) return result;
+ const value = result.value;
+ if (ArrayIsArray(value)) return result;
+ this.#valueChunks = normalizeSyncValue(value.value);
+ const batch = this.#readValue();
+ if (batch !== null) return new IterResult(false, batch);
+ }
+ }
+
+ // The next batch of the chunks of the value being normalized, or null
+ // once there are no more.
+ #readValue() {
+ const batch = [];
+ try {
+ for (;;) {
+ const result = this.#valueChunks.next();
+ if (result.done) {
+ this.#valueChunks = null;
+ break;
+ }
+ batch[batch.length] = result.value;
+ if (batch.length === FROM_BATCH_SIZE) return batch;
+ }
+ } catch (error) {
+ this.#valueChunks = null;
+ this.#reader.throw(error);
+ }
+ return batch.length > 0 ? batch : null;
+ }
+
+ return(value) {
+ const valueChunks = this.#valueChunks;
+ this.#valueChunks = null;
+ if (valueChunks !== null) {
+ try {
+ valueChunks.return();
+ } catch (error) {
+ this.#reader.throw(error);
+ }
+ }
+ this.#reader.return();
+ return new IterResult(true, value);
+ }
+
+ throw(error) {
+ const valueChunks = this.#valueChunks;
+ this.#valueChunks = null;
+ if (valueChunks !== null) {
+ try {
+ valueChunks.return();
+ } catch {
+ // The error thrown in takes precedence.
+ }
+ }
+ this.#reader.throw(error);
+ }
+
+ [SymbolIterator]() {
+ return this;
+ }
+}
+ObjectSetPrototypeOf(SyncSourceIterator.prototype, null);
+
+/**
+ * A sync iterable normalizing a sync iterable source for fromSync() into
+ * batches of Uint8Array, without generators.
+ */
+class SyncSource {
+ #source;
+
+ constructor(source) {
+ this.#source = source;
+ }
+
+ [SymbolIterator]() {
+ return new SyncSourceIterator(this.#source);
+ }
+}
+ObjectSetPrototypeOf(SyncSource.prototype, null);
+
/**
* Create a SyncByteStreamReadable from a ByteInput or SyncStreamable.
* @param {string|ArrayBuffer|ArrayBufferView|Iterable} input
@@ -1562,13 +1675,7 @@ function fromSync(input) {
// Check for primitives first (ByteInput)
if (isPrimitiveChunk(input)) {
- const chunk = primitiveToUint8Array(input);
- return {
- __proto__: null,
- *[SymbolIterator]() {
- yield [chunk];
- },
- };
+ return new SyncBatchSource([primitiveToUint8Array(input)]);
}
// Check toStreamable protocol (takes precedence over iteration protocols).
@@ -1584,32 +1691,12 @@ function fromSync(input) {
// data volume. Sub-batching keeps peak memory bounded while preserving
// the throughput benefit of batched processing.
if (ArrayIsArray(input)) {
- if (input.length === 0) {
- return {
- __proto__: null,
- *[SymbolIterator]() {
- // Empty - yield nothing
- },
- };
- }
+ // An empty array yields nothing.
+ if (input.length === 0) return new SyncBatchSource(input);
// Check if it's an array of Uint8Array (common case)
if (isUint8Array(input[0])) {
const allUint8 = ArrayPrototypeEvery(input, isUint8Array);
- if (allUint8) {
- const batch = input;
- return {
- __proto__: null,
- *[SymbolIterator]() {
- if (batch.length <= FROM_BATCH_SIZE) {
- yield batch;
- } else {
- for (let i = 0; i < batch.length; i += FROM_BATCH_SIZE) {
- yield ArrayPrototypeSlice(batch, i, i + FROM_BATCH_SIZE);
- }
- }
- },
- };
- }
+ if (allUint8) return new SyncBatchSource(input);
}
}
@@ -1643,12 +1730,7 @@ function fromSync(input) {
);
}
- return {
- __proto__: null,
- *[SymbolIterator]() {
- yield* normalizeSyncSource(input);
- },
- };
+ return new SyncSource(input);
}
// BatchSource and BatchIterator are classes, rather than object literals
@@ -1819,7 +1901,6 @@ module.exports = {
kNextUncancellable,
normalizeAsyncSource,
normalizeAsyncValue,
- normalizeSyncSource,
normalizeSyncValue,
primitiveToUint8Array,
};
diff --git a/test/parallel/test-stream-iter-from-sync.js b/test/parallel/test-stream-iter-from-sync.js
index 133597914c4..f6b2b0a5f84 100644
--- a/test/parallel/test-stream-iter-from-sync.js
+++ b/test/parallel/test-stream-iter-from-sync.js
@@ -255,7 +255,90 @@ function testFromSyncFunctionWithToStreamable() {
assert.throws(() => fromSync(() => {}), { code: 'ERR_INVALID_ARG_TYPE' });
}
+// The iterators of fromSync() behave as generators do: values are batched
+// and normalized, iterables can be iterated again, and return(), throw()
+// and errors normalizing a value close the source as for...of does.
+function testFromSyncIteratorProtocol() {
+ function loggedSource(log, values) {
+ return {
+ [Symbol.iterator]() {
+ let i = 0;
+ log.push('iterator');
+ return {
+ next() {
+ log.push(`next ${i}`);
+ return i < values.length ?
+ { done: false, value: values[i++] } :
+ { done: true, value: undefined };
+ },
+ return() {
+ log.push('return');
+ return { done: true, value: undefined };
+ },
+ };
+ },
+ };
+ }
+ const lengths = (iterable) => Array.from(iterable, (batch) => batch.length);
+
+ const chunks = Array.from({ length: 130 }, () => new Uint8Array(1));
+ let log = [];
+ const source = fromSync(loggedSource(log, [
+ ...chunks, ['ab', ['cd']], Uint8Array.of(1), [],
+ ]));
+ assert.deepStrictEqual(lengths(source), [128, 2, 2, 1]);
+ assert.strictEqual(log.at(-1), 'next 133');
+ assert.deepStrictEqual(lengths(source), [128, 2, 2, 1]);
+
+ // Values that need no normalization.
+ for (const value of ['x', Uint8Array.of(1), [Uint8Array.of(1)], []]) {
+ const iterable = fromSync(value);
+ assert.deepStrictEqual(lengths(iterable), lengths(iterable));
+ const iterator = iterable[Symbol.iterator]();
+ assert.strictEqual(iterator[Symbol.iterator](), iterator);
+ assert.deepStrictEqual({ ...iterator.return('r') },
+ { done: true, value: 'r' });
+ assert.strictEqual(iterator.next().done, true);
+ assert.throws(() => iterable[Symbol.iterator]().throw(new Error('t')),
+ { message: 't' });
+ }
+ assert.deepStrictEqual(lengths(fromSync(new Array(300).fill(chunks[0]))),
+ [128, 128, 44]);
+
+ // return() while reading the source, or a value, closes the source;
+ // before reading it, or after it ended, does not.
+ for (const values of [[[Uint8Array.of(1)], [Uint8Array.of(2)]],
+ [new Array(200).fill('a')]]) {
+ log = [];
+ const iterator = fromSync(loggedSource(log, values))[Symbol.iterator]();
+ iterator.next();
+ assert.deepStrictEqual({ ...iterator.return() },
+ { done: true, value: undefined });
+ assert.deepStrictEqual(log, ['iterator', 'next 0', 'return']);
+ assert.strictEqual(iterator.next().done, true);
+ }
+ log = [];
+ const unstarted = fromSync(loggedSource(log, ['a']))[Symbol.iterator]();
+ unstarted.return();
+ assert.deepStrictEqual(log, []);
+
+ // throw() and an error normalizing a value close the source, and the
+ // error is thrown.
+ log = [];
+ const thrown = fromSync(loggedSource(log, ['a', 'b']))[Symbol.iterator]();
+ thrown.next();
+ assert.throws(() => thrown.throw(new Error('thrown')), { message: 'thrown' });
+ assert.deepStrictEqual(log, ['iterator', 'next 0', 'return']);
+ log = [];
+ const invalid = fromSync(loggedSource(log, ['a', 42]))[Symbol.iterator]();
+ invalid.next();
+ assert.throws(() => invalid.next(), { code: 'ERR_INVALID_ARG_TYPE' });
+ assert.deepStrictEqual(log, ['iterator', 'next 0', 'next 1', 'return']);
+ assert.strictEqual(invalid.next().done, true);
+}
+
Promise.all([
+ testFromSyncIteratorProtocol(),
testFromSyncString(),
testFromSyncUint8Array(),
testFromSyncArrayBuffer(),