mocha 8.1.3 → 8.2.0

package/lib/utils.js

@@ -9,11 +9,13 @@
  * Module dependencies.
  */
 
+const {nanoid} = require('nanoid/non-secure');
 var path = require('path');
 var util = require('util');
 var he = require('he');
+const errors = require('./errors');
 
-var assign = (exports.assign = require('object.assign').getPolyfill());
+const MOCHA_ID_PROP_NAME = '__mocha_id__';
 
 /**
  * Inherit the prototype methods from one constructor into another.
@@ -127,19 +129,21 @@ function emptyRepresentation(value, typeHint) {
  * @param {*} value The value to test.
  * @returns {string} Computed type
  * @example
- * type({}) // 'object'
- * type([]) // 'array'
- * type(1) // 'number'
- * type(false) // 'boolean'
- * type(Infinity) // 'number'
- * type(null) // 'null'
- * type(new Date()) // 'date'
- * type(/foo/) // 'regexp'
- * type('type') // 'string'
- * type(global) // 'global'
- * type(new String('foo') // 'object'
+ * canonicalType({}) // 'object'
+ * canonicalType([]) // 'array'
+ * canonicalType(1) // 'number'
+ * canonicalType(false) // 'boolean'
+ * canonicalType(Infinity) // 'number'
+ * canonicalType(null) // 'null'
+ * canonicalType(new Date()) // 'date'
+ * canonicalType(/foo/) // 'regexp'
+ * canonicalType('type') // 'string'
+ * canonicalType(global) // 'global'
+ * canonicalType(new String('foo') // 'object'
+ * canonicalType(async function() {}) // 'asyncfunction'
+ * canonicalType(await import(name)) // 'module'
  */
-var type = (exports.type = function type(value) {
+var canonicalType = (exports.canonicalType = function canonicalType(value) {
   if (value === undefined) {
     return 'undefined';
   } else if (value === null) {
@@ -153,6 +157,47 @@ var type = (exports.type = function type(value) {
     .toLowerCase();
 });
 
+/**
+ *
+ * Returns a general type or data structure of a variable
+ * @private
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures
+ * @param {*} value The value to test.
+ * @returns {string} One of undefined, boolean, number, string, bigint, symbol, object
+ * @example
+ * type({}) // 'object'
+ * type([]) // 'array'
+ * type(1) // 'number'
+ * type(false) // 'boolean'
+ * type(Infinity) // 'number'
+ * type(null) // 'null'
+ * type(new Date()) // 'object'
+ * type(/foo/) // 'object'
+ * type('type') // 'string'
+ * type(global) // 'object'
+ * type(new String('foo') // 'string'
+ */
+exports.type = function type(value) {
+  // Null is special
+  if (value === null) return 'null';
+  const primitives = new Set([
+    'undefined',
+    'boolean',
+    'number',
+    'string',
+    'bigint',
+    'symbol'
+  ]);
+  const _type = typeof value;
+  if (_type === 'function') return _type;
+  if (primitives.has(_type)) return _type;
+  if (value instanceof String) return 'string';
+  if (value instanceof Error) return 'error';
+  if (Array.isArray(value)) return 'array';
+
+  return _type;
+};
+
 /**
  * Stringify `value`. Different behavior depending on type of value:
  *
@@ -169,7 +214,7 @@ var type = (exports.type = function type(value) {
  * @return {string}
  */
 exports.stringify = function(value) {
-  var typeHint = type(value);
+  var typeHint = canonicalType(value);
 
   if (!~['object', 'array', 'function'].indexOf(typeHint)) {
     if (typeHint === 'buffer') {
@@ -235,7 +280,7 @@ function jsonStringify(object, spaces, depth) {
   }
 
   function _stringify(val) {
-    switch (type(val)) {
+    switch (canonicalType(val)) {
       case 'null':
       case 'undefined':
         val = '[' + val + ']';
@@ -316,7 +361,7 @@ exports.canonicalize = function canonicalize(value, stack, typeHint) {
   /* eslint-disable no-unused-vars */
   var prop;
   /* eslint-enable no-unused-vars */
-  typeHint = typeHint || type(value);
+  typeHint = typeHint || canonicalType(value);
   function withStack(value, fn) {
     stack.push(value);
     fn();
@@ -343,7 +388,7 @@ exports.canonicalize = function canonicalize(value, stack, typeHint) {
       });
       break;
     case 'function':
-      /* eslint-disable guard-for-in */
+      /* eslint-disable-next-line no-unused-vars */
       for (prop in value) {
         canonicalizedObj = {};
         break;
@@ -378,50 +423,6 @@ exports.canonicalize = function canonicalize(value, stack, typeHint) {
   return canonicalizedObj;
 };
 
-/**
- * process.emitWarning or a polyfill
- * @see https://nodejs.org/api/process.html#process_process_emitwarning_warning_options
- * @ignore
- */
-function emitWarning(msg, type) {
-  if (process.emitWarning) {
-    process.emitWarning(msg, type);
-  } else {
-    process.nextTick(function() {
-      console.warn(type + ': ' + msg);
-    });
-  }
-}
-
-/**
- * Show a deprecation warning. Each distinct message is only displayed once.
- * Ignores empty messages.
- *
- * @param {string} [msg] - Warning to print
- * @private
- */
-exports.deprecate = function deprecate(msg) {
-  msg = String(msg);
-  if (msg && !deprecate.cache[msg]) {
-    deprecate.cache[msg] = true;
-    emitWarning(msg, 'DeprecationWarning');
-  }
-};
-exports.deprecate.cache = {};
-
-/**
- * Show a generic warning.
- * Ignores empty messages.
- *
- * @param {string} [msg] - Warning to print
- * @private
- */
-exports.warn = function warn(msg) {
-  if (msg) {
-    emitWarning(msg);
-  }
-};
-
 /**
  * @summary
  * This Filter based on `mocha-clean` module.(see: `github.com/rstacruz/mocha-clean`)
@@ -575,7 +576,7 @@ exports.noop = function() {};
  * @returns {Object} An object with no prototype, having `...obj` properties
  */
 exports.createMap = function(obj) {
-  return assign.apply(
+  return Object.assign.apply(
     null,
     [Object.create(null)].concat(Array.prototype.slice.call(arguments))
   );
@@ -594,7 +595,7 @@ exports.createMap = function(obj) {
  * @throws {TypeError} if argument is not a non-empty object.
  */
 exports.defineConstants = function(obj) {
-  if (type(obj) !== 'object' || !Object.keys(obj).length) {
+  if (canonicalType(obj) !== 'object' || !Object.keys(obj).length) {
     throw new TypeError('Invalid argument; expected a non-empty object');
   }
   return Object.freeze(exports.createMap(obj));
@@ -665,12 +666,67 @@ exports.isBrowser = function isBrowser() {
  */
 exports.lookupFiles = (...args) => {
   if (exports.isBrowser()) {
-    throw require('./errors').createUnsupportedError(
+    throw errors.createUnsupportedError(
       'lookupFiles() is only supported in Node.js!'
     );
   }
-  exports.deprecate(
+  errors.deprecate(
     '`lookupFiles()` in module `mocha/lib/utils` has moved to module `mocha/lib/cli` and will be removed in the next major revision of Mocha'
   );
   return require('./cli').lookupFiles(...args);
 };
+
+/*
+ * Casts `value` to an array; useful for optionally accepting array parameters
+ *
+ * It follows these rules, depending on `value`.  If `value` is...
+ * 1. `undefined`: return an empty Array
+ * 2. `null`: return an array with a single `null` element
+ * 3. Any other object: return the value of `Array.from()` _if_ the object is iterable
+ * 4. otherwise: return an array with a single element, `value`
+ * @param {*} value - Something to cast to an Array
+ * @returns {Array<*>}
+ */
+exports.castArray = function castArray(value) {
+  if (value === undefined) {
+    return [];
+  }
+  if (value === null) {
+    return [null];
+  }
+  if (
+    typeof value === 'object' &&
+    (typeof value[Symbol.iterator] === 'function' || value.length !== undefined)
+  ) {
+    return Array.from(value);
+  }
+  return [value];
+};
+
+exports.constants = exports.defineConstants({
+  MOCHA_ID_PROP_NAME
+});
+
+/**
+ * Creates a new unique identifier
+ * @returns {string} Unique identifier
+ */
+exports.uniqueID = () => nanoid();
+
+exports.assignNewMochaID = obj => {
+  const id = exports.uniqueID();
+  Object.defineProperty(obj, MOCHA_ID_PROP_NAME, {
+    get() {
+      return id;
+    }
+  });
+  return obj;
+};
+
+/**
+ * Retrieves a Mocha ID from an object, if present.
+ * @param {*} [obj] - Object
+ * @returns {string|void}
+ */
+exports.getMochaID = obj =>
+  obj && typeof obj === 'object' ? obj[MOCHA_ID_PROP_NAME] : undefined;