@types/node 16.4.2 → 16.4.6

node/domain.d.ts

@@ -1,25 +1,169 @@
- /**
-  * @deprecated
-  */
+/**
+ * **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
+ * in the future.
+ *
+ * Domains provide a way to handle multiple different IO operations as a
+ * single group. If any of the event emitters or callbacks registered to a
+ * domain emit an `'error'` event, or throw an error, then the domain object
+ * 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)
+ */
 declare module 'domain' {
     import EventEmitter = require('node:events');
+    /**
+     * The `Domain` class encapsulates the functionality of routing errors and
+     * uncaught exceptions to the active `Domain` object.
+     *
+     * To handle the errors that it catches, listen to its `'error'` event.
+     */
     class Domain extends EventEmitter {
+        /**
+         * An array of timers and event emitters that have been explicitly added
+         * to the domain.
+         */
         members: Array<EventEmitter | NodeJS.Timer>;
+        /**
+         * The `enter()` method is plumbing used by the `run()`, `bind()`, and`intercept()` methods to set the active domain. It sets `domain.active` and`process.domain` to the domain, and implicitly
+         * pushes the domain onto the domain
+         * stack managed by the domain module (see {@link exit} for details on the
+         * domain stack). The call to `enter()` delimits the beginning of a chain of
+         * asynchronous calls and I/O operations bound to a domain.
+         *
+         * Calling `enter()` changes only the active domain, and does not alter the domain
+         * itself. `enter()` and `exit()` can be called an arbitrary number of times on a
+         * single domain.
+         */
         enter(): void;
+        /**
+         * The `exit()` method exits the current domain, popping it off the domain stack.
+         * Any time execution is going to switch to the context of a different chain of
+         * asynchronous calls, it's important to ensure that the current domain is exited.
+         * The call to `exit()` delimits either the end of or an interruption to the chain
+         * of asynchronous calls and I/O operations bound to a domain.
+         *
+         * If there are multiple, nested domains bound to the current execution context,`exit()` will exit any domains nested within this domain.
+         *
+         * Calling `exit()` changes only the active domain, and does not alter the domain
+         * itself. `enter()` and `exit()` can be called an arbitrary number of times on a
+         * single domain.
+         */
         exit(): void;
+        /**
+         * Run the supplied function in the context of the domain, implicitly
+         * binding all event emitters, timers, and lowlevel 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 d = domain.create();
+         * d.on('error', (er) => {
+         *   console.error('Caught error!', er);
+         * });
+         * d.run(() => {
+         *   process.nextTick(() => {
+         *     setTimeout(() => { // Simulating some various async stuff
+         *       fs.open('non-existent file', 'r', (er, fd) => {
+         *         if (er) throw er;
+         *         // proceed...
+         *       });
+         *     }, 100);
+         *   });
+         * });
+         * ```
+         *
+         * In this example, the `d.on('error')` handler will be triggered, rather
+         * than crashing the program.
+         */
         run<T>(fn: (...args: any[]) => T, ...args: any[]): T;
+        /**
+         * Explicitly adds an emitter to the domain. If any event handlers called by
+         * the emitter throw an error, or if the emitter emits an `'error'` event, it
+         * will be routed to the domain's `'error'` event, just like with implicit
+         * binding.
+         *
+         * This also works with timers that are returned from `setInterval()` and `setTimeout()`. If their callback function throws, it will be caught by
+         * the domain `'error'` handler.
+         *
+         * If the Timer or `EventEmitter` was already bound to a domain, it is removed
+         * from that one, and bound to this one instead.
+         * @param emitter emitter or timer to be added to the domain
+         */
         add(emitter: EventEmitter | NodeJS.Timer): void;
+        /**
+         * The opposite of {@link add}. Removes domain handling from the
+         * specified emitter.
+         * @param emitter emitter or timer to be removed from the domain
+         */
         remove(emitter: EventEmitter | NodeJS.Timer): void;
-        bind<T extends Function>(cb: T): T;
-        intercept<T extends Function>(cb: T): T;
+        /**
+         * The returned function will be a wrapper around the supplied callback
+         * function. When the returned function is called, any errors that are
+         * thrown will be routed to the domain's `'error'` event.
+         *
+         * ```js
+         * const d = domain.create();
+         *
+         * function readSomeFile(filename, cb) {
+         *   fs.readFile(filename, 'utf8', d.bind((er, data) => {
+         *     // If this throws, it will also be passed to the domain.
+         *     return cb(er, data ? JSON.parse(data) : null);
+         *   }));
+         * }
+         *
+         * d.on('error', (er) => {
+         *   // An error occurred somewhere. If we throw it now, it will crash the program
+         *   // with the normal line number and stack message.
+         * });
+         * ```
+         * @param callback The callback function
+         * @return The bound function
+         */
+        bind<T extends Function>(callback: T): T;
+        /**
+         * This method is almost identical to {@link bind}. However, in
+         * addition to catching thrown errors, it will also intercept `Error` objects sent as the first argument to the function.
+         *
+         * In this way, the common `if (err) return callback(err);` pattern can be replaced
+         * with a single error handler in a single place.
+         *
+         * ```js
+         * const d = domain.create();
+         *
+         * function readSomeFile(filename, cb) {
+         *   fs.readFile(filename, 'utf8', d.intercept((data) => {
+         *     // Note, the first argument is never passed to the
+         *     // callback since it is assumed to be the 'Error' argument
+         *     // and thus intercepted by the domain.
+         *
+         *     // If this throws, it will also be passed to the domain
+         *     // so the error-handling logic can be moved to the 'error'
+         *     // event on the domain instead of being repeated throughout
+         *     // the program.
+         *     return cb(null, JSON.parse(data));
+         *   }));
+         * }
+         *
+         * d.on('error', (er) => {
+         *   // An error occurred somewhere. If we throw it now, it will crash the program
+         *   // with the normal line number and stack message.
+         * });
+         * ```
+         * @param callback The callback function
+         * @return The intercepted function
+         */
+        intercept<T extends Function>(callback: T): T;
     }
-
     function create(): Domain;
 }
-
- /**
-  * @deprecated
-  */
 declare module 'node:domain' {
     export * from 'domain';
 }

node/events.d.ts

@@ -1,3 +1,39 @@
+/**
+ * Much of the Node.js core API is built around an idiomatic asynchronous
+ * event-driven architecture in which certain kinds of objects (called "emitters")
+ * emit named events that cause `Function` objects ("listeners") to be called.
+ *
+ * For instance: a `net.Server` object emits an event each time a peer
+ * connects to it; a `fs.ReadStream` emits an event when the file is opened;
+ * a `stream` emits an event whenever data is available to be read.
+ *
+ * All objects that emit events are instances of the `EventEmitter` class. These
+ * objects expose an `eventEmitter.on()` function that allows one or more
+ * functions to be attached to named events emitted by the object. Typically,
+ * event names are camel-cased strings but any valid JavaScript property key
+ * can be used.
+ *
+ * When the `EventEmitter` object emits an event, all of the functions attached
+ * to that specific event are called _synchronously_. Any values returned by the
+ * called listeners are _ignored_ and discarded.
+ *
+ * The following example shows a simple `EventEmitter` instance with a single
+ * listener. The `eventEmitter.on()` method is used to register listeners, while
+ * the `eventEmitter.emit()` method is used to trigger the event.
+ *
+ * ```js
+ * const EventEmitter = require('events');
+ *
+ * class MyEmitter extends EventEmitter {}
+ *
+ * const myEmitter = new MyEmitter();
+ * myEmitter.on('event', () => {
+ *   console.log('an event occurred!');
+ * });
+ * myEmitter.emit('event');
+ * ```
+ * @see [source](https://github.com/nodejs/node/blob/v16.4.2/lib/events.js)
+ */
 declare module 'events' {
     interface EventEmitterOptions {
         /**
@@ -5,34 +41,46 @@ declare module 'events' {
          */
         captureRejections?: boolean | undefined;
     }
-
     interface NodeEventTarget {
-        once(event: string | symbol, listener: (...args: any[]) => void): this;
+        once(eventName: string | symbol, listener: (...args: any[]) => void): this;
     }
-
     interface DOMEventTarget {
-        addEventListener(event: string, listener: (...args: any[]) => void, opts?: { once: boolean }): any;
+        addEventListener(
+            eventName: string,
+            listener: (...args: any[]) => void,
+            opts?: {
+                once: boolean;
+            }
+        ): any;
     }
-
     interface StaticEventEmitterOptions {
         signal?: AbortSignal | undefined;
     }
-
     interface EventEmitter extends NodeJS.EventEmitter {}
+    /**
+     * The `EventEmitter` class is defined and exposed by the `events` module:
+     *
+     * ```js
+     * const EventEmitter = require('events');
+     * ```
+     *
+     * All `EventEmitter`s emit the event `'newListener'` when new listeners are
+     * added and `'removeListener'` when existing listeners are removed.
+     *
+     * It supports the following option:
+     * @since v0.1.26
+     */
     class EventEmitter {
         constructor(options?: EventEmitterOptions);
-
-        static once(emitter: NodeEventTarget, event: string | symbol, options?: StaticEventEmitterOptions): Promise<any[]>;
-        static once(emitter: DOMEventTarget, event: string, options?: StaticEventEmitterOptions): Promise<any[]>;
-        static on(emitter: NodeJS.EventEmitter, event: string, options?: StaticEventEmitterOptions): AsyncIterableIterator<any>;
-
+        static once(emitter: NodeEventTarget, eventName: string | symbol, options?: StaticEventEmitterOptions): Promise<any[]>;
+        static once(emitter: DOMEventTarget, eventName: string, options?: StaticEventEmitterOptions): Promise<any[]>;
+        static on(emitter: NodeJS.EventEmitter, eventName: string, options?: StaticEventEmitterOptions): AsyncIterableIterator<any>;
         /** @deprecated since v4.0.0 */
-        static listenerCount(emitter: NodeJS.EventEmitter, event: string | symbol): number;
+        static listenerCount(emitter: NodeJS.EventEmitter, eventName: string | symbol): number;
         /**
          * Returns a list listener for a specific emitter event name.
          */
         static getEventListener(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
@@ -44,7 +92,6 @@ declare module 'events' {
          */
         static readonly errorMonitor: unique symbol;
         static readonly captureRejectionSymbol: unique symbol;
-
         /**
          * Sets or gets the default captureRejection value for all emitters.
          */
@@ -52,12 +99,10 @@ declare module 'events' {
         static captureRejections: boolean;
         static defaultMaxListeners: number;
     }
-
     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 };
-
         export interface Abortable {
             /**
              * When provided the corresponding `AbortController` can be used to cancel an asynchronous action.
@@ -65,33 +110,334 @@ declare module 'events' {
             signal?: AbortSignal | undefined;
         }
     }
-
     global {
         namespace NodeJS {
             interface EventEmitter {
-                addListener(event: string | symbol, listener: (...args: any[]) => void): this;
-                on(event: string | symbol, listener: (...args: any[]) => void): this;
-                once(event: string | symbol, listener: (...args: any[]) => void): this;
-                removeListener(event: string | symbol, listener: (...args: any[]) => void): this;
-                off(event: string | symbol, listener: (...args: any[]) => void): this;
+                /**
+                 * Alias for `emitter.on(eventName, listener)`.
+                 * @since v0.1.26
+                 */
+                addListener(eventName: string | symbol, listener: (...args: any[]) => void): this;
+                /**
+                 * Adds the `listener` function to the end of the listeners array for the
+                 * event named `eventName`. No checks are made to see if the `listener` has
+                 * already been added. Multiple calls passing the same combination of `eventName`and `listener` will result in the `listener` being added, and called, multiple
+                 * times.
+                 *
+                 * ```js
+                 * server.on('connection', (stream) => {
+                 *   console.log('someone connected!');
+                 * });
+                 * ```
+                 *
+                 * Returns a reference to the `EventEmitter`, so that calls can be chained.
+                 *
+                 * By default, event listeners are invoked in the order they are added. The`emitter.prependListener()` method can be used as an alternative to add the
+                 * event listener to the beginning of the listeners array.
+                 *
+                 * ```js
+                 * const myEE = new EventEmitter();
+                 * myEE.on('foo', () => console.log('a'));
+                 * myEE.prependListener('foo', () => console.log('b'));
+                 * myEE.emit('foo');
+                 * // Prints:
+                 * //   b
+                 * //   a
+                 * ```
+                 * @since v0.1.101
+                 * @param eventName The name of the event.
+                 * @param listener The callback function
+                 */
+                on(eventName: string | symbol, listener: (...args: any[]) => void): this;
+                /**
+                 * Adds a **one-time**`listener` function for the event named `eventName`. The
+                 * next time `eventName` is triggered, this listener is removed and then invoked.
+                 *
+                 * ```js
+                 * server.once('connection', (stream) => {
+                 *   console.log('Ah, we have our first user!');
+                 * });
+                 * ```
+                 *
+                 * Returns a reference to the `EventEmitter`, so that calls can be chained.
+                 *
+                 * By default, event listeners are invoked in the order they are added. The`emitter.prependOnceListener()` method can be used as an alternative to add the
+                 * event listener to the beginning of the listeners array.
+                 *
+                 * ```js
+                 * const myEE = new EventEmitter();
+                 * myEE.once('foo', () => console.log('a'));
+                 * myEE.prependOnceListener('foo', () => console.log('b'));
+                 * myEE.emit('foo');
+                 * // Prints:
+                 * //   b
+                 * //   a
+                 * ```
+                 * @since v0.3.0
+                 * @param eventName The name of the event.
+                 * @param listener The callback function
+                 */
+                once(eventName: string | symbol, listener: (...args: any[]) => void): this;
+                /**
+                 * Removes the specified `listener` from the listener array for the event named`eventName`.
+                 *
+                 * ```js
+                 * const callback = (stream) => {
+                 *   console.log('someone connected!');
+                 * };
+                 * server.on('connection', callback);
+                 * // ...
+                 * server.removeListener('connection', callback);
+                 * ```
+                 *
+                 * `removeListener()` will remove, at most, one instance of a listener from the
+                 * listener array. If any single listener has been added multiple times to the
+                 * listener array for the specified `eventName`, then `removeListener()` must be
+                 * called multiple times to remove each instance.
+                 *
+                 * Once an event is emitted, all listeners attached to it at the
+                 * time of emitting are called in order. This implies that any`removeListener()` or `removeAllListeners()` calls _after_ emitting and_before_ the last listener finishes execution will
+                 * not remove them from`emit()` in progress. Subsequent events behave as expected.
+                 *
+                 * ```js
+                 * const myEmitter = new MyEmitter();
+                 *
+                 * const callbackA = () => {
+                 *   console.log('A');
+                 *   myEmitter.removeListener('event', callbackB);
+                 * };
+                 *
+                 * const callbackB = () => {
+                 *   console.log('B');
+                 * };
+                 *
+                 * myEmitter.on('event', callbackA);
+                 *
+                 * myEmitter.on('event', callbackB);
+                 *
+                 * // callbackA removes listener callbackB but it will still be called.
+                 * // Internal listener array at time of emit [callbackA, callbackB]
+                 * myEmitter.emit('event');
+                 * // Prints:
+                 * //   A
+                 * //   B
+                 *
+                 * // callbackB is now removed.
+                 * // Internal listener array [callbackA]
+                 * myEmitter.emit('event');
+                 * // Prints:
+                 * //   A
+                 * ```
+                 *
+                 * Because listeners are managed using an internal array, calling this will
+                 * change the position indices of any listener registered _after_ the listener
+                 * being removed. This will not impact the order in which listeners are called,
+                 * but it means that any copies of the listener array as returned by
+                 * the `emitter.listeners()` method will need to be recreated.
+                 *
+                 * When a single function has been added as a handler multiple times for a single
+                 * event (as in the example below), `removeListener()` will remove the most
+                 * recently added instance. In the example the `once('ping')`listener is removed:
+                 *
+                 * ```js
+                 * const ee = new EventEmitter();
+                 *
+                 * function pong() {
+                 *   console.log('pong');
+                 * }
+                 *
+                 * ee.on('ping', pong);
+                 * ee.once('ping', pong);
+                 * ee.removeListener('ping', pong);
+                 *
+                 * ee.emit('ping');
+                 * ee.emit('ping');
+                 * ```
+                 *
+                 * Returns a reference to the `EventEmitter`, so that calls can be chained.
+                 * @since v0.1.26
+                 */
+                removeListener(eventName: string | symbol, listener: (...args: any[]) => void): this;
+                /**
+                 * Alias for `emitter.removeListener()`.
+                 * @since v10.0.0
+                 */
+                off(eventName: string | symbol, listener: (...args: any[]) => void): this;
+                /**
+                 * Removes all listeners, or those of the specified `eventName`.
+                 *
+                 * It is bad practice to remove listeners added elsewhere in the code,
+                 * particularly when the `EventEmitter` instance was created by some other
+                 * component or module (e.g. sockets or file streams).
+                 *
+                 * Returns a reference to the `EventEmitter`, so that calls can be chained.
+                 * @since v0.1.26
+                 */
                 removeAllListeners(event?: string | symbol): this;
+                /**
+                 * By default `EventEmitter`s will print a warning if more than `10` listeners are
+                 * added for a particular event. This is a useful default that helps finding
+                 * memory leaks. The `emitter.setMaxListeners()` method allows the limit to be
+                 * modified for this specific `EventEmitter` instance. The value can be set to`Infinity` (or `0`) to indicate an unlimited number of listeners.
+                 *
+                 * Returns a reference to the `EventEmitter`, so that calls can be chained.
+                 * @since v0.3.5
+                 */
                 setMaxListeners(n: number): this;
+                /**
+                 * Returns the current max listener value for the `EventEmitter` which is either
+                 * set by `emitter.setMaxListeners(n)` or defaults to {@link defaultMaxListeners}.
+                 * @since v1.0.0
+                 */
                 getMaxListeners(): number;
-                listeners(event: string | symbol): Function[];
-                rawListeners(event: string | symbol): Function[];
-                emit(event: string | symbol, ...args: any[]): boolean;
-                listenerCount(event: string | symbol): number;
-                // Added in Node 6...
-                prependListener(event: string | symbol, listener: (...args: any[]) => void): this;
-                prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this;
+                /**
+                 * Returns a copy of the array of listeners for the event named `eventName`.
+                 *
+                 * ```js
+                 * server.on('connection', (stream) => {
+                 *   console.log('someone connected!');
+                 * });
+                 * console.log(util.inspect(server.listeners('connection')));
+                 * // Prints: [ [Function] ]
+                 * ```
+                 * @since v0.1.26
+                 */
+                listeners(eventName: string | symbol): Function[];
+                /**
+                 * Returns a copy of the array of listeners for the event named `eventName`,
+                 * including any wrappers (such as those created by `.once()`).
+                 *
+                 * ```js
+                 * const emitter = new EventEmitter();
+                 * emitter.once('log', () => console.log('log once'));
+                 *
+                 * // Returns a new Array with a function `onceWrapper` which has a property
+                 * // `listener` which contains the original listener bound above
+                 * const listeners = emitter.rawListeners('log');
+                 * const logFnWrapper = listeners[0];
+                 *
+                 * // Logs "log once" to the console and does not unbind the `once` event
+                 * logFnWrapper.listener();
+                 *
+                 * // Logs "log once" to the console and removes the listener
+                 * logFnWrapper();
+                 *
+                 * emitter.on('log', () => console.log('log persistently'));
+                 * // Will return a new Array with a single function bound by `.on()` above
+                 * const newListeners = emitter.rawListeners('log');
+                 *
+                 * // Logs "log persistently" twice
+                 * newListeners[0]();
+                 * emitter.emit('log');
+                 * ```
+                 * @since v9.4.0
+                 */
+                rawListeners(eventName: string | symbol): Function[];
+                /**
+                 * Synchronously calls each of the listeners registered for the event named`eventName`, in the order they were registered, passing the supplied arguments
+                 * to each.
+                 *
+                 * Returns `true` if the event had listeners, `false` otherwise.
+                 *
+                 * ```js
+                 * const EventEmitter = require('events');
+                 * const myEmitter = new EventEmitter();
+                 *
+                 * // First listener
+                 * myEmitter.on('event', function firstListener() {
+                 *   console.log('Helloooo! first listener');
+                 * });
+                 * // Second listener
+                 * myEmitter.on('event', function secondListener(arg1, arg2) {
+                 *   console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
+                 * });
+                 * // Third listener
+                 * myEmitter.on('event', function thirdListener(...args) {
+                 *   const parameters = args.join(', ');
+                 *   console.log(`event with parameters ${parameters} in third listener`);
+                 * });
+                 *
+                 * console.log(myEmitter.listeners('event'));
+                 *
+                 * myEmitter.emit('event', 1, 2, 3, 4, 5);
+                 *
+                 * // Prints:
+                 * // [
+                 * //   [Function: firstListener],
+                 * //   [Function: secondListener],
+                 * //   [Function: thirdListener]
+                 * // ]
+                 * // Helloooo! first listener
+                 * // event with parameters 1, 2 in second listener
+                 * // event with parameters 1, 2, 3, 4, 5 in third listener
+                 * ```
+                 * @since v0.1.26
+                 */
+                emit(eventName: string | symbol, ...args: any[]): boolean;
+                /**
+                 * Returns the number of listeners listening to the event named `eventName`.
+                 * @since v3.2.0
+                 * @param eventName The name of the event being listened for
+                 */
+                listenerCount(eventName: string | symbol): number;
+                /**
+                 * Adds the `listener` function to the _beginning_ of the listeners array for the
+                 * event named `eventName`. No checks are made to see if the `listener` has
+                 * already been added. Multiple calls passing the same combination of `eventName`and `listener` will result in the `listener` being added, and called, multiple
+                 * times.
+                 *
+                 * ```js
+                 * server.prependListener('connection', (stream) => {
+                 *   console.log('someone connected!');
+                 * });
+                 * ```
+                 *
+                 * Returns a reference to the `EventEmitter`, so that calls can be chained.
+                 * @since v6.0.0
+                 * @param eventName The name of the event.
+                 * @param listener The callback function
+                 */
+                prependListener(eventName: string | symbol, listener: (...args: any[]) => void): this;
+                /**
+                 * Adds a **one-time**`listener` function for the event named `eventName` to the_beginning_ of the listeners array. The next time `eventName` is triggered, this
+                 * listener is removed, and then invoked.
+                 *
+                 * ```js
+                 * server.prependOnceListener('connection', (stream) => {
+                 *   console.log('Ah, we have our first user!');
+                 * });
+                 * ```
+                 *
+                 * Returns a reference to the `EventEmitter`, so that calls can be chained.
+                 * @since v6.0.0
+                 * @param eventName The name of the event.
+                 * @param listener The callback function
+                 */
+                prependOnceListener(eventName: string | symbol, listener: (...args: any[]) => void): this;
+                /**
+                 * Returns an array listing the events for which the emitter has registered
+                 * listeners. The values in the array are strings or `Symbol`s.
+                 *
+                 * ```js
+                 * const EventEmitter = require('events');
+                 * const myEE = new EventEmitter();
+                 * myEE.on('foo', () => {});
+                 * myEE.on('bar', () => {});
+                 *
+                 * const sym = Symbol('symbol');
+                 * myEE.on(sym, () => {});
+                 *
+                 * console.log(myEE.eventNames());
+                 * // Prints: [ 'foo', 'bar', Symbol(symbol) ]
+                 * ```
+                 * @since v6.0.0
+                 */
                 eventNames(): Array<string | symbol>;
             }
         }
     }
-
     export = EventEmitter;
 }
-
 declare module 'node:events' {
     import events = require('events');
     export = events;