@types/node 16.3.3 → 16.4.3

node/fs/promises.d.ts

@@ -1,3 +1,13 @@
+/**
+ * The `fs/promises` API provides asynchronous file system methods that return
+ * promises.
+ *
+ * The promise APIs use the underlying Node.js threadpool to perform file
+ * system operations off the event loop thread. These operations are not
+ * synchronized or threadsafe. Care must be taken when performing multiple
+ * concurrent modifications on the same file or data corruption may occur.
+ * @since v10.0.0
+ */
 declare module 'fs/promises' {
     import { Abortable } from 'node:events';
     import { Stream } from 'node:stream';
@@ -20,17 +30,14 @@ declare module 'fs/promises' {
         Mode,
         WatchOptions,
     } from 'node:fs';
-
     interface FlagAndOpenMode {
         mode?: Mode | undefined;
         flag?: OpenMode | undefined;
     }
-
     interface FileReadResult<T extends ArrayBufferView> {
         bytesRead: number;
         buffer: T;
     }
-
     interface FileReadOptions<T extends ArrayBufferView = Buffer> {
         /**
          * @default `Buffer.alloc(0xffff)`
@@ -46,222 +53,366 @@ declare module 'fs/promises' {
         length?: number | null;
         position?: number | null;
     }
-
     // TODO: Add `EventEmitter` close
     interface FileHandle {
         /**
-         * Gets the file descriptor for this file handle.
+         * The numeric file descriptor managed by the {FileHandle} object.
+         * @since v10.0.0
          */
         readonly fd: number;
-
         /**
-         * Asynchronously append data to a file, creating the file if it does not exist. The underlying file will _not_ be closed automatically.
-         * The `FileHandle` must have been opened for appending.
-         * @param data The data to write. If something other than a `Buffer` or `Uint8Array` is provided, the value is coerced to a string.
-         * @param options Either the encoding for the file, or an object optionally specifying the encoding, file mode, and flag.
-         * If `encoding` is not supplied, the default of `'utf8'` is used.
-         * If `mode` is not supplied, the default of `0o666` is used.
-         * If `mode` is a string, it is parsed as an octal integer.
-         * If `flag` is not supplied, the default of `'a'` is used.
+         * Alias of `filehandle.writeFile()`.
+         *
+         * When operating on file handles, the mode cannot be changed from what it was set
+         * to with `fsPromises.open()`. Therefore, this is equivalent to `filehandle.writeFile()`.
+         * @since v10.0.0
+         * @return Fulfills with `undefined` upon success.
          */
-        appendFile(data: string | Uint8Array, options?: ObjectEncodingOptions & FlagAndOpenMode | BufferEncoding | null): Promise<void>;
-
+        appendFile(data: string | Uint8Array, options?: (ObjectEncodingOptions & FlagAndOpenMode) | BufferEncoding | null): Promise<void>;
         /**
-         * Asynchronous fchown(2) - Change ownership of a file.
+         * Changes the ownership of the file. A wrapper for [`chown(2)`](http://man7.org/linux/man-pages/man2/chown.2.html).
+         * @since v10.0.0
+         * @param uid The file's new owner's user id.
+         * @param gid The file's new group's group id.
+         * @return Fulfills with `undefined` upon success.
          */
         chown(uid: number, gid: number): Promise<void>;
-
         /**
-         * Asynchronous fchmod(2) - Change permissions of a file.
-         * @param mode A file mode. If a string is passed, it is parsed as an octal integer.
+         * Modifies the permissions on the file. See [`chmod(2)`](http://man7.org/linux/man-pages/man2/chmod.2.html).
+         * @since v10.0.0
+         * @param mode the file mode bit mask.
+         * @return Fulfills with `undefined` upon success.
          */
         chmod(mode: Mode): Promise<void>;
-
         /**
-         * Asynchronous fdatasync(2) - synchronize a file's in-core state with storage device.
+         * 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.
+         *
+         * Unlike `filehandle.sync` this method does not flush modified metadata.
+         * @since v10.0.0
+         * @return Fulfills with `undefined` upon success.
          */
         datasync(): Promise<void>;
-
         /**
-         * Asynchronous fsync(2) - synchronize a file's in-core state with the underlying storage device.
+         * Request that all data for the open file descriptor is flushed to the storage
+         * device. The specific implementation is operating system and device specific.
+         * Refer to the POSIX [`fsync(2)`](http://man7.org/linux/man-pages/man2/fsync.2.html) documentation for more detail.
+         * @since v10.0.0
+         * @return Fufills with `undefined` upon success.
          */
         sync(): Promise<void>;
-
         /**
-         * Asynchronously reads data from the file.
-         * The `FileHandle` must have been opened for reading.
-         * @param buffer The buffer that the data will be written to.
-         * @param offset The offset in the buffer at which to start writing.
+         * Reads data from the file and stores that in the given buffer.
+         *
+         * If the file is not modified concurrently, the end-of-file is reached when the
+         * number of bytes read is zero.
+         * @since v10.0.0
+         * @param buffer A buffer that will be filled with the file data read.
+         * @param offset The location in the buffer at which to start filling.
          * @param length The number of bytes to read.
-         * @param position The offset from the beginning of the file from which data should be read. If `null`, data will be read from the current position.
+         * @param position The location where to begin reading data from the file. If `null`, data will be read from the current file position, and the position will be updated. If `position` is an
+         * integer, the current file position will remain unchanged.
+         * @return Fulfills upon success with an object with two properties:
          */
         read<T extends ArrayBufferView>(buffer: T, offset?: number | null, length?: number | null, position?: number | null): Promise<FileReadResult<T>>;
         read<T extends ArrayBufferView = Buffer>(options?: FileReadOptions<T>): Promise<FileReadResult<T>>;
         /**
-         * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically.
-         * The `FileHandle` must have been opened for reading.
-         * @param options An object that may contain an optional flag.
-         * If a flag is not provided, it defaults to `'r'`.
+         * Asynchronously reads the entire contents of a file.
+         *
+         * If `options` is a string, then it specifies the `encoding`.
+         *
+         * The `<FileHandle>` has to support reading.
+         *
+         * If one or more `filehandle.read()` calls are made on a file handle and then a`filehandle.readFile()` call is made, the data will be read from the current
+         * position till the end of the file. It doesn't always read from the beginning
+         * of the file.
+         * @since v10.0.0
+         * @return Fulfills upon a successful read with the contents of the file. If no encoding is specified (using `options.encoding`), the data is returned as a {Buffer} object. Otherwise, the
+         * data will be a string.
          */
-        readFile(options?: { encoding?: null | undefined, flag?: OpenMode | undefined } | null): Promise<Buffer>;
-
+        readFile(
+            options?: {
+                encoding?: null | undefined;
+                flag?: OpenMode | undefined;
+            } | null
+        ): Promise<Buffer>;
         /**
          * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically.
          * The `FileHandle` must have been opened for reading.
          * @param options An object that may contain an optional flag.
          * If a flag is not provided, it defaults to `'r'`.
          */
-        readFile(options: { encoding: BufferEncoding, flag?: OpenMode | undefined } | BufferEncoding): Promise<string>;
-
+        readFile(
+            options:
+                | {
+                      encoding: BufferEncoding;
+                      flag?: OpenMode | undefined;
+                  }
+                | BufferEncoding
+        ): Promise<string>;
         /**
          * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically.
          * The `FileHandle` must have been opened for reading.
          * @param options An object that may contain an optional flag.
          * If a flag is not provided, it defaults to `'r'`.
          */
-        readFile(options?: ObjectEncodingOptions & { flag?: OpenMode | undefined } | BufferEncoding | null): Promise<string | Buffer>;
-
+        readFile(
+            options?:
+                | (ObjectEncodingOptions & {
+                      flag?: OpenMode | undefined;
+                  })
+                | BufferEncoding
+                | null
+        ): Promise<string | Buffer>;
         /**
-         * Asynchronous fstat(2) - Get file status.
+         * @since v10.0.0
+         * @return Fulfills with an {fs.Stats} for the file.
          */
-        stat(opts?: StatOptions & { bigint?: false | undefined }): Promise<Stats>;
-        stat(opts: StatOptions & { bigint: true }): Promise<BigIntStats>;
+        stat(
+            opts?: StatOptions & {
+                bigint?: false | undefined;
+            }
+        ): Promise<Stats>;
+        stat(
+            opts: StatOptions & {
+                bigint: true;
+            }
+        ): Promise<BigIntStats>;
         stat(opts?: StatOptions): Promise<Stats | BigIntStats>;
-
         /**
-         * Asynchronous ftruncate(2) - Truncate a file to a specified length.
-         * @param len If not specified, defaults to `0`.
+         * Truncates the file.
+         *
+         * If the file was larger than `len` bytes, only the first `len` bytes will be
+         * retained in the file.
+         *
+         * The following example retains only the first four bytes of the file:
+         *
+         * ```js
+         * import { open } from 'fs/promises';
+         *
+         * let filehandle = null;
+         * try {
+         *   filehandle = await open('temp.txt', 'r+');
+         *   await filehandle.truncate(4);
+         * } finally {
+         *   await filehandle?.close();
+         * }
+         * ```
+         *
+         * If the file previously was shorter than `len` bytes, it is extended, and the
+         * extended part is filled with null bytes (`'\0'`):
+         *
+         * If `len` is negative then `0` will be used.
+         * @since v10.0.0
+         * @return Fulfills with `undefined` upon success.
          */
         truncate(len?: number): Promise<void>;
-
         /**
-         * Asynchronously change file timestamps of the file.
-         * @param atime The last access time. If a string is provided, it will be coerced to number.
-         * @param mtime The last modified time. If a string is provided, it will be coerced to number.
+         * Change the file system timestamps of the object referenced by the `<FileHandle>` then resolves the promise with no arguments upon success.
+         * @since v10.0.0
          */
         utimes(atime: string | number | Date, mtime: string | number | Date): Promise<void>;
-
-        /**
-         * Asynchronously writes `buffer` to the file.
-         * The `FileHandle` must have been opened for writing.
-         * @param buffer The buffer that the data will be written to.
-         * @param offset The part of the buffer to be written. If not supplied, defaults to `0`.
-         * @param length The number of bytes to write. If not supplied, defaults to `buffer.length - offset`.
-         * @param position The offset from the beginning of the file where this data should be written. If not supplied, defaults to the current position.
-         */
-        write<TBuffer extends Uint8Array>(buffer: TBuffer, offset?: number | null, length?: number | null, position?: number | null): Promise<{ bytesWritten: number, buffer: TBuffer }>;
-
-        /**
-         * Asynchronously writes `string` to the file.
-         * The `FileHandle` must have been opened for writing.
-         * It is unsafe to call `write()` multiple times on the same file without waiting for the `Promise`
-         * to be resolved (or rejected). For this scenario, `fs.createWriteStream` is strongly recommended.
-         * @param string A string to write.
-         * @param position The offset from the beginning of the file where this data should be written. If not supplied, defaults to the current position.
-         * @param encoding The expected string encoding.
-         */
-        write(data: string | Uint8Array, position?: number | null, encoding?: BufferEncoding | null): Promise<{ bytesWritten: number, buffer: string }>;
-
         /**
-         * Asynchronously writes data to a file, replacing the file if it already exists. The underlying file will _not_ be closed automatically.
-         * The `FileHandle` must have been opened for writing.
-         * It is unsafe to call `writeFile()` multiple times on the same file without waiting for the `Promise` to be resolved (or rejected).
-         * @param data The data to write. If something other than a `Buffer` or `Uint8Array` is provided, the value is coerced to a string.
-         * @param options Either the encoding for the file, or an object optionally specifying the encoding, file mode, and flag.
-         * If `encoding` is not supplied, the default of `'utf8'` is used.
-         * If `mode` is not supplied, the default of `0o666` is used.
-         * If `mode` is a string, it is parsed as an octal integer.
-         * If `flag` is not supplied, the default of `'w'` is used.
+         * Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a buffer, or an object with an own `toString` function
+         * property. The promise is resolved with no arguments upon success.
+         *
+         * If `options` is a string, then it specifies the `encoding`.
+         *
+         * The `<FileHandle>` has to support writing.
+         *
+         * It is unsafe to use `filehandle.writeFile()` multiple times on the same file
+         * without waiting for the promise to be resolved (or rejected).
+         *
+         * If one or more `filehandle.write()` calls are made on a file handle and then a`filehandle.writeFile()` call is made, the data will be written from the
+         * current position till the end of the file. It doesn't always write from the
+         * beginning of the file.
+         * @since v10.0.0
          */
-        writeFile(data: string | Uint8Array, options?: ObjectEncodingOptions & FlagAndOpenMode & Abortable | BufferEncoding | null): Promise<void>;
-
+        writeFile(data: string | Uint8Array, options?: (ObjectEncodingOptions & FlagAndOpenMode & Abortable) | BufferEncoding | null): Promise<void>;
         /**
-         * See `fs.writev` promisified version.
+         * Write an array of [&lt;ArrayBufferView&gt;](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView)s to the file.
+         *
+         * The promise is resolved with an object containing a two properties:
+         *
+         * It is unsafe to call `writev()` multiple times on the same file without waiting
+         * for the promise to be resolved (or rejected).
+         *
+         * On Linux, positional writes don't work when the file is opened in append mode.
+         * The kernel ignores the position argument and always appends the data to
+         * the end of the file.
+         * @since v12.9.0
+         * @param position The offset from the beginning of the file where the data from `buffers` should be written. If `position` is not a `number`, the data will be written at the current
+         * position.
          */
         writev(buffers: ReadonlyArray<NodeJS.ArrayBufferView>, position?: number): Promise<WriteVResult>;
-
         /**
-         * See `fs.readv` promisified version.
+         * Read from a file and write to an array of [&lt;ArrayBufferView&gt;](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView)s
+         * @since v13.13.0, v12.17.0
+         * @param position The offset from the beginning of the file where the data should be read from. If `position` is not a `number`, the data will be read from the current position.
+         * @return Fulfills upon success an object containing two properties:
          */
         readv(buffers: ReadonlyArray<NodeJS.ArrayBufferView>, position?: number): Promise<ReadVResult>;
-
         /**
-         * Asynchronous close(2) - close a `FileHandle`.
+         * Closes the file handle after waiting for any pending operation on the handle to
+         * complete.
+         *
+         * ```js
+         * import { open } from 'fs/promises';
+         *
+         * let filehandle;
+         * try {
+         *   filehandle = await open('thefile.txt', 'r');
+         * } finally {
+         *   await filehandle?.close();
+         * }
+         * ```
+         * @since v10.0.0
+         * @return Fulfills with `undefined` upon success.
          */
         close(): Promise<void>;
     }
-
     /**
-     * Asynchronously tests a user's permissions for the file specified by path.
-     * @param path A path to a file or directory. If a URL is provided, it must use the `file:` protocol.
-     * URL support is _experimental_.
+     * Tests a user's permissions for the file or directory specified by `path`.
+     * The `mode` argument is an optional integer that specifies the accessibility
+     * checks to be performed. Check `File access constants` for possible values
+     * of `mode`. It is possible to create a mask consisting of the bitwise OR of
+     * two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`).
+     *
+     * If the accessibility check is successful, the promise is resolved with no
+     * value. If any of the accessibility checks fail, the promise is rejected
+     * with an [&lt;Error&gt;](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object. The following example checks if the file`/etc/passwd` can be read and
+     * written by the current process.
+     *
+     * ```js
+     * import { access } from 'fs/promises';
+     * import { constants } from 'fs';
+     *
+     * try {
+     *   await access('/etc/passwd', constants.R_OK | constants.W_OK);
+     *   console.log('can access');
+     * } catch {
+     *   console.error('cannot access');
+     * }
+     * ```
+     *
+     * Using `fsPromises.access()` to check for the accessibility of a file before
+     * calling `fsPromises.open()` is not recommended. Doing so introduces a race
+     * condition, since other processes may change the file's state between the two
+     * calls. Instead, user code should open/read/write the file directly and handle
+     * the error raised if the file is not accessible.
+     * @since v10.0.0
+     * @return Fulfills with `undefined` upon success.
      */
     function access(path: PathLike, mode?: number): Promise<void>;
-
-    /**
-     * Asynchronously copies `src` to `dest`. By default, `dest` is overwritten if it already exists.
-     * Node.js makes no guarantees about the atomicity of the copy operation.
-     * If an error occurs after the destination file has been opened for writing, Node.js will attempt
-     * to remove the destination.
-     * @param src A path to the source file.
-     * @param dest A path to the destination file.
-     * @param flags An optional integer that specifies the behavior of the copy operation. The only
-     * supported flag is `fs.constants.COPYFILE_EXCL`, which causes the copy operation to fail if
-     * `dest` already exists.
+    /**
+     * Asynchronously copies `src` to `dest`. By default, `dest` is overwritten if it
+     * already exists.
+     *
+     * No guarantees are made about the atomicity of the copy operation. If an
+     * error occurs after the destination file has been opened for writing, an attempt
+     * will be made to remove the destination.
+     *
+     * ```js
+     * import { constants } from 'fs';
+     * import { copyFile } from 'fs/promises';
+     *
+     * try {
+     *   await copyFile('source.txt', 'destination.txt');
+     *   console.log('source.txt was copied to destination.txt');
+     * } catch {
+     *   console.log('The file could not be copied');
+     * }
+     *
+     * // By using COPYFILE_EXCL, the operation will fail if destination.txt exists.
+     * try {
+     *   await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL);
+     *   console.log('source.txt was copied to destination.txt');
+     * } catch {
+     *   console.log('The file could not be copied');
+     * }
+     * ```
+     * @since v10.0.0
+     * @param src source filename to copy
+     * @param dest destination filename of the copy operation
+     * @param mode Optional modifiers that specify the behavior of the copy operation. It is possible to create a mask consisting of the bitwise OR of two or more values (e.g.
+     * `fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE`)
+     * @return Fulfills with `undefined` upon success.
      */
     function copyFile(src: PathLike, dest: PathLike, flags?: number): Promise<void>;
-
     /**
-     * Asynchronous open(2) - open and possibly create a file.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
-     * @param mode A file mode. If a string is passed, it is parsed as an octal integer. If not
-     * supplied, defaults to `0o666`.
+     * Opens a `<FileHandle>`.
+     *
+     * Refer to the POSIX [`open(2)`](http://man7.org/linux/man-pages/man2/open.2.html) documentation for more detail.
+     *
+     * Some characters (`< > : " / \ | ? *`) are reserved under Windows as documented
+     * by [Naming Files, Paths, and Namespaces](https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file). Under NTFS, if the filename contains
+     * a colon, Node.js will open a file system stream, as described by[this MSDN page](https://docs.microsoft.com/en-us/windows/desktop/FileIO/using-streams).
+     * @since v10.0.0
+     * @param flags See `support of file system `flags``.
+     * @param mode Sets the file mode (permission and sticky bits) if the file is created.
+     * @return Fulfills with a {FileHandle} object.
      */
     function open(path: PathLike, flags: string | number, mode?: Mode): Promise<FileHandle>;
-
     /**
-     * Asynchronous rename(2) - Change the name or location of a file or directory.
-     * @param oldPath A path to a file. If a URL is provided, it must use the `file:` protocol.
-     * URL support is _experimental_.
-     * @param newPath A path to a file. If a URL is provided, it must use the `file:` protocol.
-     * URL support is _experimental_.
+     * Renames `oldPath` to `newPath`.
+     * @since v10.0.0
+     * @return Fulfills with `undefined` upon success.
      */
     function rename(oldPath: PathLike, newPath: PathLike): Promise<void>;
-
     /**
-     * Asynchronous truncate(2) - Truncate a file to a specified length.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
-     * @param len If not specified, defaults to `0`.
+     * Truncates (shortens or extends the length) of the content at `path` to `len`bytes.
+     * @since v10.0.0
+     * @return Fulfills with `undefined` upon success.
      */
     function truncate(path: PathLike, len?: number): Promise<void>;
-
     /**
-     * Asynchronous rmdir(2) - delete a directory.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
+     * Removes the directory identified by `path`.
+     *
+     * Using `fsPromises.rmdir()` on a file (not a directory) results in the
+     * promise being rejected with an `ENOENT` error on Windows and an `ENOTDIR`error on POSIX.
+     *
+     * To get a behavior similar to the `rm -rf` Unix command, use `fsPromises.rm()` with options `{ recursive: true, force: true }`.
+     * @since v10.0.0
+     * @return Fulfills with `undefined` upon success.
      */
     function rmdir(path: PathLike, options?: RmDirOptions): Promise<void>;
-
     /**
-     * Asynchronously removes files and directories (modeled on the standard POSIX `rm` utility).
+     * Removes files and directories (modeled on the standard POSIX `rm` utility).
+     * @since v14.14.0
+     * @return Fulfills with `undefined` upon success.
      */
     function rm(path: PathLike, options?: RmOptions): Promise<void>;
-
     /**
-     * Asynchronous mkdir(2) - create a directory.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
-     * @param options Either the file mode, or an object optionally specifying the file mode and whether parent folders
-     * should be created. If a string is passed, it is parsed as an octal integer. If not specified, defaults to `0o777`.
-     */
-    function mkdir(path: PathLike, options: MakeDirectoryOptions & { recursive: true; }): Promise<string | undefined>;
-
+     * Asynchronously creates a directory.
+     *
+     * The optional `options` argument can be an integer specifying `mode` (permission
+     * and sticky bits), or an object with a `mode` property and a `recursive`property indicating whether parent directories should be created. Calling`fsPromises.mkdir()` when `path` is a directory
+     * that exists results in a
+     * rejection only when `recursive` is false.
+     * @since v10.0.0
+     * @return Upon success, fulfills with `undefined` if `recursive` is `false`, or the first directory path created if `recursive` is `true`.
+     */
+    function mkdir(
+        path: PathLike,
+        options: MakeDirectoryOptions & {
+            recursive: true;
+        }
+    ): Promise<string | undefined>;
     /**
      * Asynchronous mkdir(2) - create a directory.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
      * @param options Either the file mode, or an object optionally specifying the file mode and whether parent folders
      * should be created. If a string is passed, it is parsed as an octal integer. If not specified, defaults to `0o777`.
      */
-    function mkdir(path: PathLike, options?: Mode | (MakeDirectoryOptions & { recursive?: false | undefined; }) | null): Promise<void>;
-
+    function mkdir(
+        path: PathLike,
+        options?:
+            | Mode
+            | (MakeDirectoryOptions & {
+                  recursive?: false | undefined;
+              })
+            | null
+    ): Promise<void>;
     /**
      * Asynchronous mkdir(2) - create a directory.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
@@ -269,226 +420,399 @@ declare module 'fs/promises' {
      * should be created. If a string is passed, it is parsed as an octal integer. If not specified, defaults to `0o777`.
      */
     function mkdir(path: PathLike, options?: Mode | MakeDirectoryOptions | null): Promise<string | undefined>;
-
     /**
-     * Asynchronous readdir(3) - read a directory.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
-     * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
-     */
-    function readdir(path: PathLike, options?: ObjectEncodingOptions & { withFileTypes?: false | undefined } | BufferEncoding | null): Promise<string[]>;
-
+     * Reads the contents of a directory.
+     *
+     * The optional `options` argument can be a string specifying an encoding, or an
+     * object with an `encoding` property specifying the character encoding to use for
+     * the filenames. If the `encoding` is set to `'buffer'`, the filenames returned
+     * will be passed as `<Buffer>` objects.
+     *
+     * If `options.withFileTypes` is set to `true`, the resolved array will contain `<fs.Dirent>` objects.
+     *
+     * ```js
+     * import { readdir } from 'fs/promises';
+     *
+     * try {
+     *   const files = await readdir(path);
+     *   for (const file of files)
+     *     console.log(file);
+     * } catch (err) {
+     *   console.error(err);
+     * }
+     * ```
+     * @since v10.0.0
+     * @return Fulfills with an array of the names of the files in the directory excluding `'.'` and `'..'`.
+     */
+    function readdir(
+        path: PathLike,
+        options?:
+            | (ObjectEncodingOptions & {
+                  withFileTypes?: false | undefined;
+              })
+            | BufferEncoding
+            | null
+    ): Promise<string[]>;
     /**
      * Asynchronous readdir(3) - read a directory.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
      * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
      */
-    function readdir(path: PathLike, options: { encoding: "buffer"; withFileTypes?: false | undefined } | "buffer"): Promise<Buffer[]>;
-
+    function readdir(
+        path: PathLike,
+        options:
+            | {
+                  encoding: 'buffer';
+                  withFileTypes?: false | undefined;
+              }
+            | 'buffer'
+    ): Promise<Buffer[]>;
     /**
      * Asynchronous readdir(3) - read a directory.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
      * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
      */
-    function readdir(path: PathLike, options?: ObjectEncodingOptions & { withFileTypes?: false | undefined } | BufferEncoding | null): Promise<string[] | Buffer[]>;
-
+    function readdir(
+        path: PathLike,
+        options?:
+            | (ObjectEncodingOptions & {
+                  withFileTypes?: false | undefined;
+              })
+            | BufferEncoding
+            | null
+    ): Promise<string[] | Buffer[]>;
     /**
      * Asynchronous readdir(3) - read a directory.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
      * @param options If called with `withFileTypes: true` the result data will be an array of Dirent.
      */
-    function readdir(path: PathLike, options: ObjectEncodingOptions & { withFileTypes: true }): Promise<Dirent[]>;
-
-    /**
-     * Asynchronous readlink(2) - read value of a symbolic link.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
-     * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
+    function readdir(
+        path: PathLike,
+        options: ObjectEncodingOptions & {
+            withFileTypes: true;
+        }
+    ): Promise<Dirent[]>;
+    /**
+     * Reads the contents of the symbolic link referred to by `path`. See the POSIX[`readlink(2)`](http://man7.org/linux/man-pages/man2/readlink.2.html) documentation for more detail. The promise is
+     * resolved with the`linkString` upon success.
+     *
+     * The optional `options` argument can be a string specifying an encoding, or an
+     * object with an `encoding` property specifying the character encoding to use for
+     * the link path returned. If the `encoding` is set to `'buffer'`, the link path
+     * returned will be passed as a `<Buffer>` object.
+     * @since v10.0.0
+     * @return Fulfills with the `linkString` upon success.
      */
     function readlink(path: PathLike, options?: ObjectEncodingOptions | BufferEncoding | null): Promise<string>;
-
     /**
      * Asynchronous readlink(2) - read value of a symbolic link.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
      * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
      */
     function readlink(path: PathLike, options: BufferEncodingOption): Promise<Buffer>;
-
     /**
      * Asynchronous readlink(2) - read value of a symbolic link.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
      * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
      */
     function readlink(path: PathLike, options?: ObjectEncodingOptions | string | null): Promise<string | Buffer>;
-
     /**
-     * Asynchronous symlink(2) - Create a new symbolic link to an existing file.
-     * @param target A path to an existing file. If a URL is provided, it must use the `file:` protocol.
-     * @param path A path to the new symlink. If a URL is provided, it must use the `file:` protocol.
-     * @param type May be set to `'dir'`, `'file'`, or `'junction'` (default is `'file'`) and is only available on Windows (ignored on other platforms).
-     * When using `'junction'`, the `target` argument will automatically be normalized to an absolute path.
+     * Creates a symbolic link.
+     *
+     * The `type` argument is only used on Windows platforms and can be one of `'dir'`,`'file'`, or `'junction'`. Windows junction points require the destination path
+     * to be absolute. When using `'junction'`, the `target` argument will
+     * automatically be normalized to absolute path.
+     * @since v10.0.0
+     * @return Fulfills with `undefined` upon success.
      */
     function symlink(target: PathLike, path: PathLike, type?: string | null): Promise<void>;
-
     /**
-     * Asynchronous lstat(2) - Get file status. Does not dereference symbolic links.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
-     */
-    function lstat(path: PathLike, opts?: StatOptions & { bigint?: false | undefined }): Promise<Stats>;
-    function lstat(path: PathLike, opts: StatOptions & { bigint: true }): Promise<BigIntStats>;
+     * Equivalent to `fsPromises.stat()` unless `path` refers to a symbolic link,
+     * in which case the link itself is stat-ed, not the file that it refers to.
+     * Refer to the POSIX [`lstat(2)`](http://man7.org/linux/man-pages/man2/lstat.2.html) document for more detail.
+     * @since v10.0.0
+     * @return Fulfills with the {fs.Stats} object for the given symbolic link `path`.
+     */
+    function lstat(
+        path: PathLike,
+        opts?: StatOptions & {
+            bigint?: false | undefined;
+        }
+    ): Promise<Stats>;
+    function lstat(
+        path: PathLike,
+        opts: StatOptions & {
+            bigint: true;
+        }
+    ): Promise<BigIntStats>;
     function lstat(path: PathLike, opts?: StatOptions): Promise<Stats | BigIntStats>;
-
     /**
-     * Asynchronous stat(2) - Get file status.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
-     */
-    function stat(path: PathLike, opts?: StatOptions & { bigint?: false | undefined }): Promise<Stats>;
-    function stat(path: PathLike, opts: StatOptions & { bigint: true }): Promise<BigIntStats>;
+     * @since v10.0.0
+     * @return Fulfills with the {fs.Stats} object for the given `path`.
+     */
+    function stat(
+        path: PathLike,
+        opts?: StatOptions & {
+            bigint?: false | undefined;
+        }
+    ): Promise<Stats>;
+    function stat(
+        path: PathLike,
+        opts: StatOptions & {
+            bigint: true;
+        }
+    ): Promise<BigIntStats>;
     function stat(path: PathLike, opts?: StatOptions): Promise<Stats | BigIntStats>;
-
     /**
-     * Asynchronous link(2) - Create a new link (also known as a hard link) to an existing file.
-     * @param existingPath A path to a file. If a URL is provided, it must use the `file:` protocol.
-     * @param newPath A path to a file. If a URL is provided, it must use the `file:` protocol.
+     * Creates a new link from the `existingPath` to the `newPath`. See the POSIX[`link(2)`](http://man7.org/linux/man-pages/man2/link.2.html) documentation for more detail.
+     * @since v10.0.0
+     * @return Fulfills with `undefined` upon success.
      */
     function link(existingPath: PathLike, newPath: PathLike): Promise<void>;
-
     /**
-     * Asynchronous unlink(2) - delete a name and possibly the file it refers to.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
+     * If `path` refers to a symbolic link, then the link is removed without affecting
+     * the file or directory to which that link refers. If the `path` refers to a file
+     * path that is not a symbolic link, the file is deleted. See the POSIX [`unlink(2)`](http://man7.org/linux/man-pages/man2/unlink.2.html)documentation for more detail.
+     * @since v10.0.0
+     * @return Fulfills with `undefined` upon success.
      */
     function unlink(path: PathLike): Promise<void>;
-
     /**
-     * Asynchronous chmod(2) - Change permissions of a file.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
-     * @param mode A file mode. If a string is passed, it is parsed as an octal integer.
+     * Changes the permissions of a file.
+     * @since v10.0.0
+     * @return Fulfills with `undefined` upon success.
      */
     function chmod(path: PathLike, mode: Mode): Promise<void>;
-
     /**
-     * Asynchronous lchmod(2) - Change permissions of a file. Does not dereference symbolic links.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
-     * @param mode A file mode. If a string is passed, it is parsed as an octal integer.
+     * Changes the permissions on a symbolic link.
+     *
+     * This method is only implemented on macOS.
+     * @deprecated Since v10.0.0
+     * @return Fulfills with `undefined` upon success.
      */
     function lchmod(path: PathLike, mode: Mode): Promise<void>;
-
     /**
-     * Asynchronous lchown(2) - Change ownership of a file. Does not dereference symbolic links.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
+     * Changes the ownership on a symbolic link.
+     * @since v10.0.0
+     * @return Fulfills with `undefined` upon success.
      */
     function lchown(path: PathLike, uid: number, gid: number): Promise<void>;
-
     /**
-     * Changes the access and modification times of a file in the same way as `fsPromises.utimes()`,
-     * with the difference that if the path refers to a symbolic link, then the link is not
-     * dereferenced: instead, the timestamps of the symbolic link itself are changed.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
-     * @param atime The last access time. If a string is provided, it will be coerced to number.
-     * @param mtime The last modified time. If a string is provided, it will be coerced to number.
+     * Changes the access and modification times of a file in the same way as `fsPromises.utimes()`, with the difference that if the path refers to a
+     * symbolic link, then the link is not dereferenced: instead, the timestamps of
+     * the symbolic link itself are changed.
+     * @since v14.5.0, v12.19.0
+     * @return Fulfills with `undefined` upon success.
      */
     function lutimes(path: PathLike, atime: string | number | Date, mtime: string | number | Date): Promise<void>;
-
     /**
-     * Asynchronous chown(2) - Change ownership of a file.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
+     * Changes the ownership of a file.
+     * @since v10.0.0
+     * @return Fulfills with `undefined` upon success.
      */
     function chown(path: PathLike, uid: number, gid: number): Promise<void>;
-
     /**
-     * Asynchronously change file timestamps of the file referenced by the supplied path.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
-     * @param atime The last access time. If a string is provided, it will be coerced to number.
-     * @param mtime The last modified time. If a string is provided, it will be coerced to number.
+     * Change the file system timestamps of the object referenced by `path`.
+     *
+     * The `atime` and `mtime` arguments follow these rules:
+     *
+     * * Values can be either numbers representing Unix epoch time, `Date`s, or a
+     * numeric string like `'123456789.0'`.
+     * * If the value can not be converted to a number, or is `NaN`, `Infinity` or`-Infinity`, an `Error` will be thrown.
+     * @since v10.0.0
+     * @return Fulfills with `undefined` upon success.
      */
     function utimes(path: PathLike, atime: string | number | Date, mtime: string | number | Date): Promise<void>;
-
     /**
-     * Asynchronous realpath(3) - return the canonicalized absolute pathname.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
-     * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
+     * Determines the actual location of `path` using the same semantics as the`fs.realpath.native()` function.
+     *
+     * Only paths that can be converted to UTF8 strings are supported.
+     *
+     * The optional `options` argument can be a string specifying an encoding, or an
+     * object with an `encoding` property specifying the character encoding to use for
+     * the path. If the `encoding` is set to `'buffer'`, the path returned will be
+     * passed as a `<Buffer>` object.
+     *
+     * On Linux, when Node.js is linked against musl libc, the procfs file system must
+     * be mounted on `/proc` in order for this function to work. Glibc does not have
+     * this restriction.
+     * @since v10.0.0
+     * @return Fulfills with the resolved path upon success.
      */
     function realpath(path: PathLike, options?: ObjectEncodingOptions | BufferEncoding | null): Promise<string>;
-
     /**
      * Asynchronous realpath(3) - return the canonicalized absolute pathname.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
      * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
      */
     function realpath(path: PathLike, options: BufferEncodingOption): Promise<Buffer>;
-
     /**
      * Asynchronous realpath(3) - return the canonicalized absolute pathname.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
      * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
      */
     function realpath(path: PathLike, options?: ObjectEncodingOptions | BufferEncoding | null): Promise<string | Buffer>;
-
     /**
-     * Asynchronously creates a unique temporary directory.
-     * Generates six random characters to be appended behind a required `prefix` to create a unique temporary directory.
-     * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
+     * Creates a unique temporary directory. A unique directory name is generated by
+     * appending six random characters to the end of the provided `prefix`. Due to
+     * platform inconsistencies, avoid trailing `X` characters in `prefix`. Some
+     * platforms, notably the BSDs, can return more than six random characters, and
+     * replace trailing `X` characters in `prefix` with random characters.
+     *
+     * The optional `options` argument can be a string specifying an encoding, or an
+     * object with an `encoding` property specifying the character encoding to use.
+     *
+     * ```js
+     * import { mkdtemp } from 'fs/promises';
+     *
+     * try {
+     *   await mkdtemp(path.join(os.tmpdir(), 'foo-'));
+     * } catch (err) {
+     *   console.error(err);
+     * }
+     * ```
+     *
+     * The `fsPromises.mkdtemp()` method will append the six randomly selected
+     * characters directly to the `prefix` string. For instance, given a directory`/tmp`, if the intention is to create a temporary directory _within_`/tmp`, the`prefix` must end with a trailing
+     * platform-specific path separator
+     * (`require('path').sep`).
+     * @since v10.0.0
+     * @return Fulfills with a string containing the filesystem path of the newly created temporary directory.
      */
     function mkdtemp(prefix: string, options?: ObjectEncodingOptions | BufferEncoding | null): Promise<string>;
-
     /**
      * Asynchronously creates a unique temporary directory.
      * Generates six random characters to be appended behind a required `prefix` to create a unique temporary directory.
      * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
      */
     function mkdtemp(prefix: string, options: BufferEncodingOption): Promise<Buffer>;
-
     /**
      * Asynchronously creates a unique temporary directory.
      * Generates six random characters to be appended behind a required `prefix` to create a unique temporary directory.
      * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
      */
     function mkdtemp(prefix: string, options?: ObjectEncodingOptions | BufferEncoding | null): Promise<string | Buffer>;
-
     /**
-     * Asynchronously writes data to a file, replacing the file if it already exists.
-     * It is unsafe to call `fsPromises.writeFile()` multiple times on the same file without waiting for the `Promise` to be resolved (or rejected).
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
-     * URL support is _experimental_.
-     * If a `FileHandle` is provided, the underlying file will _not_ be closed automatically.
-     * @param data The data to write. If something other than a `Buffer` or `Uint8Array` is provided, the value is coerced to a string.
-     * @param options Either the encoding for the file, or an object optionally specifying the encoding, file mode, and flag.
-     * If `encoding` is not supplied, the default of `'utf8'` is used.
-     * If `mode` is not supplied, the default of `0o666` is used.
-     * If `mode` is a string, it is parsed as an octal integer.
-     * If `flag` is not supplied, the default of `'w'` is used.
+     * Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a `<Buffer>`, or an object with an own `toString` function
+     * property.
+     *
+     * The `encoding` option is ignored if `data` is a buffer.
+     *
+     * If `options` is a string, then it specifies the encoding.
+     *
+     * Any specified `<FileHandle>` has to support writing.
+     *
+     * It is unsafe to use `fsPromises.writeFile()` multiple times on the same file
+     * without waiting for the promise to be settled.
+     *
+     * Similarly to `fsPromises.readFile` \- `fsPromises.writeFile` is a convenience
+     * method that performs multiple `write` calls internally to write the buffer
+     * passed to it. For performance sensitive code consider using `fs.createWriteStream()`.
+     *
+     * It is possible to use an `<AbortSignal>` to cancel an `fsPromises.writeFile()`.
+     * Cancelation is "best effort", and some amount of data is likely still
+     * to be written.
+     *
+     * ```js
+     * import { writeFile } from 'fs/promises';
+     *
+     * try {
+     *   const controller = new AbortController();
+     *   const { signal } = controller;
+     *   const data = new Uint8Array(Buffer.from('Hello Node.js'));
+     *   const promise = writeFile('message.txt', data, { signal });
+     *
+     *   // Abort the request before the promise settles.
+     *   controller.abort();
+     *
+     *   await promise;
+     * } catch (err) {
+     *   // When a request is aborted - err is an AbortError
+     *   console.error(err);
+     * }
+     * ```
+     *
+     * Aborting an ongoing request does not abort individual operating
+     * system requests but rather the internal buffering `fs.writeFile` performs.
+     * @since v10.0.0
+     * @param file filename or `FileHandle`
+     * @return Fulfills with `undefined` upon success.
      */
     function writeFile(
         path: PathLike | FileHandle,
         data: string | NodeJS.ArrayBufferView | Iterable<string | NodeJS.ArrayBufferView> | AsyncIterable<string | NodeJS.ArrayBufferView> | Stream,
-        options?: ObjectEncodingOptions & { mode?: Mode | undefined, flag?: OpenMode | undefined } & Abortable | BufferEncoding | null
+        options?:
+            | (ObjectEncodingOptions & {
+                  mode?: Mode | undefined;
+                  flag?: OpenMode | undefined;
+              } & Abortable)
+            | BufferEncoding
+            | null
     ): Promise<void>;
-
     /**
-     * Asynchronously append data to a file, creating the file if it does not exist.
-     * @param file A path to a file. If a URL is provided, it must use the `file:` protocol.
-     * URL support is _experimental_.
-     * If a `FileHandle` is provided, the underlying file will _not_ be closed automatically.
-     * @param data The data to write. If something other than a `Buffer` or `Uint8Array` is provided, the value is coerced to a string.
-     * @param options Either the encoding for the file, or an object optionally specifying the encoding, file mode, and flag.
-     * If `encoding` is not supplied, the default of `'utf8'` is used.
-     * If `mode` is not supplied, the default of `0o666` is used.
-     * If `mode` is a string, it is parsed as an octal integer.
-     * If `flag` is not supplied, the default of `'a'` is used.
+     * Asynchronously append data to a file, creating the file if it does not yet
+     * exist. `data` can be a string or a `<Buffer>`.
+     *
+     * If `options` is a string, then it specifies the `encoding`.
+     *
+     * The `path` may be specified as a `<FileHandle>` that has been opened
+     * for appending (using `fsPromises.open()`).
+     * @since v10.0.0
+     * @param path filename or {FileHandle}
+     * @return Fulfills with `undefined` upon success.
      */
-    function appendFile(
-        path: PathLike | FileHandle,
-        data: string | Uint8Array,
-        options?: ObjectEncodingOptions & FlagAndOpenMode | BufferEncoding | null,
-    ): Promise<void>;
-
+    function appendFile(path: PathLike | FileHandle, data: string | Uint8Array, options?: (ObjectEncodingOptions & FlagAndOpenMode) | BufferEncoding | null): Promise<void>;
     /**
      * Asynchronously reads the entire contents of a file.
-     * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
-     * If a `FileHandle` is provided, the underlying file will _not_ be closed automatically.
-     * @param options An object that may contain an optional flag.
-     * If a flag is not provided, it defaults to `'r'`.
-     */
-    function readFile(path: PathLike | FileHandle, options?: { encoding?: null | undefined, flag?: OpenMode | undefined } & Abortable | null): Promise<Buffer>;
-
+     *
+     * If no encoding is specified (using `options.encoding`), the data is returned
+     * as a `<Buffer>` object. Otherwise, the data will be a string.
+     *
+     * If `options` is a string, then it specifies the encoding.
+     *
+     * When the `path` is a directory, the behavior of `fsPromises.readFile()` is
+     * platform-specific. On macOS, Linux, and Windows, the promise will be rejected
+     * with an error. On FreeBSD, a representation of the directory's contents will be
+     * returned.
+     *
+     * It is possible to abort an ongoing `readFile` using an `<AbortSignal>`. If a
+     * request is aborted the promise returned is rejected with an `AbortError`:
+     *
+     * ```js
+     * import { readFile } from 'fs/promises';
+     *
+     * try {
+     *   const controller = new AbortController();
+     *   const { signal } = controller;
+     *   const promise = readFile(fileName, { signal });
+     *
+     *   // Abort the request before the promise settles.
+     *   controller.abort();
+     *
+     *   await promise;
+     * } catch (err) {
+     *   // When a request is aborted - err is an AbortError
+     *   console.error(err);
+     * }
+     * ```
+     *
+     * Aborting an ongoing request does not abort individual operating
+     * system requests but rather the internal buffering `fs.readFile` performs.
+     *
+     * Any specified `<FileHandle>` has to support reading.
+     * @since v10.0.0
+     * @param path filename or `FileHandle`
+     * @return Fulfills with the contents of the file.
+     */
+    function readFile(
+        path: PathLike | FileHandle,
+        options?:
+            | ({
+                  encoding?: null | undefined;
+                  flag?: OpenMode | undefined;
+              } & Abortable)
+            | null
+    ): Promise<Buffer>;
     /**
      * Asynchronously reads the entire contents of a file.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
@@ -496,8 +820,15 @@ declare module 'fs/promises' {
      * @param options An object that may contain an optional flag.
      * If a flag is not provided, it defaults to `'r'`.
      */
-    function readFile(path: PathLike | FileHandle, options: { encoding: BufferEncoding, flag?: OpenMode | undefined } & Abortable | BufferEncoding): Promise<string>;
-
+    function readFile(
+        path: PathLike | FileHandle,
+        options:
+            | ({
+                  encoding: BufferEncoding;
+                  flag?: OpenMode | undefined;
+              } & Abortable)
+            | BufferEncoding
+    ): Promise<string>;
     /**
      * Asynchronously reads the entire contents of a file.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
@@ -505,20 +836,83 @@ declare module 'fs/promises' {
      * @param options An object that may contain an optional flag.
      * If a flag is not provided, it defaults to `'r'`.
      */
-    function readFile(path: PathLike | FileHandle, options?: ObjectEncodingOptions & Abortable & { flag?: OpenMode | undefined } | BufferEncoding | null): Promise<string | Buffer>;
-
+    function readFile(
+        path: PathLike | FileHandle,
+        options?:
+            | (ObjectEncodingOptions &
+                  Abortable & {
+                      flag?: OpenMode | undefined;
+                  })
+            | BufferEncoding
+            | null
+    ): Promise<string | Buffer>;
+    /**
+     * Asynchronously open a directory for iterative scanning. See the POSIX[`opendir(3)`](http://man7.org/linux/man-pages/man3/opendir.3.html) documentation for more detail.
+     *
+     * Creates an `<fs.Dir>`, which contains all further functions for reading from
+     * and cleaning up the directory.
+     *
+     * The `encoding` option sets the encoding for the `path` while opening the
+     * directory and subsequent read operations.
+     *
+     * Example using async iteration:
+     *
+     * ```js
+     * import { opendir } from 'fs/promises';
+     *
+     * try {
+     *   const dir = await opendir('./');
+     *   for await (const dirent of dir)
+     *     console.log(dirent.name);
+     * } catch (err) {
+     *   console.error(err);
+     * }
+     * ```
+     *
+     * When using the async iterator, the `<fs.Dir>` object will be automatically
+     * closed after the iterator exits.
+     * @since v12.12.0
+     * @return Fulfills with an {fs.Dir}.
+     */
     function opendir(path: string, options?: OpenDirOptions): Promise<Dir>;
-
     /**
-     * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`.
-     * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol.
-     * @param options Either the encoding for the filename provided to the listener, or an object optionally specifying encoding, persistent, and recursive options.
-     * If `encoding` is not supplied, the default of `'utf8'` is used.
-     * If `persistent` is not supplied, the default of `true` is used.
-     * If `recursive` is not supplied, the default of `false` is used.
+     * Returns an async iterator that watches for changes on `filename`, where `filename`is either a file or a directory.
+     *
+     * ```js
+     * const { watch } = require('fs/promises');
+     *
+     * const ac = new AbortController();
+     * const { signal } = ac;
+     * setTimeout(() => ac.abort(), 10000);
+     *
+     * (async () => {
+     *   try {
+     *     const watcher = watch(__filename, { signal });
+     *     for await (const event of watcher)
+     *       console.log(event);
+     *   } catch (err) {
+     *     if (err.name === 'AbortError')
+     *       return;
+     *     throw err;
+     *   }
+     * })();
+     * ```
+     *
+     * On most platforms, `'rename'` is emitted whenever a filename appears or
+     * disappears in the directory.
+     *
+     * All the `caveats` for `fs.watch()` also apply to `fsPromises.watch()`.
+     * @since v15.9.0
+     * @return of objects with the properties:
      */
-    function watch(filename: PathLike, options: WatchOptions & { encoding: "buffer" } | "buffer"): AsyncIterable<Buffer>;
-
+    function watch(
+        filename: PathLike,
+        options:
+            | (WatchOptions & {
+                  encoding: 'buffer';
+              })
+            | 'buffer'
+    ): AsyncIterable<Buffer>;
     /**
      * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`.
      * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol.
@@ -527,11 +921,7 @@ declare module 'fs/promises' {
      * If `persistent` is not supplied, the default of `true` is used.
      * If `recursive` is not supplied, the default of `false` is used.
      */
-    function watch(
-        filename: PathLike,
-        options?: WatchOptions | BufferEncoding
-    ): AsyncIterable<string>;
-
+    function watch(filename: PathLike, options?: WatchOptions | BufferEncoding): AsyncIterable<string>;
     /**
      * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`.
      * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol.
@@ -542,7 +932,6 @@ declare module 'fs/promises' {
      */
     function watch(filename: PathLike, options: WatchOptions | string): AsyncIterable<string> | AsyncIterable<Buffer>;
 }
-
 declare module 'node:fs/promises' {
     export * from 'fs/promises';
 }