mocha 8.1.1 → 8.2.1

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`)
@@ -508,7 +509,7 @@ exports.isPromise = function isPromise(value) {
  * Clamps a numeric value to an inclusive range.
  *
  * @param {number} value - Value to be clamped.
- * @param {numer[]} range - Two element array specifying [min, max] range.
+ * @param {number[]} range - Two element array specifying [min, max] range.
  * @returns {number} clamped value
  */
 exports.clamp = function clamp(value, range) {
@@ -568,14 +569,14 @@ exports.noop = function() {};
  * doesn't support it. Recommended for use in Mocha's public APIs.
  *
  * @public
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map|MDN:Map}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map#Custom_and_Null_objects|MDN:Map}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/create#Custom_and_Null_objects|MDN:Object.create - Custom objects}
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign|MDN:Object.assign}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign#Custom_and_Null_objects|MDN:Object.assign}
  * @param {...*} [obj] - Arguments to `Object.assign()`.
  * @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));
@@ -645,3 +646,87 @@ exports.cwd = function cwd() {
 exports.isBrowser = function isBrowser() {
   return Boolean(process.browser);
 };
+
+/**
+ * Lookup file names at the given `path`.
+ *
+ * @description
+ * Filenames are returned in _traversal_ order by the OS/filesystem.
+ * **Make no assumption that the names will be sorted in any fashion.**
+ *
+ * @public
+ * @alias module:lib/cli.lookupFiles
+ * @param {string} filepath - Base path to start searching from.
+ * @param {string[]} [extensions=[]] - File extensions to look for.
+ * @param {boolean} [recursive=false] - Whether to recurse into subdirectories.
+ * @return {string[]} An array of paths.
+ * @throws {Error} if no files match pattern.
+ * @throws {TypeError} if `filepath` is directory and `extensions` not provided.
+ * @deprecated Moved to {@link module:lib/cli.lookupFiles}
+ */
+exports.lookupFiles = (...args) => {
+  if (exports.isBrowser()) {
+    throw errors.createUnsupportedError(
+      'lookupFiles() is only supported in Node.js!'
+    );
+  }
+  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;