stream: add pull/writer methods to FileHandle conditionally

Author: jasnell

doc/api/fs.md

@@ -400,6 +400,9 @@ If transforms are provided, they are applied via [`stream/iter pull()`][].
 The file handle is locked while the iterable is being consumed and unlocked
 when iteration completes.
 
+This function is only available when the `--experimental-stream-iter` flag is
+enabled.
+
 ```mjs
 import { open } from 'node:fs/promises';
 import { text, compressGzip } from 'node:stream/iter';
@@ -954,6 +957,9 @@ Return a [`node:stream/iter`][] writer backed by this file handle.
 The writer supports `Symbol.asyncDispose`, so it can be used with
 `await using`.
 
+This function is only available when the `--experimental-stream-iter` flag is
+enabled.
+
 ```mjs
 import { open } from 'node:fs/promises';
 import { from, pipeTo, compressGzip } from 'node:stream/iter';

lib/internal/fs/promises.js

@@ -95,6 +95,7 @@ const {
   isWindows,
   isMacOS,
 } = require('internal/util');
+const { getOptionValue } = require('internal/options');
 const EventEmitter = require('events');
 const { StringDecoder } = require('string_decoder');
 const { kFSWatchStart, watch } = require('internal/fs/watchers');
@@ -354,6 +355,87 @@ class FileHandle extends EventEmitter {
     return readable;
   }
 
+  /**
+   * @typedef {import('./streams').ReadStream
+   * } ReadStream
+   * @param {{
+   *   encoding?: string;
+   *   autoClose?: boolean;
+   *   emitClose?: boolean;
+   *   start: number;
+   *   end?: number;
+   *   highWaterMark?: number;
+   *   }} [options]
+   * @returns {ReadStream}
+   */
+  createReadStream(options = undefined) {
+    const { ReadStream } = lazyFsStreams();
+    return new ReadStream(undefined, { ...options, fd: this });
+  }
+
+  /**
+   * @typedef {import('./streams').WriteStream
+   * } WriteStream
+   * @param {{
+   *   encoding?: string;
+   *   autoClose?: boolean;
+   *   emitClose?: boolean;
+   *   start: number;
+   *   highWaterMark?: number;
+   *   flush?: boolean;
+   *   }} [options]
+   * @returns {WriteStream}
+   */
+  createWriteStream(options = undefined) {
+    const { WriteStream } = lazyFsStreams();
+    return new WriteStream(undefined, { ...options, fd: this });
+  }
+
+  [kTransfer]() {
+    if (this[kClosePromise] || this[kRefs] > 1) {
+      throw lazyDOMException('Cannot transfer FileHandle while in use',
+                             'DataCloneError');
+    }
+
+    const handle = this[kHandle];
+    this[kFd] = -1;
+    this[kCloseReason] = 'The FileHandle has been transferred';
+    this[kHandle] = null;
+    this[kRefs] = 0;
+
+    return {
+      data: { handle },
+      deserializeInfo: 'internal/fs/promises:FileHandle',
+    };
+  }
+
+  [kTransferList]() {
+    return [ this[kHandle] ];
+  }
+
+  [kDeserialize]({ handle }) {
+    this[kHandle] = handle;
+    this[kFd] = handle.fd;
+  }
+
+  [kRef]() {
+    this[kRefs]++;
+  }
+
+  [kUnref]() {
+    this[kRefs]--;
+    if (this[kRefs] === 0) {
+      this[kFd] = -1;
+      PromisePrototypeThen(
+        this[kHandle].close(),
+        this[kCloseResolve],
+        this[kCloseReject],
+      );
+    }
+  }
+}
+
+if (getOptionValue('--experimental-stream-iter')) {
   /**
    * Return the file contents as an AsyncIterable<Uint8Array[]> using the
    * new streams pull model. Optional transforms and options (including
@@ -362,7 +444,7 @@ class FileHandle extends EventEmitter {
    * @param {...(Function|object)} args - Optional transforms and/or options
    * @returns {AsyncIterable<Uint8Array[]>}
    */
-  pull(...args) {
+  FileHandle.prototype.pull = function pull(...args) {
     if (this[kFd] === -1)
       throw new ERR_INVALID_STATE('The FileHandle is closed');
     if (this[kClosePromise])
@@ -380,6 +462,7 @@ class FileHandle extends EventEmitter {
     const signal = options?.signal;
 
     const source = {
+      __proto__: null,
       async *[SymbolAsyncIterator]() {
         handle[kRef]();
         const readSize = 65536;
@@ -445,7 +528,7 @@ class FileHandle extends EventEmitter {
       return newStreamsPull(source, ...pullArgs);
     }
     return source;
-  }
+  };
 
   /**
    * Return a new-streams Writer backed by this file handle.
@@ -460,7 +543,7 @@ class FileHandle extends EventEmitter {
    * }} [options]
    * @returns {{ write, writev, end, fail, failSync }}
    */
-  writer(options) {
+  FileHandle.prototype.writer = function writer(options) {
     if (this[kFd] === -1)
       throw new ERR_INVALID_STATE('The FileHandle is closed');
     if (this[kClosePromise])
@@ -558,6 +641,7 @@ class FileHandle extends EventEmitter {
     }
 
     return {
+      __proto__: null,
       write(chunk, options) {
         if (closed) {
           return PromiseReject(
@@ -617,86 +701,7 @@ class FileHandle extends EventEmitter {
         await cleanup();
       },
     };
-  }
-
-  /**
-   * @typedef {import('./streams').ReadStream
-   * } ReadStream
-   * @param {{
-   *   encoding?: string;
-   *   autoClose?: boolean;
-   *   emitClose?: boolean;
-   *   start: number;
-   *   end?: number;
-   *   highWaterMark?: number;
-   *   }} [options]
-   * @returns {ReadStream}
-   */
-  createReadStream(options = undefined) {
-    const { ReadStream } = lazyFsStreams();
-    return new ReadStream(undefined, { ...options, fd: this });
-  }
-
-  /**
-   * @typedef {import('./streams').WriteStream
-   * } WriteStream
-   * @param {{
-   *   encoding?: string;
-   *   autoClose?: boolean;
-   *   emitClose?: boolean;
-   *   start: number;
-   *   highWaterMark?: number;
-   *   flush?: boolean;
-   *   }} [options]
-   * @returns {WriteStream}
-   */
-  createWriteStream(options = undefined) {
-    const { WriteStream } = lazyFsStreams();
-    return new WriteStream(undefined, { ...options, fd: this });
-  }
-
-  [kTransfer]() {
-    if (this[kClosePromise] || this[kRefs] > 1) {
-      throw lazyDOMException('Cannot transfer FileHandle while in use',
-                             'DataCloneError');
-    }
-
-    const handle = this[kHandle];
-    this[kFd] = -1;
-    this[kCloseReason] = 'The FileHandle has been transferred';
-    this[kHandle] = null;
-    this[kRefs] = 0;
-
-    return {
-      data: { handle },
-      deserializeInfo: 'internal/fs/promises:FileHandle',
-    };
-  }
-
-  [kTransferList]() {
-    return [ this[kHandle] ];
-  }
-
-  [kDeserialize]({ handle }) {
-    this[kHandle] = handle;
-    this[kFd] = handle.fd;
-  }
-
-  [kRef]() {
-    this[kRefs]++;
-  }
-
-  [kUnref]() {
-    this[kRefs]--;
-    if (this[kRefs] === 0) {
-      this[kFd] = -1;
-      PromisePrototypeThen(
-        this[kHandle].close(),
-        this[kCloseResolve],
-        this[kCloseReject],
-      );
-    }
-  }
+  };
 }
 
 async function handleFdClose(fileOpPromise, closeFunc) {