fast-equals 4.0.2 → 5.0.0-beta.0

package/src/comparator.ts

@@ -1,37 +1,37 @@
-import { isPlainObject, isPromiseLike, sameValueZeroEqual } from './utils';
-
 import type {
-  CreateComparatorCreatorOptions,
+  ComparatorConfig,
   EqualityComparator,
-} from '../index.d';
+  State,
+} from './internalTypes';
 
 const ARGUMENTS_TAG = '[object Arguments]';
 const BOOLEAN_TAG = '[object Boolean]';
 const DATE_TAG = '[object Date]';
-const REG_EXP_TAG = '[object RegExp]';
 const MAP_TAG = '[object Map]';
 const NUMBER_TAG = '[object Number]';
 const OBJECT_TAG = '[object Object]';
+const REG_EXP_TAG = '[object RegExp]';
 const SET_TAG = '[object Set]';
 const STRING_TAG = '[object String]';
 
-const { toString } = Object.prototype;
+const { isArray } = Array;
+const getTag = Object.prototype.toString.call.bind(
+  Object.prototype.toString,
+) as (a: object) => string;
 
 export function createComparator<Meta>({
   areArraysEqual,
   areDatesEqual,
   areMapsEqual,
   areObjectsEqual,
+  arePrimitiveWrappersEqual,
   areRegExpsEqual,
   areSetsEqual,
-  createIsNestedEqual,
-}: CreateComparatorCreatorOptions<Meta>): EqualityComparator<Meta> {
-  const isEqual = createIsNestedEqual(comparator as EqualityComparator<Meta>);
-
+}: ComparatorConfig<Meta>): EqualityComparator<Meta> {
   /**
    * compare the value of the two objects and return true if they are equivalent in values
    */
-  function comparator(a: any, b: any, meta: Meta): boolean {
+  return function comparator(a: any, b: any, state: State<Meta>): boolean {
     // If the items are strictly equal, no need to do a value comparison.
     if (a === b) {
       return true;
@@ -57,79 +57,82 @@ export function createComparator<Meta>({
     // `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 (isPlainObject(a) && isPlainObject(b)) {
-      return areObjectsEqual(a, b, isEqual, meta);
+    if (a.constructor === Object && b.constructor === Object) {
+      return areObjectsEqual(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.
-    const aArray = Array.isArray(a);
-    const bArray = Array.isArray(b);
+    const aArray = isArray(a);
+    const bArray = isArray(b);
 
     if (aArray || bArray) {
-      return aArray === bArray && areArraysEqual(a, b, isEqual, meta);
+      return aArray === bArray && areArraysEqual(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.
-    const aTag = toString.call(a);
+    const tag = getTag(a);
 
-    if (aTag !== toString.call(b)) {
+    if (tag !== getTag(b)) {
       return false;
     }
 
-    if (aTag === DATE_TAG) {
-      // `getTime()` showed better results compared to alternatives like `valueOf()`
-      // or the unary `+` operator.
-      return areDatesEqual(a, b, isEqual, meta);
+    if (tag === DATE_TAG) {
+      return areDatesEqual(a, b, state);
     }
 
-    if (aTag === REG_EXP_TAG) {
-      return areRegExpsEqual(a, b, isEqual, meta);
+    if (tag === REG_EXP_TAG) {
+      return areRegExpsEqual(a, b, state);
     }
 
-    if (aTag === MAP_TAG) {
-      return areMapsEqual(a, b, isEqual, meta);
+    if (tag === MAP_TAG) {
+      return areMapsEqual(a, b, state);
     }
 
-    if (aTag === SET_TAG) {
-      return areSetsEqual(a, b, isEqual, meta);
+    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 an arguments tag, it should be treated as a standard
-    // object.
-    if (aTag === OBJECT_TAG || aTag === ARGUMENTS_TAG) {
+    // 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.
-      return isPromiseLike(a) || isPromiseLike(b)
-        ? a === b
-        : areObjectsEqual(a, b, isEqual, meta);
+      // 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' &&
+        areObjectsEqual(a, b, state)
+      );
+    }
+
+    // If an arguments tag, it should be treated as a standard object.
+    if (tag === ARGUMENTS_TAG) {
+      return areObjectsEqual(a, b, state);
     }
 
     // As the penultimate fallback, check if the values passed are primitive wrappers. This
     // is very rare in modern JS, which is why it is deprioritized compared to all other object
     // types.
-    if (aTag === BOOLEAN_TAG || aTag === NUMBER_TAG || aTag === STRING_TAG) {
-      return sameValueZeroEqual(a.valueOf(), b.valueOf());
+    if (tag === BOOLEAN_TAG || tag === NUMBER_TAG || tag === STRING_TAG) {
+      return arePrimitiveWrappersEqual(a, b, state);
     }
 
-    // If not matching any tags that require a specific type of comparison, then use strict
-    // equality. This is for a few reasons:
-    //   - For types that cannot be introspected (`Promise`, `WeakMap`, etc.), this is the only
+    // If not matching any tags that require a specific type of comparison, then we hard-code false because
+    // the only thing remaining is strict equality, which has already been compared. This is for a few reasons:
+    //   - Certain types that cannot be introspected (e.g., `WeakMap`). For these types, this is the only
     //     comparison that can be made.
     //   - For types that can be introspected, but rarely have requirements to be compared
     //     (`ArrayBuffer`, `DataView`, etc.), the cost is avoided to prioritize the common
-    //     use-cases.
-    //   - For types that can be introspected, but do not have an objective definition of what
-    //     equality is (`Error`, etc.), the subjective decision was to be conservative.
+    //     use-cases (may be included in a future release, if requested enough).
+    //   - For types that can be introspected but do not have an objective definition of what
+    //     equality is (`Error`, etc.), the subjective decision is to be conservative and strictly compare.
     // In all cases, these decisions should be reevaluated based on changes to the language and
     // common development practices.
-    return a === b;
-  }
-
-  return comparator as EqualityComparator<Meta>;
+    return false;
+  };
 }

package/src/equals.ts

@@ -0,0 +1,263 @@
+import { getStrictProperties, hasOwn, sameValueZeroEqual } from './utils';
+import type { Dictionary, State } from './internalTypes';
+
+const OWNER = '_owner';
+
+const { getOwnPropertyDescriptor, keys } = Object;
+
+/**
+ * Whether the arrays are equal in value.
+ */
+export function areArraysEqual(a: any[], b: any[], state: State<any>) {
+  let index = a.length;
+
+  if (b.length !== index) {
+    return false;
+  }
+
+  while (index-- > 0) {
+    if (!state.equals(a[index], b[index], index, index, a, b, state)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Whether the dates passed are equal in value.
+ *
+ * @NOTE
+ * This is a standalone function instead of done inline in the comparator
+ * to allow for overrides.
+ */
+export function areDatesEqual(a: Date, b: Date): boolean {
+  return sameValueZeroEqual(a.getTime(), b.getTime());
+}
+
+/**
+ * Whether the `Map`s are equal in value.
+ */
+export function areMapsEqual(
+  a: Map<any, any>,
+  b: Map<any, any>,
+  state: State<any>,
+): boolean {
+  let 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.
+
+    const matchedIndices: Record<number, true> = {};
+
+    let indexA = 0;
+
+    a.forEach((aValue, aKey) => {
+      if (!isValueEqual) {
+        return;
+      }
+
+      let hasMatch = false;
+      let matchIndexB = 0;
+
+      b.forEach((bValue, bKey) => {
+        if (
+          !hasMatch &&
+          !matchedIndices[matchIndexB] &&
+          (hasMatch =
+            state.equals(aKey, bKey, indexA, matchIndexB, a, b, state) &&
+            state.equals(aValue, bValue, aKey, bKey, a, b, state))
+        ) {
+          matchedIndices[matchIndexB] = true;
+        }
+
+        matchIndexB++;
+      });
+
+      indexA++;
+      isValueEqual = hasMatch;
+    });
+  }
+
+  return isValueEqual;
+}
+
+/**
+ * Whether the objects are equal in value.
+ */
+export function areObjectsEqual(
+  a: Dictionary,
+  b: Dictionary,
+  state: State<any>,
+): boolean {
+  const properties = keys(a);
+
+  let index = properties.length;
+
+  if (keys(b).length !== index) {
+    return false;
+  }
+
+  let property: string | symbol;
+
+  // Decrementing `while` showed faster results than either incrementing or
+  // decrementing `for` loop and than an incrementing `while` loop. Declarative
+  // methods like `some` / `every` were not used to avoid incurring the garbage
+  // cost of anonymous callbacks.
+  while (index-- > 0) {
+    property = properties[index]!;
+
+    if (
+      property === OWNER &&
+      (a.$$typeof || b.$$typeof) &&
+      a.$$typeof !== b.$$typeof
+    ) {
+      return false;
+    }
+
+    if (
+      !hasOwn(b, property) ||
+      !state.equals(a[property], b[property], property, property, a, b, state)
+    ) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Whether the objects are equal in value with strict property checking.
+ */
+export function areObjectsEqualStrict(
+  a: Dictionary,
+  b: Dictionary,
+  state: State<any>,
+): boolean {
+  const properties = getStrictProperties(a);
+
+  let index = properties.length;
+
+  if (getStrictProperties(b).length !== index) {
+    return false;
+  }
+
+  let property: string | symbol;
+  let descriptorA: ReturnType<typeof getOwnPropertyDescriptor>;
+  let descriptorB: ReturnType<typeof getOwnPropertyDescriptor>;
+
+  // Decrementing `while` showed faster results than either incrementing or
+  // decrementing `for` loop and than an incrementing `while` loop. Declarative
+  // methods like `some` / `every` were not used to avoid incurring the garbage
+  // cost of anonymous callbacks.
+  while (index-- > 0) {
+    property = properties[index]!;
+
+    if (
+      property === OWNER &&
+      (a.$$typeof || b.$$typeof) &&
+      a.$$typeof !== b.$$typeof
+    ) {
+      return false;
+    }
+
+    if (!hasOwn(b, property)) {
+      return false;
+    }
+
+    if (
+      !state.equals(a[property], b[property], property, property, a, b, state)
+    ) {
+      return false;
+    }
+
+    descriptorA = getOwnPropertyDescriptor(a, property);
+    descriptorB = getOwnPropertyDescriptor(b, property);
+
+    if (
+      (descriptorA || descriptorB) &&
+      (!descriptorA ||
+        !descriptorB ||
+        descriptorA.configurable !== descriptorB.configurable ||
+        descriptorA.enumerable !== descriptorB.enumerable ||
+        descriptorA.writable !== descriptorB.writable)
+    ) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Whether the primitive wrappers passed are equal in value.
+ *
+ * @NOTE
+ * This is a standalone function instead of done inline in the comparator
+ * to allow for overrides.
+ */
+export function arePrimitiveWrappersEqual(a: Date, b: Date): boolean {
+  return sameValueZeroEqual(a.valueOf(), b.valueOf());
+}
+
+/**
+ * Whether the regexps passed are equal in value.
+ *
+ * @NOTE
+ * This is a standalone function instead of done inline in the comparator
+ * to allow for overrides. An example of this would be supporting a
+ * pre-ES2015 environment where the `flags` property is not available.
+ */
+export function areRegExpsEqual(a: RegExp, b: RegExp): boolean {
+  return a.source === b.source && a.flags === b.flags;
+}
+
+/**
+ * Whether the `Set`s are equal in value.
+ */
+export function areSetsEqual(
+  a: Set<any>,
+  b: Set<any>,
+  state: State<any>,
+): boolean {
+  let 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.
+
+    const matchedIndices: Record<number, true> = {};
+
+    a.forEach((aValue, aKey) => {
+      if (!isValueEqual) {
+        return;
+      }
+
+      let hasMatch = false;
+      let matchIndex = 0;
+
+      b.forEach((bValue, bKey) => {
+        if (
+          !hasMatch &&
+          !matchedIndices[matchIndex] &&
+          (hasMatch = state.equals(aValue, bValue, aKey, bKey, a, b, state))
+        ) {
+          matchedIndices[matchIndex] = true;
+        }
+
+        matchIndex++;
+      });
+
+      isValueEqual = hasMatch;
+    });
+  }
+
+  return isValueEqual;
+}