@types/node 18.11.5 → 20.2.5

node/dgram.d.ts

@@ -1,13 +1,13 @@
 /**
- * The `dgram` module provides an implementation of UDP datagram sockets.
+ * The `node:dgram` module provides an implementation of UDP datagram sockets.
  *
  * ```js
- * import dgram from 'dgram';
+ * import dgram from 'node:dgram';
  *
  * const server = dgram.createSocket('udp4');
  *
  * server.on('error', (err) => {
- *   console.log(`server error:\n${err.stack}`);
+ *   console.error(`server error:\n${err.stack}`);
  *   server.close();
  * });
  *
@@ -23,7 +23,7 @@
  * server.bind(41234);
  * // Prints: server listening 0.0.0.0:41234
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/dgram.js)
+ * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/dgram.js)
  */
 declare module 'dgram' {
     import { AddressInfo } from 'node:net';
@@ -98,8 +98,8 @@ declare module 'dgram' {
          * When sharing a UDP socket across multiple `cluster` workers, the`socket.addMembership()` function must be called only once or an`EADDRINUSE` error will occur:
          *
          * ```js
-         * import cluster from 'cluster';
-         * import dgram from 'dgram';
+         * import cluster from 'node:cluster';
+         * import dgram from 'node:dgram';
          *
          * if (cluster.isPrimary) {
          *   cluster.fork(); // Works ok.
@@ -116,7 +116,7 @@ declare module 'dgram' {
         addMembership(multicastAddress: string, multicastInterface?: string): void;
         /**
          * Returns an object containing the address information for a socket.
-         * For UDP sockets, this object will contain `address`, `family` and `port`properties.
+         * For UDP sockets, this object will contain `address`, `family`, and `port`properties.
          *
          * This method throws `EBADF` if called on an unbound socket.
          * @since v0.1.99
@@ -142,12 +142,12 @@ declare module 'dgram' {
          * Example of a UDP server listening on port 41234:
          *
          * ```js
-         * import dgram from 'dgram';
+         * import dgram from 'node:dgram';
          *
          * const server = dgram.createSocket('udp4');
          *
          * server.on('error', (err) => {
-         *   console.log(`server error:\n${err.stack}`);
+         *   console.error(`server error:\n${err.stack}`);
          *   server.close();
          * });
          *
@@ -284,8 +284,8 @@ declare module 'dgram' {
          * Example of sending a UDP packet to a port on `localhost`;
          *
          * ```js
-         * import dgram from 'dgram';
-         * import { Buffer } from 'buffer';
+         * import dgram from 'node:dgram';
+         * import { Buffer } from 'node:buffer';
          *
          * const message = Buffer.from('Some bytes');
          * const client = dgram.createSocket('udp4');
@@ -297,8 +297,8 @@ declare module 'dgram' {
          * Example of sending a UDP packet composed of multiple buffers to a port on`127.0.0.1`;
          *
          * ```js
-         * import dgram from 'dgram';
-         * import { Buffer } from 'buffer';
+         * import dgram from 'node:dgram';
+         * import { Buffer } from 'node:buffer';
          *
          * const buf1 = Buffer.from('Some ');
          * const buf2 = Buffer.from('bytes');
@@ -316,8 +316,8 @@ declare module 'dgram' {
          * Example of sending a UDP packet using a socket connected to a port on`localhost`:
          *
          * ```js
-         * import dgram from 'dgram';
-         * import { Buffer } from 'buffer';
+         * import dgram from 'node:dgram';
+         * import { Buffer } from 'node:buffer';
          *
          * const message = Buffer.from('Some bytes');
          * const client = dgram.createSocket('udp4');

node/diagnostics_channel.d.ts

@@ -1,11 +1,11 @@
 /**
- * The `diagnostics_channel` module provides an API to create named channels
+ * The `node:diagnostics_channel` module provides an API to create named channels
  * to report arbitrary message data for diagnostics purposes.
  *
  * It can be accessed using:
  *
  * ```js
- * import diagnostics_channel from 'diagnostics_channel';
+ * import diagnostics_channel from 'node:diagnostics_channel';
  * ```
  *
  * It is intended that a module writer wanting to report diagnostics messages
@@ -19,8 +19,8 @@
  * channels are used along with the shape of the message data. Channel names
  * should generally include the module name to avoid collisions with data from
  * other modules.
- * @experimental
- * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/diagnostics_channel.js)
+ * @since v15.1.0, v14.17.0
+ * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/diagnostics_channel.js)
  */
 declare module 'diagnostics_channel' {
     /**
@@ -31,7 +31,7 @@ declare module 'diagnostics_channel' {
      * performance-sensitive code.
      *
      * ```js
-     * import diagnostics_channel from 'diagnostics_channel';
+     * import diagnostics_channel from 'node:diagnostics_channel';
      *
      * if (diagnostics_channel.hasSubscribers('my-channel')) {
      *   // There are subscribers, prepare and publish message
@@ -41,14 +41,14 @@ declare module 'diagnostics_channel' {
      * @param name The channel name
      * @return If there are active subscribers
      */
-    function hasSubscribers(name: string): boolean;
+    function hasSubscribers(name: string | symbol): boolean;
     /**
-     * This is the primary entry-point for anyone wanting to interact with a named
+     * This is the primary entry-point for anyone wanting to publish to a named
      * channel. It produces a channel object which is optimized to reduce overhead at
      * publish time as much as possible.
      *
      * ```js
-     * import diagnostics_channel from 'diagnostics_channel';
+     * import diagnostics_channel from 'node:diagnostics_channel';
      *
      * const channel = diagnostics_channel.channel('my-channel');
      * ```
@@ -56,11 +56,48 @@ declare module 'diagnostics_channel' {
      * @param name The channel name
      * @return The named channel object
      */
-    function channel(name: string): Channel;
-    type ChannelListener = (message: unknown, name: string) => void;
+    function channel(name: string | symbol): Channel;
+    type ChannelListener = (message: unknown, name: string | symbol) => void;
+    /**
+     * Register a message handler to subscribe to this channel. This message handler
+     * will be run synchronously whenever a message is published to the channel. Any
+     * errors thrown in the message handler will trigger an `'uncaughtException'`.
+     *
+     * ```js
+     * import diagnostics_channel from 'node:diagnostics_channel';
+     *
+     * diagnostics_channel.subscribe('my-channel', (message, name) => {
+     *   // Received data
+     * });
+     * ```
+     * @since v18.7.0, v16.17.0
+     * @param name The channel name
+     * @param onMessage The handler to receive channel messages
+     */
+    function subscribe(name: string | symbol, onMessage: ChannelListener): void;
+    /**
+     * Remove a message handler previously registered to this channel with {@link subscribe}.
+     *
+     * ```js
+     * import diagnostics_channel from 'node:diagnostics_channel';
+     *
+     * function onMessage(message, name) {
+     *   // Received data
+     * }
+     *
+     * diagnostics_channel.subscribe('my-channel', onMessage);
+     *
+     * diagnostics_channel.unsubscribe('my-channel', onMessage);
+     * ```
+     * @since v18.7.0, v16.17.0
+     * @param name The channel name
+     * @param onMessage The previous subscribed handler to remove
+     * @return `true` if the handler was found, `false` otherwise.
+     */
+    function unsubscribe(name: string | symbol, onMessage: ChannelListener): boolean;
     /**
      * The class `Channel` represents an individual named channel within the data
-     * pipeline. It is use to track subscribers and to publish messages when there
+     * pipeline. It is used to track subscribers and to publish messages when there
      * are subscribers present. It exists as a separate object to avoid channel
      * lookups at publish time, enabling very fast publish speeds and allowing
      * for heavy use while incurring very minimal cost. Channels are created with {@link channel}, constructing a channel directly
@@ -68,7 +105,7 @@ declare module 'diagnostics_channel' {
      * @since v15.1.0, v14.17.0
      */
     class Channel {
-        readonly name: string;
+        readonly name: string | symbol;
         /**
          * Check if there are active subscribers to this channel. This is helpful if
          * the message you want to send might be expensive to prepare.
@@ -77,7 +114,7 @@ declare module 'diagnostics_channel' {
          * performance-sensitive code.
          *
          * ```js
-         * import diagnostics_channel from 'diagnostics_channel';
+         * import diagnostics_channel from 'node:diagnostics_channel';
          *
          * const channel = diagnostics_channel.channel('my-channel');
          *
@@ -88,19 +125,18 @@ declare module 'diagnostics_channel' {
          * @since v15.1.0, v14.17.0
          */
         readonly hasSubscribers: boolean;
-        private constructor(name: string);
+        private constructor(name: string | symbol);
         /**
-         * Publish a message to any subscribers to the channel. This will
-         * trigger message handlers synchronously so they will execute within
-         * the same context.
+         * Publish a message to any subscribers to the channel. This will trigger
+         * message handlers synchronously so they will execute within the same context.
          *
          * ```js
-         * import diagnostics_channel from 'diagnostics_channel';
+         * import diagnostics_channel from 'node:diagnostics_channel';
          *
          * const channel = diagnostics_channel.channel('my-channel');
          *
          * channel.publish({
-         *   some: 'message'
+         *   some: 'message',
          * });
          * ```
          * @since v15.1.0, v14.17.0
@@ -113,7 +149,7 @@ declare module 'diagnostics_channel' {
          * errors thrown in the message handler will trigger an `'uncaughtException'`.
          *
          * ```js
-         * import diagnostics_channel from 'diagnostics_channel';
+         * import diagnostics_channel from 'node:diagnostics_channel';
          *
          * const channel = diagnostics_channel.channel('my-channel');
          *
@@ -122,6 +158,7 @@ declare module 'diagnostics_channel' {
          * });
          * ```
          * @since v15.1.0, v14.17.0
+         * @deprecated Since v18.7.0,v16.17.0 - Use {@link subscribe(name, onMessage)}
          * @param onMessage The handler to receive channel messages
          */
         subscribe(onMessage: ChannelListener): void;
@@ -129,7 +166,7 @@ declare module 'diagnostics_channel' {
          * Remove a message handler previously registered to this channel with `channel.subscribe(onMessage)`.
          *
          * ```js
-         * import diagnostics_channel from 'diagnostics_channel';
+         * import diagnostics_channel from 'node:diagnostics_channel';
          *
          * const channel = diagnostics_channel.channel('my-channel');
          *
@@ -142,6 +179,7 @@ declare module 'diagnostics_channel' {
          * channel.unsubscribe(onMessage);
          * ```
          * @since v15.1.0, v14.17.0
+         * @deprecated Since v18.7.0,v16.17.0 - Use {@link unsubscribe(name, onMessage)}
          * @param onMessage The previous subscribed handler to remove
          * @return `true` if the handler was found, `false` otherwise.
          */

node/dns/promises.d.ts

@@ -1,7 +1,7 @@
 /**
  * The `dns.promises` API provides an alternative set of asynchronous DNS methods
  * that return `Promise` objects rather than using callbacks. The API is accessible
- * via `require('dns').promises` or `require('dns/promises')`.
+ * via `require('node:dns').promises` or `require('node:dns/promises')`.
  * @since v10.6.0
  */
 declare module 'dns/promises' {
@@ -52,7 +52,7 @@ declare module 'dns/promises' {
      *
      * `dnsPromises.lookup()` does not necessarily have anything to do with the DNS
      * protocol. The implementation uses an operating system facility that can
-     * associate names with addresses, and vice versa. This implementation can have
+     * associate names with addresses and vice versa. This implementation can have
      * subtle but important consequences on the behavior of any Node.js program. Please
      * take some time to consult the `Implementation considerations section` before
      * using `dnsPromises.lookup()`.
@@ -60,7 +60,7 @@ declare module 'dns/promises' {
      * Example usage:
      *
      * ```js
-     * const dns = require('dns');
+     * const dns = require('node:dns');
      * const dnsPromises = dns.promises;
      * const options = {
      *   family: 6,
@@ -96,7 +96,7 @@ declare module 'dns/promises' {
      * On error, the `Promise` is rejected with an `Error` object, where `err.code`is the error code.
      *
      * ```js
-     * const dnsPromises = require('dns').promises;
+     * const dnsPromises = require('node:dns').promises;
      * dnsPromises.lookupService('127.0.0.1', 22).then((result) => {
      *   console.log(result.hostname, result.service);
      *   // Prints: localhost ssh
@@ -206,7 +206,7 @@ declare module 'dns/promises' {
      */
     function resolveMx(hostname: string): Promise<MxRecord[]>;
     /**
-     * Uses the DNS protocol to resolve regular expression based records (`NAPTR`records) for the `hostname`. On success, the `Promise` is resolved with an array
+     * Uses the DNS protocol to resolve regular expression-based records (`NAPTR`records) for the `hostname`. On success, the `Promise` is resolved with an array
      * of objects with the following properties:
      *
      * * `flags`
@@ -337,13 +337,56 @@ declare module 'dns/promises' {
      * * `ipv4first`: sets default `verbatim` `false`.
      * * `verbatim`: sets default `verbatim` `true`.
      *
-     * The default is `ipv4first` and `dnsPromises.setDefaultResultOrder()` have
+     * The default is `verbatim` and `dnsPromises.setDefaultResultOrder()` have
      * higher priority than `--dns-result-order`. When using `worker threads`,`dnsPromises.setDefaultResultOrder()` from the main thread won't affect the
      * default dns orders in workers.
      * @since v16.4.0, v14.18.0
      * @param order must be `'ipv4first'` or `'verbatim'`.
      */
     function setDefaultResultOrder(order: 'ipv4first' | 'verbatim'): void;
+    /**
+     * An independent resolver for DNS requests.
+     *
+     * Creating a new resolver uses the default server settings. Setting
+     * the servers used for a resolver using `resolver.setServers()` does not affect
+     * other resolvers:
+     *
+     * ```js
+     * const { Resolver } = require('node:dns').promises;
+     * const resolver = new Resolver();
+     * resolver.setServers(['4.4.4.4']);
+     *
+     * // This request will use the server at 4.4.4.4, independent of global settings.
+     * resolver.resolve4('example.org').then((addresses) => {
+     *   // ...
+     * });
+     *
+     * // Alternatively, the same code can be written using async-await style.
+     * (async function() {
+     *   const addresses = await resolver.resolve4('example.org');
+     * })();
+     * ```
+     *
+     * The following methods from the `dnsPromises` API are available:
+     *
+     * * `resolver.getServers()`
+     * * `resolver.resolve()`
+     * * `resolver.resolve4()`
+     * * `resolver.resolve6()`
+     * * `resolver.resolveAny()`
+     * * `resolver.resolveCaa()`
+     * * `resolver.resolveCname()`
+     * * `resolver.resolveMx()`
+     * * `resolver.resolveNaptr()`
+     * * `resolver.resolveNs()`
+     * * `resolver.resolvePtr()`
+     * * `resolver.resolveSoa()`
+     * * `resolver.resolveSrv()`
+     * * `resolver.resolveTxt()`
+     * * `resolver.reverse()`
+     * * `resolver.setServers()`
+     * @since v10.6.0
+     */
     class Resolver {
         constructor(options?: ResolverOptions);
         cancel(): void;
@@ -352,6 +395,7 @@ declare module 'dns/promises' {
         resolve4: typeof resolve4;
         resolve6: typeof resolve6;
         resolveAny: typeof resolveAny;
+        resolveCaa: typeof resolveCaa;
         resolveCname: typeof resolveCname;
         resolveMx: typeof resolveMx;
         resolveNaptr: typeof resolveNaptr;

node/dns.d.ts

@@ -1,5 +1,5 @@
 /**
- * The `dns` module enables name resolution. For example, use it to look up IP
+ * The `node:dns` module enables name resolution. For example, use it to look up IP
  * addresses of host names.
  *
  * Although named for the [Domain Name System (DNS)](https://en.wikipedia.org/wiki/Domain_Name_System), it does not always use the
@@ -9,7 +9,7 @@
  * system do, use {@link lookup}.
  *
  * ```js
- * const dns = require('dns');
+ * const dns = require('node:dns');
  *
  * dns.lookup('example.org', (err, address, family) => {
  *   console.log('address: %j family: IPv%s', address, family);
@@ -17,13 +17,13 @@
  * // address: "93.184.216.34" family: IPv4
  * ```
  *
- * All other functions in the `dns` module connect to an actual DNS server to
+ * All other functions in the `node:dns` module connect to an actual DNS server to
  * perform name resolution. They will always use the network to perform DNS
  * queries. These functions do not use the same set of configuration files used by {@link lookup} (e.g. `/etc/hosts`). Use these functions to always perform
  * DNS queries, bypassing other name-resolution facilities.
  *
  * ```js
- * const dns = require('dns');
+ * const dns = require('node:dns');
  *
  * dns.resolve4('archive.org', (err, addresses) => {
  *   if (err) throw err;
@@ -42,7 +42,7 @@
  * ```
  *
  * See the `Implementation considerations section` for more information.
- * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/dns.js)
+ * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/dns.js)
  */
 declare module 'dns' {
     import * as dnsPromises from 'node:dns/promises';
@@ -76,8 +76,8 @@ declare module 'dns' {
     /**
      * Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or
      * AAAA (IPv6) record. All `option` properties are optional. If `options` is an
-     * integer, then it must be `4` or `6` – if `options` is not provided, then IPv4
-     * and IPv6 addresses are both returned if found.
+     * integer, then it must be `4` or `6` – if `options` is `0` or not provided, then
+     * IPv4 and IPv6 addresses are both returned if found.
      *
      * With the `all` option set to `true`, the arguments for `callback` change to`(err, addresses)`, with `addresses` being an array of objects with the
      * properties `address` and `family`.
@@ -89,14 +89,14 @@ declare module 'dns' {
      *
      * `dns.lookup()` does not necessarily have anything to do with the DNS protocol.
      * The implementation uses an operating system facility that can associate names
-     * with addresses, and vice versa. This implementation can have subtle but
+     * with addresses and vice versa. This implementation can have subtle but
      * important consequences on the behavior of any Node.js program. Please take some
      * time to consult the `Implementation considerations section` before using`dns.lookup()`.
      *
      * Example usage:
      *
      * ```js
-     * const dns = require('dns');
+     * const dns = require('node:dns');
      * const options = {
      *   family: 6,
      *   hints: dns.ADDRCONFIG | dns.V4MAPPED,
@@ -135,7 +135,7 @@ declare module 'dns' {
      * On an error, `err` is an `Error` object, where `err.code` is the error code.
      *
      * ```js
-     * const dns = require('dns');
+     * const dns = require('node:dns');
      * dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
      *   console.log(hostname, service);
      *   // Prints: localhost ssh
@@ -174,7 +174,7 @@ declare module 'dns' {
         type: 'AAAA';
     }
     export interface CaaRecord {
-        critial: number;
+        critical: number;
         issue?: string | undefined;
         issuewild?: string | undefined;
         iodef?: string | undefined;
@@ -291,7 +291,7 @@ declare module 'dns' {
         function __promisify__(hostname: string, options?: ResolveOptions): Promise<string[] | RecordWithTtl[]>;
     }
     /**
-     * Uses the DNS protocol to resolve a IPv6 addresses (`AAAA` records) for the`hostname`. The `addresses` argument passed to the `callback` function
+     * Uses the DNS protocol to resolve IPv6 addresses (`AAAA` records) for the`hostname`. The `addresses` argument passed to the `callback` function
      * will contain an array of IPv6 addresses.
      * @since v0.1.16
      * @param hostname Host name to resolve.
@@ -333,7 +333,7 @@ declare module 'dns' {
         function __promisify__(hostname: string): Promise<MxRecord[]>;
     }
     /**
-     * Uses the DNS protocol to resolve regular expression based records (`NAPTR`records) for the `hostname`. The `addresses` argument passed to the `callback`function will contain an array of
+     * Uses the DNS protocol to resolve regular expression-based records (`NAPTR`records) for the `hostname`. The `addresses` argument passed to the `callback`function will contain an array of
      * objects with the following properties:
      *
      * * `flags`
@@ -484,6 +484,14 @@ declare module 'dns' {
      * @since v0.1.16
      */
     export function reverse(ip: string, callback: (err: NodeJS.ErrnoException | null, hostnames: string[]) => void): void;
+    /**
+     * Get the default value for `verbatim` in {@link lookup} and `dnsPromises.lookup()`. The value could be:
+     *
+     * * `ipv4first`: for `verbatim` defaulting to `false`.
+     * * `verbatim`: for `verbatim` defaulting to `true`.
+     * @since v20.1.0
+     */
+    export function getDefaultResultOrder(): 'ipv4first' | 'verbatim';
     /**
      * Sets the IP address and port of servers to be used when performing DNS
      * resolution. The `servers` argument is an array of [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6) formatted
@@ -535,7 +543,7 @@ declare module 'dns' {
      * * `ipv4first`: sets default `verbatim` `false`.
      * * `verbatim`: sets default `verbatim` `true`.
      *
-     * The default is `ipv4first` and {@link setDefaultResultOrder} have higher
+     * The default is `verbatim` and {@link setDefaultResultOrder} have higher
      * priority than `--dns-result-order`. When using `worker threads`,{@link setDefaultResultOrder} from the main thread won't affect the default
      * dns orders in workers.
      * @since v16.4.0, v14.18.0
@@ -582,7 +590,7 @@ declare module 'dns' {
      * other resolvers:
      *
      * ```js
-     * const { Resolver } = require('dns');
+     * const { Resolver } = require('node:dns');
      * const resolver = new Resolver();
      * resolver.setServers(['4.4.4.4']);
      *
@@ -592,7 +600,7 @@ declare module 'dns' {
      * });
      * ```
      *
-     * The following methods from the `dns` module are available:
+     * The following methods from the `node:dns` module are available:
      *
      * * `resolver.getServers()`
      * * `resolver.resolve()`
@@ -625,6 +633,7 @@ declare module 'dns' {
         resolve4: typeof resolve4;
         resolve6: typeof resolve6;
         resolveAny: typeof resolveAny;
+        resolveCaa: typeof resolveCaa;
         resolveCname: typeof resolveCname;
         resolveMx: typeof resolveMx;
         resolveNaptr: typeof resolveNaptr;
@@ -639,7 +648,7 @@ declare module 'dns' {
          * This allows programs to specify outbound interfaces when used on multi-homed
          * systems.
          *
-         * If a v4 or v6 address is not specified, it is set to the default, and the
+         * If a v4 or v6 address is not specified, it is set to the default and the
          * operating system will choose a local address automatically.
          *
          * The resolver will use the v4 local address when making requests to IPv4 DNS

node/domain.d.ts

@@ -12,7 +12,7 @@
  * will be notified, rather than losing the context of the error in the`process.on('uncaughtException')` handler, or causing the program to
  * exit immediately with an error code.
  * @deprecated Since v1.4.2 - Deprecated
- * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/domain.js)
+ * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/domain.js)
  */
 declare module 'domain' {
     import EventEmitter = require('node:events');
@@ -56,15 +56,15 @@ declare module 'domain' {
         exit(): void;
         /**
          * Run the supplied function in the context of the domain, implicitly
-         * binding all event emitters, timers, and lowlevel requests that are
+         * binding all event emitters, timers, and low-level requests that are
          * created in that context. Optionally, arguments can be passed to
          * the function.
          *
          * This is the most basic way to use a domain.
          *
          * ```js
-         * const domain = require('domain');
-         * const fs = require('fs');
+         * const domain = require('node:domain');
+         * const fs = require('node:fs');
          * const d = domain.create();
          * d.on('error', (er) => {
          *   console.error('Caught error!', er);