fixup! stream: implement toStreamIterWriter/fromStreamIterWriter

Author: jasnell

doc/api/stream.md

@@ -979,94 +979,6 @@ added: v12.3.0
 
 Getter for the property `objectMode` of a given `Writable` stream.
 
-##### `writable.toStreamIterWriter([options])`
-
-<!-- YAML
-added: REPLACEME
--->
-
-> Stability: 1 - Experimental
-
-* `options` {Object}
-  * `backpressure` {string} Backpressure policy. One of `'strict'` (default),
-    `'block'`, or `'drop-newest'`. See below for details.
-* Returns: {Object} A [`stream/iter` Writer][stream-iter-writer] adapter.
-
-When the `--experimental-stream-iter` flag is enabled, returns an adapter
-object that conforms to the [`stream/iter`][] Writer interface, allowing the
-`Writable` to be used as a destination in the iterable streams API.
-
-Since all writes on a classic `stream.Writable` are fundamentally
-asynchronous, the synchronous methods (`writeSync`, `writevSync`, `endSync`)
-always return `false` or `-1`, deferring to the async path. The per-write
-`options.signal` parameter from the Writer interface is also ignored; classic
-`stream.Writable` has no per-write abort signal support, so cancellation
-should be handled at the pipeline level.
-
-**Backpressure policies:**
-
-* `'strict'` (default) — writes are rejected with `ERR_INVALID_STATE` when
-  the buffer is full (`writableLength >= writableHighWaterMark`). This catches
-  callers that ignore backpressure.
-* `'block'` — writes wait for the `'drain'` event when the buffer is full.
-  This matches classic `stream.Writable` behavior and is the recommended
-  policy when using [`pipeTo()`][stream-iter-pipeto].
-* `'drop-newest'` — writes are silently discarded when the buffer is full.
-  The data is not written to the underlying resource, but `writer.end()`
-  still reports the total bytes (including dropped bytes) for consistency
-  with the Writer spec.
-* `'drop-oldest'` — **not supported**. Classic `stream.Writable` does not
-  provide an API to evict already-buffered data without risking partial
-  eviction of atomic `writev()` batches. Passing this value throws
-  `ERR_INVALID_ARG_VALUE`.
-
-The adapter maps:
-
-* `writer.write(chunk)` — calls `writable.write(chunk)`, subject to the
-  backpressure policy.
-* `writer.writev(chunks)` — corks the writable, writes all chunks, then
-  uncorks. Subject to the backpressure policy.
-* `writer.end()` — calls `writable.end()` and resolves with total bytes
-  written when the `'finish'` event fires.
-* `writer.fail(reason)` — calls `writable.destroy(reason)`.
-* `writer.desiredSize` — returns the available buffer space
-  (`writableHighWaterMark - writableLength`), or `null` if the stream
-  is destroyed or finished.
-
-```mjs
-import { Writable } from 'node:stream';
-import { from, pipeTo } from 'node:stream/iter';
-
-const chunks = [];
-const writable = new Writable({
-  write(chunk, encoding, cb) { chunks.push(chunk); cb(); },
-});
-
-// Use 'block' policy with pipeTo for classic backpressure behavior
-await pipeTo(from('hello world'),
-             writable.toStreamIterWriter({ backpressure: 'block' }));
-```
-
-```cjs
-const { Writable } = require('node:stream');
-const { from, pipeTo } = require('node:stream/iter');
-
-async function run() {
-  const chunks = [];
-  const writable = new Writable({
-    write(chunk, encoding, cb) { chunks.push(chunk); cb(); },
-  });
-
-  await pipeTo(from('hello world'),
-               writable.toStreamIterWriter({ backpressure: 'block' }));
-}
-
-run().catch(console.error);
-```
-
-Without the `--experimental-stream-iter` flag, calling this method throws
-[`ERR_STREAM_ITER_MISSING_FLAG`][].
-
 ##### `writable[Symbol.asyncDispose]()`
 
 <!-- YAML
@@ -2108,7 +2020,7 @@ are yielded directly as `Buffer` instances (which are `Uint8Array` subclasses).
 For object-mode or encoded streams, each chunk is normalized to `Uint8Array`
 before batching.
 
-The returned iterator is tagged as a trusted source, so [`from()`][stream-iter-from]
+The returned iterator is tagged as a validated source, so [`from()`][stream-iter-from]
 passes it through without additional normalization.
 
 ```mjs
@@ -3295,101 +3207,6 @@ Readable.from([
 ]);
 ```
 
-### `stream.Readable.fromStreamIter(source[, options])`
-
-<!-- YAML
-added: REPLACEME
--->
-
-> Stability: 1 - Experimental
-
-* `source` {AsyncIterable} An `AsyncIterable<Uint8Array[]>` source, such as
-  the return value of [`pull()`][] or [`from()`][stream-iter-from].
-* `options` {Object}
-  * `highWaterMark` {number} The internal buffer size in bytes before
-    backpressure is applied. **Default:** `65536` (64 KB).
-  * `signal` {AbortSignal} An optional signal that can be used to abort
-    the readable, destroying the stream and cleaning up the source iterator.
-* Returns: {stream.Readable}
-
-Creates a byte-mode {stream.Readable} from an `AsyncIterable<Uint8Array[]>`
-(the native batch format used by the [`stream/iter`][] API). Each
-`Uint8Array` in a yielded batch is pushed as a separate chunk into the
-Readable.
-
-This method requires the `--experimental-stream-iter` CLI flag.
-
-```mjs
-import { Readable } from 'node:stream';
-import { createWriteStream } from 'node:fs';
-import { from, pull } from 'node:stream/iter';
-import { compressGzip } from 'node:zlib/iter';
-
-// Bridge a stream/iter pipeline to a classic Readable
-const source = pull(from('hello world'), compressGzip());
-const readable = Readable.fromStreamIter(source);
-
-readable.pipe(createWriteStream('output.gz'));
-```
-
-```cjs
-const { Readable } = require('node:stream');
-const { createWriteStream } = require('node:fs');
-const { from, pull } = require('node:stream/iter');
-const { compressGzip } = require('node:zlib/iter');
-
-const source = pull(from('hello world'), compressGzip());
-const readable = Readable.fromStreamIter(source);
-
-readable.pipe(createWriteStream('output.gz'));
-```
-
-### `stream.Readable.fromStreamIterSync(source[, options])`
-
-<!-- YAML
-added: REPLACEME
--->
-
-> Stability: 1 - Experimental
-
-* `source` {Iterable} An `Iterable<Uint8Array[]>` source, such as the
-  return value of [`pullSync()`][] or [`fromSync()`][].
-* `options` {Object}
-  * `highWaterMark` {number} The internal buffer size in bytes before
-    backpressure is applied. **Default:** `65536` (64 KB).
-* Returns: {stream.Readable}
-
-Creates a byte-mode {stream.Readable} from a synchronous
-`Iterable<Uint8Array[]>` (the native batch format used by the
-[`stream/iter`][] sync API). Each `Uint8Array` in a yielded batch is
-pushed as a separate chunk into the Readable.
-
-The `_read()` method pulls from the iterator synchronously, so data is
-available immediately via `readable.read()` without waiting for async
-callbacks.
-
-This method requires the `--experimental-stream-iter` CLI flag.
-
-```mjs
-import { Readable } from 'node:stream';
-import { fromSync } from 'node:stream/iter';
-
-const source = fromSync('hello world');
-const readable = Readable.fromStreamIterSync(source);
-
-console.log(readable.read().toString()); // 'hello world'
-```
-
-```cjs
-const { Readable } = require('node:stream');
-const { fromSync } = require('node:stream/iter');
-
-const source = fromSync('hello world');
-const readable = Readable.fromStreamIterSync(source);
-
-console.log(readable.read().toString()); // 'hello world'
-```
-
 ### `stream.Readable.fromWeb(readableStream[, options])`
 
 <!-- YAML
@@ -3463,62 +3280,6 @@ changes:
     `'bytes'` or undefined.
 * Returns: {ReadableStream}
 
-### `stream.Writable.fromStreamIter(writer)`
-
-<!-- YAML
-added: REPLACEME
--->
-
-> Stability: 1 - Experimental
-
-* `writer` {Object} A [`stream/iter`][] Writer. Only the `write()` method is
-  required; `end()`, `fail()`, `writeSync()`, `writevSync()`, `endSync()`,
-  and `writev()` are optional.
-* Returns: {stream.Writable}
-
-When the `--experimental-stream-iter` flag is enabled, creates a classic
-`stream.Writable` backed by a [`stream/iter` Writer][stream-iter-writer].
-
-Each `_write()` / `_writev()` call attempts the Writer's synchronous method
-first (`writeSync` / `writevSync`), falling back to the async method if the
-sync path returns `false`. Similarly, `_final()` tries `endSync()` before
-`end()`. When the sync path succeeds, the callback is deferred via
-`queueMicrotask` to preserve the async resolution contract that Writable
-internals expect.
-
-* `_write(chunk, encoding, cb)` — tries `writer.writeSync(bytes)`, falls
-  back to `await writer.write(bytes)`.
-* `_writev(entries, cb)` — tries `writer.writevSync(chunks)`, falls
-  back to `await writer.writev(chunks)`. Only defined if `writer.writev`
-  exists.
-* `_final(cb)` — tries `writer.endSync()`, falls back to
-  `await writer.end()`.
-* `_destroy(err, cb)` — calls `writer.fail(err)`.
-
-```mjs
-import { Writable } from 'node:stream';
-import { push, from, pipeTo } from 'node:stream/iter';
-
-const { writer, readable } = push();
-const writable = Writable.fromStreamIter(writer);
-
-writable.write('hello');
-writable.end();
-```
-
-```cjs
-const { Writable } = require('node:stream');
-const { push, from, pipeTo } = require('node:stream/iter');
-
-const { writer, readable } = push();
-const writable = Writable.fromStreamIter(writer);
-
-writable.write('hello');
-writable.end();
-```
-
-This method requires the `--experimental-stream-iter` CLI flag.
-
 ### `stream.Writable.fromWeb(writableStream[, options])`
 
 <!-- YAML
@@ -5298,15 +5059,12 @@ contain multi-byte characters.
 [`Symbol.hasInstance`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/hasInstance
 [`Transform`]: #class-streamtransform
 [`Writable`]: #class-streamwritable
-[`fromSync()`]: stream_iter.md#fromsyncinput
 [`fs.createReadStream()`]: fs.md#fscreatereadstreampath-options
 [`fs.createWriteStream()`]: fs.md#fscreatewritestreampath-options
 [`net.Socket`]: net.md#class-netsocket
 [`process.stderr`]: process.md#processstderr
 [`process.stdin`]: process.md#processstdin
 [`process.stdout`]: process.md#processstdout
-[`pull()`]: stream_iter.md#pullsource-transforms-options
-[`pullSync()`]: stream_iter.md#pullsyncsource-transforms-options
 [`readable._read()`]: #readable_readsize
 [`readable.compose(stream)`]: #readablecomposestream-options
 [`readable.map`]: #readablemapfn-options
@@ -5353,8 +5111,6 @@ contain multi-byte characters.
 [stream-finished]: #streamfinishedstream-options-callback
 [stream-finished-promise]: #streamfinishedstream-options
 [stream-iter-from]: stream_iter.md#frominput
-[stream-iter-pipeto]: stream_iter.md#pipetosource-transforms-writer
-[stream-iter-writer]: stream_iter.md#writer-interface
 [stream-pause]: #readablepause
 [stream-pipeline]: #streampipelinesource-transforms-destination-callback
 [stream-pipeline-promise]: #streampipelinesource-transforms-destination-options