From a736f501f6858e715eb5bb72aef1cf3ce7cccce9 Mon Sep 17 00:00:00 2001 From: Rohit Gohri Date: Mon, 12 Apr 2021 20:25:11 +0530 Subject: [PATCH 1/5] lib: add JSDoc typings for util --- lib/util.js | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 73 insertions(+), 4 deletions(-) diff --git a/lib/util.js b/lib/util.js index abd1f6e663610e..b21a10fc051cb1 100644 --- a/lib/util.js +++ b/lib/util.js @@ -73,51 +73,99 @@ const { let internalDeepEqual; +/** + * @param {any} arg + * @returns {arg is boolean} + */ function isBoolean(arg) { return typeof arg === 'boolean'; } +/** + * @param {any} arg + * @returns {arg is null} + */ function isNull(arg) { return arg === null; } +/** + * @param {any} arg + * @returns {arg is (null | undefined)} + */ function isNullOrUndefined(arg) { return arg === null || arg === undefined; } +/** + * @param {any} arg + * @returns {arg is number} + */ function isNumber(arg) { return typeof arg === 'number'; } +/** + * @param {any} arg + * @returns {arg is string} + */ function isString(arg) { return typeof arg === 'string'; } +/** + * @param {any} arg + * @returns {arg is symbol} + */ function isSymbol(arg) { return typeof arg === 'symbol'; } +/** + * @param {any} arg + * @returns {arg is undefined} + */ function isUndefined(arg) { return arg === undefined; } +/** + * @param {any} arg + * @returns {boolean} + */ function isObject(arg) { return arg !== null && typeof arg === 'object'; } +/** + * @param {any} e + * @returns {arg is Error} + */ function isError(e) { return ObjectPrototypeToString(e) === '[object Error]' || e instanceof Error; } +/** + * @param {any} arg + * @returns {arg is Function} + */ function isFunction(arg) { return typeof arg === 'function'; } +/** + * @param {any} arg + * @returns {arg is (null | boolean | string | number | symbol)} + */ function isPrimitive(arg) { return arg === null || (typeof arg !== 'object' && typeof arg !== 'function'); } +/** + * @param {number} n + * @returns {string} + */ function pad(n) { return StringPrototypePadStart(n.toString(), 2, '0'); } @@ -125,7 +173,9 @@ function pad(n) { const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']; -// 26 Feb 16:19:34 +/** + * @returns {string} 26 Feb 16:19:34 + */ function timestamp() { const d = new Date(); const t = ArrayPrototypeJoin([ @@ -137,7 +187,10 @@ function timestamp() { } let console; -// Log is just a thin wrapper to console.log that prepends a timestamp +/** + * Log is just a thin wrapper to console.log that prepends a timestamp + * @type {(...args: any[]) => void} + */ function log(...args) { if (!console) { console = require('internal/console/global'); @@ -154,9 +207,9 @@ function log(...args) { * functions as prototype setup using normal JavaScript does not work as * expected during bootstrapping (see mirror.js in r114903). * - * @param {function} ctor Constructor function which needs to inherit the + * @param {Function} ctor Constructor function which needs to inherit the * prototype. - * @param {function} superCtor Constructor function to inherit prototype from. + * @param {Function} superCtor Constructor function to inherit prototype from. * @throws {TypeError} Will error if either constructor is null, or if * the super constructor lacks a prototype. */ @@ -180,6 +233,13 @@ function inherits(ctor, superCtor) { ObjectSetPrototypeOf(ctor.prototype, superCtor.prototype); } +/** + * @template T + * @template S + * @param {T} target + * @param {S} source + * @returns {S extends null ? T : (T & S)} + */ function _extend(target, source) { // Don't do anything if source isn't an object if (source === null || typeof source !== 'object') return target; @@ -203,6 +263,11 @@ const callbackifyOnRejected = hideStackFrames((reason, cb) => { return cb(reason); }); +/** + * @template {(...args: any[]) => Promise} T + * @param {T} original + * @returns {T extends (...args: infer TArgs) => Promise ? ((...params: [...TArgs, ((err: Error, ret: TReturn) => any)]) => void) : never} + */ function callbackify(original) { if (typeof original !== 'function') { throw new ERR_INVALID_ARG_TYPE('original', 'Function', original); @@ -237,6 +302,10 @@ function callbackify(original) { return callbackified; } +/** + * @param {number} err + * @returns {string} + */ function getSystemErrorName(err) { validateNumber(err, 'err'); if (err >= 0 || !NumberIsSafeInteger(err)) { From 3f1ea74c2cdf624e807f5e07803e44585b311d44 Mon Sep 17 00:00:00 2001 From: Rohit Gohri Date: Mon, 12 Apr 2021 21:16:10 +0530 Subject: [PATCH 2/5] lib: fix lint errors --- lib/util.js | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/lib/util.js b/lib/util.js index b21a10fc051cb1..e24bb9e7013143 100644 --- a/lib/util.js +++ b/lib/util.js @@ -74,7 +74,7 @@ const { let internalDeepEqual; /** - * @param {any} arg + * @param {any} arg * @returns {arg is boolean} */ function isBoolean(arg) { @@ -82,7 +82,7 @@ function isBoolean(arg) { } /** - * @param {any} arg + * @param {any} arg * @returns {arg is null} */ function isNull(arg) { @@ -90,7 +90,7 @@ function isNull(arg) { } /** - * @param {any} arg + * @param {any} arg * @returns {arg is (null | undefined)} */ function isNullOrUndefined(arg) { @@ -98,7 +98,7 @@ function isNullOrUndefined(arg) { } /** - * @param {any} arg + * @param {any} arg * @returns {arg is number} */ function isNumber(arg) { @@ -106,7 +106,7 @@ function isNumber(arg) { } /** - * @param {any} arg + * @param {any} arg * @returns {arg is string} */ function isString(arg) { @@ -114,7 +114,7 @@ function isString(arg) { } /** - * @param {any} arg + * @param {any} arg * @returns {arg is symbol} */ function isSymbol(arg) { @@ -122,7 +122,7 @@ function isSymbol(arg) { } /** - * @param {any} arg + * @param {any} arg * @returns {arg is undefined} */ function isUndefined(arg) { @@ -130,7 +130,7 @@ function isUndefined(arg) { } /** - * @param {any} arg + * @param {any} arg * @returns {boolean} */ function isObject(arg) { @@ -146,7 +146,7 @@ function isError(e) { } /** - * @param {any} arg + * @param {any} arg * @returns {arg is Function} */ function isFunction(arg) { @@ -154,7 +154,7 @@ function isFunction(arg) { } /** - * @param {any} arg + * @param {any} arg * @returns {arg is (null | boolean | string | number | symbol)} */ function isPrimitive(arg) { @@ -163,7 +163,7 @@ function isPrimitive(arg) { } /** - * @param {number} n + * @param {number} n * @returns {string} */ function pad(n) { @@ -266,7 +266,10 @@ const callbackifyOnRejected = hideStackFrames((reason, cb) => { /** * @template {(...args: any[]) => Promise} T * @param {T} original - * @returns {T extends (...args: infer TArgs) => Promise ? ((...params: [...TArgs, ((err: Error, ret: TReturn) => any)]) => void) : never} + * @returns {T extends (...args: infer TArgs) => Promise ? + * ((...params: [...TArgs, ((err: Error, ret: TReturn) => any)]) => void) : + * never + * } */ function callbackify(original) { if (typeof original !== 'function') { From b16a9b1ea7b2b4af6499bc2c53640f67b28ae5ac Mon Sep 17 00:00:00 2001 From: Rohit Gohri Date: Mon, 12 Apr 2021 23:15:08 +0530 Subject: [PATCH 3/5] lib: added undefined and sorted return type Co-authored-by: Bradley Farias --- lib/util.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/util.js b/lib/util.js index e24bb9e7013143..d4aca94fa937ff 100644 --- a/lib/util.js +++ b/lib/util.js @@ -155,7 +155,7 @@ function isFunction(arg) { /** * @param {any} arg - * @returns {arg is (null | boolean | string | number | symbol)} + * @returns {arg is (boolean | null | number | string | symbol | undefined)} */ function isPrimitive(arg) { return arg === null || From d9dfb9d6c260e4a4a21872d6f740dafa813aa6a8 Mon Sep 17 00:00:00 2001 From: Rohit Gohri Date: Tue, 13 Apr 2021 08:31:01 +0530 Subject: [PATCH 4/5] lib: update return type Co-authored-by: Bradley Farias --- lib/util.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/util.js b/lib/util.js index d4aca94fa937ff..bb23fbf1c3235e 100644 --- a/lib/util.js +++ b/lib/util.js @@ -131,7 +131,7 @@ function isUndefined(arg) { /** * @param {any} arg - * @returns {boolean} + * @returns {a is NonNullable} */ function isObject(arg) { return arg !== null && typeof arg === 'object'; From ab3b4816fdad01413f7740720f8c8b603efd0eef Mon Sep 17 00:00:00 2001 From: Rohit Gohri Date: Tue, 20 Apr 2021 10:18:42 +0530 Subject: [PATCH 5/5] lib: added deprecated jsdoc tags to methods Ref: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-0.html#-deprecated--support Co-authored-by: akhil marsonya <16393876+marsonya@users.noreply.github.com> --- lib/util.js | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/lib/util.js b/lib/util.js index bb23fbf1c3235e..468aefb05fa5c2 100644 --- a/lib/util.js +++ b/lib/util.js @@ -74,6 +74,7 @@ const { let internalDeepEqual; /** + * @deprecated since v4.0.0 * @param {any} arg * @returns {arg is boolean} */ @@ -82,6 +83,7 @@ function isBoolean(arg) { } /** + * @deprecated since v4.0.0 * @param {any} arg * @returns {arg is null} */ @@ -90,6 +92,7 @@ function isNull(arg) { } /** + * @deprecated since v4.0.0 * @param {any} arg * @returns {arg is (null | undefined)} */ @@ -98,6 +101,7 @@ function isNullOrUndefined(arg) { } /** + * @deprecated since v4.0.0 * @param {any} arg * @returns {arg is number} */ @@ -114,6 +118,7 @@ function isString(arg) { } /** + * @deprecated since v4.0.0 * @param {any} arg * @returns {arg is symbol} */ @@ -122,6 +127,7 @@ function isSymbol(arg) { } /** + * @deprecated since v4.0.0 * @param {any} arg * @returns {arg is undefined} */ @@ -130,6 +136,7 @@ function isUndefined(arg) { } /** + * @deprecated since v4.0.0 * @param {any} arg * @returns {a is NonNullable} */ @@ -138,6 +145,7 @@ function isObject(arg) { } /** + * @deprecated since v4.0.0 * @param {any} e * @returns {arg is Error} */ @@ -146,6 +154,7 @@ function isError(e) { } /** + * @deprecated since v4.0.0 * @param {any} arg * @returns {arg is Function} */ @@ -154,6 +163,7 @@ function isFunction(arg) { } /** + * @deprecated since v4.0.0 * @param {any} arg * @returns {arg is (boolean | null | number | string | symbol | undefined)} */ @@ -189,6 +199,7 @@ function timestamp() { let console; /** * Log is just a thin wrapper to console.log that prepends a timestamp + * @deprecated since v6.0.0 * @type {(...args: any[]) => void} */ function log(...args) { @@ -234,6 +245,7 @@ function inherits(ctor, superCtor) { } /** + * @deprecated since v6.0.0 * @template T * @template S * @param {T} target