Commit 2202b8e92ef for nodejs

commit 2202b8e92ef70d91230a8d1840bb34b8e45f16cf
Author: James M Snell <jasnell@gmail.com>
Date:   Wed Oct 7 10:27:36 2026 +0000

    stream: encode small stream/iter strings into a pool

    stream/iter encoded every string written, yielded or piped with
    TextEncoder.encode(), into an ArrayBuffer of its own. Writing many
    small strings, as a server-side renderer does, was then mostly the cost
    of allocating them.

    Encode strings whose UTF-8 encoding certainly fits in 8 KiB into a
    64 KiB pool, as Buffer.from() does, with the fast API utf8WriteStatic(),
    and pass on views of it. The pool is untransferable, so that
    transferring the buffer of one chunk cannot detach the others.

    For SSR-like strings of about 65 bytes, writing to a push() stream with
    writeSync() is about 4 times faster, and with await write() about 2.2
    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/doc/api/stream_iter.md b/doc/api/stream_iter.md
index fde0944d318..03c14e21afa 100644
--- a/doc/api/stream_iter.md
+++ b/doc/api/stream_iter.md
@@ -94,6 +94,10 @@ are automatically UTF-8 encoded when passed to `from()`, `push()`, or
 `pipeTo()`. This removes ambiguity around encodings and enables zero-copy
 transfers between streams and native code.

+Like [`Buffer.from()`][] for strings, small strings are encoded into a shared
+pool: the resulting {Uint8Array} is a view of a larger {ArrayBuffer}, which
+cannot be transferred.
+
 ### Batching

 Each iteration yields a **batch** -- an {Array} of {Uint8Array} chunks
@@ -2413,6 +2417,7 @@ console.log(textSync(stream)); // 'hello world'
 [Iterable Streams API]: https://iter-streams.proposal.wintertc.org/
 [`--experimental-stream-iter`]: cli.md#--experimental-stream-iter
 [`Broadcast.from()`]: #broadcastfrominput-options
+[`Buffer.from()`]: buffer.md#static-method-bufferfromstring-encoding
 [`Share.from()`]: #static-method-sharefrominput-options
 [`SyncShare.fromSync()`]: #static-method-syncsharefromsyncinput-options
 [`array()`]: #arraysource-options
diff --git a/lib/internal/streams/iter/utils.js b/lib/internal/streams/iter/utils.js
index c4d1e24f0f0..9a94b0db2b6 100644
--- a/lib/internal/streams/iter/utils.js
+++ b/lib/internal/streams/iter/utils.js
@@ -26,6 +26,8 @@ const {
 } = internalBinding('util');

 const { TextEncoder } = require('internal/encoding');
+const { markAsUntransferable } = require('internal/buffer');
+const { utf8WriteStatic } = internalBinding('buffer');
 const {
   codes: {
     ERR_INVALID_ARG_TYPE,
@@ -63,6 +65,37 @@ const kResolvedPromise = PromiseResolve();
 // Shared TextEncoder instance for string conversion.
 const encoder = new TextEncoder();

+// Small strings are encoded into a pool, like Buffer.from(string), instead
+// of each into an ArrayBuffer of its own: writing many small strings, as a
+// server-side renderer does, is otherwise mostly the cost of allocating
+// them. The pool is untransferable, so that transferring the buffer of one
+// chunk cannot detach the others. A string is pooled when its UTF-8 encoding
+// fits in kMaxPooledByteLength bytes for certain: every UTF-16 code unit
+// encodes to at most 3 bytes.
+const kStringPoolSize = 64 * 1024;
+const kMaxPooledLength = 8 * 1024 / 3;
+let stringPool = null;
+let stringPoolBuffer;
+let stringPoolOffset = 0;
+
+function encodeString(string) {
+  const length = string.length;
+  if (length > kMaxPooledLength) return encoder.encode(string);
+  const maxByteLength = length * 3;
+  if (stringPool === null ||
+      maxByteLength > kStringPoolSize - stringPoolOffset) {
+    stringPool = new Uint8Array(kStringPoolSize);
+    stringPoolBuffer = TypedArrayPrototypeGetBuffer(stringPool);
+    markAsUntransferable(stringPoolBuffer);
+    stringPoolOffset = 0;
+  }
+  const offset = stringPoolOffset;
+  const written = utf8WriteStatic(stringPool, string, offset, maxByteLength);
+  // Keep the chunks 8-byte aligned, as Buffer does.
+  stringPoolOffset = (offset + written + 7) & ~7;
+  return new Uint8Array(stringPoolBuffer, offset, written);
+}
+
 // Default high water marks for push and multi-consumer streams. These values
 // are somewhat arbitrary but have been tested across various workloads and
 // appear to yield the best overall throughput/latency balance.
@@ -457,7 +490,7 @@ function getMinCursor(consumers, fallback) {
  */
 function toUint8Array(chunk) {
   if (typeof chunk === 'string') {
-    return encoder.encode(chunk);
+    return encodeString(chunk);
   }
   if (!isUint8Array(chunk)) {
     throw new ERR_INVALID_ARG_TYPE('chunk', ['string', 'Uint8Array'], chunk);
diff --git a/test/parallel/test-stream-iter-push-writer.js b/test/parallel/test-stream-iter-push-writer.js
index a37c5eac2aa..0278ce569b9 100644
--- a/test/parallel/test-stream-iter-push-writer.js
+++ b/test/parallel/test-stream-iter-push-writer.js
@@ -3,7 +3,7 @@

 const common = require('../common');
 const assert = require('assert');
-const { dump, ondrain, push, text } = require('stream/iter');
+const { dump, push, ondrain, text, array } = require('stream/iter');
 const { setImmediate } = require('timers/promises');

 async function testOndrain() {
@@ -663,7 +663,36 @@ async function testFailRejectsPendingReadWithFalsyReason() {
   );
 }

+// Strings are encoded as UTF-8 (lone surrogates as U+FFFD), small ones into
+// a shared, untransferable pool, which must not mix up their bytes, also
+// when the pool fills up; large ones each into an ArrayBuffer of their own.
+async function testWriteStrings() {
+  const strings = [];
+  for (let i = 0; i < 3000; i++) {
+    strings.push(`row ${i} héllo 😀 \ud800 ${'x'.repeat(i % 97)}`);
+  }
+  strings.push('y'.repeat(10000), 'z');
+  const { writer, readable } = push();
+  const read = array(readable);
+  for (const string of strings) {
+    if (!writer.writeSync(string)) await writer.write(string);
+  }
+  await writer.end();
+  const chunks = await read;
+  const decoder = new TextDecoder();
+  assert.deepStrictEqual(chunks.map((chunk) => decoder.decode(chunk)),
+                         strings.map((s) => s.replace('\ud800', '\ufffd')));
+  for (const chunk of chunks) {
+    assert.strictEqual(Object.getPrototypeOf(chunk), Uint8Array.prototype);
+  }
+  const pooled = chunks[0];
+  assert.ok(pooled.buffer.byteLength > pooled.byteLength);
+  assert.throws(() => pooled.buffer.transfer(), TypeError);
+  assert.strictEqual(chunks[3000].buffer.byteLength, 10000);
+}
+
 Promise.all([
+  testWriteStrings(),
   testOndrain(),
   testDropPoliciesReportPhysicalCapacity(),
   testOndrainNonDrainable(),