typings: add JSDoc typings for util

PR-URL: https://github.com/nodejs/node/pull/38213
Refs: https://github.com/nodejs/node/pull/38182
Refs: https://twitter.com/bradleymeck/status/1380643627211354115
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

1 files changed, 88 insertions, 4 deletions

diff --git a/lib/util.js b/lib/util.js
index f3c10bb7720..bcb1c81933c 100644
--- a/lib/util.js
+++ b/lib/util.js
@@ -74,51 +74,109 @@ const {
 
 let internalDeepEqual;
 
+/**
+ * @deprecated since v4.0.0
+ * @param {any} arg
+ * @returns {arg is boolean}
+ */
 function isBoolean(arg) {
   return typeof arg === 'boolean';
 }
 
+/**
+ * @deprecated since v4.0.0
+ * @param {any} arg
+ * @returns {arg is null}
+ */
 function isNull(arg) {
   return arg === null;
 }
 
+/**
+ * @deprecated since v4.0.0
+ * @param {any} arg
+ * @returns {arg is (null | undefined)}
+ */
 function isNullOrUndefined(arg) {
   return arg === null || arg === undefined;
 }
 
+/**
+ * @deprecated since v4.0.0
+ * @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';
 }
 
+/**
+ * @deprecated since v4.0.0
+ * @param {any} arg
+ * @returns {arg is symbol}
+ */
 function isSymbol(arg) {
   return typeof arg === 'symbol';
 }
 
+/**
+ * @deprecated since v4.0.0
+ * @param {any} arg
+ * @returns {arg is undefined}
+ */
 function isUndefined(arg) {
   return arg === undefined;
 }
 
+/**
+ * @deprecated since v4.0.0
+ * @param {any} arg
+ * @returns {a is NonNullable<object>}
+ */
 function isObject(arg) {
   return arg !== null && typeof arg === 'object';
 }
 
+/**
+ * @deprecated since v4.0.0
+ * @param {any} e
+ * @returns {arg is Error}
+ */
 function isError(e) {
   return ObjectPrototypeToString(e) === '[object Error]' || e instanceof Error;
 }
 
+/**
+ * @deprecated since v4.0.0
+ * @param {any} arg
+ * @returns {arg is Function}
+ */
 function isFunction(arg) {
   return typeof arg === 'function';
 }
 
+/**
+ * @deprecated since v4.0.0
+ * @param {any} arg
+ * @returns {arg is (boolean | null | number | string | symbol | undefined)}
+ */
 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');
 }
@@ -126,7 +184,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([
@@ -138,7 +198,11 @@ 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
+ * @deprecated since v6.0.0
+ * @type {(...args: any[]) => void}
+ */
 function log(...args) {
   if (!console) {
     console = require('internal/console/global');
@@ -155,9 +219,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.
  */
@@ -181,6 +245,14 @@ function inherits(ctor, superCtor) {
   ObjectSetPrototypeOf(ctor.prototype, superCtor.prototype);
 }
 
+/**
+ * @deprecated since v6.0.0
+ * @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;
@@ -204,6 +276,14 @@ const callbackifyOnRejected = hideStackFrames((reason, cb) => {
   return cb(reason);
 });
 
+/**
+ * @template {(...args: any[]) => Promise<any>} T
+ * @param {T} original
+ * @returns {T extends (...args: infer TArgs) => Promise<infer TReturn> ?
+ *   ((...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);
@@ -238,6 +318,10 @@ function callbackify(original) {
   return callbackified;
 }
 
+/**
+ * @param {number} err
+ * @returns {string}
+ */
 function getSystemErrorName(err) {
   validateNumber(err, 'err');
   if (err >= 0 || !NumberIsSafeInteger(err)) {