@types/node 20.4.9 → 20.5.0

node/README.md

@@ -8,7 +8,7 @@ This package contains type definitions for Node.js (https://nodejs.org/).
 Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node.
 
 ### Additional Details
- * Last updated: Tue, 08 Aug 2023 20:32:42 GMT
+ * Last updated: Sun, 13 Aug 2023 19:32:51 GMT
  * Dependencies: none
  * Global values: `AbortController`, `AbortSignal`, `__dirname`, `__filename`, `console`, `exports`, `gc`, `global`, `module`, `process`, `require`, `structuredClone`
 

node/child_process.d.ts

@@ -302,6 +302,11 @@ declare module 'child_process' {
          * @since v0.1.90
          */
         kill(signal?: NodeJS.Signals | number): boolean;
+        /**
+         * Calls {@link ChildProcess.kill} with `'SIGTERM'`.
+         * @since v20.5.0
+         */
+        [Symbol.dispose](): void;
         /**
          * When an IPC channel has been established between the parent and child (
          * i.e. when using {@link fork}), the `subprocess.send()` method can

node/dgram.d.ts

@@ -538,6 +538,11 @@ declare module 'dgram' {
         prependOnceListener(event: 'error', listener: (err: Error) => void): this;
         prependOnceListener(event: 'listening', listener: () => void): this;
         prependOnceListener(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this;
+        /**
+         * Calls `socket.close()` and returns a promise that fulfills when the socket has closed.
+         * @since v20.5.0
+         */
+        [Symbol.asyncDispose](): Promise<void>;
     }
 }
 declare module 'node:dgram' {

node/events.d.ts

@@ -338,6 +338,41 @@ declare module 'events' {
          * objects.
          */
         static setMaxListeners(n?: number, ...eventTargets: Array<_DOMEventTarget | NodeJS.EventEmitter>): void;
+        /**
+         * Listens once to the `abort` event on the provided `signal`.
+         *
+         * Listening to the `abort` event on abort signals is unsafe and may
+         * lead to resource leaks since another third party with the signal can
+         * call `e.stopImmediatePropagation()`. Unfortunately Node.js cannot change
+         * this since it would violate the web standard. Additionally, the original
+         * API makes it easy to forget to remove listeners.
+         *
+         * This API allows safely using `AbortSignal`s in Node.js APIs by solving these
+         * two issues by listening to the event such that `stopImmediatePropagation` does
+         * not prevent the listener from running.
+         *
+         * Returns a disposable so that it may be unsubscribed from more easily.
+         *
+         * ```js
+         * import { addAbortListener } from 'node:events';
+         *
+         * function example(signal) {
+         *   let disposable;
+         *   try {
+         *     signal.addEventListener('abort', (e) => e.stopImmediatePropagation());
+         *     disposable = addAbortListener(signal, (e) => {
+         *       // Do something when signal is aborted.
+         *     });
+         *   } finally {
+         *     disposable?.[Symbol.dispose]();
+         *   }
+         * }
+         * ```
+         * @since v20.5.0
+         * @experimental
+         * @return that removes the `abort` listener.
+         */
+        static addAbortListener(signal: AbortSignal, resource: (event: Event) => void): Disposable;
         /**
          * This symbol shall be used to install a listener for only monitoring `'error'`events. Listeners installed using this symbol are called before the regular`'error'` listeners are called.
          *

node/fs/promises.d.ts

@@ -456,6 +456,11 @@ declare module 'fs/promises' {
          * @return Fulfills with `undefined` upon success.
          */
         close(): Promise<void>;
+        /**
+         * An alias for {@link FileHandle.close()}.
+         * @since v20.4.0
+         */
+        [Symbol.asyncDispose](): Promise<void>;
     }
     const constants: typeof fsConstants;
     /**

node/globals.d.ts

@@ -84,6 +84,28 @@ declare var AbortSignal: typeof globalThis extends {onmessage: any; AbortSignal:
     };
 //#endregion borrowed
 
+//#region Disposable
+interface SymbolConstructor {
+    /**
+     * A method that is used to release resources held by an object. Called by the semantics of the `using` statement.
+     */
+    readonly dispose: unique symbol;
+
+    /**
+     * A method that is used to asynchronously release resources held by an object. Called by the semantics of the `await using` statement.
+     */
+    readonly asyncDispose: unique symbol;
+}
+
+interface Disposable {
+    [Symbol.dispose](): void;
+}
+
+interface AsyncDisposable {
+    [Symbol.asyncDispose](): PromiseLike<void>;
+}
+//#endregion Disposable
+
 //#region ArrayLike.at()
 interface RelativeIndexable<T> {
     /**

node/index.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for non-npm package Node.js 20.4
+// Type definitions for non-npm package Node.js 20.5
 // Project: https://nodejs.org/
 // Definitions by: Microsoft TypeScript <https://github.com/Microsoft>
 //                 DefinitelyTyped <https://github.com/DefinitelyTyped>

node/net.d.ts

@@ -639,6 +639,11 @@ declare module 'net' {
         prependOnceListener(event: 'error', listener: (err: Error) => void): this;
         prependOnceListener(event: 'listening', listener: () => void): this;
         prependOnceListener(event: 'drop', listener: (data?: DropArgument) => void): this;
+        /**
+         * Calls {@link Server.close()} and returns a promise that fulfills when the server has closed.
+         * @since v20.5.0
+         */
+        [Symbol.asyncDispose](): Promise<void>;
     }
     type IPVersion = 'ipv4' | 'ipv6';
     /**

node/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@types/node",
-    "version": "20.4.9",
+    "version": "20.5.0",
     "description": "TypeScript definitions for Node.js",
     "homepage": "https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node",
     "license": "MIT",
@@ -227,6 +227,6 @@
     },
     "scripts": {},
     "dependencies": {},
-    "typesPublisherContentHash": "b2f4c2c06161f1c6a01968b024abf85b1541142467b4d7a7fe451165a706da3f",
+    "typesPublisherContentHash": "83e291a6a60ec56a2b56b6b885ae9a0ea199888a482d63f4a22270483f82f2a9",
     "typeScriptVersion": "4.3"
 }

node/stream.d.ts

@@ -477,6 +477,11 @@ declare module 'stream' {
         removeListener(event: 'resume', listener: () => void): this;
         removeListener(event: string | symbol, listener: (...args: any[]) => void): this;
         [Symbol.asyncIterator](): AsyncIterableIterator<any>;
+        /**
+         * Calls `readable.destroy()` with an `AbortError` and returns a promise that fulfills when the stream is finished.
+         * @since v20.4.0
+         */
+        [Symbol.asyncDispose](): Promise<void>;
     }
     import WritableOptions = internal.WritableOptions;
     class WritableBase extends Stream implements NodeJS.WritableStream {

node/test.d.ts

@@ -259,6 +259,16 @@ declare module 'node:test' {
      * If the test uses callbacks, the callback function is passed as an argument
      */
     type SuiteFn = (s: SuiteContext) => void | Promise<void>;
+    interface TestShard {
+        /**
+         * A positive integer between 1 and `<total>` that specifies the index of the shard to run.
+         */
+        index: number;
+        /**
+         * A positive integer that specifies the total number of shards to split the test files to.
+         */
+        total: number;
+    }
     interface RunOptions {
         /**
          * If a number is provided, then that many files would run in parallel.
@@ -301,9 +311,15 @@ declare module 'node:test' {
          */
         setup?: (root: Test) => void | Promise<void>;
         /**
-         * Whether to run in watch mode or not. Default: false.
+         * Whether to run in watch mode or not.
+         * @default false
          */
-        watch?: boolean;
+        watch?: boolean | undefined;
+        /**
+         * Running tests in a specific shard.
+         * @default undefined
+         */
+        shard?: TestShard | undefined;
     }
     class Test extends AsyncResource {
         concurrency: number;
@@ -1210,6 +1226,10 @@ declare module 'node:test' {
          * @since v20.4.0
          */
         runAll(): void;
+        /**
+         * Calls {@link MockTimers.reset()}.
+         */
+        [Symbol.dispose](): void;
     }
     export { test as default, run, test, describe, it, before, after, beforeEach, afterEach, mock, skip, only, todo };
 }
@@ -1241,6 +1261,11 @@ interface TestFail {
          * The error thrown by the test.
          */
         error: Error;
+        /**
+         * The type of the test, used to denote whether this is a suite.
+         * @since 20.0.0, 19.9.0, 18.17.0
+         */
+        type?: 'suite';
     };
     /**
      * The test name.
@@ -1276,6 +1301,11 @@ interface TestPass {
          * The duration of the test in milliseconds.
          */
         duration_ms: number;
+        /**
+         * The type of the test, used to denote whether this is a suite.
+         * @since 20.0.0, 19.9.0, 18.17.0
+         */
+        type?: 'suite';
     };
     /**
      * The test name.

node/timers.d.ts

@@ -68,6 +68,11 @@ declare module 'timers' {
                  */
                 hasRef(): boolean;
                 _onImmediate: Function; // to distinguish it from the Timeout class
+                /**
+                 * Cancels the immediate. This is similar to calling `clearImmediate()`.
+                 * @since v20.5.0
+                 */
+                [Symbol.dispose](): void;
             }
             /**
              * This object is created internally and is returned from `setTimeout()` and `setInterval()`. It can be passed to either `clearTimeout()` or `clearInterval()` in order to cancel the
@@ -114,6 +119,11 @@ declare module 'timers' {
                  */
                 refresh(): this;
                 [Symbol.toPrimitive](): number;
+                /**
+                 * Cancels the timeout.
+                 * @since v20.5.0
+                 */
+                [Symbol.dispose](): void;
             }
         }
         /**
@@ -163,10 +173,10 @@ declare module 'timers' {
          * @param args Optional arguments to pass when the `callback` is called.
          * @return for use with {@link clearInterval}
          */
-        function setInterval<TArgs extends any[]>(callback: (...args: TArgs) => void, ms?: number, ...args: TArgs): NodeJS.Timer;
+        function setInterval<TArgs extends any[]>(callback: (...args: TArgs) => void, ms?: number, ...args: TArgs): NodeJS.Timeout;
         // util.promisify no rest args compability
         // tslint:disable-next-line void-return
-        function setInterval(callback: (args: void) => void, ms?: number): NodeJS.Timer;
+        function setInterval(callback: (args: void) => void, ms?: number): NodeJS.Timeout;
         namespace setInterval {
             const __promisify__: typeof setIntervalPromise;
         }

node/ts4.8/child_process.d.ts

@@ -302,6 +302,11 @@ declare module 'child_process' {
          * @since v0.1.90
          */
         kill(signal?: NodeJS.Signals | number): boolean;
+        /**
+         * Calls {@link ChildProcess.kill} with `'SIGTERM'`.
+         * @since v20.5.0
+         */
+        [Symbol.dispose](): void;
         /**
          * When an IPC channel has been established between the parent and child (
          * i.e. when using {@link fork}), the `subprocess.send()` method can

node/ts4.8/dgram.d.ts

@@ -538,6 +538,11 @@ declare module 'dgram' {
         prependOnceListener(event: 'error', listener: (err: Error) => void): this;
         prependOnceListener(event: 'listening', listener: () => void): this;
         prependOnceListener(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this;
+        /**
+         * Calls `socket.close()` and returns a promise that fulfills when the socket has closed.
+         * @since v20.5.0
+         */
+        [Symbol.asyncDispose](): Promise<void>;
     }
 }
 declare module 'node:dgram' {

node/ts4.8/events.d.ts

@@ -338,6 +338,41 @@ declare module 'events' {
          * objects.
          */
         static setMaxListeners(n?: number, ...eventTargets: Array<_DOMEventTarget | NodeJS.EventEmitter>): void;
+        /**
+         * Listens once to the `abort` event on the provided `signal`.
+         *
+         * Listening to the `abort` event on abort signals is unsafe and may
+         * lead to resource leaks since another third party with the signal can
+         * call `e.stopImmediatePropagation()`. Unfortunately Node.js cannot change
+         * this since it would violate the web standard. Additionally, the original
+         * API makes it easy to forget to remove listeners.
+         *
+         * This API allows safely using `AbortSignal`s in Node.js APIs by solving these
+         * two issues by listening to the event such that `stopImmediatePropagation` does
+         * not prevent the listener from running.
+         *
+         * Returns a disposable so that it may be unsubscribed from more easily.
+         *
+         * ```js
+         * import { addAbortListener } from 'node:events';
+         *
+         * function example(signal) {
+         *   let disposable;
+         *   try {
+         *     signal.addEventListener('abort', (e) => e.stopImmediatePropagation());
+         *     disposable = addAbortListener(signal, (e) => {
+         *       // Do something when signal is aborted.
+         *     });
+         *   } finally {
+         *     disposable?.[Symbol.dispose]();
+         *   }
+         * }
+         * ```
+         * @since v20.5.0
+         * @experimental
+         * @return that removes the `abort` listener.
+         */
+        static addAbortListener(signal: AbortSignal, resource: (event: Event) => void): Disposable;
         /**
          * This symbol shall be used to install a listener for only monitoring `'error'`events. Listeners installed using this symbol are called before the regular`'error'` listeners are called.
          *

node/ts4.8/fs/promises.d.ts

@@ -456,6 +456,11 @@ declare module 'fs/promises' {
          * @return Fulfills with `undefined` upon success.
          */
         close(): Promise<void>;
+        /**
+         * An alias for {@link FileHandle.close()}.
+         * @since v20.4.0
+         */
+        [Symbol.asyncDispose](): Promise<void>;
     }
     const constants: typeof fsConstants;
     /**

node/ts4.8/globals.d.ts

@@ -84,6 +84,28 @@ declare var AbortSignal: typeof globalThis extends {onmessage: any; AbortSignal:
     };
 //#endregion borrowed
 
+//#region Disposable
+interface SymbolConstructor {
+    /**
+     * A method that is used to release resources held by an object. Called by the semantics of the `using` statement.
+     */
+    readonly dispose: unique symbol;
+
+    /**
+     * A method that is used to asynchronously release resources held by an object. Called by the semantics of the `await using` statement.
+     */
+    readonly asyncDispose: unique symbol;
+}
+
+interface Disposable {
+    [Symbol.dispose](): void;
+}
+
+interface AsyncDisposable {
+    [Symbol.asyncDispose](): PromiseLike<void>;
+}
+//#endregion Disposable
+
 //#region ArrayLike.at()
 interface RelativeIndexable<T> {
     /**

node/ts4.8/net.d.ts

@@ -639,6 +639,11 @@ declare module 'net' {
         prependOnceListener(event: 'error', listener: (err: Error) => void): this;
         prependOnceListener(event: 'listening', listener: () => void): this;
         prependOnceListener(event: 'drop', listener: (data?: DropArgument) => void): this;
+        /**
+         * Calls {@link Server.close()} and returns a promise that fulfills when the server has closed.
+         * @since v20.5.0
+         */
+        [Symbol.asyncDispose](): Promise<void>;
     }
     type IPVersion = 'ipv4' | 'ipv6';
     /**