DefinitelyTyped · typescript-bot · Aug 13, 2023 · Aug 11, 2023
@@ -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

@@ -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' {

@@ -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.
          *

@@ -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;
     /**

@@ -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> {
     /**

@@ -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>

@@ -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';
     /**

@@ -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 {

@@ -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 };
 }

@@ -377,6 +377,7 @@ async function testPromisify() {
     _boolean = cp.kill();
     _boolean = cp.kill(9);
     _boolean = cp.kill("SIGTERM");
+    cp[Symbol.dispose]();
 
     _maybeNumber = cp.exitCode;
     _maybeSignal = cp.signalCode;

@@ -18,6 +18,7 @@ import * as dns from 'node:dns';
     ds = ds.close();
     ds.setMulticastInterface("127.0.0.1");
     ds = dgram.createSocket({ type: "udp4", reuseAddr: true, recvBufferSize: 1000, sendBufferSize: 1000, lookup: dns.lookup });
+    ds[Symbol.asyncDispose]();
 }
 
 {

@@ -130,3 +130,16 @@ async function test() {
     const eventEmitter = new events.EventEmitter();
     events.EventEmitter.setMaxListeners(42, eventTarget, eventEmitter);
 }
+
+{
+    let disposable: Disposable | undefined;
+    try {
+        const signal = new AbortSignal();
+        signal.addEventListener('abort', (e) => e.stopImmediatePropagation());
+        disposable = events.addAbortListener(signal, (e) => {
+            console.log(e);
+        });
+    } finally {
+        disposable?.[Symbol.dispose]();
+    }
+}
@@ -35,6 +35,9 @@ import * as dns from 'node:dns';
         keepAliveTimeout: 100
     }, reqListener);
 
+    server.close();
+    server[Symbol.asyncDispose]();
+
     // test public props
     const maxHeadersCount: number | null = server.maxHeadersCount;
     const maxRequestsPerSocket: number | null = server.maxRequestsPerSocket;

@@ -351,6 +351,7 @@ import { Socket } from 'node:dgram';
 
     _socket.destroy();
     _server.close();
+    _server[Symbol.asyncDispose]();
 }
 
 {

@@ -521,6 +521,9 @@ function stream_readable_pipe_test() {
     r.close();
     z.close();
     rs.close();
+
+    rs.destroy();
+    rs[Symbol.asyncDispose]();
 }
 
 function stream_duplex_allowHalfOpen_test() {

@@ -22,7 +22,11 @@ run({
     inspectPort: () => 8081,
     testNamePatterns: ['executed'],
     setup: (root) => {},
-    watch: true
+    watch: true,
+    shard: {
+        index: 1,
+        total: 3,
+    },
 });
 
 // TestsStream should be a NodeJS.ReadableStream

@@ -96,9 +96,12 @@ import * as timers from 'node:timers';
     function waitFor(options?: { timeout: number }) {
         const timerId = options && setTimeout(() => {}, options.timeout);
         clearTimeout(timerId);
+        timerId?.[Symbol.dispose]();
         const intervalId = options && setTimeout(() => {}, options.timeout);
         clearInterval(intervalId);
+        intervalId?.[Symbol.dispose]();
         const immediateId = options && setImmediate(() => {});
         clearImmediate(immediateId);
+        immediateId?.[Symbol.dispose]();
     }
 }
@@ -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;
         }

@@ -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

@@ -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' {

@@ -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.
          *

@@ -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;
     /**
-Original file line number
+Diff line change
@@ Expand Up / @@ -351,6 +351,7 @@ import { Socket } from 'node:dgram'; @@
         _socket.destroy();
         _server.close();
+        _server[Symbol.asyncDispose]();
     }
     {
@@ Expand Down @@