chai 5.1.0 → 5.1.2

package/lib/chai/interface/expect.js

@@ -8,6 +8,11 @@ import * as chai from '../../../index.js';
 import {Assertion} from '../assertion.js';
 import {AssertionError} from 'assertion-error';
 
+/**
+ * @param {unknown} val
+ * @param {string} message
+ * @returns {Assertion}
+ */
 function expect(val, message) {
   return new Assertion(val, message);
 }
@@ -30,8 +35,8 @@ export {expect};
  * @name fail
  * @param {unknown} actual
  * @param {unknown} expected
- * @param {String} message
- * @param {String} operator
+ * @param {string} message
+ * @param {string} operator
  * @namespace expect
  * @public
  */

package/lib/chai/interface/should.js

@@ -7,8 +7,14 @@
 import {Assertion} from '../assertion.js';
 import {AssertionError} from 'assertion-error';
 
+/**
+ * @returns {void}
+ */
 function loadShould () {
   // explicitly define this method as function as to have it's name to include as `ssfi`
+  /**
+   * @returns {Assertion}
+   */
   function shouldGetter() {
     if (this instanceof String
         || this instanceof Number
@@ -19,6 +25,9 @@ function loadShould () {
     }
     return new Assertion(this, null, shouldGetter);
   }
+  /**
+   * @param {unknown} value
+   */
   function shouldSetter(value) {
     // See https://github.com/chaijs/chai/issues/86: this makes
     // `whatever.should = someValue` actually set `someValue`, which is
@@ -55,12 +64,11 @@ function loadShould () {
    *     should.fail(1, 2, "custom error message", ">");
    *     should.fail(1, 2, undefined, ">");
    *
-   *
    * @name fail
    * @param {unknown} actual
    * @param {unknown} expected
-   * @param {String} message
-   * @param {String} operator
+   * @param {string} message
+   * @param {string} operator
    * @namespace BDD
    * @public
    */
@@ -88,12 +96,12 @@ function loadShould () {
    * @name equal
    * @param {unknown} actual
    * @param {unknown} expected
-   * @param {String} message
+   * @param {string} message
    * @namespace Should
    * @public
    */
-  should.equal = function (val1, val2, msg) {
-    new Assertion(val1, msg).to.equal(val2);
+  should.equal = function (actual, expected, message) {
+    new Assertion(actual, message).to.equal(expected);
   };
 
   /**
@@ -111,10 +119,10 @@ function loadShould () {
    *
    * @name throw
    * @alias Throw
-   * @param {Function} function
-   * @param {ErrorConstructor} constructor
-   * @param {RegExp} regexp
-   * @param {String} message
+   * @param {Function} fn
+   * @param {Error} errt
+   * @param {RegExp} errs
+   * @param {string} msg
    * @see https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error#Error_types
    * @namespace Should
    * @public
@@ -129,9 +137,10 @@ function loadShould () {
    * Asserts that the target is neither `null` nor `undefined`.
    *
    *     var foo = 'hi';
-   *
    *     should.exist(foo, 'foo exists');
    *
+   * @param {unknown} val
+   * @param {string} msg
    * @name exist
    * @namespace Should
    * @public
@@ -153,12 +162,12 @@ function loadShould () {
    * @name not.equal
    * @param {unknown} actual
    * @param {unknown} expected
-   * @param {String} message
+   * @param {string} msg
    * @namespace Should
    * @public
    */
-  should.not.equal = function (val1, val2, msg) {
-    new Assertion(val1, msg).to.not.equal(val2);
+  should.not.equal = function (actual, expected, msg) {
+    new Assertion(actual, msg).to.not.equal(expected);
   };
 
   /**
@@ -172,10 +181,10 @@ function loadShould () {
    *
    * @name not.throw
    * @alias not.Throw
-   * @param {Function} function
-   * @param {ErrorConstructor} constructor
-   * @param {RegExp} regexp
-   * @param {String} message
+   * @param {Function} fn
+   * @param {Error} errt
+   * @param {RegExp} errs
+   * @param {string} msg
    * @see https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error#Error_types
    * @namespace Should
    * @public
@@ -190,11 +199,12 @@ function loadShould () {
    * Asserts that the target is neither `null` nor `undefined`.
    *
    *     var bar = null;
-   *
    *     should.not.exist(bar, 'bar does not exist');
    *
-   * @name not.exist
    * @namespace Should
+   * @name not.exist
+   * @param {unknown} val
+   * @param {string} msg
    * @public
    */
   should.not.exist = function (val, msg) {

package/lib/chai/utils/addChainableMethod.js

@@ -43,8 +43,8 @@ var call  = Function.prototype.call,
  * Adds a method to an object, such that the method can also be chained.
  *
  *     utils.addChainableMethod(chai.Assertion.prototype, 'foo', function (str) {
- *       var obj = utils.flag(this, 'object');
- *       new chai.Assertion(obj).to.be.equal(str);
+ *         var obj = utils.flag(this, 'object');
+ *         new chai.Assertion(obj).to.be.equal(str);
  *     });
  *
  * Can also be accessed directly from `chai.Assertion`.
@@ -57,15 +57,14 @@ var call  = Function.prototype.call,
  *     expect(fooStr).to.be.foo('bar');
  *     expect(fooStr).to.be.foo.equal('foo');
  *
- * @param {Object} ctx object to which the method is added
- * @param {String} name of method to add
+ * @param {object} ctx object to which the method is added
+ * @param {string} name of method to add
  * @param {Function} method function to be used for `name`, when called
  * @param {Function} chainingBehavior function to be called every time the property is accessed
  * @namespace Utils
  * @name addChainableMethod
- * @api public
+ * @public
  */
-
 export function addChainableMethod(ctx, name, method, chainingBehavior) {
   if (typeof chainingBehavior !== 'function') {
     chainingBehavior = function () { };

package/lib/chai/utils/addLengthGuard.js

@@ -34,12 +34,12 @@ const fnLengthDesc = Object.getOwnPropertyDescriptor(function () {}, 'length');
  * environments is the priority.
  *
  * @param {Function} fn
- * @param {String} assertionName
- * @param {Boolean} isChainable
+ * @param {string} assertionName
+ * @param {boolean} isChainable
+ * @returns {unknown}
  * @namespace Utils
  * @name addLengthGuard
  */
-
 export function addLengthGuard(fn, assertionName, isChainable) {
   if (!fnLengthDesc.configurable) return fn;
 

package/lib/chai/utils/addMethod.js

@@ -16,8 +16,8 @@ import {Assertion} from '../assertion.js';
  * Adds a method to the prototype of an object.
  *
  *     utils.addMethod(chai.Assertion.prototype, 'foo', function (str) {
- *       var obj = utils.flag(this, 'object');
- *       new chai.Assertion(obj).to.be.equal(str);
+ *         var obj = utils.flag(this, 'object');
+ *         new chai.Assertion(obj).to.be.equal(str);
  *     });
  *
  * Can also be accessed directly from `chai.Assertion`.
@@ -28,14 +28,13 @@ import {Assertion} from '../assertion.js';
  *
  *     expect(fooStr).to.be.foo('bar');
  *
- * @param {Object} ctx object to which the method is added
- * @param {String} name of method to add
+ * @param {object} ctx object to which the method is added
+ * @param {string} name of method to add
  * @param {Function} method function to be used for name
  * @namespace Utils
  * @name addMethod
- * @api public
+ * @public
  */
-
 export function addMethod(ctx, name, method) {
   var methodWrapper = function () {
     // Setting the `ssfi` flag to `methodWrapper` causes this function to be the

package/lib/chai/utils/addProperty.js

@@ -15,8 +15,8 @@ import {transferFlags} from './transferFlags.js';
  * Adds a property to the prototype of an object.
  *
  *     utils.addProperty(chai.Assertion.prototype, 'foo', function () {
- *       var obj = utils.flag(this, 'object');
- *       new chai.Assertion(obj).to.be.instanceof(Foo);
+ *         var obj = utils.flag(this, 'object');
+ *         new chai.Assertion(obj).to.be.instanceof(Foo);
  *     });
  *
  * Can also be accessed directly from `chai.Assertion`.
@@ -27,14 +27,13 @@ import {transferFlags} from './transferFlags.js';
  *
  *     expect(myFoo).to.be.foo;
  *
- * @param {Object} ctx object to which the property is added
- * @param {String} name of property to add
+ * @param {object} ctx object to which the property is added
+ * @param {string} name of property to add
  * @param {Function} getter function to be used for name
  * @namespace Utils
  * @name addProperty
- * @api public
+ * @public
  */
-
 export function addProperty(ctx, name, getter) {
   getter = getter === undefined ? function () {} : getter;
 

package/lib/chai/utils/compareByInspect.js

@@ -14,14 +14,13 @@ import {inspect} from './inspect.js';
  * and objects with irregular/missing toString can still be sorted without a
  * TypeError.
  *
- * @param {Mixed} first element to compare
- * @param {Mixed} second element to compare
- * @returns {Number} -1 if 'a' should come before 'b'; otherwise 1
+ * @param {unknown} a first element to compare
+ * @param {unknown} b second element to compare
+ * @returns {number} -1 if 'a' should come before 'b'; otherwise 1
  * @name compareByInspect
  * @namespace Utils
- * @api public
+ * @public
  */
-
 export function compareByInspect(a, b) {
   return inspect(a) < inspect(b) ? -1 : 1;
 }

package/lib/chai/utils/expectTypes.js

@@ -4,6 +4,10 @@
  * MIT Licensed
  */
 
+import {AssertionError} from 'assertion-error';
+import {flag} from './flag.js';
+import {type} from './type-detect.js';
+
 /**
  * ### .expectTypes(obj, types)
  *
@@ -11,17 +15,12 @@
  *
  *     utils.expectTypes(this, ['array', 'object', 'string']);
  *
- * @param {Mixed} obj constructed Assertion
- * @param {Array} type A list of allowed types for this assertion
+ * @param {unknown} obj constructed Assertion
+ * @param {Array} types A list of allowed types for this assertion
  * @namespace Utils
  * @name expectTypes
- * @api public
+ * @public
  */
-
-import {AssertionError} from 'assertion-error';
-import {flag} from './flag.js';
-import {type} from './type-detect.js';
-
 export function expectTypes(obj, types) {
   var flagMsg = flag(obj, 'message');
   var ssfi = flag(obj, 'ssfi');

package/lib/chai/utils/flag.js

@@ -15,14 +15,14 @@
  *     utils.flag(this, 'foo', 'bar'); // setter
  *     utils.flag(this, 'foo'); // getter, returns `bar`
  *
- * @param {Object} object constructed Assertion
- * @param {String} key
- * @param {Mixed} value (optional)
+ * @param {object} obj object constructed Assertion
+ * @param {string} key
+ * @param {unknown} value (optional)
  * @namespace Utils
  * @name flag
- * @api private
+ * @returns {unknown | undefined}
+ * @private
  */
-
 export function flag(obj, key, value) {
   var flags = obj.__flags || (obj.__flags = Object.create(null));
   if (arguments.length === 3) {

package/lib/chai/utils/getActual.js

@@ -9,12 +9,12 @@
  *
  * Returns the `actual` value for an Assertion.
  *
- * @param {Object} object (constructed Assertion)
- * @param {Arguments} chai.Assertion.prototype.assert arguments
+ * @param {object} obj object (constructed Assertion)
+ * @param {unknown} args chai.Assertion.prototype.assert arguments
+ * @returns {unknown}
  * @namespace Utils
  * @name getActual
  */
-
 export function getActual(obj, args) {
   return args.length > 4 ? args[4] : obj._obj;
 }

package/lib/chai/utils/getEnumerableProperties.js

@@ -10,13 +10,12 @@
  * This allows the retrieval of enumerable property names of an object,
  * inherited or not.
  *
- * @param {Object} object
+ * @param {object} object
  * @returns {Array}
  * @namespace Utils
  * @name getEnumerableProperties
- * @api public
+ * @public
  */
-
 module.exports = function getEnumerableProperties(object) {
   var result = [];
   for (var name in object) {

package/lib/chai/utils/getMessage.js

@@ -20,13 +20,13 @@ import {objDisplay} from './objDisplay.js';
  * - `#{act}` actual value
  * - `#{exp}` expected value
  *
- * @param {Object} object (constructed Assertion)
- * @param {Arguments} chai.Assertion.prototype.assert arguments
+ * @param {object} obj object (constructed Assertion)
+ * @param {unknown} args chai.Assertion.prototype.assert arguments
+ * @returns {unknown}
  * @namespace Utils
  * @name getMessage
- * @api public
+ * @public
  */
-
 export function getMessage(obj, args) {
   var negate = flag(obj, 'negate')
     , val = flag(obj, 'object')

package/lib/chai/utils/getOperator.js

@@ -1,6 +1,10 @@
 import {flag} from './flag.js';
 import {type} from './type-detect.js';
 
+/**
+ * @param {unknown} obj
+ * @returns {boolean}
+ */
 function isObjectType(obj) {
   var objectType = type(obj);
   var objectTypes = ['Array', 'Object', 'Function'];
@@ -17,13 +21,13 @@ function isObjectType(obj) {
  *
  * Returns the `operator` or `undefined` value for an Assertion.
  *
- * @param {Object} object (constructed Assertion)
- * @param {Arguments} chai.Assertion.prototype.assert arguments
+ * @param {object} obj object (constructed Assertion)
+ * @param {unknown} args chai.Assertion.prototype.assert arguments
+ * @returns {unknown}
  * @namespace Utils
  * @name getOperator
- * @api public
+ * @public
  */
-
 export function getOperator(obj, args) {
   var operator = flag(obj, 'operator');
   var negate = flag(obj, 'negate');

package/lib/chai/utils/getOwnEnumerableProperties.js

@@ -13,13 +13,12 @@ import {getOwnEnumerablePropertySymbols} from './getOwnEnumerablePropertySymbols
  * symbols of an object. This function is necessary because Object.keys only
  * returns enumerable property names, not enumerable property symbols.
  *
- * @param {Object} object
+ * @param {object} obj
  * @returns {Array}
  * @namespace Utils
  * @name getOwnEnumerableProperties
- * @api public
+ * @public
  */
-
 export function getOwnEnumerableProperties(obj) {
   return Object.keys(obj).concat(getOwnEnumerablePropertySymbols(obj));
 }

package/lib/chai/utils/getOwnEnumerablePropertySymbols.js

@@ -11,13 +11,12 @@
  * object. This function is necessary because Object.getOwnPropertySymbols
  * returns both enumerable and non-enumerable property symbols.
  *
- * @param {Object} object
+ * @param {object} obj
  * @returns {Array}
  * @namespace Utils
  * @name getOwnEnumerablePropertySymbols
- * @api public
+ * @public
  */
-
 export function getOwnEnumerablePropertySymbols(obj) {
   if (typeof Object.getOwnPropertySymbols !== 'function') return [];
 

package/lib/chai/utils/getProperties.js

@@ -10,16 +10,18 @@
  * This allows the retrieval of property names of an object, enumerable or not,
  * inherited or not.
  *
- * @param {Object} object
+ * @param {object} object
  * @returns {Array}
  * @namespace Utils
  * @name getProperties
- * @api public
+ * @public
  */
-
 export function getProperties(object) {
   var result = Object.getOwnPropertyNames(object);
 
+  /**
+   * @param {unknown} property
+   */
   function addProperty(property) {
     if (result.indexOf(property) === -1) {
       result.push(property);

package/lib/chai/utils/index.js

@@ -11,7 +11,8 @@ import * as checkError from 'check-error';
 export {test} from './test.js';
 
 // type utility
-export {type} from './type-detect.js';
+import {type} from './type-detect.js';
+export {type};
 
 // expectTypes utility
 export {expectTypes} from './expectTypes.js';
@@ -40,7 +41,12 @@ export {default as eql} from 'deep-eql';
 // Deep path info
 export {getPathInfo, hasProperty} from 'pathval';
 
-// Function name
+/**
+ * Function name
+ *
+ * @param {Function} fn
+ * @returns {string}
+ */
 export function getName(fn) {
   return fn.name
 }
@@ -89,3 +95,18 @@ export {isNaN} from './isNaN.js';
 
 // getOperator method
 export {getOperator} from './getOperator.js';
+
+/**
+ * Determines if an object is a `RegExp`
+ * This is used since `instanceof` will not work in virtual contexts
+ *
+ * @param {*} obj Object to test
+ * @returns {boolean}
+ */
+export function isRegExp(obj) {
+  return Object.prototype.toString.call(obj) === '[object RegExp]';
+}
+
+export function isNumeric(obj) {
+  return ['Number', 'BigInt'].includes(type(obj))
+}

package/lib/chai/utils/inspect.js

@@ -10,12 +10,13 @@ import {config} from '../config.js';
  * Echoes the value of a value. Tries to print the value out
  * in the best way possible given the different types.
  *
- * @param {Object} obj The object to print out.
- * @param {Boolean} showHidden Flag that shows hidden (not enumerable)
+ * @param {object} obj The object to print out.
+ * @param {boolean} showHidden Flag that shows hidden (not enumerable)
  *    properties of objects. Default is false.
- * @param {Number} depth Depth in which to descend in object. Default is 2.
- * @param {Boolean} colors Flag to turn on ANSI escape codes to color the
+ * @param {number} depth Depth in which to descend in object. Default is 2.
+ * @param {boolean} colors Flag to turn on ANSI escape codes to color the
  *    output. Default is false (no coloring).
+ * @returns {string}
  * @namespace Utils
  * @name inspect
  */

package/lib/chai/utils/isNaN.js

@@ -11,11 +11,11 @@
  *
  *     utils.isNaN(NaN); // true
  *
- * @param {Value} The value which has to be checked if it is NaN
+ * @param {unknown} value The value which has to be checked if it is NaN
+ * @returns {boolean}
  * @name isNaN
- * @api private
+ * @private
  */
-
 function _isNaN(value) {
   // Refer http://www.ecma-international.org/ecma-262/6.0/#sec-isnan-number
   // section's NOTE.

package/lib/chai/utils/isProxyEnabled.js

@@ -15,8 +15,8 @@ import {config} from '../config.js';
  *
  * @namespace Utils
  * @name isProxyEnabled
+ * @returns {boolean}
  */
-
 export function isProxyEnabled() {
   return config.useProxy &&
     typeof Proxy !== 'undefined' &&

package/lib/chai/utils/objDisplay.js

@@ -14,13 +14,12 @@ import {config} from '../config.js';
  * criteria to be inspected in-line for error
  * messages or should be truncated.
  *
- * @param {Mixed} javascript object to inspect
+ * @param {unknown} obj javascript object to inspect
  * @returns {string} stringified object
  * @name objDisplay
  * @namespace Utils
- * @api public
+ * @public
  */
-
 export function objDisplay(obj) {
   var str = inspect(obj)
     , type = Object.prototype.toString.call(obj);

package/lib/chai/utils/overwriteChainableMethod.js

@@ -16,10 +16,10 @@ import {transferFlags} from './transferFlags.js';
  * name.
  *
  *     utils.overwriteChainableMethod(chai.Assertion.prototype, 'lengthOf',
- *       function (_super) {
- *       }
- *     , function (_super) {
- *       }
+ *         function (_super) {
+ *         }
+ *         , function (_super) {
+ *         }
  *     );
  *
  * Can also be accessed directly from `chai.Assertion`.
@@ -31,15 +31,14 @@ import {transferFlags} from './transferFlags.js';
  *     expect(myFoo).to.have.lengthOf(3);
  *     expect(myFoo).to.have.lengthOf.above(3);
  *
- * @param {Object} ctx object whose method / property is to be overwritten
- * @param {String} name of method / property to overwrite
+ * @param {object} ctx object whose method / property is to be overwritten
+ * @param {string} name of method / property to overwrite
  * @param {Function} method function that returns a function to be used for name
  * @param {Function} chainingBehavior function that returns a function to be used for property
  * @namespace Utils
  * @name overwriteChainableMethod
- * @api public
+ * @public
  */
-
 export function overwriteChainableMethod(ctx, name, method, chainingBehavior) {
   var chainableBehavior = ctx.__methods[name];
 

package/lib/chai/utils/overwriteMethod.js

@@ -18,14 +18,14 @@ import {transferFlags} from './transferFlags.js';
  * to be used for name.
  *
  *     utils.overwriteMethod(chai.Assertion.prototype, 'equal', function (_super) {
- *       return function (str) {
- *         var obj = utils.flag(this, 'object');
- *         if (obj instanceof Foo) {
- *           new chai.Assertion(obj.value).to.equal(str);
- *         } else {
- *           _super.apply(this, arguments);
+ *         return function (str) {
+ *             var obj = utils.flag(this, 'object');
+ *             if (obj instanceof Foo) {
+ *                 new chai.Assertion(obj.value).to.equal(str);
+ *             } else {
+ *                 _super.apply(this, arguments);
+ *             }
  *         }
- *       }
  *     });
  *
  * Can also be accessed directly from `chai.Assertion`.
@@ -36,14 +36,13 @@ import {transferFlags} from './transferFlags.js';
  *
  *     expect(myFoo).to.equal('bar');
  *
- * @param {Object} ctx object whose method is to be overwritten
- * @param {String} name of method to overwrite
+ * @param {object} ctx object whose method is to be overwritten
+ * @param {string} name of method to overwrite
  * @param {Function} method function that returns a function to be used for name
  * @namespace Utils
  * @name overwriteMethod
- * @api public
+ * @public
  */
-
 export function overwriteMethod(ctx, name, method) {
   var _method = ctx[name]
     , _super = function () {