From ab9b5900dd1b43c9cf5b7f908788f68ec22f5a4a 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 831532c6d4f37a..bb981290168c8c 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 664d7a3d95cacf..de8a8bb9b83b34 100644 --- a/lib/internal/validators.js +++ b/lib/internal/validators.js @@ -34,10 +34,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); } @@ -70,6 +78,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') @@ -81,6 +99,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. @@ -96,7 +124,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); } @@ -111,11 +148,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); @@ -129,6 +184,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( @@ -140,6 +204,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); @@ -152,7 +224,8 @@ function getOwnPropertyValueOrDefault(options, key, defaultValue) { } /** - * @param {unknown} value + * @callback validateObject + * @param {*} value * @param {string} name * @param {{ * allowArray?: boolean, @@ -160,8 +233,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); @@ -174,6 +249,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); @@ -184,6 +268,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); @@ -197,6 +287,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, @@ -205,6 +303,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; @@ -215,8 +317,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) || @@ -228,6 +336,13 @@ function validatePort(port, name = 'Port', allowZero = true) { return port | 0; } +/** + * @callback validateAbortSignal + * @param {*} signal + * @param {string} name + */ + +/** @type {validateAbortSignal} */ const validateAbortSignal = hideStackFrames((signal, name) => { if (signal !== undefined && (signal === null || @@ -237,21 +352,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);