@types/node 22.15.33 → 22.18.13

{node v22.15 → node v22.18}/fs.d.ts

@@ -19,6 +19,7 @@
  * @see [source](https://github.com/nodejs/node/blob/v22.x/lib/fs.js)
  */
 declare module "fs" {
+    import { NonSharedBuffer } from "node:buffer";
     import * as stream from "node:stream";
     import { Abortable, EventEmitter } from "node:events";
     import { URL } from "node:url";
@@ -243,8 +244,8 @@ declare module "fs" {
          */
         name: Name;
         /**
-         * The base path that this `fs.Dirent` object refers to.
-         * @since v20.12.0
+         * The path to the parent directory of the file this `fs.Dirent` object refers to.
+         * @since v20.12.0, v18.20.0
          */
         parentPath: string;
         /**
@@ -328,6 +329,20 @@ declare module "fs" {
          * @since v12.12.0
          */
         readSync(): Dirent | null;
+        /**
+         * Calls `dir.close()` if the directory handle is open, and returns a promise that
+         * fulfills when disposal is complete.
+         * @since v22.17.0
+         * @experimental
+         */
+        [Symbol.asyncDispose](): Promise<void>;
+        /**
+         * Calls `dir.closeSync()` if the directory handle is open, and returns
+         * `undefined`.
+         * @since v22.17.0
+         * @experimental
+         */
+        [Symbol.dispose](): void;
     }
     /**
      * Class: fs.StatWatcher
@@ -388,23 +403,29 @@ declare module "fs" {
          *   3. error
          */
         addListener(event: string, listener: (...args: any[]) => void): this;
-        addListener(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this;
+        addListener(event: "change", listener: (eventType: string, filename: string | NonSharedBuffer) => void): this;
         addListener(event: "close", listener: () => void): this;
         addListener(event: "error", listener: (error: Error) => void): this;
         on(event: string, listener: (...args: any[]) => void): this;
-        on(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this;
+        on(event: "change", listener: (eventType: string, filename: string | NonSharedBuffer) => void): this;
         on(event: "close", listener: () => void): this;
         on(event: "error", listener: (error: Error) => void): this;
         once(event: string, listener: (...args: any[]) => void): this;
-        once(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this;
+        once(event: "change", listener: (eventType: string, filename: string | NonSharedBuffer) => void): this;
         once(event: "close", listener: () => void): this;
         once(event: "error", listener: (error: Error) => void): this;
         prependListener(event: string, listener: (...args: any[]) => void): this;
-        prependListener(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this;
+        prependListener(
+            event: "change",
+            listener: (eventType: string, filename: string | NonSharedBuffer) => void,
+        ): this;
         prependListener(event: "close", listener: () => void): this;
         prependListener(event: "error", listener: (error: Error) => void): this;
         prependOnceListener(event: string, listener: (...args: any[]) => void): this;
-        prependOnceListener(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this;
+        prependOnceListener(
+            event: "change",
+            listener: (eventType: string, filename: string | NonSharedBuffer) => void,
+        ): this;
         prependOnceListener(event: "close", listener: () => void): this;
         prependOnceListener(event: "error", listener: (error: Error) => void): this;
     }
@@ -1320,7 +1341,7 @@ declare module "fs" {
     export function readlink(
         path: PathLike,
         options: BufferEncodingOption,
-        callback: (err: NodeJS.ErrnoException | null, linkString: Buffer) => void,
+        callback: (err: NodeJS.ErrnoException | null, linkString: NonSharedBuffer) => void,
     ): void;
     /**
      * Asynchronous readlink(2) - read value of a symbolic link.
@@ -1330,7 +1351,7 @@ declare module "fs" {
     export function readlink(
         path: PathLike,
         options: EncodingOption,
-        callback: (err: NodeJS.ErrnoException | null, linkString: string | Buffer) => void,
+        callback: (err: NodeJS.ErrnoException | null, linkString: string | NonSharedBuffer) => void,
     ): void;
     /**
      * Asynchronous readlink(2) - read value of a symbolic link.
@@ -1352,13 +1373,13 @@ declare module "fs" {
          * @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 __promisify__(path: PathLike, options: BufferEncodingOption): Promise<Buffer>;
+        function __promisify__(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 __promisify__(path: PathLike, options?: EncodingOption): Promise<string | Buffer>;
+        function __promisify__(path: PathLike, options?: EncodingOption): Promise<string | NonSharedBuffer>;
     }
     /**
      * Returns the symbolic link's string value.
@@ -1377,13 +1398,13 @@ declare module "fs" {
      * @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.
      */
-    export function readlinkSync(path: PathLike, options: BufferEncodingOption): Buffer;
+    export function readlinkSync(path: PathLike, options: BufferEncodingOption): NonSharedBuffer;
     /**
      * Synchronous 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.
      */
-    export function readlinkSync(path: PathLike, options?: EncodingOption): string | Buffer;
+    export function readlinkSync(path: PathLike, options?: EncodingOption): string | NonSharedBuffer;
     /**
      * Asynchronously computes the canonical pathname by resolving `.`, `..`, and
      * symbolic links.
@@ -1423,7 +1444,7 @@ declare module "fs" {
     export function realpath(
         path: PathLike,
         options: BufferEncodingOption,
-        callback: (err: NodeJS.ErrnoException | null, resolvedPath: Buffer) => void,
+        callback: (err: NodeJS.ErrnoException | null, resolvedPath: NonSharedBuffer) => void,
     ): void;
     /**
      * Asynchronous realpath(3) - return the canonicalized absolute pathname.
@@ -1433,7 +1454,7 @@ declare module "fs" {
     export function realpath(
         path: PathLike,
         options: EncodingOption,
-        callback: (err: NodeJS.ErrnoException | null, resolvedPath: string | Buffer) => void,
+        callback: (err: NodeJS.ErrnoException | null, resolvedPath: string | NonSharedBuffer) => void,
     ): void;
     /**
      * Asynchronous realpath(3) - return the canonicalized absolute pathname.
@@ -1455,13 +1476,13 @@ declare module "fs" {
          * @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 __promisify__(path: PathLike, options: BufferEncodingOption): Promise<Buffer>;
+        function __promisify__(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.
          * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
          */
-        function __promisify__(path: PathLike, options?: EncodingOption): Promise<string | Buffer>;
+        function __promisify__(path: PathLike, options?: EncodingOption): Promise<string | NonSharedBuffer>;
         /**
          * Asynchronous [`realpath(3)`](http://man7.org/linux/man-pages/man3/realpath.3.html).
          *
@@ -1487,12 +1508,12 @@ declare module "fs" {
         function native(
             path: PathLike,
             options: BufferEncodingOption,
-            callback: (err: NodeJS.ErrnoException | null, resolvedPath: Buffer) => void,
+            callback: (err: NodeJS.ErrnoException | null, resolvedPath: NonSharedBuffer) => void,
         ): void;
         function native(
             path: PathLike,
             options: EncodingOption,
-            callback: (err: NodeJS.ErrnoException | null, resolvedPath: string | Buffer) => void,
+            callback: (err: NodeJS.ErrnoException | null, resolvedPath: string | NonSharedBuffer) => void,
         ): void;
         function native(
             path: PathLike,
@@ -1512,17 +1533,17 @@ declare module "fs" {
      * @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.
      */
-    export function realpathSync(path: PathLike, options: BufferEncodingOption): Buffer;
+    export function realpathSync(path: PathLike, options: BufferEncodingOption): NonSharedBuffer;
     /**
      * Synchronous 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.
      */
-    export function realpathSync(path: PathLike, options?: EncodingOption): string | Buffer;
+    export function realpathSync(path: PathLike, options?: EncodingOption): string | NonSharedBuffer;
     export namespace realpathSync {
         function native(path: PathLike, options?: EncodingOption): string;
-        function native(path: PathLike, options: BufferEncodingOption): Buffer;
-        function native(path: PathLike, options?: EncodingOption): string | Buffer;
+        function native(path: PathLike, options: BufferEncodingOption): NonSharedBuffer;
+        function native(path: PathLike, options?: EncodingOption): string | NonSharedBuffer;
     }
     /**
      * Asynchronously removes a file or symbolic link. No arguments other than a
@@ -1892,12 +1913,8 @@ declare module "fs" {
      */
     export function mkdtemp(
         prefix: string,
-        options:
-            | "buffer"
-            | {
-                encoding: "buffer";
-            },
-        callback: (err: NodeJS.ErrnoException | null, folder: Buffer) => void,
+        options: BufferEncodingOption,
+        callback: (err: NodeJS.ErrnoException | null, folder: NonSharedBuffer) => void,
     ): void;
     /**
      * Asynchronously creates a unique temporary directory.
@@ -1907,7 +1924,7 @@ declare module "fs" {
     export function mkdtemp(
         prefix: string,
         options: EncodingOption,
-        callback: (err: NodeJS.ErrnoException | null, folder: string | Buffer) => void,
+        callback: (err: NodeJS.ErrnoException | null, folder: string | NonSharedBuffer) => void,
     ): void;
     /**
      * Asynchronously creates a unique temporary directory.
@@ -1929,13 +1946,13 @@ declare module "fs" {
          * 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 __promisify__(prefix: string, options: BufferEncodingOption): Promise<Buffer>;
+        function __promisify__(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 __promisify__(prefix: string, options?: EncodingOption): Promise<string | Buffer>;
+        function __promisify__(prefix: string, options?: EncodingOption): Promise<string | NonSharedBuffer>;
     }
     /**
      * Returns the created directory path.
@@ -1953,13 +1970,13 @@ declare module "fs" {
      * 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.
      */
-    export function mkdtempSync(prefix: string, options: BufferEncodingOption): Buffer;
+    export function mkdtempSync(prefix: string, options: BufferEncodingOption): NonSharedBuffer;
     /**
      * Synchronously 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.
      */
-    export function mkdtempSync(prefix: string, options?: EncodingOption): string | Buffer;
+    export function mkdtempSync(prefix: string, options?: EncodingOption): string | NonSharedBuffer;
     /**
      * Reads the contents of a directory. The callback gets two arguments `(err, files)` where `files` is an array of the names of the files in the directory excluding `'.'` and `'..'`.
      *
@@ -2000,7 +2017,7 @@ declare module "fs" {
                 recursive?: boolean | undefined;
             }
             | "buffer",
-        callback: (err: NodeJS.ErrnoException | null, files: Buffer[]) => void,
+        callback: (err: NodeJS.ErrnoException | null, files: NonSharedBuffer[]) => void,
     ): void;
     /**
      * Asynchronous readdir(3) - read a directory.
@@ -2017,7 +2034,7 @@ declare module "fs" {
             | BufferEncoding
             | undefined
             | null,
-        callback: (err: NodeJS.ErrnoException | null, files: string[] | Buffer[]) => void,
+        callback: (err: NodeJS.ErrnoException | null, files: string[] | NonSharedBuffer[]) => void,
     ): void;
     /**
      * Asynchronous readdir(3) - read a directory.
@@ -2052,7 +2069,7 @@ declare module "fs" {
             withFileTypes: true;
             recursive?: boolean | undefined;
         },
-        callback: (err: NodeJS.ErrnoException | null, files: Dirent<Buffer>[]) => void,
+        callback: (err: NodeJS.ErrnoException | null, files: Dirent<NonSharedBuffer>[]) => void,
     ): void;
     export namespace readdir {
         /**
@@ -2085,7 +2102,7 @@ declare module "fs" {
                     withFileTypes?: false | undefined;
                     recursive?: boolean | undefined;
                 },
-        ): 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.
@@ -2100,7 +2117,7 @@ declare module "fs" {
                 })
                 | 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.
@@ -2125,7 +2142,7 @@ declare module "fs" {
                 withFileTypes: true;
                 recursive?: boolean | undefined;
             },
-        ): Promise<Dirent<Buffer>[]>;
+        ): Promise<Dirent<NonSharedBuffer>[]>;
     }
     /**
      * Reads the contents of the directory.
@@ -2165,7 +2182,7 @@ declare module "fs" {
                 recursive?: boolean | undefined;
             }
             | "buffer",
-    ): Buffer[];
+    ): NonSharedBuffer[];
     /**
      * Synchronous readdir(3) - read a directory.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
@@ -2180,7 +2197,7 @@ declare module "fs" {
             })
             | BufferEncoding
             | null,
-    ): string[] | Buffer[];
+    ): string[] | NonSharedBuffer[];
     /**
      * Synchronous readdir(3) - read a directory.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
@@ -2205,7 +2222,7 @@ declare module "fs" {
             withFileTypes: true;
             recursive?: boolean | undefined;
         },
-    ): Dirent<Buffer>[];
+    ): Dirent<NonSharedBuffer>[];
     /**
      * Closes the file descriptor. No arguments other than a possible exception are
      * given to the completion callback.
@@ -2371,7 +2388,7 @@ declare module "fs" {
         /**
          * @default null
          */
-        position?: number | undefined | null;
+        position?: number | null | undefined;
     }
     /**
      * Write `buffer` to the file specified by `fd`.
@@ -2572,7 +2589,7 @@ declare module "fs" {
         encoding?: BufferEncoding | null,
     ): number;
     export type ReadPosition = number | bigint;
-    export interface ReadSyncOptions {
+    export interface ReadOptions {
         /**
          * @default 0
          */
@@ -2586,9 +2603,15 @@ declare module "fs" {
          */
         position?: ReadPosition | null | undefined;
     }
-    export interface ReadAsyncOptions<TBuffer extends NodeJS.ArrayBufferView> extends ReadSyncOptions {
-        buffer?: TBuffer;
+    export interface ReadOptionsWithBuffer<T extends NodeJS.ArrayBufferView> extends ReadOptions {
+        buffer?: T | undefined;
     }
+    /** @deprecated Use `ReadOptions` instead. */
+    // TODO: remove in future major
+    export interface ReadSyncOptions extends ReadOptions {}
+    /** @deprecated Use `ReadOptionsWithBuffer` instead. */
+    // TODO: remove in future major
+    export interface ReadAsyncOptions<T extends NodeJS.ArrayBufferView> extends ReadOptionsWithBuffer<T> {}
     /**
      * Read data from the file specified by `fd`.
      *
@@ -2623,15 +2646,15 @@ declare module "fs" {
      * `position` defaults to `null`
      * @since v12.17.0, 13.11.0
      */
-    export function read<TBuffer extends NodeJS.ArrayBufferView>(
+    export function read<TBuffer extends NodeJS.ArrayBufferView = NonSharedBuffer>(
         fd: number,
-        options: ReadAsyncOptions<TBuffer>,
+        options: ReadOptionsWithBuffer<TBuffer>,
         callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void,
     ): void;
     export function read<TBuffer extends NodeJS.ArrayBufferView>(
         fd: number,
         buffer: TBuffer,
-        options: ReadSyncOptions,
+        options: ReadOptions,
         callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void,
     ): void;
     export function read<TBuffer extends NodeJS.ArrayBufferView>(
@@ -2641,7 +2664,7 @@ declare module "fs" {
     ): void;
     export function read(
         fd: number,
-        callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: NodeJS.ArrayBufferView) => void,
+        callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: NonSharedBuffer) => void,
     ): void;
     export namespace read {
         /**
@@ -2661,16 +2684,16 @@ declare module "fs" {
             bytesRead: number;
             buffer: TBuffer;
         }>;
-        function __promisify__<TBuffer extends NodeJS.ArrayBufferView>(
+        function __promisify__<TBuffer extends NodeJS.ArrayBufferView = NonSharedBuffer>(
             fd: number,
-            options: ReadAsyncOptions<TBuffer>,
+            options: ReadOptionsWithBuffer<TBuffer>,
         ): Promise<{
             bytesRead: number;
             buffer: TBuffer;
         }>;
         function __promisify__(fd: number): Promise<{
             bytesRead: number;
-            buffer: NodeJS.ArrayBufferView;
+            buffer: NonSharedBuffer;
         }>;
     }
     /**
@@ -2692,7 +2715,7 @@ declare module "fs" {
      * Similar to the above `fs.readSync` function, this version takes an optional `options` object.
      * If no `options` object is specified, it will default with the above values.
      */
-    export function readSync(fd: number, buffer: NodeJS.ArrayBufferView, opts?: ReadSyncOptions): number;
+    export function readSync(fd: number, buffer: NodeJS.ArrayBufferView, opts?: ReadOptions): number;
     /**
      * Asynchronously reads the entire contents of a file.
      *
@@ -3327,6 +3350,12 @@ declare module "fs" {
         persistent?: boolean | undefined;
         recursive?: boolean | undefined;
     }
+    export interface WatchOptionsWithBufferEncoding extends WatchOptions {
+        encoding: "buffer";
+    }
+    export interface WatchOptionsWithStringEncoding extends WatchOptions {
+        encoding?: BufferEncoding | undefined;
+    }
     export type WatchEventType = "rename" | "change";
     export type WatchListener<T> = (event: WatchEventType, filename: T | null) => void;
     export type StatsListener = (curr: Stats, prev: Stats) => void;
@@ -3353,44 +3382,20 @@ declare module "fs" {
      */
     export function watch(
         filename: PathLike,
-        options:
-            | (WatchOptions & {
-                encoding: "buffer";
-            })
-            | "buffer",
-        listener?: WatchListener<Buffer>,
+        options?: WatchOptionsWithStringEncoding | BufferEncoding | null,
+        listener?: WatchListener<string>,
     ): FSWatcher;
-    /**
-     * 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.
-     */
     export function watch(
         filename: PathLike,
-        options?: WatchOptions | BufferEncoding | null,
-        listener?: WatchListener<string>,
+        options: WatchOptionsWithBufferEncoding | "buffer",
+        listener: WatchListener<NonSharedBuffer>,
     ): FSWatcher;
-    /**
-     * 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.
-     */
     export function watch(
         filename: PathLike,
-        options: WatchOptions | string,
-        listener?: WatchListener<string | Buffer>,
+        options: WatchOptions | BufferEncoding | "buffer" | null,
+        listener: WatchListener<string | NonSharedBuffer>,
     ): FSWatcher;
-    /**
-     * 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.
-     */
-    export function watch(filename: PathLike, listener?: WatchListener<string>): FSWatcher;
+    export function watch(filename: PathLike, listener: WatchListener<string>): FSWatcher;
     /**
      * Test whether or not the given path exists by checking with the file system.
      * Then call the `callback` argument with either true or false:
@@ -4099,27 +4104,29 @@ declare module "fs" {
      * @since v12.9.0
      * @param [position='null']
      */
-    export function writev(
+    export function writev<TBuffers extends readonly NodeJS.ArrayBufferView[]>(
         fd: number,
-        buffers: readonly NodeJS.ArrayBufferView[],
-        cb: (err: NodeJS.ErrnoException | null, bytesWritten: number, buffers: NodeJS.ArrayBufferView[]) => void,
+        buffers: TBuffers,
+        cb: (err: NodeJS.ErrnoException | null, bytesWritten: number, buffers: TBuffers) => void,
     ): void;
-    export function writev(
+    export function writev<TBuffers extends readonly NodeJS.ArrayBufferView[]>(
         fd: number,
-        buffers: readonly NodeJS.ArrayBufferView[],
+        buffers: TBuffers,
         position: number | null,
-        cb: (err: NodeJS.ErrnoException | null, bytesWritten: number, buffers: NodeJS.ArrayBufferView[]) => void,
+        cb: (err: NodeJS.ErrnoException | null, bytesWritten: number, buffers: TBuffers) => void,
     ): void;
-    export interface WriteVResult {
+    // Providing a default type parameter doesn't provide true BC for userland consumers, but at least suppresses TS2314
+    // TODO: remove default in future major version
+    export interface WriteVResult<T extends readonly NodeJS.ArrayBufferView[] = NodeJS.ArrayBufferView[]> {
         bytesWritten: number;
-        buffers: NodeJS.ArrayBufferView[];
+        buffers: T;
     }
     export namespace writev {
-        function __promisify__(
+        function __promisify__<TBuffers extends readonly NodeJS.ArrayBufferView[]>(
             fd: number,
-            buffers: readonly NodeJS.ArrayBufferView[],
+            buffers: TBuffers,
             position?: number,
-        ): Promise<WriteVResult>;
+        ): Promise<WriteVResult<TBuffers>>;
     }
     /**
      * For detailed information, see the documentation of the asynchronous version of
@@ -4144,27 +4151,29 @@ declare module "fs" {
      * @since v13.13.0, v12.17.0
      * @param [position='null']
      */
-    export function readv(
+    export function readv<TBuffers extends readonly NodeJS.ArrayBufferView[]>(
         fd: number,
-        buffers: readonly NodeJS.ArrayBufferView[],
-        cb: (err: NodeJS.ErrnoException | null, bytesRead: number, buffers: NodeJS.ArrayBufferView[]) => void,
+        buffers: TBuffers,
+        cb: (err: NodeJS.ErrnoException | null, bytesRead: number, buffers: TBuffers) => void,
     ): void;
-    export function readv(
+    export function readv<TBuffers extends readonly NodeJS.ArrayBufferView[]>(
         fd: number,
-        buffers: readonly NodeJS.ArrayBufferView[],
+        buffers: TBuffers,
         position: number | null,
-        cb: (err: NodeJS.ErrnoException | null, bytesRead: number, buffers: NodeJS.ArrayBufferView[]) => void,
+        cb: (err: NodeJS.ErrnoException | null, bytesRead: number, buffers: TBuffers) => void,
     ): void;
-    export interface ReadVResult {
+    // Providing a default type parameter doesn't provide true BC for userland consumers, but at least suppresses TS2314
+    // TODO: remove default in future major version
+    export interface ReadVResult<T extends readonly NodeJS.ArrayBufferView[] = NodeJS.ArrayBufferView[]> {
         bytesRead: number;
-        buffers: NodeJS.ArrayBufferView[];
+        buffers: T;
     }
     export namespace readv {
-        function __promisify__(
+        function __promisify__<TBuffers extends readonly NodeJS.ArrayBufferView[]>(
             fd: number,
-            buffers: readonly NodeJS.ArrayBufferView[],
+            buffers: TBuffers,
             position?: number,
-        ): Promise<ReadVResult>;
+        ): Promise<ReadVResult<TBuffers>>;
     }
     /**
      * For detailed information, see the documentation of the asynchronous version of
@@ -4200,7 +4209,6 @@ declare module "fs" {
      * blob.stream();
      * ```
      * @since v19.8.0
-     * @experimental
      */
     export function openAsBlob(path: PathLike, options?: OpenAsBlobOptions): Promise<Blob>;
 
@@ -4219,7 +4227,7 @@ declare module "fs" {
         /**
          * @default false
          */
-        recursive?: boolean;
+        recursive?: boolean | undefined;
     }
     /**
      * Synchronously open a directory. See [`opendir(3)`](http://man7.org/linux/man-pages/man3/opendir.3.html).
@@ -4272,54 +4280,54 @@ declare module "fs" {
          * Dereference symlinks
          * @default false
          */
-        dereference?: boolean;
+        dereference?: boolean | undefined;
         /**
          * When `force` is `false`, and the destination
          * exists, throw an error.
          * @default false
          */
-        errorOnExist?: boolean;
+        errorOnExist?: boolean | undefined;
         /**
          * Overwrite existing file or directory. _The copy
          * operation will ignore errors if you set this to false and the destination
          * exists. Use the `errorOnExist` option to change this behavior.
          * @default true
          */
-        force?: boolean;
+        force?: boolean | undefined;
         /**
          * Modifiers for copy operation. See `mode` flag of {@link copyFileSync()}
          */
-        mode?: number;
+        mode?: number | undefined;
         /**
          * When `true` timestamps from `src` will
          * be preserved.
          * @default false
          */
-        preserveTimestamps?: boolean;
+        preserveTimestamps?: boolean | undefined;
         /**
          * Copy directories recursively.
          * @default false
          */
-        recursive?: boolean;
+        recursive?: boolean | undefined;
         /**
          * When true, path resolution for symlinks will be skipped
          * @default false
          */
-        verbatimSymlinks?: boolean;
+        verbatimSymlinks?: boolean | undefined;
     }
     export interface CopyOptions extends CopyOptionsBase {
         /**
          * Function to filter copied files/directories. Return
          * `true` to copy the item, `false` to ignore it.
          */
-        filter?(source: string, destination: string): boolean | Promise<boolean>;
+        filter?: ((source: string, destination: string) => boolean | Promise<boolean>) | undefined;
     }
     export interface CopySyncOptions extends CopyOptionsBase {
         /**
          * Function to filter copied files/directories. Return
          * `true` to copy the item, `false` to ignore it.
          */
-        filter?(source: string, destination: string): boolean;
+        filter?: ((source: string, destination: string) => boolean) | undefined;
     }
     /**
      * Asynchronously copies the entire directory structure from `src` to `dest`,
@@ -4361,7 +4369,7 @@ declare module "fs" {
          * Current working directory.
          * @default process.cwd()
          */
-        cwd?: string | undefined;
+        cwd?: string | URL | undefined;
         /**
          * `true` if the glob should return paths as `Dirent`s, `false` otherwise.
          * @default false
@@ -4386,13 +4394,23 @@ declare module "fs" {
 
     /**
      * Retrieves the files matching the specified pattern.
+     *
+     * ```js
+     * import { glob } from 'node:fs';
+     *
+     * glob('*.js', (err, matches) => {
+     *   if (err) throw err;
+     *   console.log(matches);
+     * });
+     * ```
+     * @since v22.0.0
      */
     export function glob(
-        pattern: string | string[],
+        pattern: string | readonly string[],
         callback: (err: NodeJS.ErrnoException | null, matches: string[]) => void,
     ): void;
     export function glob(
-        pattern: string | string[],
+        pattern: string | readonly string[],
         options: GlobOptionsWithFileTypes,
         callback: (
             err: NodeJS.ErrnoException | null,
@@ -4400,7 +4418,7 @@ declare module "fs" {
         ) => void,
     ): void;
     export function glob(
-        pattern: string | string[],
+        pattern: string | readonly string[],
         options: GlobOptionsWithoutFileTypes,
         callback: (
             err: NodeJS.ErrnoException | null,
@@ -4408,7 +4426,7 @@ declare module "fs" {
         ) => void,
     ): void;
     export function glob(
-        pattern: string | string[],
+        pattern: string | readonly string[],
         options: GlobOptions,
         callback: (
             err: NodeJS.ErrnoException | null,
@@ -4416,19 +4434,25 @@ declare module "fs" {
         ) => void,
     ): void;
     /**
-     * Retrieves the files matching the specified pattern.
+     * ```js
+     * import { globSync } from 'node:fs';
+     *
+     * console.log(globSync('*.js'));
+     * ```
+     * @since v22.0.0
+     * @returns paths of files that match the pattern.
      */
-    export function globSync(pattern: string | string[]): string[];
+    export function globSync(pattern: string | readonly string[]): string[];
     export function globSync(
-        pattern: string | string[],
+        pattern: string | readonly string[],
         options: GlobOptionsWithFileTypes,
     ): Dirent[];
     export function globSync(
-        pattern: string | string[],
+        pattern: string | readonly string[],
         options: GlobOptionsWithoutFileTypes,
     ): string[];
     export function globSync(
-        pattern: string | string[],
+        pattern: string | readonly string[],
         options: GlobOptions,
     ): Dirent[] | string[];
 }