@types/node 16.6.2 → 16.7.0

node/events.d.ts

@@ -32,7 +32,7 @@
  * });
  * myEmitter.emit('event');
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v16.6.0/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).
@@ -384,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.
      *
@@ -471,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';
@@ -544,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.
      */
@@ -677,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
@@ -739,13 +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 (not inherited)`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.
@@ -754,7 +755,7 @@ 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.
      *
@@ -797,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}
@@ -812,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.
      *
@@ -821,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
@@ -845,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.
@@ -895,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
@@ -915,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}.
@@ -977,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';