chai 5.1.0 → 5.1.1

package/lib/chai/core/assertions.js

@@ -39,7 +39,7 @@ const {flag} = _;
  *
  * @name language chains
  * @namespace BDD
- * @api public
+ * @public
  */
 
 [ 'to', 'be', 'been', 'is'
@@ -69,7 +69,7 @@ const {flag} = _;
  *
  * @name not
  * @namespace BDD
- * @api public
+ * @public
  */
 
 Assertion.addProperty('not', function () {
@@ -110,7 +110,7 @@ Assertion.addProperty('not', function () {
  *
  * @name deep
  * @namespace BDD
- * @api public
+ * @public
  */
 
 Assertion.addProperty('deep', function () {
@@ -136,7 +136,7 @@ Assertion.addProperty('deep', function () {
  *
  * @name nested
  * @namespace BDD
- * @api public
+ * @public
  */
 
 Assertion.addProperty('nested', function () {
@@ -162,7 +162,7 @@ Assertion.addProperty('nested', function () {
  *
  * @name own
  * @namespace BDD
- * @api public
+ * @public
  */
 
 Assertion.addProperty('own', function () {
@@ -186,7 +186,7 @@ Assertion.addProperty('own', function () {
  *
  * @name ordered
  * @namespace BDD
- * @api public
+ * @public
  */
 
 Assertion.addProperty('ordered', function () {
@@ -206,7 +206,7 @@ Assertion.addProperty('ordered', function () {
  *
  * @name any
  * @namespace BDD
- * @api public
+ * @public
  */
 
 Assertion.addProperty('any', function () {
@@ -231,7 +231,7 @@ Assertion.addProperty('any', function () {
  *
  * @name all
  * @namespace BDD
- * @api public
+ * @public
  */
 
 Assertion.addProperty('all', function () {
@@ -265,7 +265,7 @@ const functionTypes = {
  * `.a` supports objects that have a custom type set via `Symbol.toStringTag`.
  *
  *     var myObj = {
- *       [Symbol.toStringTag]: 'myCustomType'
+ *         [Symbol.toStringTag]: 'myCustomType'
  *     };
  *
  *     expect(myObj).to.be.a('myCustomType').but.not.an('object');
@@ -300,10 +300,10 @@ const functionTypes = {
  *
  * @name a
  * @alias an
- * @param {String} type
- * @param {String} msg _optional_
+ * @param {string} type
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
 function an (type, msg) {
   if (msg) flag(this, 'message', msg);
@@ -331,6 +331,23 @@ function an (type, msg) {
 Assertion.addChainableMethod('an', an);
 Assertion.addChainableMethod('a', an);
 
+/**
+ *
+ * @param {unknown} a
+ * @param {unknown} b
+ * @returns {boolean}
+ */
+function SameValueZero(a, b) {
+  return (_.isNaN(a) && _.isNaN(b)) || a === b;
+}
+
+/**
+ *
+ */
+function includeChainingBehavior () {
+  flag(this, 'contains', true);
+}
+
 /**
  * ### .include(val[, msg])
  *
@@ -472,20 +489,11 @@ Assertion.addChainableMethod('a', an);
  * @alias contain
  * @alias includes
  * @alias contains
- * @param {Mixed} val
- * @param {String} msg _optional_
+ * @param {unknown} val
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
-function SameValueZero(a, b) {
-  return (_.isNaN(a) && _.isNaN(b)) || a === b;
-}
-
-function includeChainingBehavior () {
-  flag(this, 'contains', true);
-}
-
 function include (val, msg) {
   if (msg) flag(this, 'message', msg);
 
@@ -643,9 +651,8 @@ Assertion.addChainableMethod('includes', include, includeChainingBehavior);
  *
  * @name ok
  * @namespace BDD
- * @api public
+ * @public
  */
-
 Assertion.addProperty('ok', function () {
   this.assert(
       flag(this, 'object')
@@ -676,9 +683,8 @@ Assertion.addProperty('ok', function () {
  *
  * @name true
  * @namespace BDD
- * @api public
+ * @public
  */
-
 Assertion.addProperty('true', function () {
   this.assert(
       true === flag(this, 'object')
@@ -701,7 +707,7 @@ Assertion.addProperty('true', function () {
  *
  * @name callable
  * @namespace BDD
- * @api public
+ * @public
  */
 Assertion.addProperty('callable', function () {
   const val = flag(this, 'object')
@@ -748,9 +754,8 @@ Assertion.addProperty('callable', function () {
  *
  * @name false
  * @namespace BDD
- * @api public
+ * @public
  */
-
 Assertion.addProperty('false', function () {
   this.assert(
       false === flag(this, 'object')
@@ -780,9 +785,8 @@ Assertion.addProperty('false', function () {
  *
  * @name null
  * @namespace BDD
- * @api public
+ * @public
  */
-
 Assertion.addProperty('null', function () {
   this.assert(
       null === flag(this, 'object')
@@ -811,9 +815,8 @@ Assertion.addProperty('null', function () {
  *
  * @name undefined
  * @namespace BDD
- * @api public
+ * @public
  */
-
 Assertion.addProperty('undefined', function () {
   this.assert(
       undefined === flag(this, 'object')
@@ -842,9 +845,8 @@ Assertion.addProperty('undefined', function () {
  *
  * @name NaN
  * @namespace BDD
- * @api public
+ * @public
  */
-
 Assertion.addProperty('NaN', function () {
   this.assert(
       _.isNaN(flag(this, 'object'))
@@ -883,9 +885,8 @@ Assertion.addProperty('NaN', function () {
  * @name exist
  * @alias exists
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function assertExist () {
   var val = flag(this, 'object');
   this.assert(
@@ -944,9 +945,8 @@ Assertion.addProperty('exists', assertExist);
  *
  * @name empty
  * @namespace BDD
- * @api public
+ * @public
  */
-
 Assertion.addProperty('empty', function () {
   var val = flag(this, 'object')
     , ssfi = flag(this, 'ssfi')
@@ -998,7 +998,7 @@ Assertion.addProperty('empty', function () {
  * Asserts that the target is an `arguments` object.
  *
  *     function test () {
- *       expect(arguments).to.be.arguments;
+ *         expect(arguments).to.be.arguments;
  *     }
  *
  *     test();
@@ -1019,9 +1019,8 @@ Assertion.addProperty('empty', function () {
  * @name arguments
  * @alias Arguments
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function checkArguments () {
   var obj = flag(this, 'object')
     , type = _.type(obj);
@@ -1074,12 +1073,11 @@ Assertion.addProperty('Arguments', checkArguments);
  * @name equal
  * @alias equals
  * @alias eq
- * @param {Mixed} val
- * @param {String} msg _optional_
+ * @param {unknown} val
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function assertEqual (val, msg) {
   if (msg) flag(this, 'message', msg);
   var obj = flag(this, 'object');
@@ -1139,12 +1137,11 @@ Assertion.addMethod('eq', assertEqual);
  *
  * @name eql
  * @alias eqls
- * @param {Mixed} obj
- * @param {String} msg _optional_
+ * @param {unknown} obj
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function assertEql(obj, msg) {
   if (msg) flag(this, 'message', msg);
   var eql = flag(this, 'eql');
@@ -1198,12 +1195,11 @@ Assertion.addMethod('eqls', assertEql);
  * @name above
  * @alias gt
  * @alias greaterThan
- * @param {Number} n
- * @param {String} msg _optional_
+ * @param {number} n
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function assertAbove (n, msg) {
   if (msg) flag(this, 'message', msg);
   var obj = flag(this, 'object')
@@ -1303,12 +1299,11 @@ Assertion.addMethod('greaterThan', assertAbove);
  * @name least
  * @alias gte
  * @alias greaterThanOrEqual
- * @param {Number} n
- * @param {String} msg _optional_
+ * @param {number} n
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function assertLeast (n, msg) {
   if (msg) flag(this, 'message', msg);
   var obj = flag(this, 'object')
@@ -1407,12 +1402,11 @@ Assertion.addMethod('greaterThanOrEqual', assertLeast);
  * @name below
  * @alias lt
  * @alias lessThan
- * @param {Number} n
- * @param {String} msg _optional_
+ * @param {number} n
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function assertBelow (n, msg) {
   if (msg) flag(this, 'message', msg);
   var obj = flag(this, 'object')
@@ -1512,12 +1506,11 @@ Assertion.addMethod('lessThan', assertBelow);
  * @name most
  * @alias lte
  * @alias lessThanOrEqual
- * @param {Number} n
- * @param {String} msg _optional_
+ * @param {number} n
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function assertMost (n, msg) {
   if (msg) flag(this, 'message', msg);
   var obj = flag(this, 'object')
@@ -1615,13 +1608,12 @@ Assertion.addMethod('lessThanOrEqual', assertMost);
  *     expect(4, 'nooo why fail??').to.be.within(1, 3);
  *
  * @name within
- * @param {Number} start lower bound inclusive
- * @param {Number} finish upper bound inclusive
- * @param {String} msg _optional_
+ * @param {number} start lower bound inclusive
+ * @param {number} finish upper bound inclusive
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 Assertion.addMethod('within', function (start, finish, msg) {
   if (msg) flag(this, 'message', msg);
   var obj = flag(this, 'object')
@@ -1712,13 +1704,12 @@ Assertion.addMethod('within', function (start, finish, msg) {
  * The alias `.instanceOf` can be used interchangeably with `.instanceof`.
  *
  * @name instanceof
- * @param {Constructor} constructor
- * @param {String} msg _optional_
+ * @param {unknown} constructor
+ * @param {string} msg _optional_
  * @alias instanceOf
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function assertInstanceOf (constructor, msg) {
   if (msg) flag(this, 'message', msg);
 
@@ -1860,14 +1851,12 @@ Assertion.addMethod('instanceOf', assertInstanceOf);
  * interchangeably with `.own.property`.
  *
  * @name property
- * @param {String} name
- * @param {Mixed} val (optional)
- * @param {String} msg _optional_
- * @returns value of property for chaining
+ * @param {string} name
+ * @param {unknown} val (optional)
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function assertProperty (name, val, msg) {
   if (msg) flag(this, 'message', msg);
 
@@ -1958,6 +1947,12 @@ function assertProperty (name, val, msg) {
 
 Assertion.addMethod('property', assertProperty);
 
+/**
+ *
+ * @param {unknown} name
+ * @param {unknown} value
+ * @param {string} msg
+ */
 function assertOwnProperty (name, value, msg) {
   flag(this, 'own', true);
   assertProperty.apply(this, arguments);
@@ -1981,10 +1976,10 @@ Assertion.addMethod('haveOwnProperty', assertOwnProperty);
  * https://github.com/chaijs/deep-eql.
  *
  *     expect({a: 1}).to.have.ownPropertyDescriptor('a', {
- *       configurable: true,
- *       enumerable: true,
- *       writable: true,
- *       value: 1,
+ *         configurable: true,
+ *         enumerable: true,
+ *         writable: true,
+ *         value: 1,
  *     });
  *
  * Add `.not` earlier in the chain to negate `.ownPropertyDescriptor`.
@@ -2007,10 +2002,10 @@ Assertion.addMethod('haveOwnProperty', assertOwnProperty);
  *
  *     // Not recommended
  *     expect({b: 2}).to.not.have.ownPropertyDescriptor('a', {
- *       configurable: true,
- *       enumerable: true,
- *       writable: true,
- *       value: 1,
+ *         configurable: true,
+ *         enumerable: true,
+ *         writable: true,
+ *         value: 1,
  *     });
  *
  * When the target is expected to have a property descriptor with the given
@@ -2020,18 +2015,18 @@ Assertion.addMethod('haveOwnProperty', assertOwnProperty);
  *
  *     // Recommended
  *     expect({a: 3}).to.have.ownPropertyDescriptor('a', {
- *       configurable: true,
- *       enumerable: true,
- *       writable: true,
- *       value: 3,
+ *         configurable: true,
+ *         enumerable: true,
+ *         writable: true,
+ *         value: 3,
  *     });
  *
  *     // Not recommended
  *     expect({a: 3}).to.not.have.ownPropertyDescriptor('a', {
- *       configurable: true,
- *       enumerable: true,
- *       writable: true,
- *       value: 1,
+ *         configurable: true,
+ *         enumerable: true,
+ *         writable: true,
+ *         value: 1,
  *     });
  *
  * `.ownPropertyDescriptor` changes the target of any assertions that follow
@@ -2048,18 +2043,18 @@ Assertion.addMethod('haveOwnProperty', assertOwnProperty);
  *
  *     // Recommended
  *     expect({a: 1}).to.have.ownPropertyDescriptor('a', {
- *       configurable: true,
- *       enumerable: true,
- *       writable: true,
- *       value: 2,
+ *         configurable: true,
+ *         enumerable: true,
+ *         writable: true,
+ *         value: 2,
  *     }, 'nooo why fail??');
  *
  *     // Recommended
  *     expect({a: 1}, 'nooo why fail??').to.have.ownPropertyDescriptor('a', {
- *       configurable: true,
- *       enumerable: true,
- *       writable: true,
- *       value: 2,
+ *         configurable: true,
+ *         enumerable: true,
+ *         writable: true,
+ *         value: 2,
  *     });
  *
  *     // Recommended
@@ -2078,13 +2073,12 @@ Assertion.addMethod('haveOwnProperty', assertOwnProperty);
  *
  * @name ownPropertyDescriptor
  * @alias haveOwnPropertyDescriptor
- * @param {String} name
- * @param {Object} descriptor _optional_
- * @param {String} msg _optional_
+ * @param {string} name
+ * @param {object} descriptor _optional_
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function assertOwnPropertyDescriptor (name, descriptor, msg) {
   if (typeof descriptor === 'string') {
     msg = descriptor;
@@ -2116,6 +2110,13 @@ function assertOwnPropertyDescriptor (name, descriptor, msg) {
 Assertion.addMethod('ownPropertyDescriptor', assertOwnPropertyDescriptor);
 Assertion.addMethod('haveOwnPropertyDescriptor', assertOwnPropertyDescriptor);
 
+/**
+ *
+ */
+function assertLengthChain () {
+  flag(this, 'doLength', true);
+}
+
 /**
  * ### .lengthOf(n[, msg])
  *
@@ -2168,16 +2169,11 @@ Assertion.addMethod('haveOwnPropertyDescriptor', assertOwnPropertyDescriptor);
  *
  * @name lengthOf
  * @alias length
- * @param {Number} n
- * @param {String} msg _optional_
+ * @param {number} n
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
-function assertLengthChain () {
-  flag(this, 'doLength', true);
-}
-
 function assertLength (n, msg) {
   if (msg) flag(this, 'message', msg);
   var obj = flag(this, 'object')
@@ -2233,9 +2229,9 @@ Assertion.addChainableMethod('lengthOf', assertLength, assertLengthChain);
  * @name match
  * @alias matches
  * @param {RegExp} re
- * @param {String} msg _optional_
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
 function assertMatch(re, msg) {
   if (msg) flag(this, 'message', msg);
@@ -2269,12 +2265,11 @@ Assertion.addMethod('matches', assertMatch);
  *     expect('foobar', 'nooo why fail??').to.have.string('taco');
  *
  * @name string
- * @param {String} str
- * @param {String} msg _optional_
+ * @param {string} str
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 Assertion.addMethod('string', function (str, msg) {
   if (msg) flag(this, 'message', msg);
   var obj = flag(this, 'object')
@@ -2388,11 +2383,10 @@ Assertion.addMethod('string', function (str, msg) {
  *
  * @name keys
  * @alias key
- * @param {...String|Array|Object} keys
+ * @param {...string | Array | object} keys
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function assertKeys (keys) {
   var obj = flag(this, 'object')
     , objType = _.type(obj)
@@ -2522,7 +2516,6 @@ Assertion.addMethod('key', assertKeys);
  * asserts that an error is thrown.
  *
  *     var badFn = function () { throw new TypeError('Illegal salmon!'); };
- *
  *     expect(badFn).to.throw();
  *
  * When one argument is provided, and it's an error constructor, `.throw`
@@ -2530,7 +2523,6 @@ Assertion.addMethod('key', assertKeys);
  * instance of that error constructor.
  *
  *     var badFn = function () { throw new TypeError('Illegal salmon!'); };
- *
  *     expect(badFn).to.throw(TypeError);
  *
  * When one argument is provided, and it's an error instance, `.throw` invokes
@@ -2547,7 +2539,6 @@ Assertion.addMethod('key', assertKeys);
  * contains that string.
  *
  *     var badFn = function () { throw new TypeError('Illegal salmon!'); };
- *
  *     expect(badFn).to.throw('salmon');
  *
  * When one argument is provided, and it's a regular expression, `.throw`
@@ -2555,7 +2546,6 @@ Assertion.addMethod('key', assertKeys);
  * message that matches that regular expression.
  *
  *     var badFn = function () { throw new TypeError('Illegal salmon!'); };
- *
  *     expect(badFn).to.throw(/salmon/);
  *
  * When two arguments are provided, and the first is an error instance or
@@ -2574,7 +2564,6 @@ Assertion.addMethod('key', assertKeys);
  * Add `.not` earlier in the chain to negate `.throw`.
  *
  *     var goodFn = function () {};
- *
  *     expect(goodFn).to.not.throw();
  *
  * However, it's dangerous to negate `.throw` when providing any arguments.
@@ -2671,15 +2660,14 @@ Assertion.addMethod('key', assertKeys);
  * @name throw
  * @alias throws
  * @alias Throw
- * @param {Error|ErrorConstructor} errorLike
- * @param {String|RegExp} errMsgMatcher error message
- * @param {String} msg _optional_
+ * @param {Error} errorLike
+ * @param {string | RegExp} errMsgMatcher error message
+ * @param {string} msg _optional_
  * @see https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error#Error_types
- * @returns error for chaining (null if no error)
+ * @returns {void} error for chaining (null if no error)
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function assertThrows (errorLike, errMsgMatcher, msg) {
   if (msg) flag(this, 'message', msg);
   var obj = flag(this, 'object')
@@ -2688,15 +2676,17 @@ function assertThrows (errorLike, errMsgMatcher, msg) {
     , negate = flag(this, 'negate') || false;
   new Assertion(obj, flagMsg, ssfi, true).is.a('function');
 
-  if (errorLike instanceof RegExp || typeof errorLike === 'string') {
+  if (_.isRegExp(errorLike) || typeof errorLike === 'string') {
     errMsgMatcher = errorLike;
     errorLike = null;
   }
 
-  var caughtErr;
+  let caughtErr;
+  let errorWasThrown = false;
   try {
     obj();
   } catch (err) {
+    errorWasThrown = true;
     caughtErr = err;
   }
 
@@ -2720,14 +2710,26 @@ function assertThrows (errorLike, errMsgMatcher, msg) {
       errorLikeString = _.checkError.getConstructorName(errorLike);
     }
 
+    let actual = caughtErr;
+    if (caughtErr instanceof Error) {
+      actual = caughtErr.toString();
+    } else if (typeof caughtErr === 'string') {
+      actual = caughtErr;
+    } else if (caughtErr && (typeof caughtErr === 'object' || typeof caughtErr === 'function')) {
+      try {
+        actual = _.checkError.getConstructorName(caughtErr);
+      } catch (_err) {
+        // somehow wasn't a constructor, maybe we got a function thrown
+        // or similar
+      }
+    }
+
     this.assert(
-        caughtErr
+      errorWasThrown
       , 'expected #{this} to throw ' + errorLikeString
       , 'expected #{this} to not throw an error but #{act} was thrown'
       , errorLike && errorLike.toString()
-      , (caughtErr instanceof Error ?
-          caughtErr.toString() : (typeof caughtErr === 'string' ? caughtErr : caughtErr &&
-                                  _.checkError.getConstructorName(caughtErr)))
+      , actual
     );
   }
 
@@ -2772,7 +2774,7 @@ function assertThrows (errorLike, errMsgMatcher, msg) {
   if (caughtErr && errMsgMatcher !== undefined && errMsgMatcher !== null) {
     // Here we check compatible messages
     var placeholder = 'including';
-    if (errMsgMatcher instanceof RegExp) {
+    if (_.isRegExp(errMsgMatcher)) {
       placeholder = 'matching'
     }
 
@@ -2869,12 +2871,11 @@ Assertion.addMethod('Throw', assertThrows);
  *
  * @name respondTo
  * @alias respondsTo
- * @param {String} method
- * @param {String} msg _optional_
+ * @param {string} method
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function respondTo (method, msg) {
   if (msg) flag(this, 'message', msg);
   var obj = flag(this, 'object')
@@ -2910,9 +2911,8 @@ Assertion.addMethod('respondsTo', respondTo);
  *
  * @name itself
  * @namespace BDD
- * @api public
+ * @public
  */
-
 Assertion.addProperty('itself', function () {
   flag(this, 'itself', true);
 });
@@ -2924,13 +2924,13 @@ Assertion.addProperty('itself', function () {
  * first argument, and asserts that the value returned is truthy.
  *
  *     expect(1).to.satisfy(function(num) {
- *       return num > 0;
+ *         return num > 0;
  *     });
  *
  * Add `.not` earlier in the chain to negate `.satisfy`.
  *
  *     expect(1).to.not.satisfy(function(num) {
- *       return num > 2;
+ *         return num > 2;
  *     });
  *
  * `.satisfy` accepts an optional `msg` argument which is a custom error
@@ -2938,11 +2938,11 @@ Assertion.addProperty('itself', function () {
  * the second argument to `expect`.
  *
  *     expect(1).to.satisfy(function(num) {
- *       return num > 2;
+ *         return num > 2;
  *     }, 'nooo why fail??');
  *
  *     expect(1, 'nooo why fail??').to.satisfy(function(num) {
- *       return num > 2;
+ *         return num > 2;
  *     });
  *
  * The alias `.satisfies` can be used interchangeably with `.satisfy`.
@@ -2950,11 +2950,10 @@ Assertion.addProperty('itself', function () {
  * @name satisfy
  * @alias satisfies
  * @param {Function} matcher
- * @param {String} msg _optional_
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function satisfy (matcher, msg) {
   if (msg) flag(this, 'message', msg);
   var obj = flag(this, 'object');
@@ -3002,13 +3001,12 @@ Assertion.addMethod('satisfies', satisfy);
  *
  * @name closeTo
  * @alias approximately
- * @param {Number} expected
- * @param {Number} delta
- * @param {String} msg _optional_
+ * @param {number} expected
+ * @param {number} delta
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function closeTo(expected, delta, msg) {
   if (msg) flag(this, 'message', msg);
   var obj = flag(this, 'object')
@@ -3036,7 +3034,14 @@ function closeTo(expected, delta, msg) {
 Assertion.addMethod('closeTo', closeTo);
 Assertion.addMethod('approximately', closeTo);
 
-// Note: Duplicates are ignored if testing for inclusion instead of sameness.
+/**
+ * @param {unknown} _subset
+ * @param {unknown} _superset
+ * @param {unknown} cmp
+ * @param {unknown} contains
+ * @param {unknown} ordered
+ * @returns {boolean}
+ */
 function isSubsetOf(_subset, _superset, cmp, contains, ordered) {
   let superset = Array.from(_superset);
   let subset = Array.from(_subset);
@@ -3131,9 +3136,9 @@ function isSubsetOf(_subset, _superset, cmp, contains, ordered) {
  *
  * @name members
  * @param {Array} set
- * @param {String} msg _optional_
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
 Assertion.addMethod('members', function (subset, msg) {
   if (msg) flag(this, 'message', msg);
@@ -3190,7 +3195,7 @@ Assertion.addMethod('members', function (subset, msg) {
  *
  * @name iterable
  * @namespace BDD
- * @api public
+ * @public
  */
 Assertion.addProperty('iterable', function(msg) {
   if (msg) flag(this, 'message', msg);
@@ -3237,11 +3242,10 @@ Assertion.addProperty('iterable', function(msg) {
  *
  * @name oneOf
  * @param {Array<*>} list
- * @param {String} msg _optional_
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function oneOf (list, msg) {
   if (msg) flag(this, 'message', msg);
   var expected = flag(this, 'object')
@@ -3292,8 +3296,8 @@ Assertion.addMethod('oneOf', oneOf);
  * to assert that `subject` is equal to its expected value.
  *
  *     var dots = ''
- *       , addDot = function () { dots += '.'; }
- *       , getDots = function () { return dots; };
+ *     , addDot = function () { dots += '.'; }
+ *     , getDots = function () { return dots; };
  *
  *     // Recommended
  *     expect(getDots()).to.equal('');
@@ -3308,7 +3312,7 @@ Assertion.addMethod('oneOf', oneOf);
  * target function compared to afterward.
  *
  *     var myObj = {dots: ''}
- *       , addDot = function () { myObj.dots += '.'; };
+ *     , addDot = function () { myObj.dots += '.'; };
  *
  *     // Recommended
  *     expect(myObj).to.have.property('dots', '');
@@ -3323,13 +3327,13 @@ Assertion.addMethod('oneOf', oneOf);
  * Add `.not` earlier in the chain to negate `.change`.
  *
  *     var dots = ''
- *       , noop = function () {}
- *       , getDots = function () { return dots; };
+ *     , noop = function () {}
+ *     , getDots = function () { return dots; };
  *
  *     expect(noop).to.not.change(getDots);
  *
  *     var myObj = {dots: ''}
- *       , noop = function () {};
+ *     , noop = function () {};
  *
  *     expect(noop).to.not.change(myObj, 'dots');
  *
@@ -3339,13 +3343,13 @@ Assertion.addMethod('oneOf', oneOf);
  * use the second form.
  *
  *     var myObj = {dots: ''}
- *       , addDot = function () { myObj.dots += '.'; };
+ *     , addDot = function () { myObj.dots += '.'; };
  *
  *     expect(addDot).to.not.change(myObj, 'dots', 'nooo why fail??');
  *
  *     var dots = ''
- *       , addDot = function () { dots += '.'; }
- *       , getDots = function () { return dots; };
+ *     , addDot = function () { dots += '.'; }
+ *     , getDots = function () { return dots; };
  *
  *     expect(addDot, 'nooo why fail??').to.not.change(getDots);
  *
@@ -3358,8 +3362,8 @@ Assertion.addMethod('oneOf', oneOf);
  * that only accepts that exact output.
  *
  *     var myObj = {val: 1}
- *       , addTwo = function () { myObj.val += 2; }
- *       , subtractTwo = function () { myObj.val -= 2; };
+ *     , addTwo = function () { myObj.val += 2; }
+ *     , subtractTwo = function () { myObj.val -= 2; };
  *
  *     expect(addTwo).to.increase(myObj, 'val').by(2); // Recommended
  *     expect(addTwo).to.change(myObj, 'val').by(2); // Not recommended
@@ -3371,13 +3375,12 @@ Assertion.addMethod('oneOf', oneOf);
  *
  * @name change
  * @alias changes
- * @param {String} subject
- * @param {String} prop name _optional_
- * @param {String} msg _optional_
+ * @param {string} subject
+ * @param {string} prop name _optional_
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function assertChanges (subject, prop, msg) {
   if (msg) flag(this, 'message', msg);
   var fn = flag(this, 'object')
@@ -3428,8 +3431,8 @@ Assertion.addMethod('changes', assertChanges);
  * by any amount.
  *
  *     var val = 1
- *       , addTwo = function () { val += 2; }
- *       , getVal = function () { return val; };
+ *     , addTwo = function () { val += 2; }
+ *     , getVal = function () { return val; };
  *
  *     expect(addTwo).to.increase(getVal).by(2); // Recommended
  *     expect(addTwo).to.increase(getVal); // Not recommended
@@ -3439,7 +3442,7 @@ Assertion.addMethod('changes', assertChanges);
  * target function compared to beforehand.
  *
  *     var myObj = {val: 1}
- *       , addTwo = function () { myObj.val += 2; };
+ *     , addTwo = function () { myObj.val += 2; };
  *
  *     expect(addTwo).to.increase(myObj, 'val').by(2); // Recommended
  *     expect(addTwo).to.increase(myObj, 'val'); // Not recommended
@@ -3454,7 +3457,7 @@ Assertion.addMethod('changes', assertChanges);
  * decreased by the expected amount.
  *
  *     var myObj = {val: 1}
- *       , subtractTwo = function () { myObj.val -= 2; };
+ *     , subtractTwo = function () { myObj.val -= 2; };
  *
  *     expect(subtractTwo).to.decrease(myObj, 'val').by(2); // Recommended
  *     expect(subtractTwo).to.not.increase(myObj, 'val'); // Not recommended
@@ -3463,7 +3466,7 @@ Assertion.addMethod('changes', assertChanges);
  * exactly that.
  *
  *     var myObj = {val: 1}
- *       , noop = function () {};
+ *     , noop = function () {};
  *
  *     expect(noop).to.not.change(myObj, 'val'); // Recommended
  *     expect(noop).to.not.increase(myObj, 'val'); // Not recommended
@@ -3474,13 +3477,13 @@ Assertion.addMethod('changes', assertChanges);
  * use the second form.
  *
  *     var myObj = {val: 1}
- *       , noop = function () {};
+ *     , noop = function () {};
  *
  *     expect(noop).to.increase(myObj, 'val', 'nooo why fail??');
  *
  *     var val = 1
- *       , noop = function () {}
- *       , getVal = function () { return val; };
+ *     , noop = function () {}
+ *     , getVal = function () { return val; };
  *
  *     expect(noop, 'nooo why fail??').to.increase(getVal);
  *
@@ -3488,13 +3491,12 @@ Assertion.addMethod('changes', assertChanges);
  *
  * @name increase
  * @alias increases
- * @param {String|Function} subject
- * @param {String} prop name _optional_
- * @param {String} msg _optional_
+ * @param {string | Function} subject
+ * @param {string} prop name _optional_
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function assertIncreases (subject, prop, msg) {
   if (msg) flag(this, 'message', msg);
   var fn = flag(this, 'object')
@@ -3607,13 +3609,12 @@ Assertion.addMethod('increases', assertIncreases);
  *
  * @name decrease
  * @alias decreases
- * @param {String|Function} subject
- * @param {String} prop name _optional_
- * @param {String} msg _optional_
+ * @param {string | Function} subject
+ * @param {string} prop name _optional_
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function assertDecreases (subject, prop, msg) {
   if (msg) flag(this, 'message', msg);
   var fn = flag(this, 'object')
@@ -3714,12 +3715,11 @@ Assertion.addMethod('decreases', assertDecreases);
  *     expect(addTwo, 'nooo why fail??').to.increase(myObj, 'val').by(3);
  *
  * @name by
- * @param {Number} delta
- * @param {String} msg _optional_
+ * @param {number} delta
+ * @param {string} msg _optional_
  * @namespace BDD
- * @api public
+ * @public
  */
-
 function assertDelta(delta, msg) {
   if (msg) flag(this, 'message', msg);
 
@@ -3756,8 +3756,8 @@ Assertion.addMethod('by', assertDelta);
  * Add `.not` earlier in the chain to negate `.extensible`.
  *
  *     var nonExtensibleObject = Object.preventExtensions({})
- *       , sealedObject = Object.seal({})
- *       , frozenObject = Object.freeze({});
+ *     , sealedObject = Object.seal({})
+ *     , frozenObject = Object.freeze({});
  *
  *     expect(nonExtensibleObject).to.not.be.extensible;
  *     expect(sealedObject).to.not.be.extensible;
@@ -3770,9 +3770,8 @@ Assertion.addMethod('by', assertDelta);
  *
  * @name extensible
  * @namespace BDD
- * @api public
+ * @public
  */
-
 Assertion.addProperty('extensible', function() {
   var obj = flag(this, 'object');
 
@@ -3815,9 +3814,8 @@ Assertion.addProperty('extensible', function() {
  *
  * @name sealed
  * @namespace BDD
- * @api public
+ * @public
  */
-
 Assertion.addProperty('sealed', function() {
   var obj = flag(this, 'object');
 
@@ -3857,9 +3855,8 @@ Assertion.addProperty('sealed', function() {
  *
  * @name frozen
  * @namespace BDD
- * @api public
+ * @public
  */
-
 Assertion.addProperty('frozen', function() {
   var obj = flag(this, 'object');
 
@@ -3923,9 +3920,8 @@ Assertion.addProperty('frozen', function() {
  *
  * @name finite
  * @namespace BDD
- * @api public
+ * @public
  */
-
 Assertion.addProperty('finite', function(msg) {
   var obj = flag(this, 'object');