@types/node 16.4.14 → 16.7.0

node/dgram.d.ts

@@ -2,7 +2,8 @@
  * The `dgram` module provides an implementation of UDP datagram sockets.
  *
  * ```js
- * const dgram = require('dgram');
+ * import dgram from 'dgram';
+ *
  * const server = dgram.createSocket('udp4');
  *
  * server.on('error', (err) => {
@@ -22,7 +23,7 @@
  * server.bind(41234);
  * // Prints: server listening 0.0.0.0:41234
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v16.4.2/lib/dgram.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.7.0/lib/dgram.js)
  */
 declare module 'dgram' {
     import { AddressInfo } from 'node:net';
@@ -97,8 +98,9 @@ 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
-         * const cluster = require('cluster');
-         * const dgram = require('dgram');
+         * import cluster from 'cluster';
+         * import dgram from 'dgram';
+         *
          * if (cluster.isPrimary) {
          *   cluster.fork(); // Works ok.
          *   cluster.fork(); // Fails with EADDRINUSE.
@@ -140,7 +142,8 @@ declare module 'dgram' {
          * Example of a UDP server listening on port 41234:
          *
          * ```js
-         * const dgram = require('dgram');
+         * import dgram from 'dgram';
+         *
          * const server = dgram.createSocket('udp4');
          *
          * server.on('error', (err) => {
@@ -281,7 +284,9 @@ declare module 'dgram' {
          * Example of sending a UDP packet to a port on `localhost`;
          *
          * ```js
-         * const dgram = require('dgram');
+         * import dgram from 'dgram';
+         * import { Buffer } from 'buffer';
+         *
          * const message = Buffer.from('Some bytes');
          * const client = dgram.createSocket('udp4');
          * client.send(message, 41234, 'localhost', (err) => {
@@ -292,7 +297,9 @@ declare module 'dgram' {
          * Example of sending a UDP packet composed of multiple buffers to a port on`127.0.0.1`;
          *
          * ```js
-         * const dgram = require('dgram');
+         * import dgram from 'dgram';
+         * import { Buffer } from 'buffer';
+         *
          * const buf1 = Buffer.from('Some ');
          * const buf2 = Buffer.from('bytes');
          * const client = dgram.createSocket('udp4');
@@ -309,7 +316,9 @@ declare module 'dgram' {
          * Example of sending a UDP packet using a socket connected to a port on`localhost`:
          *
          * ```js
-         * const dgram = require('dgram');
+         * import dgram from 'dgram';
+         * import { Buffer } from 'buffer';
+         *
          * const message = Buffer.from('Some bytes');
          * const client = dgram.createSocket('udp4');
          * client.connect(41234, 'localhost', (err) => {

node/diagnostics_channel.d.ts

@@ -5,7 +5,7 @@
  * It can be accessed using:
  *
  * ```js
- * const diagnostics_channel = require('diagnostics_channel');
+ * import diagnostics_channel from 'diagnostics_channel';
  * ```
  *
  * It is intended that a module writer wanting to report diagnostics messages
@@ -20,7 +20,7 @@
  * should generally include the module name to avoid collisions with data from
  * other modules.
  * @experimental
- * @see [source](https://github.com/nodejs/node/blob/v16.4.2/lib/diagnostics_channel.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.7.0/lib/diagnostics_channel.js)
  */
 declare module 'diagnostics_channel' {
     /**
@@ -31,7 +31,7 @@ declare module 'diagnostics_channel' {
      * performance-sensitive code.
      *
      * ```js
-     * const diagnostics_channel = require('diagnostics_channel');
+     * import diagnostics_channel from 'diagnostics_channel';
      *
      * if (diagnostics_channel.hasSubscribers('my-channel')) {
      *   // There are subscribers, prepare and publish message
@@ -47,7 +47,7 @@ declare module 'diagnostics_channel' {
      * publish time as much as possible.
      *
      * ```js
-     * const diagnostics_channel = require('diagnostics_channel');
+     * import diagnostics_channel from 'diagnostics_channel';
      *
      * const channel = diagnostics_channel.channel('my-channel');
      * ```
@@ -66,7 +66,24 @@ declare module 'diagnostics_channel' {
      */
     class Channel {
         readonly name: string;
-        readonly hashSubscribers: boolean;
+        /**
+         * Check if there are active subscribers to this channel. This is helpful if
+         * the message you want to send might be expensive to prepare.
+         *
+         * This API is optional but helpful when trying to publish messages from very
+         * performance-sensitive code.
+         *
+         * ```js
+         * import diagnostics_channel from 'diagnostics_channel';
+         *
+         * const channel = diagnostics_channel.channel('my-channel');
+         *
+         * if (channel.hasSubscribers) {
+         *   // There are subscribers, prepare and publish message
+         * }
+         * ```
+         */
+        readonly hasSubscribers: boolean;
         private constructor(name: string);
         /**
          * Register a message handler to subscribe to this channel. This message handler
@@ -74,7 +91,7 @@ declare module 'diagnostics_channel' {
          * errors thrown in the message handler will trigger an `'uncaughtException'`.
          *
          * ```js
-         * const diagnostics_channel = require('diagnostics_channel');
+         * import diagnostics_channel from 'diagnostics_channel';
          *
          * const channel = diagnostics_channel.channel('my-channel');
          *
@@ -89,7 +106,7 @@ declare module 'diagnostics_channel' {
          * Remove a message handler previously registered to this channel with `channel.subscribe(onMessage)`.
          *
          * ```js
-         * const diagnostics_channel = require('diagnostics_channel');
+         * import diagnostics_channel from 'diagnostics_channel';
          *
          * const channel = diagnostics_channel.channel('my-channel');
          *

node/dns.d.ts

@@ -42,7 +42,7 @@
  * ```
  *
  * See the `Implementation considerations section` for more information.
- * @see [source](https://github.com/nodejs/node/blob/v16.4.2/lib/dns.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.7.0/lib/dns.js)
  */
 declare module 'dns' {
     import * as dnsPromises from 'node:dns/promises';
@@ -553,6 +553,10 @@ declare module 'dns' {
     export const CANCELLED: string;
     export interface ResolverOptions {
         timeout?: number | undefined;
+        /**
+         * @default 4
+         */
+        tries?: number;
     }
     /**
      * An independent resolver for DNS requests.

node/domain.d.ts

@@ -1,5 +1,5 @@
 /**
- * **This module is pending deprecation**. Once a replacement API has been
+ * **This module is pending deprecation.** Once a replacement API has been
  * finalized, this module will be fully deprecated. Most developers should**not** have cause to use this module. Users who absolutely must have
  * the functionality that domains provide may rely on it for the time being
  * but should expect to have to migrate to a different solution
@@ -11,7 +11,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/v16.4.2/lib/domain.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.7.0/lib/domain.js)
  */
 declare module 'domain' {
     import EventEmitter = require('node:events');

node/events.d.ts

@@ -32,7 +32,7 @@
  * });
  * myEmitter.emit('event');
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v16.4.2/lib/events.js)
+ * @see [source](https://github.com/nodejs/node/blob/v16.7.0/lib/events.js)
  */
 declare module 'events' {
     interface EventEmitterOptions {
@@ -72,15 +72,194 @@ declare module 'events' {
      */
     class EventEmitter {
         constructor(options?: EventEmitterOptions);
+        /**
+         * Creates a `Promise` that is fulfilled when the `EventEmitter` emits the given
+         * event or that is rejected if the `EventEmitter` emits `'error'` while waiting.
+         * The `Promise` will resolve with an array of all the arguments emitted to the
+         * given event.
+         *
+         * This method is intentionally generic and works with the web platform[EventTarget](https://dom.spec.whatwg.org/#interface-eventtarget) interface, which has no special`'error'` event
+         * semantics and does not listen to the `'error'` event.
+         *
+         * ```js
+         * const { once, EventEmitter } = require('events');
+         *
+         * async function run() {
+         *   const ee = new EventEmitter();
+         *
+         *   process.nextTick(() => {
+         *     ee.emit('myevent', 42);
+         *   });
+         *
+         *   const [value] = await once(ee, 'myevent');
+         *   console.log(value);
+         *
+         *   const err = new Error('kaboom');
+         *   process.nextTick(() => {
+         *     ee.emit('error', err);
+         *   });
+         *
+         *   try {
+         *     await once(ee, 'myevent');
+         *   } catch (err) {
+         *     console.log('error happened', err);
+         *   }
+         * }
+         *
+         * run();
+         * ```
+         *
+         * The special handling of the `'error'` event is only used when `events.once()`is used to wait for another event. If `events.once()` is used to wait for the
+         * '`error'` event itself, then it is treated as any other kind of event without
+         * special handling:
+         *
+         * ```js
+         * const { EventEmitter, once } = require('events');
+         *
+         * const ee = new EventEmitter();
+         *
+         * once(ee, 'error')
+         *   .then(([err]) => console.log('ok', err.message))
+         *   .catch((err) => console.log('error', err.message));
+         *
+         * ee.emit('error', new Error('boom'));
+         *
+         * // Prints: ok boom
+         * ```
+         *
+         * An `AbortSignal` can be used to cancel waiting for the event:
+         *
+         * ```js
+         * const { EventEmitter, once } = require('events');
+         *
+         * const ee = new EventEmitter();
+         * const ac = new AbortController();
+         *
+         * async function foo(emitter, event, signal) {
+         *   try {
+         *     await once(emitter, event, { signal });
+         *     console.log('event emitted!');
+         *   } catch (error) {
+         *     if (error.name === 'AbortError') {
+         *       console.error('Waiting for the event was canceled!');
+         *     } else {
+         *       console.error('There was an error', error.message);
+         *     }
+         *   }
+         * }
+         *
+         * foo(ee, 'foo', ac.signal);
+         * ac.abort(); // Abort waiting for the event
+         * ee.emit('foo'); // Prints: Waiting for the event was canceled!
+         * ```
+         * @since v11.13.0, v10.16.0
+         */
         static once(emitter: NodeEventTarget, eventName: string | symbol, options?: StaticEventEmitterOptions): Promise<any[]>;
         static once(emitter: DOMEventTarget, eventName: string, options?: StaticEventEmitterOptions): Promise<any[]>;
+        /**
+         * ```js
+         * const { on, EventEmitter } = require('events');
+         *
+         * (async () => {
+         *   const ee = new EventEmitter();
+         *
+         *   // Emit later on
+         *   process.nextTick(() => {
+         *     ee.emit('foo', 'bar');
+         *     ee.emit('foo', 42);
+         *   });
+         *
+         *   for await (const event of on(ee, 'foo')) {
+         *     // The execution of this inner block is synchronous and it
+         *     // processes one event at a time (even with await). Do not use
+         *     // if concurrent execution is required.
+         *     console.log(event); // prints ['bar'] [42]
+         *   }
+         *   // Unreachable here
+         * })();
+         * ```
+         *
+         * Returns an `AsyncIterator` that iterates `eventName` events. It will throw
+         * if the `EventEmitter` emits `'error'`. It removes all listeners when
+         * exiting the loop. The `value` returned by each iteration is an array
+         * composed of the emitted event arguments.
+         *
+         * An `AbortSignal` can be used to cancel waiting on events:
+         *
+         * ```js
+         * const { on, EventEmitter } = require('events');
+         * const ac = new AbortController();
+         *
+         * (async () => {
+         *   const ee = new EventEmitter();
+         *
+         *   // Emit later on
+         *   process.nextTick(() => {
+         *     ee.emit('foo', 'bar');
+         *     ee.emit('foo', 42);
+         *   });
+         *
+         *   for await (const event of on(ee, 'foo', { signal: ac.signal })) {
+         *     // The execution of this inner block is synchronous and it
+         *     // processes one event at a time (even with await). Do not use
+         *     // if concurrent execution is required.
+         *     console.log(event); // prints ['bar'] [42]
+         *   }
+         *   // Unreachable here
+         * })();
+         *
+         * process.nextTick(() => ac.abort());
+         * ```
+         * @since v13.6.0, v12.16.0
+         * @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>;
-        /** @deprecated since v4.0.0 */
+        /**
+         * A class method that returns the number of listeners for the given `eventName`registered on the given `emitter`.
+         *
+         * ```js
+         * const { EventEmitter, listenerCount } = require('events');
+         * const myEmitter = new EventEmitter();
+         * myEmitter.on('event', () => {});
+         * myEmitter.on('event', () => {});
+         * console.log(listenerCount(myEmitter, 'event'));
+         * // Prints: 2
+         * ```
+         * @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;
         /**
-         * Returns a list listener for a specific emitter event name.
+         * Returns a copy of the array of listeners for the event named `eventName`.
+         *
+         * For `EventEmitter`s this behaves exactly the same as calling `.listeners` on
+         * the emitter.
+         *
+         * For `EventTarget`s this is the only way to get the event listeners for the
+         * event target. This is useful for debugging and diagnostic purposes.
+         *
+         * ```js
+         * const { getEventListeners, EventEmitter } = require('events');
+         *
+         * {
+         *   const ee = new EventEmitter();
+         *   const listener = () => console.log('Events are fun');
+         *   ee.on('foo', listener);
+         *   getEventListeners(ee, 'foo'); // [listener]
+         * }
+         * {
+         *   const et = new EventTarget();
+         *   const listener = () => console.log('Events are fun');
+         *   et.addEventListener('foo', listener);
+         *   getEventListeners(et, 'foo'); // [listener]
+         * }
+         * ```
+         * @since v15.2.0
          */
-        static getEventListener(emitter: DOMEventTarget | NodeJS.EventEmitter, name: string | symbol): Function[];
+        static getEventListeners(emitter: DOMEventTarget | NodeJS.EventEmitter, name: string | symbol): Function[];
         /**
          * This symbol shall be used to install a listener for only monitoring `'error'`
          * events. Listeners installed using this symbol are called before the regular

node/fs/promises.d.ts

@@ -30,8 +30,9 @@ declare module 'fs/promises' {
         Mode,
         WatchOptions,
         WatchEventType,
+        CopyOptions,
     } from 'node:fs';
-    interface FileChangeInfo<T extends (string | Buffer)> {
+    interface FileChangeInfo<T extends string | Buffer> {
         eventType: WatchEventType;
         filename: T;
     }
@@ -126,7 +127,7 @@ declare module 'fs/promises' {
          *
          * If `options` is a string, then it specifies the `encoding`.
          *
-         * The `<FileHandle>` has to support reading.
+         * 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
          * position till the end of the file. It doesn't always read from the beginning
@@ -214,7 +215,7 @@ declare module 'fs/promises' {
          */
         truncate(len?: number): Promise<void>;
         /**
-         * Change the file system timestamps of the object referenced by the `<FileHandle>` then resolves the promise with no arguments upon success.
+         * Change the file system timestamps of the object referenced by the `FileHandle` then resolves the promise with no arguments upon success.
          * @since v10.0.0
          */
         utimes(atime: string | number | Date, mtime: string | number | Date): Promise<void>;
@@ -224,7 +225,7 @@ declare module 'fs/promises' {
          *
          * If `options` is a string, then it specifies the `encoding`.
          *
-         * The `<FileHandle>` has to support writing.
+         * The `FileHandle` has to support writing.
          *
          * It is unsafe to use `filehandle.writeFile()` multiple times on the same file
          * without waiting for the promise to be resolved (or rejected).
@@ -238,6 +239,8 @@ declare module 'fs/promises' {
         /**
          * Write `buffer` to the file.
          *
+         * If `buffer` is a plain object, it must have an own (not inherited) `toString`function property.
+         *
          * The promise is resolved with an object containing two properties:
          *
          * It is unsafe to use `filehandle.write()` multiple times on the same file
@@ -382,7 +385,7 @@ declare module 'fs/promises' {
      */
     function copyFile(src: PathLike, dest: PathLike, mode?: number): Promise<void>;
     /**
-     * Opens a `<FileHandle>`.
+     * Opens a `FileHandle`.
      *
      * Refer to the POSIX [`open(2)`](http://man7.org/linux/man-pages/man2/open.2.html) documentation for more detail.
      *
@@ -469,9 +472,9 @@ declare module 'fs/promises' {
      * The optional `options` argument can be a string specifying an encoding, or an
      * object with an `encoding` property specifying the character encoding to use for
      * the filenames. If the `encoding` is set to `'buffer'`, the filenames returned
-     * will be passed as `<Buffer>` objects.
+     * will be passed as `Buffer` objects.
      *
-     * If `options.withFileTypes` is set to `true`, the resolved array will contain `<fs.Dirent>` objects.
+     * If `options.withFileTypes` is set to `true`, the resolved array will contain `fs.Dirent` objects.
      *
      * ```js
      * import { readdir } from 'fs/promises';
@@ -542,7 +545,7 @@ declare module 'fs/promises' {
      * The optional `options` argument can be a string specifying an encoding, or an
      * object with an `encoding` property specifying the character encoding to use for
      * the link path returned. If the `encoding` is set to `'buffer'`, the link path
-     * returned will be passed as a `<Buffer>` object.
+     * returned will be passed as a `Buffer` object.
      * @since v10.0.0
      * @return Fulfills with the `linkString` upon success.
      */
@@ -675,7 +678,7 @@ declare module 'fs/promises' {
      * The optional `options` argument can be a string specifying an encoding, or an
      * object with an `encoding` property specifying the character encoding to use for
      * the path. If the `encoding` is set to `'buffer'`, the path returned will be
-     * passed as a `<Buffer>` object.
+     * passed as a `Buffer` object.
      *
      * On Linux, when Node.js is linked against musl libc, the procfs file system must
      * be mounted on `/proc` in order for this function to work. Glibc does not have
@@ -737,14 +740,13 @@ declare module 'fs/promises' {
      */
     function mkdtemp(prefix: string, options?: ObjectEncodingOptions | BufferEncoding | null): Promise<string | Buffer>;
     /**
-     * Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a `<Buffer>`, or an object with an own `toString` function
-     * property.
+     * Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a `Buffer`, or, an object with an own (not inherited)`toString` function property.
      *
      * The `encoding` option is ignored if `data` is a buffer.
      *
      * If `options` is a string, then it specifies the encoding.
      *
-     * Any specified `<FileHandle>` has to support writing.
+     * Any specified `FileHandle` has to support writing.
      *
      * It is unsafe to use `fsPromises.writeFile()` multiple times on the same file
      * without waiting for the promise to be settled.
@@ -753,12 +755,13 @@ declare module 'fs/promises' {
      * method that performs multiple `write` calls internally to write the buffer
      * passed to it. For performance sensitive code consider using `fs.createWriteStream()`.
      *
-     * It is possible to use an `<AbortSignal>` to cancel an `fsPromises.writeFile()`.
+     * It is possible to use an `AbortSignal` to cancel an `fsPromises.writeFile()`.
      * Cancelation is "best effort", and some amount of data is likely still
      * to be written.
      *
      * ```js
      * import { writeFile } from 'fs/promises';
+     * import { Buffer } from 'buffer';
      *
      * try {
      *   const controller = new AbortController();
@@ -795,11 +798,11 @@ declare module 'fs/promises' {
     ): Promise<void>;
     /**
      * Asynchronously append data to a file, creating the file if it does not yet
-     * exist. `data` can be a string or a `<Buffer>`.
+     * exist. `data` can be a string or a `Buffer`.
      *
      * If `options` is a string, then it specifies the `encoding`.
      *
-     * The `path` may be specified as a `<FileHandle>` that has been opened
+     * The `path` may be specified as a `FileHandle` that has been opened
      * for appending (using `fsPromises.open()`).
      * @since v10.0.0
      * @param path filename or {FileHandle}
@@ -810,7 +813,7 @@ declare module 'fs/promises' {
      * Asynchronously reads the entire contents of a file.
      *
      * If no encoding is specified (using `options.encoding`), the data is returned
-     * as a `<Buffer>` object. Otherwise, the data will be a string.
+     * as a `Buffer` object. Otherwise, the data will be a string.
      *
      * If `options` is a string, then it specifies the encoding.
      *
@@ -819,7 +822,7 @@ declare module 'fs/promises' {
      * with an error. On FreeBSD, a representation of the directory's contents will be
      * returned.
      *
-     * It is possible to abort an ongoing `readFile` using an `<AbortSignal>`. If a
+     * It is possible to abort an ongoing `readFile` using an `AbortSignal`. If a
      * request is aborted the promise returned is rejected with an `AbortError`:
      *
      * ```js
@@ -843,7 +846,7 @@ declare module 'fs/promises' {
      * Aborting an ongoing request does not abort individual operating
      * system requests but rather the internal buffering `fs.readFile` performs.
      *
-     * Any specified `<FileHandle>` has to support reading.
+     * Any specified `FileHandle` has to support reading.
      * @since v10.0.0
      * @param path filename or `FileHandle`
      * @return Fulfills with the contents of the file.
@@ -893,7 +896,7 @@ declare module 'fs/promises' {
     /**
      * 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.
      *
-     * Creates an `<fs.Dir>`, which contains all further functions for reading from
+     * Creates an `fs.Dir`, which contains all further functions for reading from
      * and cleaning up the directory.
      *
      * The `encoding` option sets the encoding for the `path` while opening the
@@ -913,7 +916,7 @@ declare module 'fs/promises' {
      * }
      * ```
      *
-     * When using the async iterator, the `<fs.Dir>` object will be automatically
+     * When using the async iterator, the `fs.Dir` object will be automatically
      * closed after the iterator exits.
      * @since v12.12.0
      * @return Fulfills with an {fs.Dir}.
@@ -975,6 +978,19 @@ declare module 'fs/promises' {
      * If `recursive` is not supplied, the default of `false` is used.
      */
     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.
+     *
+     * When copying a directory to another directory, globs are not supported and
+     * behavior is similar to `cp dir1/ dir2/`.
+     * @since v16.7.0
+     * @experimental
+     * @param src source path to copy.
+     * @param dest destination path to copy to.
+     * @return Fulfills with `undefined` upon success.
+     */
+    function cp(source: string, destination: string, opts?: CopyOptions): Promise<void>;
 }
 declare module 'node:fs/promises' {
     export * from 'fs/promises';