@rio-cloud/cdk-v2-constructs 8.2.0 → 8.2.1-alpha.0

package/node_modules/@types/node/fs/promises.d.ts

@@ -9,6 +9,7 @@
  * @since v10.0.0
  */
 declare module "fs/promises" {
+    import { NonSharedBuffer } from "node:buffer";
     import { Abortable } from "node:events";
     import { Stream } from "node:stream";
     import { ReadableStream } from "node:stream/web";
@@ -20,12 +21,19 @@ declare module "fs/promises" {
         CopyOptions,
         Dir,
         Dirent,
+        EncodingOption,
+        GlobOptions,
+        GlobOptionsWithFileTypes,
+        GlobOptionsWithoutFileTypes,
         MakeDirectoryOptions,
         Mode,
         ObjectEncodingOptions,
         OpenDirOptions,
         OpenMode,
         PathLike,
+        ReadOptions,
+        ReadOptionsWithBuffer,
+        ReadPosition,
         ReadStream,
         ReadVResult,
         RmDirOptions,
@@ -36,7 +44,7 @@ declare module "fs/promises" {
         StatsFs,
         TimeLike,
         WatchEventType,
-        WatchOptions,
+        WatchOptions as _WatchOptions,
         WriteStream,
         WriteVResult,
     } from "node:fs";
@@ -53,6 +61,7 @@ declare module "fs/promises" {
         bytesRead: number;
         buffer: T;
     }
+    /** @deprecated This interface will be removed in a future version. Use `import { ReadOptionsWithBuffer } from "node:fs"` instead. */
     interface FileReadOptions<T extends NodeJS.ArrayBufferView = Buffer> {
         /**
          * @default `Buffer.alloc(0xffff)`
@@ -66,9 +75,9 @@ declare module "fs/promises" {
          * @default `buffer.byteLength`
          */
         length?: number | null;
-        position?: number | null;
+        position?: ReadPosition | null;
     }
-    interface CreateReadStreamOptions {
+    interface CreateReadStreamOptions extends Abortable {
         encoding?: BufferEncoding | null | undefined;
         autoClose?: boolean | undefined;
         emitClose?: boolean | undefined;
@@ -82,13 +91,10 @@ declare module "fs/promises" {
         emitClose?: boolean | undefined;
         start?: number | undefined;
         highWaterMark?: number | undefined;
+        flush?: boolean | undefined;
     }
     interface ReadableWebStreamOptions {
-        /**
-         * Whether to open a normal or a `'bytes'` stream.
-         * @since v20.0.0
-         */
-        type?: "bytes" | undefined;
+        autoClose?: boolean | undefined;
     }
     // TODO: Add `EventEmitter` close
     interface FileHandle {
@@ -107,7 +113,10 @@ declare module "fs/promises" {
          */
         appendFile(
             data: string | Uint8Array,
-            options?: (ObjectEncodingOptions & FlagAndOpenMode) | BufferEncoding | null,
+            options?:
+                | (ObjectEncodingOptions & Abortable)
+                | BufferEncoding
+                | null,
         ): Promise<void>;
         /**
          * Changes the ownership of the file. A wrapper for [`chown(2)`](http://man7.org/linux/man-pages/man2/chown.2.html).
@@ -185,7 +194,7 @@ declare module "fs/promises" {
          * 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,
+         * 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.
@@ -229,11 +238,18 @@ declare module "fs/promises" {
             buffer: T,
             offset?: number | null,
             length?: number | null,
-            position?: number | null,
+            position?: ReadPosition | null,
+        ): Promise<FileReadResult<T>>;
+        read<T extends NodeJS.ArrayBufferView>(
+            buffer: T,
+            options?: ReadOptions,
+        ): Promise<FileReadResult<T>>;
+        read<T extends NodeJS.ArrayBufferView = NonSharedBuffer>(
+            options?: ReadOptionsWithBuffer<T>,
         ): Promise<FileReadResult<T>>;
-        read<T extends NodeJS.ArrayBufferView = Buffer>(options?: FileReadOptions<T>): Promise<FileReadResult<T>>;
         /**
-         * Returns a `ReadableStream` that may be used to read the files data.
+         * Returns a byte-oriented `ReadableStream` that may be used to read the file's
+         * contents.
          *
          * An error will be thrown if this method is called more than once or is called
          * after the `FileHandle` is closed or closing.
@@ -254,7 +270,6 @@ declare module "fs/promises" {
          * While the `ReadableStream` will read the file to completion, it will not
          * close the `FileHandle` automatically. User code must still call the`fileHandle.close()` method.
          * @since v17.0.0
-         * @experimental
          */
         readableWebStream(options?: ReadableWebStreamOptions): ReadableStream;
         /**
@@ -264,7 +279,7 @@ declare module "fs/promises" {
          *
          * 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
+         * 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
@@ -272,39 +287,29 @@ declare module "fs/promises" {
          * data will be a string.
          */
         readFile(
-            options?: {
-                encoding?: null | undefined;
-                flag?: OpenMode | undefined;
-            } | null,
-        ): Promise<Buffer>;
+            options?:
+                | ({ encoding?: null | undefined } & Abortable)
+                | null,
+        ): Promise<NonSharedBuffer>;
         /**
          * 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;
-                }
+                | ({ encoding: BufferEncoding } & Abortable)
                 | 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;
-                })
+                | (ObjectEncodingOptions & Abortable)
                 | BufferEncoding
                 | null,
-        ): Promise<string | Buffer>;
+        ): Promise<string | NonSharedBuffer>;
         /**
          * Convenience method to create a `readline` interface and stream over the file.
          * See `filehandle.createReadStream()` for the options.
@@ -366,22 +371,22 @@ declare module "fs/promises" {
          */
         truncate(len?: number): Promise<void>;
         /**
-         * Change the file system timestamps of the object referenced by the `FileHandle` then resolves the promise with no arguments upon success.
+         * Change the file system timestamps of the object referenced by the `FileHandle` then fulfills the promise with no arguments upon success.
          * @since v10.0.0
          */
         utimes(atime: TimeLike, mtime: TimeLike): Promise<void>;
         /**
-         * Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a buffer, an
+         * Asynchronously writes data to a file, replacing the file if it already exists. `data` can be a string, a buffer, an
          * [AsyncIterable](https://tc39.github.io/ecma262/#sec-asynciterable-interface), or an
          * [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol) object.
-         * The promise is resolved with no arguments upon success.
+         * The promise is fulfilled 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).
+         * without waiting for the promise to be fulfilled (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
@@ -390,15 +395,18 @@ declare module "fs/promises" {
          */
         writeFile(
             data: string | Uint8Array,
-            options?: (ObjectEncodingOptions & FlagAndOpenMode & Abortable) | BufferEncoding | null,
+            options?:
+                | (ObjectEncodingOptions & Abortable)
+                | BufferEncoding
+                | null,
         ): Promise<void>;
         /**
          * Write `buffer` to the file.
          *
-         * The promise is resolved with an object containing two properties:
+         * The promise is fulfilled with an object containing two properties:
          *
          * It is unsafe to use `filehandle.write()` multiple times on the same file
-         * without waiting for the promise to be resolved (or rejected). For this
+         * without waiting for the promise to be fulfilled (or rejected). For this
          * scenario, use `filehandle.createWriteStream()`.
          *
          * On Linux, positional writes do not work when the file is opened in append mode.
@@ -410,7 +418,7 @@ declare module "fs/promises" {
          * @param [position='null'] The offset from the beginning of the file where the data from `buffer` should be written. If `position` is not a `number`, the data will be written at the current
          * position. See the POSIX pwrite(2) documentation for more detail.
          */
-        write<TBuffer extends Uint8Array>(
+        write<TBuffer extends NodeJS.ArrayBufferView>(
             buffer: TBuffer,
             offset?: number | null,
             length?: number | null,
@@ -419,6 +427,13 @@ declare module "fs/promises" {
             bytesWritten: number;
             buffer: TBuffer;
         }>;
+        write<TBuffer extends Uint8Array>(
+            buffer: TBuffer,
+            options?: { offset?: number; length?: number; position?: number },
+        ): Promise<{
+            bytesWritten: number;
+            buffer: TBuffer;
+        }>;
         write(
             data: string,
             position?: number | null,
@@ -430,10 +445,10 @@ declare module "fs/promises" {
         /**
          * Write an array of [ArrayBufferView](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:
+         * The promise is fulfilled 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).
+         * for the promise to be fulfilled (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
@@ -442,14 +457,20 @@ declare module "fs/promises" {
          * @param [position='null'] 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: readonly NodeJS.ArrayBufferView[], position?: number): Promise<WriteVResult>;
+        writev<TBuffers extends readonly NodeJS.ArrayBufferView[]>(
+            buffers: TBuffers,
+            position?: number,
+        ): Promise<WriteVResult<TBuffers>>;
         /**
          * Read from a file and write to an array of [ArrayBufferView](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView) s
          * @since v13.13.0, v12.17.0
          * @param [position='null'] 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: readonly NodeJS.ArrayBufferView[], position?: number): Promise<ReadVResult>;
+        readv<TBuffers extends readonly NodeJS.ArrayBufferView[]>(
+            buffers: TBuffers,
+            position?: number,
+        ): Promise<ReadVResult<TBuffers>>;
         /**
          * Closes the file handle after waiting for any pending operation on the handle to
          * complete.
@@ -469,8 +490,9 @@ declare module "fs/promises" {
          */
         close(): Promise<void>;
         /**
-         * An alias for {@link FileHandle.close()}.
-         * @since v20.4.0
+         * Calls `filehandle.close()` and returns a promise that fulfills when the
+         * filehandle is closed.
+         * @since v20.4.0, v18.8.0
          */
         [Symbol.asyncDispose](): Promise<void>;
     }
@@ -478,11 +500,11 @@ declare module "fs/promises" {
     /**
      * 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. `mode` should be either the value `fs.constants.F_OK`or a mask consisting of the bitwise OR of any of `fs.constants.R_OK`,`fs.constants.W_OK`, and `fs.constants.X_OK`
+     * checks to be performed. `mode` should be either the value `fs.constants.F_OK` or a mask consisting of the bitwise OR of any of `fs.constants.R_OK`, `fs.constants.W_OK`, and `fs.constants.X_OK`
      * (e.g.`fs.constants.W_OK | fs.constants.R_OK`). Check `File access constants` for
      * possible values of `mode`.
      *
-     * If the accessibility check is successful, the promise is resolved with no
+     * If the accessibility check is successful, the promise is fulfilled with no
      * value. If any of the accessibility checks fail, the promise is rejected
      * with an [Error](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.
@@ -563,7 +585,7 @@ declare module "fs/promises" {
      */
     function rename(oldPath: PathLike, newPath: PathLike): Promise<void>;
     /**
-     * Truncates (shortens or extends the length) of the content at `path` to `len`bytes.
+     * Truncates (shortens or extends the length) of the content at `path` to `len` bytes.
      * @since v10.0.0
      * @param [len=0]
      * @return Fulfills with `undefined` upon success.
@@ -573,7 +595,7 @@ declare module "fs/promises" {
      * 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.
+     * 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
@@ -590,7 +612,7 @@ declare module "fs/promises" {
      * 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
+     * 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.
      *
@@ -645,7 +667,7 @@ declare module "fs/promises" {
      * 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.
+     * If `options.withFileTypes` is set to `true`, the returned array will contain `fs.Dirent` objects.
      *
      * ```js
      * import { readdir } from 'node:fs/promises';
@@ -685,7 +707,7 @@ declare module "fs/promises" {
                 recursive?: boolean | undefined;
             }
             | "buffer",
-    ): Promise<Buffer[]>;
+    ): Promise<NonSharedBuffer[]>;
     /**
      * Asynchronous readdir(3) - read a directory.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
@@ -700,7 +722,7 @@ declare module "fs/promises" {
             })
             | BufferEncoding
             | null,
-    ): Promise<string[] | Buffer[]>;
+    ): Promise<string[] | NonSharedBuffer[]>;
     /**
      * Asynchronous readdir(3) - read a directory.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
@@ -713,9 +735,22 @@ declare module "fs/promises" {
             recursive?: boolean | undefined;
         },
     ): Promise<Dirent[]>;
+    /**
+     * Asynchronous readdir(3) - read a directory.
+     * @param path A path to a directory. If a URL is provided, it must use the `file:` protocol.
+     * @param options Must include `withFileTypes: true` and `encoding: 'buffer'`.
+     */
+    function readdir(
+        path: PathLike,
+        options: {
+            encoding: "buffer";
+            withFileTypes: true;
+            recursive?: boolean | undefined;
+        },
+    ): Promise<Dirent<NonSharedBuffer>[]>;
     /**
      * 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.
+     * fulfilled 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
@@ -730,17 +765,20 @@ declare module "fs/promises" {
      * @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>;
+    function readlink(path: PathLike, options: BufferEncodingOption): Promise<NonSharedBuffer>;
     /**
      * 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>;
+    function readlink(
+        path: PathLike,
+        options?: ObjectEncodingOptions | string | null,
+    ): Promise<string | NonSharedBuffer>;
     /**
      * Creates a symbolic link.
      *
-     * The `type` argument is only used on Windows platforms and can be one of `'dir'`,`'file'`, or `'junction'`. If the `type` argument is not a string, Node.js will
+     * The `type` argument is only used on Windows platforms and can be one of `'dir'`, `'file'`, or `'junction'`. If the `type` argument is not a string, Node.js will
      * autodetect `target` type and use `'file'` or `'dir'`. If the `target` does not
      * exist, `'file'` will be used. Windows junction points require the destination
      * path to be absolute. When using `'junction'`, the `target` argument will
@@ -860,13 +898,13 @@ declare module "fs/promises" {
      *
      * * 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.
+     * * 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: TimeLike, mtime: TimeLike): Promise<void>;
     /**
-     * Determines the actual location of `path` using the same semantics as the`fs.realpath.native()` function.
+     * 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.
      *
@@ -887,7 +925,7 @@ declare module "fs/promises" {
      * @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>;
+    function realpath(path: PathLike, options: BufferEncodingOption): Promise<NonSharedBuffer>;
     /**
      * 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.
@@ -896,7 +934,7 @@ declare module "fs/promises" {
     function realpath(
         path: PathLike,
         options?: ObjectEncodingOptions | BufferEncoding | null,
-    ): Promise<string | Buffer>;
+    ): Promise<string | NonSharedBuffer>;
     /**
      * 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
@@ -920,9 +958,9 @@ declare module "fs/promises" {
      * ```
      *
      * 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
+     * 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('node:path').sep`).
+     * (`import { sep } from 'node:path'`).
      * @since v10.0.0
      * @return Fulfills with a string containing the file system path of the newly created temporary directory.
      */
@@ -932,15 +970,52 @@ declare module "fs/promises" {
      * 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>;
+    function mkdtemp(prefix: string, options: BufferEncodingOption): Promise<NonSharedBuffer>;
     /**
      * 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>;
+    function mkdtemp(
+        prefix: string,
+        options?: ObjectEncodingOptions | BufferEncoding | null,
+    ): Promise<string | NonSharedBuffer>;
+    interface DisposableTempDir extends AsyncDisposable {
+        /**
+         * The path of the created directory.
+         */
+        path: string;
+        /**
+         * A function which removes the created directory.
+         */
+        remove(): Promise<void>;
+        /**
+         * The same as `remove`.
+         */
+        [Symbol.asyncDispose](): Promise<void>;
+    }
+    /**
+     * The resulting Promise holds an async-disposable object whose `path` property
+     * holds the created directory path. When the object is disposed, the directory
+     * and its contents will be removed asynchronously if it still exists. If the
+     * directory cannot be deleted, disposal will throw an error. The object has an
+     * async `remove()` method which will perform the same task.
+     *
+     * Both this function and the disposal function on the resulting object are
+     * async, so it should be used with `await` + `await using` as in
+     * `await using dir = await fsPromises.mkdtempDisposable('prefix')`.
+     *
+     * <!-- TODO: link MDN docs for disposables once https://github.com/mdn/content/pull/38027 lands -->
+     *
+     * For detailed information, see the documentation of `fsPromises.mkdtemp()`.
+     *
+     * The optional `options` argument can be a string specifying an encoding, or an
+     * object with an `encoding` property specifying the character encoding to use.
+     * @since v24.4.0
+     */
+    function mkdtempDisposable(prefix: PathLike, options?: EncodingOption): Promise<DisposableTempDir>;
     /**
-     * Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a buffer, an
+     * Asynchronously writes data to a file, replacing the file if it already exists. `data` can be a string, a buffer, an
      * [AsyncIterable](https://tc39.github.io/ecma262/#sec-asynciterable-interface), or an
      * [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol) object.
      *
@@ -1001,6 +1076,12 @@ declare module "fs/promises" {
             | (ObjectEncodingOptions & {
                 mode?: Mode | undefined;
                 flag?: OpenMode | undefined;
+                /**
+                 * If all data is successfully written to the file, and `flush`
+                 * is `true`, `filehandle.sync()` is used to flush the data.
+                 * @default false
+                 */
+                flush?: boolean | undefined;
             } & Abortable)
             | BufferEncoding
             | null,
@@ -1022,7 +1103,7 @@ declare module "fs/promises" {
     function appendFile(
         path: PathLike | FileHandle,
         data: string | Uint8Array,
-        options?: (ObjectEncodingOptions & FlagAndOpenMode) | BufferEncoding | null,
+        options?: (ObjectEncodingOptions & FlagAndOpenMode & { flush?: boolean | undefined }) | BufferEncoding | null,
     ): Promise<void>;
     /**
      * Asynchronously reads the entire contents of a file.
@@ -1088,7 +1169,7 @@ declare module "fs/promises" {
                 flag?: OpenMode | undefined;
             } & Abortable)
             | null,
-    ): Promise<Buffer>;
+    ): Promise<NonSharedBuffer>;
     /**
      * 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.
@@ -1124,7 +1205,7 @@ declare module "fs/promises" {
             )
             | BufferEncoding
             | null,
-    ): Promise<string | Buffer>;
+    ): Promise<string | NonSharedBuffer>;
     /**
      * 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.
      *
@@ -1154,11 +1235,21 @@ declare module "fs/promises" {
      * @return Fulfills with an {fs.Dir}.
      */
     function opendir(path: PathLike, options?: OpenDirOptions): Promise<Dir>;
+    interface WatchOptions extends _WatchOptions {
+        maxQueue?: number | undefined;
+        overflow?: "ignore" | "throw" | undefined;
+    }
+    interface WatchOptionsWithBufferEncoding extends WatchOptions {
+        encoding: "buffer";
+    }
+    interface WatchOptionsWithStringEncoding extends WatchOptions {
+        encoding?: BufferEncoding | undefined;
+    }
     /**
      * Returns an async iterator that watches for changes on `filename`, where `filename`is either a file or a directory.
      *
      * ```js
-     * const { watch } = require('node:fs/promises');
+     * import { watch } from 'node:fs/promises';
      *
      * const ac = new AbortController();
      * const { signal } = ac;
@@ -1186,33 +1277,16 @@ declare module "fs/promises" {
      */
     function watch(
         filename: PathLike,
-        options:
-            | (WatchOptions & {
-                encoding: "buffer";
-            })
-            | "buffer",
-    ): AsyncIterable<FileChangeInfo<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.
-     * @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.
-     */
-    function watch(filename: PathLike, options?: WatchOptions | BufferEncoding): AsyncIterable<FileChangeInfo<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.
-     * @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.
-     */
+        options?: WatchOptionsWithStringEncoding | BufferEncoding,
+    ): NodeJS.AsyncIterator<FileChangeInfo<string>>;
     function watch(
         filename: PathLike,
-        options: WatchOptions | string,
-    ): AsyncIterable<FileChangeInfo<string>> | AsyncIterable<FileChangeInfo<Buffer>>;
+        options: WatchOptionsWithBufferEncoding | "buffer",
+    ): NodeJS.AsyncIterator<FileChangeInfo<NonSharedBuffer>>;
+    function watch(
+        filename: PathLike,
+        options: WatchOptions | BufferEncoding | "buffer",
+    ): NodeJS.AsyncIterator<FileChangeInfo<string | NonSharedBuffer>>;
     /**
      * Asynchronously copies the entire directory structure from `src` to `dest`,
      * including subdirectories and files.
@@ -1226,6 +1300,30 @@ declare module "fs/promises" {
      * @return Fulfills with `undefined` upon success.
      */
     function cp(source: string | URL, destination: string | URL, opts?: CopyOptions): Promise<void>;
+    /**
+     * ```js
+     * import { glob } from 'node:fs/promises';
+     *
+     * for await (const entry of glob('*.js'))
+     *   console.log(entry);
+     * ```
+     * @since v22.0.0
+     * @returns An AsyncIterator that yields the paths of files
+     * that match the pattern.
+     */
+    function glob(pattern: string | readonly string[]): NodeJS.AsyncIterator<string>;
+    function glob(
+        pattern: string | readonly string[],
+        options: GlobOptionsWithFileTypes,
+    ): NodeJS.AsyncIterator<Dirent>;
+    function glob(
+        pattern: string | readonly string[],
+        options: GlobOptionsWithoutFileTypes,
+    ): NodeJS.AsyncIterator<string>;
+    function glob(
+        pattern: string | readonly string[],
+        options: GlobOptions,
+    ): NodeJS.AsyncIterator<Dirent | string>;
 }
 declare module "node:fs/promises" {
     export * from "fs/promises";