@types/node 18.11.5 → 20.2.5

node/ts4.8/assert.d.ts

@@ -1,7 +1,7 @@
 /**
- * The `assert` module provides a set of assertion functions for verifying
+ * The `node:assert` module provides a set of assertion functions for verifying
  * invariants.
- * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/assert.js)
+ * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/assert.js)
  */
 declare module 'assert' {
     /**
@@ -12,14 +12,28 @@ declare module 'assert' {
     function assert(value: unknown, message?: string | Error): asserts value;
     namespace assert {
         /**
-         * Indicates the failure of an assertion. All errors thrown by the `assert` module
-         * will be instances of the `AssertionError` class.
+         * Indicates the failure of an assertion. All errors thrown by the `node:assert`module will be instances of the `AssertionError` class.
          */
         class AssertionError extends Error {
+            /**
+             * Set to the `actual` argument for methods such as {@link assert.strictEqual()}.
+             */
             actual: unknown;
+            /**
+             * Set to the `expected` argument for methods such as {@link assert.strictEqual()}.
+             */
             expected: unknown;
+            /**
+             * Set to the passed in operator value.
+             */
             operator: string;
+            /**
+             * Indicates if the message was auto-generated (`true`) or not.
+             */
             generatedMessage: boolean;
+            /**
+             * Value is always `ERR_ASSERTION` to show that the error is an assertion error.
+             */
             code: 'ERR_ASSERTION';
             constructor(options?: {
                 /** If provided, the error message is set to this value. */
@@ -36,9 +50,10 @@ declare module 'assert' {
             });
         }
         /**
-         * This feature is currently experimental and behavior might still change.
+         * This feature is deprecated and will be removed in a future version.
+         * Please consider using alternatives such as the `mock` helper function.
          * @since v14.2.0, v12.19.0
-         * @experimental
+         * @deprecated Deprecated
          */
         class CallTracker {
             /**
@@ -47,7 +62,7 @@ declare module 'assert' {
              * error.
              *
              * ```js
-             * import assert from 'assert';
+             * import assert from 'node:assert';
              *
              * // Creates call tracker.
              * const tracker = new assert.CallTracker();
@@ -78,12 +93,11 @@ declare module 'assert' {
              * callsfunc(1, 2, 3);
              *
              * assert.deepStrictEqual(tracker.getCalls(callsfunc),
-             *                        [{ thisArg: this, arguments: [1, 2, 3 ] }]);
+             *                        [{ thisArg: undefined, arguments: [1, 2, 3] }]);
              * ```
-             *
              * @since v18.8.0, v16.18.0
-             * @params fn
-             * @returns An Array with the calls to a tracked function.
+             * @param fn
+             * @return An Array with all the calls to a tracked function.
              */
             getCalls(fn: Function): CallTrackerCall[];
             /**
@@ -91,21 +105,19 @@ declare module 'assert' {
              * the functions that have not been called the expected number of times.
              *
              * ```js
-             * import assert from 'assert';
+             * import assert from 'node:assert';
              *
              * // Creates call tracker.
              * const tracker = new assert.CallTracker();
              *
              * function func() {}
              *
-             * function foo() {}
-             *
              * // Returns a function that wraps func() that must be called exact times
              * // before tracker.verify().
              * const callsfunc = tracker.calls(func, 2);
              *
              * // Returns an array containing information on callsfunc()
-             * tracker.report();
+             * console.log(tracker.report());
              * // [
              * //  {
              * //    message: 'Expected the func function to be executed 2 time(s) but was
@@ -118,7 +130,7 @@ declare module 'assert' {
              * // ]
              * ```
              * @since v14.2.0, v12.19.0
-             * @return of objects containing information about the wrapper functions returned by `calls`.
+             * @return An Array of objects containing information about the wrapper functions returned by `calls`.
              */
             report(): CallTrackerReportInformation[];
             /**
@@ -136,12 +148,11 @@ declare module 'assert' {
              *
              * callsfunc();
              * // Tracker was called once
-             * tracker.getCalls(callsfunc).length === 1;
+             * assert.strictEqual(tracker.getCalls(callsfunc).length, 1);
              *
              * tracker.reset(callsfunc);
-             * tracker.getCalls(callsfunc).length === 0;
+             * assert.strictEqual(tracker.getCalls(callsfunc).length, 0);
              * ```
-             *
              * @since v18.8.0, v16.18.0
              * @param fn a tracked function to reset.
              */
@@ -151,7 +162,7 @@ declare module 'assert' {
              * have not been called the expected number of times.
              *
              * ```js
-             * import assert from 'assert';
+             * import assert from 'node:assert';
              *
              * // Creates call tracker.
              * const tracker = new assert.CallTracker();
@@ -193,7 +204,7 @@ declare module 'assert' {
          * it will be thrown instead of the `AssertionError`.
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * assert.fail();
          * // AssertionError [ERR_ASSERTION]: Failed
@@ -231,7 +242,7 @@ declare module 'assert' {
          * thrown in a file! See below for further details.
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * assert.ok(true);
          * // OK
@@ -266,7 +277,7 @@ declare module 'assert' {
          * ```
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * // Using `assert()` works the same:
          * assert(0);
@@ -291,7 +302,7 @@ declare module 'assert' {
          * and treated as being identical if both sides are `NaN`.
          *
          * ```js
-         * import assert from 'assert';
+         * import assert from 'node:assert';
          *
          * assert.equal(1, 1);
          * // OK, 1 == 1
@@ -324,7 +335,7 @@ declare module 'assert' {
          * specially handled and treated as being identical if both sides are `NaN`.
          *
          * ```js
-         * import assert from 'assert';
+         * import assert from 'node:assert';
          *
          * assert.notEqual(1, 2);
          * // OK
@@ -371,24 +382,24 @@ declare module 'assert' {
          * Tests for any deep inequality. Opposite of {@link deepEqual}.
          *
          * ```js
-         * import assert from 'assert';
+         * import assert from 'node:assert';
          *
          * const obj1 = {
          *   a: {
-         *     b: 1
-         *   }
+         *     b: 1,
+         *   },
          * };
          * const obj2 = {
          *   a: {
-         *     b: 2
-         *   }
+         *     b: 2,
+         *   },
          * };
          * const obj3 = {
          *   a: {
-         *     b: 1
-         *   }
+         *     b: 1,
+         *   },
          * };
-         * const obj4 = Object.create(obj1);
+         * const obj4 = { __proto__: obj1 };
          *
          * assert.notDeepEqual(obj1, obj1);
          * // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
@@ -414,7 +425,7 @@ declare module 'assert' {
          * determined by [`Object.is()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is).
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * assert.strictEqual(1, 2);
          * // AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:
@@ -452,7 +463,7 @@ declare module 'assert' {
          * determined by [`Object.is()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is).
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * assert.notStrictEqual(1, 2);
          * // OK
@@ -483,7 +494,7 @@ declare module 'assert' {
          * Tests for deep strict inequality. Opposite of {@link deepStrictEqual}.
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * assert.notDeepStrictEqual({ a: 1 }, { a: '1' });
          * // OK
@@ -514,14 +525,14 @@ declare module 'assert' {
          * Custom validation object/error instance:
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * const err = new TypeError('Wrong value');
          * err.code = 404;
          * err.foo = 'bar';
          * err.info = {
          *   nested: true,
-         *   baz: 'text'
+         *   baz: 'text',
          * };
          * err.reg = /abc/i;
          *
@@ -534,16 +545,16 @@ declare module 'assert' {
          *     message: 'Wrong value',
          *     info: {
          *       nested: true,
-         *       baz: 'text'
-         *     }
+         *       baz: 'text',
+         *     },
          *     // Only properties on the validation object will be tested for.
          *     // Using nested objects requires all properties to be present. Otherwise
          *     // the validation is going to fail.
-         *   }
+         *   },
          * );
          *
          * // Using regular expressions to validate error properties:
-         * throws(
+         * assert.throws(
          *   () => {
          *     throw err;
          *   },
@@ -557,17 +568,17 @@ declare module 'assert' {
          *     info: {
          *       nested: true,
          *       // It is not possible to use regular expressions for nested properties!
-         *       baz: 'text'
+         *       baz: 'text',
          *     },
          *     // The `reg` property contains a regular expression and only if the
          *     // validation object contains an identical regular expression, it is going
          *     // to pass.
-         *     reg: /abc/i
-         *   }
+         *     reg: /abc/i,
+         *   },
          * );
          *
          * // Fails due to the different `message` and `name` properties:
-         * throws(
+         * assert.throws(
          *   () => {
          *     const otherErr = new Error('Not found');
          *     // Copy all enumerable properties from `err` to `otherErr`.
@@ -578,20 +589,20 @@ declare module 'assert' {
          *   },
          *   // The error's `message` and `name` properties will also be checked when using
          *   // an error as validation object.
-         *   err
+         *   err,
          * );
          * ```
          *
          * Validate instanceof using constructor:
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * assert.throws(
          *   () => {
          *     throw new Error('Wrong value');
          *   },
-         *   Error
+         *   Error,
          * );
          * ```
          *
@@ -601,13 +612,13 @@ declare module 'assert' {
          * therefore also include the error name.
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * assert.throws(
          *   () => {
          *     throw new Error('Wrong value');
          *   },
-         *   /^Error: Wrong value$/
+         *   /^Error: Wrong value$/,
          * );
          * ```
          *
@@ -617,7 +628,7 @@ declare module 'assert' {
          * It will otherwise fail with an `AssertionError`.
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * assert.throws(
          *   () => {
@@ -633,7 +644,7 @@ declare module 'assert' {
          *     // possible.
          *     return true;
          *   },
-         *   'unexpected error'
+         *   'unexpected error',
          * );
          * ```
          *
@@ -643,7 +654,7 @@ declare module 'assert' {
          * a string as the second argument gets considered:
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * function throwingFirst() {
          *   throw new Error('First');
@@ -699,20 +710,20 @@ declare module 'assert' {
          * propagated back to the caller.
          *
          * If specified, `error` can be a [`Class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes),
-         * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) or a validation
+         * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions), or a validation
          * function. See {@link throws} for more details.
          *
          * The following, for instance, will throw the `TypeError` because there is no
          * matching error type in the assertion:
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * assert.doesNotThrow(
          *   () => {
          *     throw new TypeError('Wrong value');
          *   },
-         *   SyntaxError
+         *   SyntaxError,
          * );
          * ```
          *
@@ -720,27 +731,27 @@ declare module 'assert' {
          * 'Got unwanted exception...':
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * assert.doesNotThrow(
          *   () => {
          *     throw new TypeError('Wrong value');
          *   },
-         *   TypeError
+         *   TypeError,
          * );
          * ```
          *
          * If an `AssertionError` is thrown and a value is provided for the `message`parameter, the value of `message` will be appended to the `AssertionError` message:
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * assert.doesNotThrow(
          *   () => {
          *     throw new TypeError('Wrong value');
          *   },
          *   /Wrong value/,
-         *   'Whoops'
+         *   'Whoops',
          * );
          * // Throws: AssertionError: Got unwanted exception: Whoops
          * ```
@@ -754,7 +765,7 @@ declare module 'assert' {
          * from the error passed to `ifError()` including the potential new frames for`ifError()` itself.
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * assert.ifError(null);
          * // OK
@@ -800,7 +811,7 @@ declare module 'assert' {
          * If specified, `message` will be the message provided by the `AssertionError` if the `asyncFn` fails to reject.
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * await assert.rejects(
          *   async () => {
@@ -808,13 +819,13 @@ declare module 'assert' {
          *   },
          *   {
          *     name: 'TypeError',
-         *     message: 'Wrong value'
-         *   }
+         *     message: 'Wrong value',
+         *   },
          * );
          * ```
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * await assert.rejects(
          *   async () => {
@@ -824,16 +835,16 @@ declare module 'assert' {
          *     assert.strictEqual(err.name, 'TypeError');
          *     assert.strictEqual(err.message, 'Wrong value');
          *     return true;
-         *   }
+         *   },
          * );
          * ```
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * assert.rejects(
          *   Promise.reject(new Error('Wrong value')),
-         *   Error
+         *   Error,
          * ).then(() => {
          *   // ...
          * });
@@ -863,24 +874,24 @@ declare module 'assert' {
          * error messages as expressive as possible.
          *
          * If specified, `error` can be a [`Class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes),
-         * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) or a validation
+         * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions), or a validation
          * function. See {@link throws} for more details.
          *
          * Besides the async nature to await the completion behaves identically to {@link doesNotThrow}.
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * await assert.doesNotReject(
          *   async () => {
          *     throw new TypeError('Wrong value');
          *   },
-         *   SyntaxError
+         *   SyntaxError,
          * );
          * ```
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * assert.doesNotReject(Promise.reject(new TypeError('Wrong value')))
          *   .then(() => {
@@ -895,7 +906,7 @@ declare module 'assert' {
          * Expects the `string` input to match the regular expression.
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * assert.match('I will fail', /pass/);
          * // AssertionError [ERR_ASSERTION]: The input did not match the regular ...
@@ -918,7 +929,7 @@ declare module 'assert' {
          * Expects the `string` input not to match the regular expression.
          *
          * ```js
-         * import assert from 'assert/strict';
+         * import assert from 'node:assert/strict';
          *
          * assert.doesNotMatch('I will fail', /fail/);
          * // AssertionError [ERR_ASSERTION]: The input was expected to not match the ...