@types/node 18.16.3 → 20.0.0

node/test.d.ts

@@ -10,7 +10,6 @@ declare module 'node:test' {
      * @returns A {@link TestsStream} that emits events about the test execution.
      */
     function run(options?: RunOptions): TestsStream;
-
     /**
      * The `test()` function is the value imported from the test module. Each invocation of this
      * function results in reporting the test to the {@link TestsStream}.
@@ -49,7 +48,6 @@ declare module 'node:test' {
     function test(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
     function test(options?: TestOptions, fn?: TestFn): Promise<void>;
     function test(fn?: TestFn): Promise<void>;
-
     /**
      * @since v18.6.0
      * @param name The name of the suite, which is displayed when reporting suite results.
@@ -67,14 +65,12 @@ declare module 'node:test' {
         function skip(name?: string, fn?: SuiteFn): void;
         function skip(options?: TestOptions, fn?: SuiteFn): void;
         function skip(fn?: SuiteFn): void;
-
         // Shorthand for marking a suite as `TODO`, same as `describe([name], { todo: true }[, fn])`.
         function todo(name?: string, options?: TestOptions, fn?: SuiteFn): void;
         function todo(name?: string, fn?: SuiteFn): void;
         function todo(options?: TestOptions, fn?: SuiteFn): void;
         function todo(fn?: SuiteFn): void;
     }
-
     /**
      * @since v18.6.0
      * @param name The name of the test, which is displayed when reporting test results.
@@ -93,33 +89,28 @@ declare module 'node:test' {
         function skip(name?: string, fn?: ItFn): void;
         function skip(options?: TestOptions, fn?: ItFn): void;
         function skip(fn?: ItFn): void;
-
         // Shorthand for marking a test as `TODO`, same as `it([name], { todo: true }[, fn])`.
         function todo(name?: string, options?: TestOptions, fn?: ItFn): void;
         function todo(name?: string, fn?: ItFn): void;
         function todo(options?: TestOptions, fn?: ItFn): void;
         function todo(fn?: ItFn): void;
     }
-
     /**
      * The type of a function under test. The first argument to this function is a
      * {@link TestContext} object. If the test uses callbacks, the callback function is passed as
      * the second argument.
      */
     type TestFn = (t: TestContext, done: (result?: any) => void) => any;
-
     /**
      * The type of a function under Suite.
      * If the test uses callbacks, the callback function is passed as an argument
      */
     type SuiteFn = (done: (result?: any) => void) => void;
-
     /**
      * The type of a function under test.
      * If the test uses callbacks, the callback function is passed as an argument
      */
     type ItFn = (done: (result?: any) => void) => any;
-
     interface RunOptions {
         /**
          * If a number is provided, then that many files would run in parallel.
@@ -129,26 +120,22 @@ declare module 'node:test' {
          * @default true
          */
         concurrency?: number | boolean | undefined;
-
         /**
          * An array containing the list of files to run.
          * If unspecified, the test runner execution model will be used.
          */
         files?: readonly string[] | undefined;
-
         /**
          * Allows aborting an in-progress test execution.
          * @default undefined
          */
         signal?: AbortSignal | undefined;
-
         /**
          * A number of milliseconds the test will fail after.
          * If unspecified, subtests inherit this value from their parent.
          * @default Infinity
          */
         timeout?: number | undefined;
-
         /**
          * Sets inspector port of test child process.
          * If a nullish value is provided, each process gets its own port,
@@ -156,7 +143,6 @@ declare module 'node:test' {
          */
         inspectPort?: number | (() => number) | undefined;
     }
-
     /**
      * A successful call of the `run()` method will return a new `TestsStream` object,
      * streaming a series of events representing the execution of the tests.
@@ -201,19 +187,16 @@ declare module 'node:test' {
         prependOnceListener(event: 'test:start', listener: (data: TestStart) => void): this;
         prependOnceListener(event: string, listener: (...args: any[]) => void): this;
     }
-
     interface DiagnosticData {
         /**
          * The diagnostic message.
          */
         message: string;
-
         /**
          * The nesting level of the test.
          */
         nesting: number;
     }
-
     interface TestFail {
         /**
          * Additional execution metadata.
@@ -223,39 +206,32 @@ declare module 'node:test' {
              * The duration of the test in milliseconds.
              */
             duration: number;
-
             /**
              * The error thrown by the test.
              */
             error: Error;
         };
-
         /**
          * The test name.
          */
         name: string;
-
         /**
          * The nesting level of the test.
          */
         nesting: number;
-
         /**
          * The ordinal number of the test.
          */
         testNumber: number;
-
         /**
          * Present if `context.todo` is called.
          */
         todo?: string | boolean;
-
         /**
          * Present if `context.skip` is called.
          */
         skip?: string | boolean;
     }
-
     interface TestPass {
         /**
          * Additional execution metadata.
@@ -266,57 +242,47 @@ declare module 'node:test' {
              */
             duration: number;
         };
-
         /**
          * The test name.
          */
         name: string;
-
         /**
          * The nesting level of the test.
          */
         nesting: number;
-
         /**
          * The ordinal number of the test.
          */
         testNumber: number;
-
         /**
          * Present if `context.todo` is called.
          */
         todo?: string | boolean;
-
         /**
          * Present if `context.skip` is called.
          */
         skip?: string | boolean;
     }
-
     interface TestPlan {
         /**
          * The nesting level of the test.
          */
         nesting: number;
-
         /**
          * The number of subtests that have ran.
          */
         count: number;
     }
-
     interface TestStart {
         /**
          * The test name.
          */
         name: string;
-
         /**
          * The nesting level of the test.
          */
         nesting: number;
     }
-
     /**
      * An instance of `TestContext` is passed to each test function in order to interact with the
      * test runner. However, the `TestContext` constructor is not exposed as part of the API.
@@ -331,7 +297,6 @@ declare module 'node:test' {
          * @since v18.8.0
          */
         beforeEach: typeof beforeEach;
-
         /**
          * This function is used to create a hook that runs after the current test finishes.
          * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
@@ -340,7 +305,6 @@ declare module 'node:test' {
          * @since v18.13.0
          */
         after: typeof after;
-
         /**
          * This function is used to create a hook running after each subtest of the current test.
          * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
@@ -349,7 +313,6 @@ declare module 'node:test' {
          * @since v18.8.0
          */
         afterEach: typeof afterEach;
-
         /**
          * This function is used to write diagnostics to the output. Any diagnostic information is
          * included at the end of the test's results. This function does not return a value.
@@ -357,13 +320,11 @@ declare module 'node:test' {
          * @since v18.0.0
          */
         diagnostic(message: string): void;
-
         /**
          * The name of the test.
          * @since v18.8.0
          */
         readonly name: string;
-
         /**
          * If `shouldRunOnlyTests` is truthy, the test context will only run tests that have the `only`
          * option set. Otherwise, all tests are run. If Node.js was not started with the `--test-only`
@@ -372,13 +333,11 @@ declare module 'node:test' {
          * @since v18.0.0
          */
         runOnly(shouldRunOnlyTests: boolean): void;
-
         /**
          * Can be used to abort test subtasks when the test has been aborted.
          * @since v18.7.0
          */
         readonly signal: AbortSignal;
-
         /**
          * This function causes the test's output to indicate the test as skipped. If `message` is
          * provided, it is included in the output. Calling `skip()` does not terminate execution of
@@ -387,7 +346,6 @@ declare module 'node:test' {
          * @since v18.0.0
          */
         skip(message?: string): void;
-
         /**
          * This function adds a `TODO` directive to the test's output. If `message` is provided, it is
          * included in the output. Calling `todo()` does not terminate execution of the test
@@ -396,7 +354,6 @@ declare module 'node:test' {
          * @since v18.0.0
          */
         todo(message?: string): void;
-
         /**
          * This function is used to create subtests under the current test. This function behaves in
          * the same fashion as the top level {@link test} function.
@@ -415,7 +372,6 @@ declare module 'node:test' {
          */
         readonly mock: MockTracker;
     }
-
     interface TestOptions {
         /**
          * If a number is provided, then that many tests would run in parallel.
@@ -426,27 +382,23 @@ declare module 'node:test' {
          * @default false
          */
         concurrency?: number | boolean | undefined;
-
         /**
          * If truthy, and the test context is configured to run `only` tests, then this test will be
          * run. Otherwise, the test is skipped.
          * @default false
          */
         only?: boolean | undefined;
-
         /**
          * Allows aborting an in-progress test.
          * @since v18.8.0
          */
         signal?: AbortSignal | undefined;
-
         /**
          * If truthy, the test is skipped. If a string is provided, that string is displayed in the
          * test results as the reason for skipping the test.
          * @default false
          */
         skip?: boolean | string | undefined;
-
         /**
          * A number of milliseconds the test will fail after. If unspecified, subtests inherit this
          * value from their parent.
@@ -454,7 +406,6 @@ declare module 'node:test' {
          * @since v18.7.0
          */
         timeout?: number | undefined;
-
         /**
          * If truthy, the test marked as `TODO`. If a string is provided, that string is displayed in
          * the test results as the reason why the test is `TODO`.
@@ -462,7 +413,6 @@ declare module 'node:test' {
          */
         todo?: boolean | string | undefined;
     }
-
     /**
      * This function is used to create a hook running before running a suite.
      * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
@@ -471,7 +421,6 @@ declare module 'node:test' {
      * @since v18.8.0
      */
     function before(fn?: HookFn, options?: HookOptions): void;
-
     /**
      * This function is used to create a hook running after running a suite.
      * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
@@ -480,7 +429,6 @@ declare module 'node:test' {
      * @since v18.8.0
      */
     function after(fn?: HookFn, options?: HookOptions): void;
-
     /**
      * This function is used to create a hook running before each subtest of the current suite.
      * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
@@ -489,7 +437,6 @@ declare module 'node:test' {
      * @since v18.8.0
      */
     function beforeEach(fn?: HookFn, options?: HookOptions): void;
-
     /**
      * This function is used to create a hook running after each subtest of the current test.
      * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
@@ -498,13 +445,11 @@ declare module 'node:test' {
      * @since v18.8.0
      */
     function afterEach(fn?: HookFn, options?: HookOptions): void;
-
     /**
      * The hook function. If the hook uses callbacks, the callback function is passed as the
      * second argument.
      */
     type HookFn = (done: (result?: any) => void) => any;
-
     /**
      * Configuration options for hooks.
      * @since v18.8.0
@@ -514,7 +459,6 @@ declare module 'node:test' {
          * Allows aborting an in-progress hook.
          */
         signal?: AbortSignal | undefined;
-
         /**
          * A number of milliseconds the hook will fail after. If unspecified, subtests inherit this
          * value from their parent.
@@ -522,7 +466,6 @@ declare module 'node:test' {
          */
         timeout?: number | undefined;
     }
-
     interface MockFunctionOptions {
         /**
          * The number of times that the mock will use the behavior of `implementation`.
@@ -533,31 +476,25 @@ declare module 'node:test' {
          */
         times?: number | undefined;
     }
-
     interface MockMethodOptions extends MockFunctionOptions {
         /**
          * If `true`, `object[methodName]` is treated as a getter.
          * This option cannot be used with the `setter` option.
          */
         getter?: boolean | undefined;
-
         /**
          * If `true`, `object[methodName]` is treated as a setter.
          * This option cannot be used with the `getter` option.
          */
         setter?: boolean | undefined;
     }
-
     type Mock<F extends Function> = F & {
         mock: MockFunctionContext<F>;
     };
-
     type NoOpFunction = (...args: any[]) => undefined;
-
     type FunctionPropertyNames<T> = {
         [K in keyof T]: T[K] extends Function ? K : never;
     }[keyof T];
-
     interface MockTracker {
         /**
          * This function is used to create a mock function.
@@ -568,7 +505,6 @@ declare module 'node:test' {
          */
         fn<F extends Function = NoOpFunction>(original?: F, options?: MockFunctionOptions): Mock<F>;
         fn<F extends Function = NoOpFunction, Implementation extends Function = F>(original?: F, implementation?: Implementation, options?: MockFunctionOptions): Mock<F | Implementation>;
-
         /**
          * This function is used to create a mock on an existing object method.
          * @param object The object whose method is being mocked.
@@ -631,7 +567,6 @@ declare module 'node:test' {
             implementation?: Implementation,
             options?: MockFunctionOptions,
         ): Mock<(() => MockedObject[MethodName]) | Implementation>;
-
         /**
          * This function is syntax sugar for {@link MockTracker.method} with `options.setter` set to `true`.
          */
@@ -653,7 +588,6 @@ declare module 'node:test' {
             implementation?: Implementation,
             options?: MockFunctionOptions,
         ): Mock<((value: MockedObject[MethodName]) => void) | Implementation>;
-
         /**
          * This function restores the default behavior of all mocks that were previously created by this `MockTracker`
          * and disassociates the mocks from the `MockTracker` instance. Once disassociated, the mocks can still be used,
@@ -663,16 +597,13 @@ declare module 'node:test' {
          * If the global `MockTracker` is used extensively, calling this function manually is recommended.
          */
         reset(): void;
-
         /**
          * This function restores the default behavior of all mocks that were previously created by this `MockTracker`.
          * Unlike `mock.reset()`, `mock.restoreAll()` does not disassociate the mocks from the `MockTracker` instance.
          */
         restoreAll(): void;
     }
-
     const mock: MockTracker;
-
     interface MockFunctionCall<
         F extends Function,
         ReturnType = F extends (...args: any) => infer T
@@ -714,26 +645,22 @@ declare module 'node:test' {
          */
         this: unknown;
     }
-
     interface MockFunctionContext<F extends Function> {
         /**
          * A getter that returns a copy of the internal array used to track calls to the mock.
          */
         readonly calls: Array<MockFunctionCall<F>>;
-
         /**
          * This function returns the number of times that this mock has been invoked.
          * This function is more efficient than checking `ctx.calls.length`
          * because `ctx.calls` is a getter that creates a copy of the internal call tracking array.
          */
         callCount(): number;
-
         /**
          * This function is used to change the behavior of an existing mock.
          * @param implementation The function to be used as the mock's new implementation.
          */
         mockImplementation(implementation: Function): void;
-
         /**
          * This function is used to change the behavior of an existing mock for a single invocation.
          * Once invocation `onCall` has occurred, the mock will revert to whatever behavior
@@ -743,18 +670,15 @@ declare module 'node:test' {
          *  If the specified invocation has already occurred then an exception is thrown.
          */
         mockImplementationOnce(implementation: Function, onCall?: number): void;
-
         /**
          * Resets the call history of the mock function.
          */
         resetCalls(): void;
-
         /**
          * Resets the implementation of the mock function to its original behavior.
          * The mock can still be used after calling this function.
          */
         restore(): void;
     }
-
     export { test as default, run, test, describe, it, before, after, beforeEach, afterEach, mock };
 }

node/timers/promises.d.ts

@@ -1,6 +1,6 @@
 /**
  * The `timers/promises` API provides an alternative set of timer functions
- * that return `Promise` objects. The API is accessible via`require('timers/promises')`.
+ * that return `Promise` objects. The API is accessible via`require('node:timers/promises')`.
  *
  * ```js
  * import {
@@ -44,6 +44,8 @@ declare module 'timers/promises' {
     function setImmediate<T = void>(value?: T, options?: TimerOptions): Promise<T>;
     /**
      * Returns an async iterator that generates values in an interval of `delay` ms.
+     * If `ref` is `true`, you need to call `next()` of async iterator explicitly
+     * or implicitly to keep the event loop alive.
      *
      * ```js
      * import {
@@ -62,7 +64,6 @@ declare module 'timers/promises' {
      * @since v15.9.0
      */
     function setInterval<T = void>(delay?: number, value?: T, options?: TimerOptions): AsyncIterable<T>;
-
     interface Scheduler {
         /**
          * ```js
@@ -85,7 +86,6 @@ declare module 'timers/promises' {
          */
         yield: () => Promise<void>;
     }
-
     const scheduler: Scheduler;
 }
 declare module 'node:timers/promises' {

node/timers.d.ts

@@ -1,12 +1,12 @@
 /**
  * The `timer` module exposes a global API for scheduling functions to
  * be called at some future period of time. Because the timer functions are
- * globals, there is no need to call `require('timers')` to use the API.
+ * globals, there is no need to call `require('node:timers')` to use the API.
  *
  * The timer functions within Node.js implement a similar API as the timers API
  * provided by Web Browsers but use a different internal implementation that is
  * built around the Node.js [Event Loop](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/#setimmediate-vs-settimeout).
- * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/timers.js)
+ * @see [source](https://github.com/nodejs/node/blob/v20.0.0/lib/timers.js)
  */
 declare module 'timers' {
     import { Abortable } from 'node:events';

node/tls.d.ts

@@ -1,12 +1,12 @@
 /**
- * The `tls` module provides an implementation of the Transport Layer Security
+ * The `node:tls` module provides an implementation of the Transport Layer Security
  * (TLS) and Secure Socket Layer (SSL) protocols that is built on top of OpenSSL.
  * The module can be accessed using:
  *
  * ```js
- * const tls = require('tls');
+ * const tls = require('node:tls');
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/tls.js)
+ * @see [source](https://github.com/nodejs/node/blob/v20.0.0/lib/tls.js)
  */
 declare module 'tls' {
     import { X509Certificate } from 'node:crypto';
@@ -212,7 +212,7 @@ declare module 'tls' {
      *
      * Instances of `tls.TLSSocket` implement the duplex `Stream` interface.
      *
-     * Methods that return TLS connection metadata (e.g.{@link TLSSocket.getPeerCertificate} will only return data while the
+     * Methods that return TLS connection metadata (e.g.{@link TLSSocket.getPeerCertificate}) will only return data while the
      * connection is open.
      * @since v0.11.4
      */
@@ -259,13 +259,13 @@ declare module 'tls' {
         /**
          * Returns an object containing information on the negotiated cipher suite.
          *
-         * For example:
+         * For example, a TLSv1.2 protocol with AES256-SHA cipher:
          *
          * ```json
          * {
-         *     "name": "AES128-SHA256",
-         *     "standardName": "TLS_RSA_WITH_AES_128_CBC_SHA256",
-         *     "version": "TLSv1.2"
+         *     "name": "AES256-SHA",
+         *     "standardName": "TLS_RSA_WITH_AES_256_CBC_SHA",
+         *     "version": "SSLv3"
          * }
          * ```
          *
@@ -912,14 +912,14 @@ declare module 'tls' {
      * Creates a new {@link Server}. The `secureConnectionListener`, if provided, is
      * automatically set as a listener for the `'secureConnection'` event.
      *
-     * The `ticketKeys` options is automatically shared between `cluster` module
+     * The `ticketKeys` options is automatically shared between `node:cluster` module
      * workers.
      *
      * The following illustrates a simple echo server:
      *
      * ```js
-     * const tls = require('tls');
-     * const fs = require('fs');
+     * const tls = require('node:tls');
+     * const fs = require('node:fs');
      *
      * const options = {
      *   key: fs.readFileSync('server-key.pem'),
@@ -929,7 +929,7 @@ declare module 'tls' {
      *   requestCert: true,
      *
      *   // This is necessary only if the client uses a self-signed certificate.
-     *   ca: [ fs.readFileSync('client-cert.pem') ]
+     *   ca: [ fs.readFileSync('client-cert.pem') ],
      * };
      *
      * const server = tls.createServer(options, (socket) => {
@@ -964,8 +964,8 @@ declare module 'tls' {
      *
      * ```js
      * // Assumes an echo server that is listening on port 8000.
-     * const tls = require('tls');
-     * const fs = require('fs');
+     * const tls = require('node:tls');
+     * const fs = require('node:fs');
      *
      * const options = {
      *   // Necessary only if the server requires client certificate authentication.
@@ -1041,12 +1041,19 @@ declare module 'tls' {
      * APIs that create secure contexts have no default value.
      *
      * The `tls.createSecureContext()` method creates a `SecureContext` object. It is
-     * usable as an argument to several `tls` APIs, such as {@link createServer} and `server.addContext()`, but has no public methods.
+     * usable as an argument to several `tls` APIs, such as `server.addContext()`,
+     * but has no public methods. The {@link Server} constructor and the {@link createServer} method do not support the `secureContext` option.
      *
      * A key is _required_ for ciphers that use certificates. Either `key` or`pfx` can be used to provide it.
      *
      * If the `ca` option is not given, then Node.js will default to using [Mozilla's publicly trusted list of
      * CAs](https://hg.mozilla.org/mozilla-central/raw-file/tip/security/nss/lib/ckfw/builtins/certdata.txt).
+     *
+     * Custom DHE parameters are discouraged in favor of the new `dhparam: 'auto'`option. When set to `'auto'`, well-known DHE parameters of sufficient strength
+     * will be selected automatically. Otherwise, if necessary, `openssl dhparam` can
+     * be used to create custom parameters. The key length must be greater than or
+     * equal to 1024 bits or else an error will be thrown. Although 1024 bits is
+     * permissible, use 2048 bits or larger for stronger security.
      * @since v0.11.13
      */
     function createSecureContext(options?: SecureContextOptions): SecureContext;