@types/node 18.17.18 → 18.18.0

{node v18.17 → node v18.18}/events.d.ts

@@ -34,7 +34,7 @@
  * ```
  * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/events.js)
  */
-declare module 'events' {
+declare module "events" {
     // NOTE: This class is in the docs but is **not actually exported** by Node.
     // If https://github.com/nodejs/node/issues/39903 gets resolved and Node
     // actually starts exporting the class, uncomment below.
@@ -87,7 +87,7 @@ declare module 'events' {
             listener: (...args: any[]) => void,
             opts?: {
                 once: boolean;
-            }
+            },
         ): any;
     }
     interface StaticEventEmitterOptions {
@@ -191,7 +191,11 @@ declare module 'events' {
          * ```
          * @since v11.13.0, v10.16.0
          */
-        static once(emitter: _NodeEventTarget, eventName: string | symbol, options?: StaticEventEmitterOptions): Promise<any[]>;
+        static once(
+            emitter: _NodeEventTarget,
+            eventName: string | symbol,
+            options?: StaticEventEmitterOptions,
+        ): Promise<any[]>;
         static once(emitter: _DOMEventTarget, eventName: string, options?: StaticEventEmitterOptions): Promise<any[]>;
         /**
          * ```js
@@ -251,7 +255,11 @@ declare module 'events' {
          * @param eventName The name of the event being listened for
          * @return that iterates `eventName` events emitted by the `emitter`
          */
-        static on(emitter: NodeJS.EventEmitter, eventName: string, options?: StaticEventEmitterOptions): AsyncIterableIterator<any>;
+        static on(
+            emitter: NodeJS.EventEmitter,
+            eventName: string,
+            options?: StaticEventEmitterOptions,
+        ): AsyncIterableIterator<any>;
         /**
          * A class method that returns the number of listeners for the given `eventName`registered on the given `emitter`.
          *
@@ -344,6 +352,41 @@ declare module 'events' {
          * objects.
          */
         static setMaxListeners(n?: number, ...eventTargets: Array<_DOMEventTarget | NodeJS.EventEmitter>): void;
+        /**
+         * Listens once to the `abort` event on the provided `signal`.
+         *
+         * Listening to the `abort` event on abort signals is unsafe and may
+         * lead to resource leaks since another third party with the signal can
+         * call `e.stopImmediatePropagation()`. Unfortunately Node.js cannot change
+         * this since it would violate the web standard. Additionally, the original
+         * API makes it easy to forget to remove listeners.
+         *
+         * This API allows safely using `AbortSignal`s in Node.js APIs by solving these
+         * two issues by listening to the event such that `stopImmediatePropagation` does
+         * not prevent the listener from running.
+         *
+         * Returns a disposable so that it may be unsubscribed from more easily.
+         *
+         * ```js
+         * import { addAbortListener } from 'node:events';
+         *
+         * function example(signal) {
+         *   let disposable;
+         *   try {
+         *     signal.addEventListener('abort', (e) => e.stopImmediatePropagation());
+         *     disposable = addAbortListener(signal, (e) => {
+         *       // Do something when signal is aborted.
+         *     });
+         *   } finally {
+         *     disposable?.[Symbol.dispose]();
+         *   }
+         * }
+         * ```
+         * @since v18.18.0
+         * @experimental
+         * @return Disposable that removes the `abort` listener.
+         */
+        static addAbortListener(signal: AbortSignal, resource: (event: Event) => void): Disposable;
         /**
          * This symbol shall be used to install a listener for only monitoring `'error'`
          * events. Listeners installed using this symbol are called before the regular
@@ -362,7 +405,7 @@ declare module 'events' {
         static captureRejections: boolean;
         static defaultMaxListeners: number;
     }
-    import internal = require('node:events');
+    import internal = require("node:events");
     namespace EventEmitter {
         // Should just be `export { EventEmitter }`, but that doesn't work in TypeScript 3.4
         export { internal as EventEmitter };
@@ -705,7 +748,7 @@ declare module 'events' {
     }
     export = EventEmitter;
 }
-declare module 'node:events' {
-    import events = require('events');
+declare module "node:events" {
+    import events = require("events");
     export = events;
 }

{node v18.17 → node v18.18}/fs/promises.d.ts

@@ -8,10 +8,10 @@
  * 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';
-    import { ReadableStream } from 'node:stream/web';
+declare module "fs/promises" {
+    import { Abortable } from "node:events";
+    import { Stream } from "node:stream";
+    import { ReadableStream } from "node:stream/web";
     import {
         BigIntStats,
         BigIntStatsFs,
@@ -30,8 +30,8 @@ declare module 'fs/promises' {
         ReadVResult,
         RmDirOptions,
         RmOptions,
-        StatOptions,
         StatFsOptions,
+        StatOptions,
         Stats,
         StatsFs,
         TimeLike,
@@ -39,8 +39,8 @@ declare module 'fs/promises' {
         WatchOptions,
         WriteStream,
         WriteVResult,
-    } from 'node:fs';
-    import { Interface as ReadlineInterface } from 'node:readline';
+    } from "node:fs";
+    import { Interface as ReadlineInterface } from "node:readline";
 
     interface FileChangeInfo<T extends string | Buffer> {
         eventType: WatchEventType;
@@ -89,7 +89,7 @@ declare module 'fs/promises' {
          * Whether to open a normal or a `'bytes'` stream.
          * @since v18.17.0
          */
-        type?: 'bytes' | undefined;
+        type?: "bytes" | undefined;
     }
     // TODO: Add `EventEmitter` close
     interface FileHandle {
@@ -106,7 +106,10 @@ declare module 'fs/promises' {
          * @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>;
         /**
          * 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
@@ -223,7 +226,12 @@ declare module 'fs/promises' {
          * integer, the current file position will remain unchanged.
          * @return Fulfills upon success with an object with two properties:
          */
-        read<T extends NodeJS.ArrayBufferView>(buffer: T, offset?: number | null, length?: number | null, position?: number | null): Promise<FileReadResult<T>>;
+        read<T extends NodeJS.ArrayBufferView>(
+            buffer: T,
+            offset?: number | null,
+            length?: number | null,
+            position?: number | null,
+        ): 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.
@@ -266,7 +274,7 @@ declare module 'fs/promises' {
             options?: {
                 encoding?: null | undefined;
                 flag?: OpenMode | undefined;
-            } | null
+            } | null,
         ): Promise<Buffer>;
         /**
          * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically.
@@ -277,10 +285,10 @@ declare module 'fs/promises' {
         readFile(
             options:
                 | {
-                      encoding: BufferEncoding;
-                      flag?: OpenMode | undefined;
-                  }
-                | BufferEncoding
+                    encoding: BufferEncoding;
+                    flag?: OpenMode | undefined;
+                }
+                | BufferEncoding,
         ): Promise<string>;
         /**
          * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically.
@@ -291,10 +299,10 @@ declare module 'fs/promises' {
         readFile(
             options?:
                 | (ObjectEncodingOptions & {
-                      flag?: OpenMode | undefined;
-                  })
+                    flag?: OpenMode | undefined;
+                })
                 | BufferEncoding
-                | null
+                | null,
         ): Promise<string | Buffer>;
         /**
          * Convenience method to create a `readline` interface and stream over the file. For example:
@@ -320,12 +328,12 @@ declare module 'fs/promises' {
         stat(
             opts?: StatOptions & {
                 bigint?: false | undefined;
-            }
+            },
         ): Promise<Stats>;
         stat(
             opts: StatOptions & {
                 bigint: true;
-            }
+            },
         ): Promise<BigIntStats>;
         stat(opts?: StatOptions): Promise<Stats | BigIntStats>;
         /**
@@ -380,7 +388,10 @@ declare module 'fs/promises' {
          * 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>;
         /**
          * Write `buffer` to the file.
          *
@@ -403,7 +414,7 @@ declare module 'fs/promises' {
             buffer: TBuffer,
             offset?: number | null,
             length?: number | null,
-            position?: number | null
+            position?: number | null,
         ): Promise<{
             bytesWritten: number;
             buffer: TBuffer;
@@ -411,7 +422,7 @@ declare module 'fs/promises' {
         write(
             data: string,
             position?: number | null,
-            encoding?: BufferEncoding | null
+            encoding?: BufferEncoding | null,
         ): Promise<{
             bytesWritten: number;
             buffer: string;
@@ -457,6 +468,11 @@ declare module 'fs/promises' {
          * @return Fulfills with `undefined` upon success.
          */
         close(): Promise<void>;
+        /**
+         * An alias for {@link FileHandle.close()}.
+         * @since v18.18.0
+         */
+        [Symbol.asyncDispose](): Promise<void>;
     }
 
     const constants: typeof fsConstants;
@@ -588,7 +604,7 @@ declare module 'fs/promises' {
         path: PathLike,
         options: MakeDirectoryOptions & {
             recursive: true;
-        }
+        },
     ): Promise<string | undefined>;
     /**
      * Asynchronous mkdir(2) - create a directory.
@@ -601,9 +617,9 @@ declare module 'fs/promises' {
         options?:
             | Mode
             | (MakeDirectoryOptions & {
-                  recursive?: false | undefined;
-              })
-            | null
+                recursive?: false | undefined;
+            })
+            | null,
     ): Promise<void>;
     /**
      * Asynchronous mkdir(2) - create a directory.
@@ -640,11 +656,11 @@ declare module 'fs/promises' {
         path: PathLike,
         options?:
             | (ObjectEncodingOptions & {
-                  withFileTypes?: false | undefined;
-                  recursive?: boolean | undefined;
-              })
+                withFileTypes?: false | undefined;
+                recursive?: boolean | undefined;
+            })
             | BufferEncoding
-            | null
+            | null,
     ): Promise<string[]>;
     /**
      * Asynchronous readdir(3) - read a directory.
@@ -655,11 +671,11 @@ declare module 'fs/promises' {
         path: PathLike,
         options:
             | {
-                  encoding: 'buffer';
-                  withFileTypes?: false | undefined;
-                  recursive?: boolean | undefined;
-              }
-            | 'buffer'
+                encoding: "buffer";
+                withFileTypes?: false | undefined;
+                recursive?: boolean | undefined;
+            }
+            | "buffer",
     ): Promise<Buffer[]>;
     /**
      * Asynchronous readdir(3) - read a directory.
@@ -670,11 +686,11 @@ declare module 'fs/promises' {
         path: PathLike,
         options?:
             | (ObjectEncodingOptions & {
-                  withFileTypes?: false | undefined;
-                  recursive?: boolean | undefined;
-              })
+                withFileTypes?: false | undefined;
+                recursive?: boolean | undefined;
+            })
             | BufferEncoding
-            | null
+            | null,
     ): Promise<string[] | Buffer[]>;
     /**
      * Asynchronous readdir(3) - read a directory.
@@ -686,7 +702,7 @@ declare module 'fs/promises' {
         options: ObjectEncodingOptions & {
             withFileTypes: true;
             recursive?: boolean | undefined;
-        }
+        },
     ): 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
@@ -734,13 +750,13 @@ declare module 'fs/promises' {
         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>;
     /**
@@ -751,13 +767,13 @@ declare module 'fs/promises' {
         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>;
     /**
@@ -768,13 +784,13 @@ declare module 'fs/promises' {
         path: PathLike,
         opts?: StatFsOptions & {
             bigint?: false | undefined;
-        }
+        },
     ): Promise<StatsFs>;
     function statfs(
         path: PathLike,
         opts: StatFsOptions & {
             bigint: true;
-        }
+        },
     ): Promise<BigIntStatsFs>;
     function statfs(path: PathLike, opts?: StatFsOptions): Promise<StatsFs | BigIntStatsFs>;
 
@@ -866,7 +882,10 @@ 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?: ObjectEncodingOptions | BufferEncoding | null): Promise<string | Buffer>;
+    function realpath(
+        path: PathLike,
+        options?: ObjectEncodingOptions | BufferEncoding | null,
+    ): Promise<string | Buffer>;
     /**
      * 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
@@ -959,14 +978,19 @@ declare module 'fs/promises' {
      */
     function writeFile(
         file: PathLike | FileHandle,
-        data: string | NodeJS.ArrayBufferView | Iterable<string | NodeJS.ArrayBufferView> | AsyncIterable<string | NodeJS.ArrayBufferView> | Stream,
+        data:
+            | string
+            | NodeJS.ArrayBufferView
+            | Iterable<string | NodeJS.ArrayBufferView>
+            | AsyncIterable<string | NodeJS.ArrayBufferView>
+            | Stream,
         options?:
             | (ObjectEncodingOptions & {
-                  mode?: Mode | undefined;
-                  flag?: OpenMode | undefined;
-              } & Abortable)
+                mode?: Mode | undefined;
+                flag?: OpenMode | undefined;
+            } & Abortable)
             | BufferEncoding
-            | null
+            | null,
     ): Promise<void>;
     /**
      * Asynchronously append data to a file, creating the file if it does not yet
@@ -982,7 +1006,11 @@ declare module 'fs/promises' {
      * @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.
      *
@@ -1029,10 +1057,10 @@ declare module 'fs/promises' {
         path: PathLike | FileHandle,
         options?:
             | ({
-                  encoding?: null | undefined;
-                  flag?: OpenMode | undefined;
-              } & Abortable)
-            | null
+                encoding?: null | undefined;
+                flag?: OpenMode | undefined;
+            } & Abortable)
+            | null,
     ): Promise<Buffer>;
     /**
      * Asynchronously reads the entire contents of a file.
@@ -1045,10 +1073,10 @@ declare module 'fs/promises' {
         path: PathLike | FileHandle,
         options:
             | ({
-                  encoding: BufferEncoding;
-                  flag?: OpenMode | undefined;
-              } & Abortable)
-            | BufferEncoding
+                encoding: BufferEncoding;
+                flag?: OpenMode | undefined;
+            } & Abortable)
+            | BufferEncoding,
     ): Promise<string>;
     /**
      * Asynchronously reads the entire contents of a file.
@@ -1060,12 +1088,15 @@ declare module 'fs/promises' {
     function readFile(
         path: PathLike | FileHandle,
         options?:
-            | (ObjectEncodingOptions &
-                  Abortable & {
-                      flag?: OpenMode | undefined;
-                  })
+            | (
+                & ObjectEncodingOptions
+                & Abortable
+                & {
+                    flag?: OpenMode | undefined;
+                }
+            )
             | BufferEncoding
-            | null
+            | 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.
@@ -1130,9 +1161,9 @@ declare module 'fs/promises' {
         filename: PathLike,
         options:
             | (WatchOptions & {
-                  encoding: 'buffer';
-              })
-            | 'buffer'
+                encoding: "buffer";
+            })
+            | "buffer",
     ): AsyncIterable<FileChangeInfo<Buffer>>;
     /**
      * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`.
@@ -1151,7 +1182,10 @@ 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 | string): AsyncIterable<FileChangeInfo<string>> | AsyncIterable<FileChangeInfo<Buffer>>;
+    function watch(
+        filename: PathLike,
+        options: WatchOptions | string,
+    ): AsyncIterable<FileChangeInfo<string>> | AsyncIterable<FileChangeInfo<Buffer>>;
     /**
      * Asynchronously copies the entire directory structure from `src` to `dest`,
      * including subdirectories and files.
@@ -1166,6 +1200,6 @@ declare module 'fs/promises' {
      */
     function cp(source: string | URL, destination: string | URL, opts?: CopyOptions): Promise<void>;
 }
-declare module 'node:fs/promises' {
-    export * from 'fs/promises';
+declare module "node:fs/promises" {
+    export * from "fs/promises";
 }