@types/node 24.13.5 → 24.19.0

{node v24.13 → node v24.19}/dgram.d.ts

@@ -42,6 +42,10 @@ declare module "dgram" {
         exclusive?: boolean | undefined;
         fd?: number | undefined;
     }
+    interface BindSyncOptions {
+        port?: number | undefined;
+        address?: string | undefined;
+    }
     type SocketType = "udp4" | "udp6";
     interface SocketOptions extends Abortable {
         type: SocketType;
@@ -137,10 +141,12 @@ declare module "dgram" {
          * messages on a named `port` and optional `address`. If `port` is not
          * specified or is `0`, the operating system will attempt to bind to a
          * random port. If `address` is not specified, the operating system will
-         * attempt to listen on all addresses. Once binding is complete, a `'listening'` event is emitted and the optional `callback` function is
+         * attempt to listen on all addresses. Once binding is complete, a
+         * `'listening'` event is emitted and the optional `callback` function is
          * called.
          *
-         * Specifying both a `'listening'` event listener and passing a `callback` to the `socket.bind()` method is not harmful but not very
+         * Specifying both a `'listening'` event listener and passing a
+         * `callback` to the `socket.bind()` method is not harmful but not very
          * useful.
          *
          * A bound datagram socket keeps the Node.js process running to receive
@@ -177,9 +183,82 @@ declare module "dgram" {
          * @param callback with no parameters. Called when binding is complete.
          */
         bind(port?: number, address?: string, callback?: () => void): this;
-        bind(port?: number, callback?: () => void): this;
-        bind(callback?: () => void): this;
+        bind(port: number, callback: () => void): this;
+        bind(callback: () => void): this;
+        /**
+         * For UDP sockets, causes the `dgram.Socket` to listen for datagram
+         * messages on a named `port` and optional `address` that are passed as
+         * properties of an `options` object passed as the first argument. If
+         * `port` is not specified or is `0`, the operating system will attempt
+         * to bind to a random port. If `address` is not specified, the operating
+         * system will attempt to listen on all addresses. Once binding is
+         * complete, a `'listening'` event is emitted and the optional `callback`
+         * function is called.
+         *
+         * The `options` object may contain a `fd` property. When a `fd` greater
+         * than `0` is set, it will wrap around an existing socket with the given
+         * file descriptor. In this case, the properties of `port` and `address`
+         * will be ignored.
+         *
+         * Specifying both a `'listening'` event listener and passing a
+         * `callback` to the `socket.bind()` method is not harmful but not very
+         * useful.
+         *
+         * The `options` object may contain an additional `exclusive` property that is
+         * used when using `dgram.Socket` objects with the [`cluster`](https://nodejs.org/docs/latest-v24.x/api/cluster.html) module. When
+         * `exclusive` is set to `false` (the default), cluster workers will use the same
+         * underlying socket handle allowing connection handling duties to be shared.
+         * When `exclusive` is `true`, however, the handle is not shared and attempted
+         * port sharing results in an error. Creating a `dgram.Socket` with the `reusePort`
+         * option set to `true` causes `exclusive` to always be `true` when `socket.bind()`
+         * is called.
+         *
+         * A bound datagram socket keeps the Node.js process running to receive
+         * datagram messages.
+         *
+         * If binding fails, an `'error'` event is generated. In rare case (e.g.
+         * attempting to bind with a closed socket), an `Error` may be thrown.
+         *
+         * An example socket listening on an exclusive port is shown below.
+         *
+         * ```js
+         * socket.bind({
+         *   address: 'localhost',
+         *   port: 8000,
+         *   exclusive: true,
+         * });
+         * ```
+         * @since v0.11.14
+         * @param options Required. Supports the following properties:
+         */
         bind(options: BindOptions, callback?: () => void): this;
+        /**
+         * The synchronous counterpart of `socket.bind()`. `bind(2)` is a local,
+         * non-blocking system call, so the bind is performed inline and the resolved
+         * address is returned immediately, including the operating-system-assigned
+         * ephemeral port when `port` is `0`:
+         *
+         * ```js
+         * const dgram = require('node:dgram');
+         *
+         * const socket = dgram.createSocket('udp4');
+         * const address = socket.bindSync({ address: '0.0.0.0', port: 0 });
+         * console.log(address); // e.g. { address: '0.0.0.0', family: 'IPv4', port: 53124 }
+         * ```
+         *
+         * A bind failure such as `EADDRINUSE` is thrown synchronously rather than emitted
+         * as an `'error'` event. After `bindSync()` returns, `socket.address()` is
+         * valid synchronously and the `'listening'` event is emitted on the next tick.
+         *
+         * `address` must be a numeric IP literal; `bindSync()` never performs DNS
+         * resolution (asynchronous name resolution being the only genuinely blocking part
+         * of binding). Incoming datagrams continue to be delivered asynchronously via the
+         * `'message'` event. `bindSync()` always binds the socket's own handle and
+         * does not participate in [`cluster`](https://nodejs.org/docs/latest-v24.x/api/cluster.html) handle sharing.
+         * @since v24.19.0
+         * @returns The bound address as returned by `socket.address()`.
+         */
+        bindSync(options?: BindSyncOptions): AddressInfo;
         /**
          * Close the underlying socket and stop listening for data on it. If a callback is
          * provided, it is added as a listener for the `'close'` event.
@@ -202,6 +281,42 @@ declare module "dgram" {
          */
         connect(port: number, address?: string, callback?: () => void): void;
         connect(port: number, callback: () => void): void;
+        /**
+         * The synchronous counterpart of `socket.connect()`. For a UDP socket
+         * `connect(2)` only records the default peer address and is a local, non-blocking
+         * system call, so the association is performed inline. Any error raised by the
+         * call itself (for example `EAFNOSUPPORT` for a mismatched address family) is
+         * thrown synchronously rather than reported via the `'error'` event. Because
+         * `connect(2)` does not probe reachability, errors such as `ECONNREFUSED` are
+         * still surfaced asynchronously on a later send or receive, exactly as for
+         * `socket.connect()`:
+         *
+         * ```js
+         * const dgram = require('node:dgram');
+         *
+         * const socket = dgram.createSocket('udp4');
+         * socket.connectSync(41234, '127.0.0.1');
+         * console.log(socket.remoteAddress()); // { address: '127.0.0.1', family: 'IPv4', port: 41234 }
+         * ```
+         *
+         * If the socket is still unbound it is bound synchronously first. After
+         * `connectSync()` returns, `socket.remoteAddress()` is valid synchronously
+         * and the `'connect'` event is emitted on the next tick. Trying to call
+         * `connectSync()` on an already connected socket throws an
+         * `ERR_SOCKET_DGRAM_IS_CONNECTED` exception, and calling it while an
+         * asynchronous `socket.bind()` is still in progress throws an
+         * `ERR_SOCKET_ALREADY_BOUND` exception.
+         *
+         * `address` must be a numeric IP literal; `connectSync()` never performs DNS
+         * resolution (asynchronous name resolution being the only genuinely blocking part
+         * of connecting).
+         * @since v24.19.0
+         * @param address A numeric IP address to connect to. Unlike
+         * `socket.connect()`, no DNS resolution is performed, so a host name is not
+         * accepted. If omitted, `'127.0.0.1'` (for `udp4` sockets) or `'::1'` (for
+         * `udp6` sockets) is used.
+         */
+        connectSync(port: number, address?: string): void;
         /**
          * A synchronous function that disassociates a connected `dgram.Socket` from
          * its remote address. Trying to call `disconnect()` on an unbound or already

{node v24.13 → node v24.19}/dns/promises.d.ts

@@ -189,7 +189,7 @@ declare module "dns/promises" {
      *     refresh: 900,
      *     retry: 900,
      *     expire: 1800,
-     *     minttl: 60 } ]
+     *     minttl: 60 } ];
      * ```
      * @since v10.6.0
      */
@@ -232,7 +232,7 @@ declare module "dns/promises" {
      *   regexp: '',
      *   replacement: '_sip._udp.example.com',
      *   order: 30,
-     *   preference: 100
+     *   preference: 100,
      * }
      * ```
      * @since v10.6.0
@@ -271,7 +271,7 @@ declare module "dns/promises" {
      *   refresh: 10000,
      *   retry: 2400,
      *   expire: 604800,
-     *   minttl: 3600
+     *   minttl: 3600,
      * }
      * ```
      * @since v10.6.0
@@ -291,7 +291,7 @@ declare module "dns/promises" {
      *   priority: 10,
      *   weight: 5,
      *   port: 21223,
-     *   name: 'service.example.com'
+     *   name: 'service.example.com',
      * }
      * ```
      * @since v10.6.0
@@ -312,7 +312,7 @@ declare module "dns/promises" {
      *   certUsage: 3,
      *   selector: 1,
      *   match: 1,
-     *   data: [ArrayBuffer]
+     *   data: [ArrayBuffer],
      * }
      * ```
      * @since v23.9.0, v22.15.0

{node v24.13 → node v24.19}/dns.d.ts

@@ -81,7 +81,7 @@ declare module "dns" {
          */
         all?: boolean | undefined;
         /**
-         * When `verbatim`, the resolved addresses are return unsorted. When `ipv4first`, the resolved addresses are sorted
+         * When `verbatim`, the resolved addresses are returned unsorted. When `ipv4first`, the resolved addresses are sorted
          * by placing IPv4 addresses before IPv6 addresses. When `ipv6first`, the resolved addresses are sorted by placing IPv6
          * addresses before IPv4 addresses. Default value is configurable using
          * {@link setDefaultResultOrder} or [`--dns-result-order`](https://nodejs.org/docs/latest-v24.x/api/cli.html#--dns-result-orderorder).
@@ -539,7 +539,7 @@ declare module "dns" {
      *   regexp: '',
      *   replacement: '_sip._udp.example.com',
      *   order: 30,
-     *   preference: 100
+     *   preference: 100,
      * }
      * ```
      * @since v0.9.12
@@ -596,7 +596,7 @@ declare module "dns" {
      *   refresh: 10000,
      *   retry: 2400,
      *   expire: 604800,
-     *   minttl: 3600
+     *   minttl: 3600,
      * }
      * ```
      * @since v0.11.10
@@ -622,7 +622,7 @@ declare module "dns" {
      *   priority: 10,
      *   weight: 5,
      *   port: 21223,
-     *   name: 'service.example.com'
+     *   name: 'service.example.com',
      * }
      * ```
      * @since v0.1.27
@@ -649,7 +649,7 @@ declare module "dns" {
      *   certUsage: 3,
      *   selector: 1,
      *   match: 1,
-     *   data: [ArrayBuffer]
+     *   data: [ArrayBuffer],
      * }
      * ```
      * @since v23.9.0, v22.15.0
@@ -699,7 +699,7 @@ declare module "dns" {
      *     refresh: 900,
      *     retry: 900,
      *     expire: 1800,
-     *     minttl: 60 } ]
+     *     minttl: 60 } ];
      * ```
      *
      * DNS server operators may choose not to respond to `ANY` queries. It may be better to call individual methods like {@link resolve4}, {@link resolveMx}, and so on. For more details, see

{node v24.13 → node v24.19}/events.d.ts

@@ -278,23 +278,17 @@ declare module "events" {
             options?: StaticEventEmitterIteratorOptions,
         ): NodeJS.AsyncIterator<any[]>;
         /**
-         * A class method that returns the number of listeners for the given `eventName` registered on the given `emitter`.
+         * Returns the number of registered listeners for the event named `eventName`.
          *
-         * ```js
-         * import { EventEmitter, listenerCount } from 'node:events';
+         * For `EventEmitter`s this behaves exactly the same as calling `.listenerCount`
+         * on the emitter.
          *
-         * const myEmitter = new EventEmitter();
-         * myEmitter.on('event', () => {});
-         * myEmitter.on('event', () => {});
-         * console.log(listenerCount(myEmitter, 'event'));
-         * // Prints: 2
-         * ```
+         * For `EventTarget`s this is the only way to obtain the listener count. This can
+         * be useful for debugging and diagnostic purposes.
          * @since v0.9.12
-         * @deprecated Since v3.2.0 - Use `listenerCount` instead.
-         * @param emitter The emitter to query
-         * @param eventName The event name
          */
-        static listenerCount(emitter: NodeJS.EventEmitter, eventName: string | symbol): number;
+        static listenerCount(emitter: EventEmitter, eventName: string | symbol): number;
+        static listenerCount(emitter: EventTarget, eventName: string): number;
         /**
          * Returns a copy of the array of listeners for the event named `eventName`.
          *
@@ -386,15 +380,12 @@ declare module "events" {
          * 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]();
-         *   }
+         *   signal.addEventListener('abort', (e) => e.stopImmediatePropagation());
+         *   // addAbortListener() returns a disposable, so the `using` keyword ensures
+         *   // the abort listener is automatically removed when this scope exits.
+         *   using _ = addAbortListener(signal, (e) => {
+         *     // Do something when signal is aborted.
+         *   });
          * }
          * ```
          * @since v20.5.0

{node v24.13 → node v24.19}/fs/promises.d.ts

@@ -9,9 +9,8 @@
  * @since v10.0.0
  */
 declare module "fs/promises" {
-    import { NonSharedBuffer } from "node:buffer";
+    import { BufferView, NonSharedBuffer } from "node:buffer";
     import { Abortable } from "node:events";
-    import { Stream } from "node:stream";
     import { ReadableStream } from "node:stream/web";
     import {
         BigIntStats,
@@ -31,6 +30,10 @@ declare module "fs/promises" {
         OpenDirOptions,
         OpenMode,
         PathLike,
+        ReadFileOptions,
+        ReadFileOptionsWithBuffer,
+        ReadFileOptionsWithBufferEncoding,
+        ReadFileOptionsWithStringEncoding,
         ReadOptions,
         ReadOptionsWithBuffer,
         ReadPosition,
@@ -281,39 +284,61 @@ declare module "fs/promises" {
          *
          * If `options` is a string, then it specifies the `encoding`.
          *
+         * If `buffer` is provided and no encoding is specified, the returned {Buffer} is
+         * a view over the supplied buffer containing only the bytes read. If the
+         * supplied buffer is too small to contain the entire file, the operation will
+         * fail.
+         *
          * 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.
+         *
+         * An example using the `buffer` option with a pre-allocated buffer:
+         *
+         * ```js
+         * import { Buffer } from 'node:buffer';
+         * import { open } from 'node:fs/promises';
+         *
+         * const file = await open('./some/file/to/read');
+         * try {
+         *   const buf = Buffer.alloc(16384);
+         *   const contents = await file.readFile({ buffer: buf });
+         *   console.log(contents); // A view over `buf` containing only the bytes read
+         * } finally {
+         *   await file.close();
+         * }
+         * ```
+         *
+         * An example using the `buffer` option with a function returning a buffer:
+         *
+         * ```js
+         * import { Buffer } from 'node:buffer';
+         * import { open } from 'node:fs/promises';
+         *
+         * const file = await open('./some/file/to/read');
+         * try {
+         *   const contents = await file.readFile({
+         *     buffer: (size) => Buffer.alloc(size),
+         *   });
+         *   console.log(contents);
+         * } finally {
+         *   await file.close();
+         * }
+         * ```
          * @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.
+         * @returns 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 } & 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.
-         */
-        readFile(
-            options:
-                | ({ 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.
-         */
-        readFile(
-            options?:
-                | (ObjectEncodingOptions & Abortable)
-                | BufferEncoding
-                | null,
-        ): Promise<string | NonSharedBuffer>;
+        readFile<T extends NodeJS.ArrayBufferView>(
+            options: Omit<ReadFileOptionsWithBuffer<T>, "flag">,
+        ): Promise<BufferView<T>>;
+        readFile(options?: Omit<ReadFileOptionsWithBufferEncoding, "flag"> | null): Promise<NonSharedBuffer>;
+        readFile(options: Omit<ReadFileOptionsWithStringEncoding, "flag"> | BufferEncoding): Promise<string>;
+        readFile(options: Omit<ReadFileOptions, "flag"> | BufferEncoding | null): Promise<string | NonSharedBuffer>;
         /**
          * Convenience method to create a `readline` interface and stream over the file.
          * See `filehandle.createReadStream()` for the options.
@@ -337,14 +362,28 @@ declare module "fs/promises" {
         stat(
             opts?: StatOptions & {
                 bigint?: false | undefined;
+                throwIfNoEntry?: true | undefined;
             },
         ): Promise<Stats>;
         stat(
             opts: StatOptions & {
                 bigint: true;
+                throwIfNoEntry?: true | undefined;
             },
         ): Promise<BigIntStats>;
-        stat(opts?: StatOptions): Promise<Stats | BigIntStats>;
+        stat(
+            opts?: StatOptions & {
+                bigint?: false | undefined;
+                throwIfNoEntry: false;
+            },
+        ): Promise<Stats | undefined>;
+        stat(
+            opts: StatOptions & {
+                bigint: true;
+                throwIfNoEntry: false;
+            },
+        ): Promise<BigIntStats | undefined>;
+        stat(opts?: StatOptions): Promise<Stats | BigIntStats | undefined>;
         /**
          * Truncates the file.
          *
@@ -1172,50 +1211,21 @@ declare module "fs/promises" {
      * @param path filename or `FileHandle`
      * @return Fulfills with the contents of the file.
      */
+    function readFile<T extends NodeJS.ArrayBufferView>(
+        path: PathLike | FileHandle,
+        options: ReadFileOptionsWithBuffer<T>,
+    ): Promise<BufferView<T>>;
     function readFile(
         path: PathLike | FileHandle,
-        options?:
-            | ({
-                encoding?: null | undefined;
-                flag?: OpenMode | undefined;
-            } & Abortable)
-            | null,
+        options?: ReadFileOptionsWithBufferEncoding | null,
     ): 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.
-     * 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: BufferEncoding;
-                flag?: OpenMode | undefined;
-            } & Abortable)
-            | BufferEncoding,
+        options: ReadFileOptionsWithStringEncoding | 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.
-     * 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?:
-            | (
-                & ObjectEncodingOptions
-                & Abortable
-                & {
-                    flag?: OpenMode | undefined;
-                }
-            )
-            | BufferEncoding
-            | null,
+        options: ReadFileOptions | BufferEncoding | null,
     ): 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.
@@ -1312,6 +1322,9 @@ declare module "fs/promises" {
      */
     function cp(source: string | URL, destination: string | URL, opts?: CopyOptions): Promise<void>;
     /**
+     * When `followSymlinks` is enabled, detected symbolic link cycles are not
+     * traversed recursively.
+     *
      * ```js
      * import { glob } from 'node:fs/promises';
      *