Skip to content

Commit

Permalink
typings: add JSDoc typings for util
Browse files Browse the repository at this point in the history
PR-URL: #38213
Refs: #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>
  • Loading branch information
rohit-gohri authored and targos committed May 30, 2021
1 parent 89fe999 commit c116df7
Showing 1 changed file with 88 additions and 4 deletions.
92 changes: 88 additions & 4 deletions lib/util.js
Original file line number Diff line number Diff line change
@@ -65,59 +65,119 @@ 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 n.toString().padStart(2, '0');
}

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 time = [pad(d.getHours()),
@@ -127,7 +187,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');
@@ -144,9 +208,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.
*/
@@ -170,6 +234,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;
@@ -193,6 +265,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);
@@ -227,6 +307,10 @@ function callbackify(original) {
return callbackified;
}

/**
* @param {number} err
* @returns {string}
*/
function getSystemErrorName(err) {
validateNumber(err, 'err');
if (err >= 0 || !NumberIsSafeInteger(err)) {

0 comments on commit c116df7

Please sign in to comment.