From fee39ea59839836f1603fde94fccccaf7e6be5c1 Mon Sep 17 00:00:00 2001 From: Voltrex <62040526+VoltrexMaster@users.noreply.github.com> Date: Sat, 10 Apr 2021 23:13:52 +0430 Subject: [PATCH] typings: add JSDoc typings for assert MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR-URL: https://github.com/nodejs/node/pull/38188 Reviewed-By: Bradley Farias Reviewed-By: Michaël Zasso --- lib/assert.js | 131 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 123 insertions(+), 8 deletions(-) diff --git a/lib/assert.js b/lib/assert.js index af6b1fc59a953c..48daa56a29c4bd 100644 --- a/lib/assert.js +++ b/lib/assert.js @@ -105,6 +105,14 @@ function innerFail(obj) { throw new AssertionError(obj); } +/** + * @param {any} actual + * @param {any} expected + * @param {string | Error} [message] + * @param {string} [operator] + * @param {Function} [stackStartFn] + * @returns {never} + */ function fail(actual, expected, message, operator, stackStartFn) { const argsLen = arguments.length; @@ -384,14 +392,24 @@ function innerOk(fn, argLen, value, message) { } } -// Pure assertion tests whether a value is truthy, as determined -// by !!value. +/** + * Pure assertion tests whether a value is truthy, as determined + * by !!value. + * @param {...any} args + * @returns {void} + */ function ok(...args) { innerOk(ok, args.length, ...args); } assert.ok = ok; -// The equality assertion tests shallow, coercive equality with ==. +/** + * The equality assertion tests shallow, coercive equality with ==. + * @param {any} actual + * @param {any} expected + * @param {string | Error} [message] + * @returns {void} + */ /* eslint-disable no-restricted-properties */ assert.equal = function equal(actual, expected, message) { if (arguments.length < 2) { @@ -409,8 +427,14 @@ assert.equal = function equal(actual, expected, message) { } }; -// The non-equality assertion tests for whether two objects are not -// equal with !=. +/** + * The non-equality assertion tests for whether two objects are not + * equal with !=. + * @param {any} actual + * @param {any} expected + * @param {string | Error} [message] + * @returns {void} + */ assert.notEqual = function notEqual(actual, expected, message) { if (arguments.length < 2) { throw new ERR_MISSING_ARGS('actual', 'expected'); @@ -427,7 +451,13 @@ assert.notEqual = function notEqual(actual, expected, message) { } }; -// The equivalence assertion tests a deep equality relation. +/** + * The deep equivalence assertion tests a deep equality relation. + * @param {any} actual + * @param {any} expected + * @param {string | Error} [message] + * @returns {void} + */ assert.deepEqual = function deepEqual(actual, expected, message) { if (arguments.length < 2) { throw new ERR_MISSING_ARGS('actual', 'expected'); @@ -444,7 +474,13 @@ assert.deepEqual = function deepEqual(actual, expected, message) { } }; -// The non-equivalence assertion tests for any deep inequality. +/** + * The deep non-equivalence assertion tests for any deep inequality. + * @param {any} actual + * @param {any} expected + * @param {string | Error} [message] + * @returns {void} + */ assert.notDeepEqual = function notDeepEqual(actual, expected, message) { if (arguments.length < 2) { throw new ERR_MISSING_ARGS('actual', 'expected'); @@ -462,6 +498,14 @@ assert.notDeepEqual = function notDeepEqual(actual, expected, message) { }; /* eslint-enable */ +/** + * The deep strict equivalence assertion tests a deep strict equality + * relation. + * @param {any} actual + * @param {any} expected + * @param {string | Error} [message] + * @returns {void} + */ assert.deepStrictEqual = function deepStrictEqual(actual, expected, message) { if (arguments.length < 2) { throw new ERR_MISSING_ARGS('actual', 'expected'); @@ -478,6 +522,14 @@ assert.deepStrictEqual = function deepStrictEqual(actual, expected, message) { } }; +/** + * The deep strict non-equivalence assertion tests for any deep strict + * inequality. + * @param {any} actual + * @param {any} expected + * @param {string | Error} [message] + * @returns {void} + */ assert.notDeepStrictEqual = notDeepStrictEqual; function notDeepStrictEqual(actual, expected, message) { if (arguments.length < 2) { @@ -495,6 +547,13 @@ function notDeepStrictEqual(actual, expected, message) { } } +/** + * The strict equivalence assertion tests a strict equality relation. + * @param {any} actual + * @param {any} expected + * @param {string | Error} [message] + * @returns {void} + */ assert.strictEqual = function strictEqual(actual, expected, message) { if (arguments.length < 2) { throw new ERR_MISSING_ARGS('actual', 'expected'); @@ -510,6 +569,13 @@ assert.strictEqual = function strictEqual(actual, expected, message) { } }; +/** + * The strict non-equivalence assertion tests for any strict inequality. + * @param {any} actual + * @param {any} expected + * @param {string | Error} [message] + * @returns {void} + */ assert.notStrictEqual = function notStrictEqual(actual, expected, message) { if (arguments.length < 2) { throw new ERR_MISSING_ARGS('actual', 'expected'); @@ -820,22 +886,51 @@ function expectsNoError(stackStartFn, actual, error, message) { throw actual; } +/** + * Expects the function `promiseFn` to throw an error. + * @param {() => any} promiseFn + * @param {...any} [args] + * @returns {void} + */ assert.throws = function throws(promiseFn, ...args) { expectsError(throws, getActual(promiseFn), ...args); }; +/** + * Expects `promiseFn` function or its value to reject. + * @param {() => Promise} promiseFn + * @param {...any} [args] + * @returns {Promise} + */ assert.rejects = async function rejects(promiseFn, ...args) { expectsError(rejects, await waitForActual(promiseFn), ...args); }; +/** + * Asserts that the function `fn` does not throw an error. + * @param {() => any} fn + * @param {...any} [args] + * @returns {void} + */ assert.doesNotThrow = function doesNotThrow(fn, ...args) { expectsNoError(doesNotThrow, getActual(fn), ...args); }; +/** + * Expects `fn` or its value to not reject. + * @param {() => Promise} fn + * @param {...any} [args] + * @returns {Promise} + */ assert.doesNotReject = async function doesNotReject(fn, ...args) { expectsNoError(doesNotReject, await waitForActual(fn), ...args); }; +/** + * Throws `value` if the value is not `null` or `undefined`. + * @param {any} err + * @returns {void} + */ assert.ifError = function ifError(err) { if (err !== null && err !== undefined) { let message = 'ifError got unwanted exception: '; @@ -919,24 +1014,44 @@ function internalMatch(string, regexp, message, fn) { } } +/** + * Expects the `string` input to match the regular expression. + * @param {string} string + * @param {RegExp} regexp + * @param {string | Error} [message] + * @returns {void} + */ assert.match = function match(string, regexp, message) { internalMatch(string, regexp, message, match); }; +/** + * Expects the `string` input not to match the regular expression. + * @param {string} string + * @param {RegExp} regexp + * @param {string | Error} [message] + * @returns {void} + */ assert.doesNotMatch = function doesNotMatch(string, regexp, message) { internalMatch(string, regexp, message, doesNotMatch); }; assert.CallTracker = CallTracker; -// Expose a strict only variant of assert +/** + * Expose a strict only variant of assert. + * @param {...any} args + * @returns {void} + */ function strict(...args) { innerOk(strict, args.length, ...args); } + assert.strict = ObjectAssign(strict, assert, { equal: assert.strictEqual, deepEqual: assert.deepStrictEqual, notEqual: assert.notStrictEqual, notDeepEqual: assert.notDeepStrictEqual }); + assert.strict.strict = assert.strict;