stream: add dump()/dumpSync() for stream/iter

Every consumer in node:stream/iter retains what it reads, so there is
no way to read a streamable to completion while keeping nothing. To
clear a stream, callers write `for await (const _ of source) {}`. This
is apparent throughout multiple test suites, including the stream/iter
tests themselves.

These are especially useful for QUIC where a receiver doesn't want the
payload, but still has to read it to completion to relieve
backpressure. bytes() does that too, but allocates the whole payload to
discard it.

dump() pulls every batch and drops it, so peak memory is one batch
regardless of volume. It takes the same signal and limit options as
the other consumers, rejects if the source errors mid-stream, and
fulfills with undefined. dumpSync() is the synchronous form.

The name follows undici's body.dump(). drain() was the obvious
alternative but this module already exports ondrain() and
drainableProtocol() for writer-side backpressure, which is the
opposite side of the pipe.

Assisted-by: Claude Opus 5
Signed-off-by: Ethan Arrowood <ethan@arrowood.dev>

Author: Ethan-Arrowood

doc/api/quic.md

@@ -343,6 +343,10 @@ Only one async iterator can be obtained per stream. The stream is also
 compatible with `node:stream/iter` utilities such as `Stream.bytes()`,
 `Stream.text()`, and `Stream.pipeTo()`.
 
+Consuming a stream is what returns flow-control credit to the peer, so a
+stream whose payload is not wanted should still be read to completion. Use
+`Stream.dump()` to read the stream without retaining any of it.
+
 ### Datagrams
 
 In addition to streams, QUIC supports unreliable datagrams ([RFC 9221][]) for

doc/api/stream_iter.md

@@ -1025,6 +1025,81 @@ added:
 
 Synchronous version of [`bytes()`][].
 
+### `dump(source[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `source` {AsyncIterable|Iterable} whose chunks must be {Uint8Array\[]}
+* `options` {Object}
+  * `signal` {AbortSignal}
+  * `limit` {number} Maximum number of bytes to consume. If the total bytes
+    read exceeds limit, an `ERR_OUT_OF_RANGE` error is thrown
+* Returns: {Promise} Fulfills with `undefined`.
+
+Read a source to completion, discarding every chunk. Unlike the other
+consumers, `dump()` retains nothing. Memory tops-out at a single batch no
+matter how much data the source produces.
+
+Use this to consume a stream when the content doesn't matter. For example, A
+QUIC stream only returns flow-control credit to the peer as its data is
+consumed, so a receiver that does not want the payload must still read it to
+completion.
+
+If the source errors part-way through, the returned promise rejects with that
+error.
+
+There is no default `limit`. `dump()` reads until the source is exhausted
+unless a limit is specified. When a limit is configured and the source exceeds
+it, the promise rejects and the source is cancelled. A partial dump is never
+reported as success.
+
+```mjs
+import { dump, from, pull, tap } from 'node:stream/iter';
+
+// Count the bytes flowing through a stream without retaining any of them.
+let bytesSeen = 0;
+const counter = tap((chunks) => {
+  for (const chunk of chunks) bytesSeen += chunk.byteLength;
+});
+
+await dump(pull(from('hello world'), counter));
+console.log(bytesSeen); // 11
+```
+
+```cjs
+const { dump, from, pull, tap } = require('node:stream/iter');
+
+async function run() {
+  // Count the bytes flowing through a stream without retaining any of them.
+  let bytesSeen = 0;
+  const counter = tap((chunks) => {
+    for (const chunk of chunks) bytesSeen += chunk.byteLength;
+  });
+
+  await dump(pull(from('hello world'), counter));
+  console.log(bytesSeen); // 11
+}
+
+run().catch(console.error);
+```
+
+### `dumpSync(source[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `source` {Iterable} whose chunks must be {Uint8Array\[]}
+* `options` {Object}
+  * `limit` {number} Maximum number of bytes to consume. If the total bytes
+    read exceeds limit, an `ERR_OUT_OF_RANGE` error is thrown
+* Returns: {undefined}
+
+Synchronous version of [`dump()`][]. Throws `ERR_INVALID_ARG_TYPE` if `source`
+is not synchronously iterable.
+
 ### `text(source[, options])`
 
 <!-- YAML
@@ -2167,6 +2242,7 @@ console.log(textSync(stream)); // 'hello world'
 [`array()`]: #arraysource-options
 [`arrayBuffer()`]: #arraybuffersource-options
 [`bytes()`]: #bytessource-options
+[`dump()`]: #drainsource-options
 [`from()`]: #frominput
 [`fromSync()`]: #fromsyncinput
 [`node:zlib/iter`]: zlib.md#iterable-compression

lib/internal/streams/iter/consumers.js

@@ -3,6 +3,7 @@
 // New Streams API - Consumers & Utilities
 //
 // bytes(), text(), arrayBuffer() - collect entire stream
+// dump() - consume entire stream, retaining nothing
 // tap(), tapSync() - observe without modifying
 // merge() - temporal combining of sources
 // ondrain() - backpressure drain utility
@@ -230,6 +231,20 @@ function validateSyncConsumerOptions(options) {
   validateBaseConsumerOptions(options);
 }
 
+function validateSyncDumpOptions(options) {
+  validateObject(options, 'options');
+  if (options.limit !== undefined) {
+    validateInteger(options.limit, 'options.limit', 0);
+  }
+}
+
+function validateDumpOptions(options) {
+  validateSyncDumpOptions(options);
+  if (options.signal !== undefined) {
+    validateAbortSignal(options.signal, 'options.signal');
+  }
+}
+
 // =============================================================================
 // Sync Consumers
 // =============================================================================
@@ -285,6 +300,32 @@ function arraySync(source, options = kNullPrototype) {
   return collectSync(source, options.limit);
 }
 
+/**
+ * Read a sync source to completion, discarding every chunk.
+ * @param {Iterable<Uint8Array[]>} source
+ * @param {{ limit?: number }} [options]
+ * @returns {undefined}
+ */
+function dumpSync(source, options = kNullPrototype) {
+  validateSyncDumpOptions(options);
+
+  const limit = options.limit;
+  const normalized = fromSync(source);
+  let totalBytes = 0;
+
+  for (const batch of normalized) {
+    // With no limit, just iterate through the stream completely.
+    if (limit === undefined) continue;
+    // Otherwise, calculate totalBytes and track the limit.
+    for (let i = 0; i < batch.length; i++) {
+      totalBytes += TypedArrayPrototypeGetByteLength(batch[i]);
+      if (totalBytes > limit) {
+        throw new ERR_OUT_OF_RANGE('totalBytes', `<= ${limit}`, totalBytes);
+      }
+    }
+  }
+}
+
 // =============================================================================
 // Async Consumers
 // =============================================================================
@@ -341,6 +382,40 @@ async function array(source, options = kNullPrototype) {
   return collectAsync(source, options.signal, options.limit);
 }
 
+/**
+ * Read an async or sync source to completion, discarding every chunk.
+ * @param {AsyncIterable<Uint8Array[]>|Iterable<Uint8Array[]>} source
+ * @param {{ signal?: AbortSignal, limit?: number }} [options]
+ * @returns {Promise<undefined>}
+ */
+async function dump(source, options = kNullPrototype) {
+  validateDumpOptions(options);
+  const signal = options.signal;
+  const limit = options.limit;
+
+  signal?.throwIfAborted();
+
+  const abortableSource = signal && isAsyncIterable(source) ?
+    yieldAbortable(source, signal) : source;
+  const normalized = from(abortableSource);
+  const iterable = signal ? yieldAbortable(normalized, signal) : normalized;
+
+  let totalBytes = 0;
+
+  for await (const batch of iterable) {
+    signal?.throwIfAborted();
+    // With no limit, just iterate through the stream completely.
+    if (limit === undefined) continue;
+    // Otherwise, calculate totalBytes and track the limit.
+    for (let i = 0; i < batch.length; i++) {
+      totalBytes += TypedArrayPrototypeGetByteLength(batch[i]);
+      if (totalBytes > limit) {
+        throw new ERR_OUT_OF_RANGE('totalBytes', `<= ${limit}`, totalBytes);
+      }
+    }
+  }
+}
+
 // =============================================================================
 // Tap Utilities
 // =============================================================================
@@ -610,6 +685,8 @@ module.exports = {
   arraySync,
   bytes,
   bytesSync,
+  dump,
+  dumpSync,
   merge,
   ondrain,
   tap,

lib/stream/iter.js

@@ -44,6 +44,8 @@ const {
   arrayBufferSync,
   array,
   arraySync,
+  dump,
+  dumpSync,
   tap,
   tapSync,
   merge,
@@ -100,12 +102,14 @@ const Stream = ObjectFreeze({
   text,
   arrayBuffer,
   array,
+  dump,
 
   // Consumers (sync)
   bytesSync,
   textSync,
   arrayBufferSync,
   arraySync,
+  dumpSync,
 
   // Combining
   merge,
@@ -164,12 +168,14 @@ module.exports = {
   text,
   arrayBuffer,
   array,
+  dump,
 
   // Consumers (sync)
   bytesSync,
   textSync,
   arrayBufferSync,
   arraySync,
+  dumpSync,
 
   // Combining
   merge,