stream: rename Duplex.toWeb() type option to readableType

Renegade334 · aduh95 · commit 608736e19e5b · 2026-02-19T11:13:47.000+01:00
PR-URL: #61632 Refs: #58664 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Mattias Buelens <mattias@buelens.com>
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
@@ -4400,6 +4400,21 @@ import { opendir } from 'node:fs/promises';
 }
 ```
 
+### DEP0201: Passing `options.type` to `Duplex.toWeb()`
+
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/61632
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+Passing the `type` option to [`Duplex.toWeb()`][] is deprecated. To specify the
+type of the readable half of the constructed readable-writable pair, use the
+`readableType` option instead.
+
 [DEP0142]: #dep0142-repl_builtinlibs
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
@@ -4418,6 +4433,7 @@ import { opendir } from 'node:fs/promises';
 [`Buffer.isBuffer()`]: buffer.md#static-method-bufferisbufferobj
 [`Cipheriv`]: crypto.md#class-cipheriv
 [`Decipheriv`]: crypto.md#class-decipheriv
+[`Duplex.toWeb()`]: stream.md#streamduplextowebstreamduplex-options
 [`Error.isError`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/isError
 [`REPLServer.clearBufferedCommand()`]: repl.md#replserverclearbufferedcommand
 [`ReadStream.open()`]: fs.md#class-fsreadstream
diff --git a/doc/api/stream.md b/doc/api/stream.md
@@ -3219,7 +3219,8 @@ changes:
       If no value is provided, the size will be `1` for all the chunks.
       * `chunk` {any}
       * Returns: {number}
-  * `type` {string} Must be 'bytes' or undefined.
+  * `type` {string} Specifies the type of the created `ReadableStream`. Must be
+    `'bytes'` or undefined.
 * Returns: {ReadableStream}
 
 ### `stream.Writable.fromWeb(writableStream[, options])`
@@ -3398,9 +3399,13 @@ duplex.once('readable', () => console.log('readable', duplex.read()));
 <!-- YAML
 added: v17.0.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/61632
+    description: Added the 'readableType' option to specify the ReadableStream
+                 type. The 'type' option is deprecated.
   - version: v25.4.0
     pr-url: https://github.com/nodejs/node/pull/58664
-    description: Add 'type' option to specify 'bytes'.
+    description: Added the 'type' option to specify the ReadableStream type.
   - version:
       - v24.0.0
       - v22.17.0
@@ -3410,7 +3415,9 @@ changes:
 
 * `streamDuplex` {stream.Duplex}
 * `options` {Object}
-  * `type` {string} Must be 'bytes' or undefined.
+  * `readableType` {string} Specifies the type of the `ReadableStream` half of
+    the created readable-writable pair. Must be `'bytes'` or undefined.
+    (`options.type` is a deprecated alias for this option.)
 * Returns: {Object}
   * `readable` {ReadableStream}
   * `writable` {WritableStream}
diff --git a/lib/internal/webstreams/adapters.js b/lib/internal/webstreams/adapters.js
@@ -624,7 +624,7 @@ function newStreamReadableFromReadableStream(readableStream, options = kEmptyObj
 
 /**
  * @param {Duplex} duplex
- * @param {{ type?: 'bytes' }} [options]
+ * @param {{ readableType?: 'bytes' }} [options]
  * @returns {ReadableWritablePair}
  */
 function newReadableWritablePairFromDuplex(duplex, options = kEmptyObject) {
@@ -641,9 +641,15 @@ function newReadableWritablePairFromDuplex(duplex, options = kEmptyObject) {
 
   validateObject(options, 'options');
 
+  const readableOptions = {
+    __proto__: null,
+    // DEP0201: 'options.type' is a deprecated alias for 'options.readableType'
+    type: options.readableType ?? options.type,
+  };
+
   if (isDestroyed(duplex)) {
     const writable = new WritableStream();
-    const readable = new ReadableStream({ type: options.type });
+    const readable = new ReadableStream({ type: readableOptions.type });
     writable.close();
     readable.cancel();
     return { readable, writable };
@@ -659,8 +665,8 @@ function newReadableWritablePairFromDuplex(duplex, options = kEmptyObject) {
 
   const readable =
     isReadable(duplex) ?
-      newReadableStreamFromStreamReadable(duplex, options) :
-      new ReadableStream({ type: options.type });
+      newReadableStreamFromStreamReadable(duplex, readableOptions) :
+      new ReadableStream({ type: readableOptions.type });
 
   if (!isReadable(duplex))
     readable.cancel();
diff --git a/test/parallel/test-stream-duplex.js b/test/parallel/test-stream-duplex.js
@@ -147,10 +147,14 @@ process.on('exit', () => {
     })
   });
 
-  const { writable, readable } = Duplex.toWeb(duplex, { type: 'bytes' });
+  const { writable, readable } = Duplex.toWeb(duplex, { readableType: 'bytes' });
   writable.getWriter().write(dataToWrite);
   const data = new Uint8Array(dataToRead.length);
   readable.getReader({ mode: 'byob' }).read(data).then(common.mustCall((result) => {
     assert.deepStrictEqual(Buffer.from(result.value), dataToRead);
   }));
+
+  // Ensure that the originally-named `options.type` still works as an alias for `options.readableType`
+  // `getReader({ mode: 'byob' })` throws if the underlying ReadableStream is not a byte stream
+  Duplex.toWeb(duplex, { type: 'bytes' }).readable.getReader({ mode: 'byob' });
 }
