fast-equals 5.0.0-beta.4 → 5.0.0-beta.6

package/CHANGELOG.md

@@ -4,9 +4,21 @@
 
 ### Breaking changes
 
+#### `constructor` equality now required
+
+To align with other implementations common in the community, but also to be more functionally correct, the two objects being compared now must have equal `constructor`s.
+
+#### `Map` / `Set` comparisons no longer support IE11
+
+In previous verisons, `.forEach()` was used to ensure that support for `Symbol` was not required, as IE11 did not have `Symbol` and therefore both `Map` and `Set` did not have iterator-based methods such as `.values()` or `.entries()`. Since IE11 is no longer a supported browser, and support for those methods is present in all browsers and Node for quite a while, the comparison has moved to use these methods. This results in a ~20% performance increase.
+
 #### `createCustomEqual` contract has changed
 
-To better facilitate strict comparisons, but also to allow for `meta` use separate from caching, the contract for `createCustomEqual` has changed. See the [README documentation](./README.md#createcustomequal) for more details.
+To better facilitate strict comparisons, but also to allow for `meta` use separate from caching, the contract for `createCustomEqual` has changed. See the [README documentation](./README.md#createcustomequal) for more details, but froma high-level:
+
+- `meta` is no longer passed through to equality comparators, but rather a general `state` object which contains `meta`
+- `cache` now also lives on the `state` object, which allows for use of the `meta` property separate from but in parallel with the circular cache
+- `equals` is now on `state`, which prevents the need to pass through the separate `isEqual` method for the equality comparator
 
 #### `createCustomCircularEqual` has been removed
 

package/README.md

@@ -4,18 +4,21 @@
 <img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg"/>
 <img src="https://img.shields.io/badge/license-MIT-blue.svg"/>
 
-Perform [blazing fast](#benchmarks) equality comparisons (either deep or shallow) on two objects passed. It has no dependencies, and is ~1.75kB when minified and gzipped.
+Perform [blazing fast](#benchmarks) equality comparisons (either deep or shallow) on two objects passed, while also maintaining a high degree of flexibility for various implementation use-cases. It has no dependencies, and is ~1.8kB when minified and gzipped.
 
-Unlike most equality validation libraries, the following types are handled out-of-the-box:
+The following types are handled out-of-the-box:
 
-- `NaN`
+- Plain objects (including `react` elements and `Arguments`)
+- Arrays
+- Typed Arrays
 - `Date` objects
 - `RegExp` objects
 - `Map` / `Set` iterables
 - `Promise` objects
-- `react` elements
+- Primitive wrappers (`new Boolean()` / `new Number()` / `new String()`)
+- Custom class instances, including subclasses of native classes
 
-Starting with version `1.5.0`, circular objects are supported for both deep and shallow equality (see [`circularDeepEqual`](#circulardeepequal) and [`circularShallowEqual`](#circularshallowequal)). You can also create a custom nested comparator, for specific scenarios ([see below](#createcustomequal)).
+Methods are available for deep, shallow, or referential equality comparison. In addition, you can opt into support for circular objects, or performing a "strict" comparison with unconventional property definition, or both. You can also customize any specific type comparison based on your application's use-cases.
 
 ## Table of contents
 
@@ -162,7 +165,6 @@ console.log(circularShallowEqual(array, [array])); // false
 
 Performs the same comparison as `deepEqual` but performs a strict comparison of the objects. In this includes:
 
-- Checking constructors match
 - Checking non-enumerable properties in object comparisons
 - Checking full descriptor of properties on the object to match
 - Checking non-index properties on arrays
@@ -269,24 +271,13 @@ Creates a custom equality comparator that will be used on nested values in the o
 The signature is as follows:
 
 ```ts
-interface BaseCircular extends Pick<WeakMap<any, any>, 'delete' | 'get'> {
-  set(key: object, value: any): any;
-}
-
-interface DefaultState<Meta> {
-  readonly cache: undefined | BaseCircular;
-  readonly equals: InternalEqualityComparator<Meta>;
-  meta: Meta;
-  readonly strict: boolean;
+interface Cache<Key extends object, Value> {
+  delete(key: Key): boolean;
+  get(key: Key): Value | undefined;
+  set(key: Key, value: any): any;
 }
 
-type EqualityComparator<Meta> = <A, B>(
-  a: A,
-  b: B,
-  state: State<Meta>,
-) => boolean;
-
-interface CreateComparatorCreatorOptions<Meta> {
+interface ComparatorConfig<Meta> {
   areArraysEqual: TypeEqualityComparator<any[], Meta>;
   areDatesEqual: TypeEqualityComparator<Date, Meta>;
   areMapsEqual: TypeEqualityComparator<Map<any, any>, Meta>;
@@ -300,20 +291,25 @@ interface CreateComparatorCreatorOptions<Meta> {
   areTypedArraysEqual: TypeEqualityComparatory<TypedArray, Meta>;
 }
 
-interface CustomEqualCreatorOptions<Meta> {
+function createCustomEqual<Meta>(options: {
   circular?: boolean;
-  comparator?: EqualityComparator<Meta>;
-  createCustomConfig?: CreateCustomComparatorConfig<Meta>;
-  createInternalComparator?: <Meta>(
-    compare: EqualityComparator<Meta>,
-  ) => InternalEqualityComparator<Meta>;
-  createState?: CreateState<Meta>;
+  createCustomConfig?: (
+    defaultConfig: ComparatorConfig<Meta>,
+  ) => Partial<ComparatorConfig<Meta>>;
+  createInternalComparator?: (
+    compare: <A, B>(a: A, b: B, state: State<Meta>) => boolean,
+  ) => (
+    a: any,
+    b: any,
+    indexOrKeyA: any,
+    indexOrKeyB: any,
+    parentA: any,
+    parentB: any,
+    state: State<Meta>,
+  ) => boolean;
+  createState?: () => { cache?: Cache; meta?: Meta };
   strict?: boolean;
-}
-
-function createCustomEqual(
-  options: CustomEqualCreatorOptions<Meta>,
-): <A, B>(a: A, b: B, metaOverride?: Meta) => boolean;
+}): <A, B>(a: A, b: B, metaOverride?: Meta) => boolean;
 ```
 
 Create a custom equality comparator. This allows complete control over building a bespoke equality method, in case your use-case requires a higher degree of performance, legacy environment support, or any other non-standard usage. The [recipes](#recipes) provide examples of use in different use-cases, but if you have a specific goal in mind and would like assistance feel free to [file an issue](https://github.com/planttheidea/fast-equals/issues).

package/dist/cjs/index.cjs

@@ -2,7 +2,6 @@
 
 var getOwnPropertyNames = Object.getOwnPropertyNames, getOwnPropertySymbols = Object.getOwnPropertySymbols;
 var hasOwnProperty = Object.prototype.hasOwnProperty;
-var SUPPORTS_ARRAY_BUFFER = typeof ArrayBuffer === 'function' && Boolean(ArrayBuffer.isView);
 /**
  * Combine two comparators into a single comparators.
  */
@@ -11,15 +10,6 @@ function combineComparators(comparatorA, comparatorB) {
         return comparatorA(a, b, state) && comparatorB(a, b, state);
     };
 }
-/**
- * Default equality comparator pass-through, used as the standard `isEqual` creator for
- * use inside the built comparator.
- */
-function createInternalComparator(compare) {
-    return function (a, b, _indexOrKeyA, _indexOrKeyB, _parentA, _parentB, state) {
-        return compare(a, b, state);
-    };
-}
 /**
  * Wrap the provided `areItemsEqual` method to manage the circular state, allowing
  * for circular references to be safely included in the comparison without creating
@@ -58,9 +48,6 @@ var hasOwn = Object.hasOwn ||
     (function (object, property) {
         return hasOwnProperty.call(object, property);
     });
-function isArrayBuffer(value) {
-    return SUPPORTS_ARRAY_BUFFER && ArrayBuffer.isView(value);
-}
 /**
  * Whether the values passed are strictly equal or both NaN.
  */
@@ -95,36 +82,42 @@ function areDatesEqual(a, b) {
  * Whether the `Map`s are equal in value.
  */
 function areMapsEqual(a, b, state) {
-    var isValueEqual = a.size === b.size;
-    if (isValueEqual && a.size) {
-        // The use of `forEach()` is to avoid the transpilation cost of `for...of` comparisons, and
-        // the inability to control the performance of the resulting code. It also avoids excessive
-        // iteration compared to doing comparisons of `keys()` and `values()`. As a result, though,
-        // we cannot short-circuit the iterations; bookkeeping must be done to short-circuit the
-        // equality checks themselves.
-        var matchedIndices_1 = {};
-        var indexA_1 = 0;
-        a.forEach(function (aValue, aKey) {
-            if (!isValueEqual) {
-                return;
+    if (a.size !== b.size) {
+        return false;
+    }
+    var matchedIndices = {};
+    var aIterable = a.entries();
+    var index = 0;
+    var aResult;
+    var bResult;
+    while ((aResult = aIterable.next())) {
+        if (aResult.done) {
+            break;
+        }
+        var bIterable = b.entries();
+        var hasMatch = false;
+        var matchIndex = 0;
+        while ((bResult = bIterable.next())) {
+            if (bResult.done) {
+                break;
             }
-            var hasMatch = false;
-            var matchIndexB = 0;
-            b.forEach(function (bValue, bKey) {
-                if (!hasMatch &&
-                    !matchedIndices_1[matchIndexB] &&
-                    (hasMatch =
-                        state.equals(aKey, bKey, indexA_1, matchIndexB, a, b, state) &&
-                            state.equals(aValue, bValue, aKey, bKey, a, b, state))) {
-                    matchedIndices_1[matchIndexB] = true;
-                }
-                matchIndexB++;
-            });
-            indexA_1++;
-            isValueEqual = hasMatch;
-        });
+            var _a = aResult.value, aKey = _a[0], aValue = _a[1];
+            var _b = bResult.value, bKey = _b[0], bValue = _b[1];
+            if (!hasMatch &&
+                !matchedIndices[matchIndex] &&
+                (hasMatch =
+                    state.equals(aKey, bKey, index, matchIndex, a, b, state) &&
+                        state.equals(aValue, bValue, aKey, bKey, a, b, state))) {
+                matchedIndices[matchIndex] = true;
+            }
+            matchIndex++;
+        }
+        if (!hasMatch) {
+            return false;
+        }
+        index++;
     }
-    return isValueEqual;
+    return true;
 }
 /**
  * Whether the objects are equal in value.
@@ -212,33 +205,40 @@ function areRegExpsEqual(a, b) {
  * Whether the `Set`s are equal in value.
  */
 function areSetsEqual(a, b, state) {
-    var isValueEqual = a.size === b.size;
-    if (isValueEqual && a.size) {
-        // The use of `forEach()` is to avoid the transpilation cost of `for...of` comparisons, and
-        // the inability to control the performance of the resulting code. It also avoids excessive
-        // iteration compared to doing comparisons of `keys()` and `values()`. As a result, though,
-        // we cannot short-circuit the iterations; bookkeeping must be done to short-circuit the
-        // equality checks themselves.
-        var matchedIndices_2 = {};
-        a.forEach(function (aValue, aKey) {
-            if (!isValueEqual) {
-                return;
+    if (a.size !== b.size) {
+        return false;
+    }
+    var matchedIndices = {};
+    var aIterable = a.values();
+    var aResult;
+    var bResult;
+    while ((aResult = aIterable.next())) {
+        if (aResult.done) {
+            break;
+        }
+        var bIterable = b.values();
+        var hasMatch = false;
+        var matchIndex = 0;
+        while ((bResult = bIterable.next())) {
+            if (bResult.done) {
+                break;
             }
-            var hasMatch = false;
-            var matchIndex = 0;
-            b.forEach(function (bValue, bKey) {
-                if (!hasMatch &&
-                    !matchedIndices_2[matchIndex] &&
-                    (hasMatch = state.equals(aValue, bValue, aKey, bKey, a, b, state))) {
-                    matchedIndices_2[matchIndex] = true;
-                }
-                matchIndex++;
-            });
-            isValueEqual = hasMatch;
-        });
+            if (!hasMatch &&
+                !matchedIndices[matchIndex] &&
+                (hasMatch = state.equals(aResult.value, bResult.value, aResult.value, bResult.value, a, b, state))) {
+                matchedIndices[matchIndex] = true;
+            }
+            matchIndex++;
+        }
+        if (!hasMatch) {
+            return false;
+        }
     }
-    return isValueEqual;
+    return true;
 }
+/**
+ * Whether the TypedArray instances are equal in value.
+ */
 function areTypedArraysEqual(a, b) {
     var index = a.length;
     if (b.length !== index) {
@@ -262,12 +262,15 @@ var REG_EXP_TAG = '[object RegExp]';
 var SET_TAG = '[object Set]';
 var STRING_TAG = '[object String]';
 var isArray = Array.isArray;
+var isTypedArray = typeof ArrayBuffer === 'function' && ArrayBuffer.isView
+    ? ArrayBuffer.isView
+    : null;
 var assign = Object.assign;
 var getTag = Object.prototype.toString.call.bind(Object.prototype.toString);
 /**
  * Create a comparator method based on the type-specific equality comparators passed.
  */
-function createComparator(_a) {
+function createEqualityComparator(_a) {
     var areArraysEqual = _a.areArraysEqual, areDatesEqual = _a.areDatesEqual, areMapsEqual = _a.areMapsEqual, areObjectsEqual = _a.areObjectsEqual, arePrimitiveWrappersEqual = _a.arePrimitiveWrappersEqual, areRegExpsEqual = _a.areRegExpsEqual, areSetsEqual = _a.areSetsEqual, areTypedArraysEqual = _a.areTypedArraysEqual;
     /**
      * compare the value of the two objects and return true if they are equivalent in values
@@ -281,9 +284,13 @@ function createComparator(_a) {
         // of them being equal but not strictly is if they are both `NaN`. Since
         // `NaN` is uniquely not equal to itself, we can use self-comparison of
         // both objects, which is faster than `isNaN()`.
-        if (!a || !b || typeof a !== 'object' || typeof b !== 'object') {
+        if (a == null ||
+            b == null ||
+            typeof a !== 'object' ||
+            typeof b !== 'object') {
             return a !== a && b !== b;
         }
+        var constructor = a.constructor;
         // Checks are listed in order of commonality of use-case:
         //   1. Common complex object types (plain object, array)
         //   2. Common data values (date, regexp)
@@ -292,39 +299,47 @@ function createComparator(_a) {
         // Inherently this is both subjective and assumptive, however
         // when reviewing comparable libraries in the wild this order
         // appears to be generally consistent.
+        // Constructors should match, otherwise there is potential for false positives
+        // between class and subclass or custom object and POJO.
+        if (constructor !== b.constructor) {
+            return false;
+        }
         // `isPlainObject` only checks against the object's own realm. Cross-realm
         // comparisons are rare, and will be handled in the ultimate fallback, so
-        // we can avoid the `toString.call()` cost unless necessary.
-        if (a.constructor === Object && b.constructor === Object) {
+        // we can avoid capturing the string tag.
+        if (constructor === Object) {
             return areObjectsEqual(a, b, state);
         }
-        // In strict mode, constructors should match. We placed this after the plain object check
-        // because the constructors must match to meet plain object requirements (must both be `Object`
-        // in the given Realm), so it slightly improves performance on a very common use-case.
-        if (state.strict && a.constructor !== b.constructor) {
-            return false;
+        // `isArray()` works on subclasses and is cross-realm, so we can avoid capturing
+        // the string tag or doing an `instanceof` check.
+        if (isArray(a)) {
+            return areArraysEqual(a, b, state);
         }
-        // `isArray()` works on subclasses and is cross-realm, so we can again avoid
-        // the `toString.call()` cost unless necessary by just checking if either
-        // and then both are arrays.
-        var aArray = isArray(a);
-        var bArray = isArray(b);
-        if (aArray || bArray) {
-            return aArray === bArray && areArraysEqual(a, b, state);
-        }
-        aArray = isArrayBuffer(a);
-        bArray = isArrayBuffer(b);
-        if (aArray || bArray) {
-            return aArray === bArray && areTypedArraysEqual(a, b, state);
-        }
-        // Since this is a custom object, use the classic `toString.call()` to get its
-        // type. This is reasonably performant in modern environments like v8 and
-        // SpiderMonkey, and allows for cross-realm comparison when other checks like
-        // `instanceof` do not.
-        var tag = getTag(a);
-        if (tag !== getTag(b)) {
-            return false;
+        // `isTypedArray()` works on all possible TypedArray classes, so we can avoid
+        // capturing the string tag or comparing against all possible constructors.
+        if (isTypedArray != null && isTypedArray(a)) {
+            return areTypedArraysEqual(a, b, state);
+        }
+        // Try to fast-path equality checks for other complex object types in the
+        // same realm to avoid capturing the string tag. Strict equality is used
+        // instead of `instanceof` because it is more performant for the common
+        // use-case. If someone is subclassing a native class, it will be handled
+        // with the string tag comparison.
+        if (constructor === Date) {
+            return areDatesEqual(a, b, state);
         }
+        if (constructor === RegExp) {
+            return areRegExpsEqual(a, b, state);
+        }
+        if (constructor === Map) {
+            return areMapsEqual(a, b, state);
+        }
+        if (constructor === Set) {
+            return areSetsEqual(a, b, state);
+        }
+        // Since this is a custom object, capture the string tag to determing its type.
+        // This is reasonably performant in modern environments like v8 and SpiderMonkey.
+        var tag = getTag(a);
         if (tag === DATE_TAG) {
             return areDatesEqual(a, b, state);
         }
@@ -337,11 +352,9 @@ function createComparator(_a) {
         if (tag === SET_TAG) {
             return areSetsEqual(a, b, state);
         }
-        // If a simple object tag, then we can prioritize a simple object comparison because
-        // it is likely a custom class.
         if (tag === OBJECT_TAG) {
-            // The exception for value comparison is `Promise`-like contracts. These should be
-            // treated the same as standard `Promise` objects, which means strict equality, and if
+            // The exception for value comparison is custom `Promise`-like class instances. These should
+            // be treated the same as standard `Promise` objects, which means strict equality, and if
             // it reaches this point then that strict equality comparison has already failed.
             return (typeof a.then !== 'function' &&
                 typeof b.then !== 'function' &&
@@ -374,7 +387,7 @@ function createComparator(_a) {
 /**
  * Create the configuration object used for building comparators.
  */
-function createComparatorConfig(_a) {
+function createEqualityComparatorConfig(_a) {
     var circular = _a.circular, createCustomConfig = _a.createCustomConfig, strict = _a.strict;
     var config = {
         areArraysEqual: strict
@@ -393,7 +406,7 @@ function createComparatorConfig(_a) {
             ? combineComparators(areSetsEqual, areObjectsEqualStrict)
             : areSetsEqual,
         areTypedArraysEqual: strict
-            ? combineComparators(areTypedArraysEqual, areObjectsEqualStrict)
+            ? areObjectsEqualStrict
             : areTypedArraysEqual,
     };
     if (createCustomConfig) {
@@ -413,6 +426,51 @@ function createComparatorConfig(_a) {
     }
     return config;
 }
+/**
+ * Default equality comparator pass-through, used as the standard `isEqual` creator for
+ * use inside the built comparator.
+ */
+function createInternalEqualityComparator(compare) {
+    return function (a, b, _indexOrKeyA, _indexOrKeyB, _parentA, _parentB, state) {
+        return compare(a, b, state);
+    };
+}
+/**
+ * Create the `isEqual` function used by the consuming application.
+ */
+function createIsEqual(_a) {
+    var circular = _a.circular, comparator = _a.comparator, createState = _a.createState, equals = _a.equals, strict = _a.strict;
+    if (createState) {
+        return function isEqual(a, b) {
+            var _a = createState(), _b = _a.cache, cache = _b === void 0 ? circular ? new WeakMap() : undefined : _b, meta = _a.meta;
+            return comparator(a, b, {
+                cache: cache,
+                equals: equals,
+                meta: meta,
+                strict: strict,
+            });
+        };
+    }
+    if (circular) {
+        return function isEqual(a, b) {
+            return comparator(a, b, {
+                cache: new WeakMap(),
+                equals: equals,
+                meta: undefined,
+                strict: strict,
+            });
+        };
+    }
+    var state = {
+        cache: undefined,
+        equals: equals,
+        meta: undefined,
+        strict: strict,
+    };
+    return function isEqual(a, b) {
+        return comparator(a, b, state);
+    };
+}
 
 /**
  * Whether the items passed are deeply-equal in value.
@@ -438,29 +496,29 @@ var strictCircularDeepEqual = createCustomEqual({
  * Whether the items passed are shallowly-equal in value.
  */
 var shallowEqual = createCustomEqual({
-    comparator: sameValueZeroEqual,
+    createInternalComparator: function () { return sameValueZeroEqual; },
 });
 /**
  * Whether the items passed are shallowly-equal in value based on strict comparison
  */
 var strictShallowEqual = createCustomEqual({
-    comparator: sameValueZeroEqual,
     strict: true,
+    createInternalComparator: function () { return sameValueZeroEqual; },
 });
 /**
  * Whether the items passed are shallowly-equal in value, including circular references.
  */
 var circularShallowEqual = createCustomEqual({
-    comparator: sameValueZeroEqual,
     circular: true,
+    createInternalComparator: function () { return sameValueZeroEqual; },
 });
 /**
  * Whether the items passed are shallowly-equal in value, including circular references,
  * based on strict comparison.
  */
 var strictCircularShallowEqual = createCustomEqual({
-    comparator: sameValueZeroEqual,
     circular: true,
+    createInternalComparator: function () { return sameValueZeroEqual; },
     strict: true,
 });
 /**
@@ -473,43 +531,13 @@ var strictCircularShallowEqual = createCustomEqual({
  */
 function createCustomEqual(options) {
     if (options === void 0) { options = {}; }
-    var circular = options.circular, comparator = options.comparator, createCustomInternalComparator = options.createInternalComparator, createState = options.createState, _a = options.strict, baseStrict = _a === void 0 ? false : _a;
-    var config = createComparatorConfig(options);
-    var isEqualCustom = createComparator(config);
-    var isEqualCustomComparator = comparator ||
-        (createCustomInternalComparator
-            ? createCustomInternalComparator(isEqualCustom)
-            : createInternalComparator(isEqualCustom));
-    if (createState) {
-        return function isEqual(a, b, metaOverride) {
-            var _a = createState(isEqualCustom), _b = _a.cache, cache = _b === void 0 ? circular ? new WeakMap() : undefined : _b, _c = _a.equals, equals = _c === void 0 ? isEqualCustomComparator : _c, meta = _a.meta, _d = _a.strict, strict = _d === void 0 ? baseStrict : _d;
-            return isEqualCustom(a, b, {
-                cache: cache,
-                equals: equals,
-                meta: metaOverride !== undefined ? metaOverride : meta,
-                strict: strict,
-            });
-        };
-    }
-    if (circular) {
-        return function equals(a, b) {
-            return isEqualCustom(a, b, {
-                cache: new WeakMap(),
-                equals: isEqualCustomComparator,
-                meta: undefined,
-                strict: baseStrict,
-            });
-        };
-    }
-    var state = Object.freeze({
-        cache: undefined,
-        equals: isEqualCustomComparator,
-        meta: undefined,
-        strict: baseStrict,
-    });
-    return function equals(a, b) {
-        return isEqualCustom(a, b, state);
-    };
+    var _a = options.circular, circular = _a === void 0 ? false : _a, createCustomInternalComparator = options.createInternalComparator, createState = options.createState, _b = options.strict, strict = _b === void 0 ? false : _b;
+    var config = createEqualityComparatorConfig(options);
+    var comparator = createEqualityComparator(config);
+    var equals = createCustomInternalComparator
+        ? createCustomInternalComparator(comparator)
+        : createInternalEqualityComparator(comparator);
+    return createIsEqual({ circular: circular, comparator: comparator, createState: createState, equals: equals, strict: strict });
 }
 
 exports.circularDeepEqual = circularDeepEqual;