add stream utilities to FileHandle

types/node/fs/promises.d.ts

@@ -31,6 +31,8 @@ declare module 'fs/promises' {
         WatchOptions,
         WatchEventType,
         CopyOptions,
+        ReadStream,
+        WriteStream,
     } from 'node:fs';
     interface FileChangeInfo<T extends string | Buffer> {
         eventType: WatchEventType;
@@ -59,6 +61,20 @@ declare module 'fs/promises' {
         length?: number | null;
         position?: number | null;
     }
+    interface CreateReadStreamOptions {
+        encoding?: BufferEncoding | null | undefined;
+        autoClose?: boolean | undefined;
+        emitClose?: boolean | undefined;
+        start?: number | undefined;
+        end?: number | undefined;
+        highWaterMark?: number | undefined;
+    }
+    interface CreateWriteStreamOptions {
+        encoding?: BufferEncoding | null | undefined;
+        autoClose?: boolean | undefined;
+        emitClose?: boolean | undefined;
+        start?: number | undefined;
+    }
     // TODO: Add `EventEmitter` close
     interface FileHandle {
         /**
@@ -90,6 +106,77 @@ declare module 'fs/promises' {
          * @return Fulfills with `undefined` upon success.
          */
         chmod(mode: Mode): Promise<void>;
+        /**
+         * Unlike the 16 kb default `highWaterMark` for a `stream.Readable`, the stream
+         * returned by this method has a default `highWaterMark` of 64 kb.
+         *
+         * `options` can include `start` and `end` values to read a range of bytes from
+         * the file instead of the entire file. Both `start` and `end` are inclusive and
+         * start counting at 0, allowed values are in the
+         * \[0, [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)\] range. If `start` is
+         * omitted or `undefined`, `filehandle.createReadStream()` reads sequentially from
+         * the current file position. The `encoding` can be any one of those accepted by `Buffer`.
+         *
+         * If the `FileHandle` points to a character device that only supports blocking
+         * reads (such as keyboard or sound card), read operations do not finish until data
+         * is available. This can prevent the process from exiting and the stream from
+         * closing naturally.
+         *
+         * By default, the stream will emit a `'close'` event after it has been
+         * destroyed.  Set the `emitClose` option to `false` to change this behavior.
+         *
+         * ```js
+         * import { open } from 'fs/promises';
+         *
+         * const fd = await open('/dev/input/event0');
+         * // Create a stream from some character device.
+         * const stream = fd.createReadStream();
+         * setTimeout(() => {
+         *   stream.close(); // This may not close the stream.
+         *   // Artificially marking end-of-stream, as if the underlying resource had
+         *   // indicated end-of-file by itself, allows the stream to close.
+         *   // This does not cancel pending read operations, and if there is such an
+         *   // operation, the process may still not be able to exit successfully
+         *   // until it finishes.
+         *   stream.push(null);
+         *   stream.read(0);
+         * }, 100);
+         * ```
+         *
+         * If `autoClose` is false, then the file descriptor won't be closed, even if
+         * there's an error. It is the application's responsibility to close it and make
+         * sure there's no file descriptor leak. If `autoClose` is set to true (default
+         * behavior), on `'error'` or `'end'` the file descriptor will be closed
+         * automatically.
+         *
+         * An example to read the last 10 bytes of a file which is 100 bytes long:
+         *
+         * ```js
+         * import { open } from 'fs/promises';
+         *
+         * const fd = await open('sample.txt');
+         * fd.createReadStream({ start: 90, end: 99 });
+         * ```
+         * @since v16.11.0
+         */
+        createReadStream(options?: CreateReadStreamOptions): ReadStream;
+        /**
+         * `options` may also include a `start` option to allow writing data at some
+         * position past the beginning of the file, allowed values are in the
+         * \[0, [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)\] range. Modifying a file rather than replacing
+         * it may require the `flags` `open` option to be set to `r+` rather than the
+         * default `r`. The `encoding` can be any one of those accepted by `Buffer`.
+         *
+         * If `autoClose` is set to true (default behavior) on `'error'` or `'finish'`the file descriptor will be closed automatically. If `autoClose` is false,
+         * then the file descriptor won't be closed, even if there's an error.
+         * It is the application's responsibility to close it and make sure there's no
+         * file descriptor leak.
+         *
+         * By default, the stream will emit a `'close'` event after it has been
+         * destroyed.  Set the `emitClose` option to `false` to change this behavior.
+         * @since v16.11.0
+         */
+        createWriteStream(options?: CreateWriteStreamOptions): WriteStream;
         /**
          * Forces all currently queued I/O operations associated with the file to the
          * operating system's synchronized I/O completion state. Refer to the POSIX [`fdatasync(2)`](http://man7.org/linux/man-pages/man2/fdatasync.2.html) documentation for details.

types/node/test/fs.ts

@@ -630,3 +630,21 @@ const anyStats: fs.Stats | fs.BigIntStats = fs.statSync('.', { bigint: Math.rand
     cpAsync('src', 'dest'); // $ExpectType Promise<void>
     cpAsync('src', 'dest', opts); // $ExpectType Promise<void>
 }
+
+{
+    fs.promises.open('/dev/input/event0', 'r').then((fd) => {
+        // Create a stream from some character device.
+        const stream = fd.createReadStream(); // $ExpectType ReadStream
+        stream.close();
+        stream.push(null);
+        stream.read(0);
+    });
+}
+
+{
+    fs.promises.open('/tmp/tmp.txt', 'w').then((fd) => {
+        // Create a stream from some character device.
+        const stream = fd.createWriteStream(); // $ExpectType WriteStream
+        stream.close();
+    });
+}