From df11d14be707a613cd5869684838e15232944607 Mon Sep 17 00:00:00 2001 From: Yagiz Nizipli Date: Wed, 17 Aug 2022 14:25:01 -0400 Subject: [PATCH] typings: add JSDoc for `internal/validators` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR-URL: https://github.com/nodejs/node/pull/44181 Reviewed-By: Antoine du Hamel Reviewed-By: Michaël Zasso --- lib/internal/errors.js | 5 +- lib/internal/validators.js | 155 +++++++++++++++++++++++++++++++++++-- 2 files changed, 153 insertions(+), 7 deletions(-) diff --git a/lib/internal/errors.js b/lib/internal/errors.js index d07be809f71..1ad2a640b4c 100644 --- a/lib/internal/errors.js +++ b/lib/internal/errors.js @@ -392,8 +392,9 @@ function makeNodeErrorWithCode(Base, key) { /** * This function removes unnecessary frames from Node.js core errors. - * @template {(...args: any[]) => any} T - * @type {(fn: T) => T} + * @template {(...args: unknown[]) => unknown} T + * @param {T} fn + * @returns {T} */ function hideStackFrames(fn) { // We rename the functions that will be hidden to cut off the stacktrace diff --git a/lib/internal/validators.js b/lib/internal/validators.js index 3c1d6de582c..84c8eacba72 100644 --- a/lib/internal/validators.js +++ b/lib/internal/validators.js @@ -35,10 +35,18 @@ const { } = require('internal/util/types'); const { signals } = internalBinding('constants').os; +/** + * @param {*} value + * @returns {boolean} + */ function isInt32(value) { return value === (value | 0); } +/** + * @param {*} value + * @returns {boolean} + */ function isUint32(value) { return value === (value >>> 0); } @@ -71,6 +79,16 @@ function parseFileMode(value, name, def) { return value; } +/** + * @callback validateInteger + * @param {*} value + * @param {string} name + * @param {number} [min] + * @param {number} [max] + * @returns {asserts value is number} + */ + +/** @type {validateInteger} */ const validateInteger = hideStackFrames( (value, name, min = NumberMIN_SAFE_INTEGER, max = NumberMAX_SAFE_INTEGER) => { if (typeof value !== 'number') @@ -82,6 +100,16 @@ const validateInteger = hideStackFrames( } ); +/** + * @callback validateInt32 + * @param {*} value + * @param {string} name + * @param {number} [min] + * @param {number} [max] + * @returns {asserts value is number} + */ + +/** @type {validateInt32} */ const validateInt32 = hideStackFrames( (value, name, min = -2147483648, max = 2147483647) => { // The defaults for min and max correspond to the limits of 32-bit integers. @@ -97,7 +125,16 @@ const validateInt32 = hideStackFrames( } ); -const validateUint32 = hideStackFrames((value, name, positive) => { +/** + * @callback validateUint32 + * @param {*} value + * @param {string} name + * @param {number|boolean} [positive=false] + * @returns {asserts value is number} + */ + +/** @type {validateUint32} */ +const validateUint32 = hideStackFrames((value, name, positive = false) => { if (typeof value !== 'number') { throw new ERR_INVALID_ARG_TYPE(name, 'number', value); } @@ -112,11 +149,29 @@ const validateUint32 = hideStackFrames((value, name, positive) => { } }); +/** + * @callback validateString + * @param {*} value + * @param {string} name + * @returns {asserts value is string} + */ + +/** @type {validateString} */ function validateString(value, name) { if (typeof value !== 'string') throw new ERR_INVALID_ARG_TYPE(name, 'string', value); } +/** + * @callback validateNumber + * @param {*} value + * @param {string} name + * @param {number} [min] + * @param {number} [max] + * @returns {asserts value is number} + */ + +/** @type {validateNumber} */ function validateNumber(value, name, min = undefined, max) { if (typeof value !== 'number') throw new ERR_INVALID_ARG_TYPE(name, 'number', value); @@ -130,6 +185,15 @@ function validateNumber(value, name, min = undefined, max) { } } +/** + * @callback validateOneOf + * @template T + * @param {T} value + * @param {string} name + * @param {T[]} oneOf + */ + +/** @type {validateOneOf} */ const validateOneOf = hideStackFrames((value, name, oneOf) => { if (!ArrayPrototypeIncludes(oneOf, value)) { const allowed = ArrayPrototypeJoin( @@ -141,6 +205,14 @@ const validateOneOf = hideStackFrames((value, name, oneOf) => { } }); +/** + * @callback validateBoolean + * @param {*} value + * @param {string} name + * @returns {asserts value is boolean} + */ + +/** @type {validateBoolean} */ function validateBoolean(value, name) { if (typeof value !== 'boolean') throw new ERR_INVALID_ARG_TYPE(name, 'boolean', value); @@ -153,7 +225,8 @@ function getOwnPropertyValueOrDefault(options, key, defaultValue) { } /** - * @param {unknown} value + * @callback validateObject + * @param {*} value * @param {string} name * @param {{ * allowArray?: boolean, @@ -161,8 +234,10 @@ function getOwnPropertyValueOrDefault(options, key, defaultValue) { * nullable?: boolean * }} [options] */ + +/** @type {validateObject} */ const validateObject = hideStackFrames( - (value, name, options) => { + (value, name, options = null) => { const allowArray = getOwnPropertyValueOrDefault(options, 'allowArray', false); const allowFunction = getOwnPropertyValueOrDefault(options, 'allowFunction', false); const nullable = getOwnPropertyValueOrDefault(options, 'nullable', false); @@ -175,6 +250,15 @@ const validateObject = hideStackFrames( } }); +/** + * @callback validateArray + * @param {*} value + * @param {string} name + * @param {number} [minLength] + * @returns {asserts value is any[]} + */ + +/** @type {validateArray} */ const validateArray = hideStackFrames((value, name, minLength = 0) => { if (!ArrayIsArray(value)) { throw new ERR_INVALID_ARG_TYPE(name, 'Array', value); @@ -185,6 +269,12 @@ const validateArray = hideStackFrames((value, name, minLength = 0) => { } }); +// eslint-disable-next-line jsdoc/require-returns-check +/** + * @param {*} signal + * @param {string} [name='signal'] + * @returns {asserts signal is keyof signals} + */ function validateSignalName(signal, name = 'signal') { validateString(signal, name); @@ -198,6 +288,14 @@ function validateSignalName(signal, name = 'signal') { } } +/** + * @callback validateBuffer + * @param {*} buffer + * @param {string} [name='buffer'] + * @returns {asserts buffer is ArrayBufferView} + */ + +/** @type {validateBuffer} */ const validateBuffer = hideStackFrames((buffer, name = 'buffer') => { if (!isArrayBufferView(buffer)) { throw new ERR_INVALID_ARG_TYPE(name, @@ -206,6 +304,10 @@ const validateBuffer = hideStackFrames((buffer, name = 'buffer') => { } }); +/** + * @param {string} data + * @param {string} encoding + */ function validateEncoding(data, encoding) { const normalizedEncoding = normalizeEncoding(encoding); const length = data.length; @@ -216,8 +318,14 @@ function validateEncoding(data, encoding) { } } -// Check that the port number is not NaN when coerced to a number, -// is an integer and that it falls within the legal range of port numbers. +/** + * Check that the port number is not NaN when coerced to a number, + * is an integer and that it falls within the legal range of port numbers. + * @param {*} port + * @param {string} [name='Port'] + * @param {boolean} [allowZero=true] + * @returns {number} + */ function validatePort(port, name = 'Port', allowZero = true) { if ((typeof port !== 'number' && typeof port !== 'string') || (typeof port === 'string' && StringPrototypeTrim(port).length === 0) || @@ -234,6 +342,13 @@ const validateCallback = hideStackFrames((callback) => { throw new ERR_INVALID_CALLBACK(callback); }); +/** + * @callback validateAbortSignal + * @param {*} signal + * @param {string} name + */ + +/** @type {validateAbortSignal} */ const validateAbortSignal = hideStackFrames((signal, name) => { if (signal !== undefined && (signal === null || @@ -243,21 +358,51 @@ const validateAbortSignal = hideStackFrames((signal, name) => { } }); +/** + * @callback validateFunction + * @param {*} value + * @param {string} name + * @returns {asserts value is Function} + */ + +/** @type {validateFunction} */ const validateFunction = hideStackFrames((value, name) => { if (typeof value !== 'function') throw new ERR_INVALID_ARG_TYPE(name, 'Function', value); }); +/** + * @callback validatePlainFunction + * @param {*} value + * @param {string} name + * @returns {asserts value is Function} + */ + +/** @type {validatePlainFunction} */ const validatePlainFunction = hideStackFrames((value, name) => { if (typeof value !== 'function' || isAsyncFunction(value)) throw new ERR_INVALID_ARG_TYPE(name, 'Function', value); }); +/** + * @callback validateUndefined + * @param {*} value + * @param {string} name + * @returns {asserts value is undefined} + */ + +/** @type {validateUndefined} */ const validateUndefined = hideStackFrames((value, name) => { if (value !== undefined) throw new ERR_INVALID_ARG_TYPE(name, 'undefined', value); }); +/** + * @template T + * @param {T} value + * @param {string} name + * @param {T[]} union + */ function validateUnion(value, name, union) { if (!ArrayPrototypeIncludes(union, value)) { throw new ERR_INVALID_ARG_TYPE(name, `('${ArrayPrototypeJoin(union, '|')}')`, value);