fast-equals 3.0.2 → 4.0.0

package/src/comparator.ts

@@ -0,0 +1,146 @@
+import { isPlainObject, isPromiseLike, sameValueZeroEqual } from './utils';
+
+import type {
+  EqualityComparator,
+  EqualityComparatorCreator,
+  TypeEqualityComparator,
+} from './utils';
+
+export interface CreateComparatorCreatorOptions<Meta> {
+  areArraysEqual: TypeEqualityComparator<any[], Meta>;
+  areDatesEqual: TypeEqualityComparator<Date, Meta>;
+  areMapsEqual: TypeEqualityComparator<Map<any, any>, Meta>;
+  areObjectsEqual: TypeEqualityComparator<Record<string, any>, Meta>;
+  areRegExpsEqual: TypeEqualityComparator<RegExp, Meta>;
+  areSetsEqual: TypeEqualityComparator<Set<any>, Meta>;
+  createIsNestedEqual: EqualityComparatorCreator<Meta>;
+}
+
+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 SET_TAG = '[object Set]';
+const STRING_TAG = '[object String]';
+
+const { toString } = Object.prototype;
+
+export function createComparator<Meta>({
+  areArraysEqual,
+  areDatesEqual,
+  areMapsEqual,
+  areObjectsEqual,
+  areRegExpsEqual,
+  areSetsEqual,
+  createIsNestedEqual,
+}: CreateComparatorCreatorOptions<Meta>): EqualityComparator<Meta> {
+  const isEqual = createIsNestedEqual(comparator as 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 {
+    // If the items are strictly equal, no need to do a value comparison.
+    if (a === b) {
+      return true;
+    }
+
+    // If the items are not non-nullish objects, then the only possibility
+    // 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') {
+      return a !== a && b !== b;
+    }
+
+    // Checks are listed in order of commonality of use-case:
+    //   1. Common complex object types (plain object, array)
+    //   2. Common data values (date, regexp)
+    //   3. Less-common complex object types (map, set)
+    //   4. Less-common data values (promise, primitive wrappers)
+    // Inherently this is both subjective and assumptive, however
+    // when reviewing comparable libraries in the wild this order
+    // appears to be generally consistent.
+
+    // `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);
+    }
+
+    // `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);
+
+    if (aArray || bArray) {
+      return aArray === bArray && areArraysEqual(a, b, isEqual, meta);
+    }
+
+    // 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);
+
+    if (aTag !== toString.call(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 (aTag === REG_EXP_TAG) {
+      return areRegExpsEqual(a, b, isEqual, meta);
+    }
+
+    if (aTag === MAP_TAG) {
+      return areMapsEqual(a, b, isEqual, meta);
+    }
+
+    if (aTag === SET_TAG) {
+      return areSetsEqual(a, b, isEqual, meta);
+    }
+
+    // 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) {
+      // 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);
+    }
+
+    // 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 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
+    //     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.
+    // 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>;
+}

package/src/dates.ts

@@ -0,0 +1,12 @@
+import { sameValueZeroEqual } from './utils';
+
+/**
+ * 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.valueOf(), b.valueOf());
+}

package/src/index.ts

@@ -0,0 +1,139 @@
+import { createComparator } from './comparator';
+import { areArraysEqual, areArraysEqualCircular } from './arrays';
+import { areDatesEqual } from './dates';
+import { areMapsEqual, areMapsEqualCircular } from './maps';
+import { areObjectsEqual, areObjectsEqualCircular } from './objects';
+import { areRegExpsEqual } from './regexps';
+import { areSetsEqual, areSetsEqualCircular } from './sets';
+import {
+  createDefaultIsNestedEqual,
+  EqualityComparator,
+  merge,
+  sameValueZeroEqual,
+} from './utils';
+
+import type { CreateComparatorCreatorOptions } from './comparator';
+
+export { sameValueZeroEqual };
+
+export type { CreateComparatorCreatorOptions } from './comparator';
+export type {
+  EqualityComparator,
+  EqualityComparatorCreator,
+  InternalEqualityComparator,
+  NativeEqualityComparator,
+  TypeEqualityComparator,
+} from './utils';
+
+export type BaseCircularMeta = Pick<
+  WeakMap<any, any>,
+  'delete' | 'get' | 'set'
+>;
+
+export type GetComparatorOptions<Meta> = (
+  defaultOptions: CreateComparatorCreatorOptions<Meta>,
+) => Partial<CreateComparatorCreatorOptions<Meta>>;
+
+const DEFAULT_CONFIG: CreateComparatorCreatorOptions<undefined> = Object.freeze(
+  {
+    areArraysEqual,
+    areDatesEqual,
+    areMapsEqual,
+    areObjectsEqual,
+    areRegExpsEqual,
+    areSetsEqual,
+    createIsNestedEqual: createDefaultIsNestedEqual,
+  },
+);
+const DEFAULT_CIRCULAR_CONFIG: CreateComparatorCreatorOptions<
+  WeakMap<object, any>
+> = Object.freeze(
+  merge(DEFAULT_CONFIG, {
+    areArraysEqual: areArraysEqualCircular,
+    areMapsEqual: areMapsEqualCircular,
+    areObjectsEqual: areObjectsEqualCircular,
+    areSetsEqual: areSetsEqualCircular,
+  }),
+);
+
+const isDeepEqual = createComparator(DEFAULT_CONFIG);
+
+/**
+ * Whether the items passed are deeply-equal in value.
+ */
+export function deepEqual<A, B>(a: A, b: B): boolean {
+  return isDeepEqual(a, b, undefined);
+}
+
+const isShallowEqual = createComparator(
+  merge(DEFAULT_CONFIG, { createIsNestedEqual: () => sameValueZeroEqual }),
+);
+
+/**
+ * Whether the items passed are shallowly-equal in value.
+ */
+export function shallowEqual<A, B>(a: A, b: B): boolean {
+  return isShallowEqual(a, b, undefined);
+}
+
+const isCircularDeepEqual = createComparator(DEFAULT_CIRCULAR_CONFIG);
+
+/**
+ * Whether the items passed are deeply-equal in value, including circular references.
+ */
+export function circularDeepEqual<A, B>(a: A, b: B): boolean {
+  return isCircularDeepEqual(a, b, new WeakMap());
+}
+
+const isCircularShallowEqual = createComparator(
+  merge(DEFAULT_CIRCULAR_CONFIG, {
+    createIsNestedEqual: () => sameValueZeroEqual,
+  }),
+);
+
+/**
+ * Whether the items passed are shallowly-equal in value, including circular references.
+ */
+export function circularShallowEqual<A, B>(a: A, b: B): boolean {
+  return isCircularShallowEqual(a, b, new WeakMap());
+}
+
+/**
+ * Create a custom equality comparison method.
+ *
+ * This can be done to create very targeted comparisons in extreme hot-path scenarios
+ * where the standard methods are not performant enough, but can also be used to provide
+ * support for legacy environments that do not support expected features like
+ * `RegExp.prototype.flags` out of the box.
+ */
+export function createCustomEqual<Meta = undefined>(
+  getComparatorOptions: GetComparatorOptions<Meta>,
+): EqualityComparator<Meta> {
+  return createComparator<Meta>(
+    merge(DEFAULT_CONFIG, getComparatorOptions(DEFAULT_CONFIG)),
+  );
+}
+
+/**
+ * Create a custom equality comparison method that handles circular references. This is very
+ * similar to `createCustomEqual`, with the only difference being that `meta` expects to be
+ * populated with a `WeakMap`-like contract.
+ *
+ * This can be done to create very targeted comparisons in extreme hot-path scenarios
+ * where the standard methods are not performant enough, but can also be used to provide
+ * support for legacy environments that do not support expected features like
+ * `WeakMap` out of the box.
+ */
+export function createCustomCircularEqual<
+  Meta extends BaseCircularMeta = WeakMap<any, any>,
+>(getComparatorOptions: GetComparatorOptions<Meta>): EqualityComparator<Meta> {
+  const comparator = createComparator<Meta>(
+    merge(
+      DEFAULT_CIRCULAR_CONFIG,
+      getComparatorOptions(DEFAULT_CIRCULAR_CONFIG as any),
+    ),
+  );
+
+  return ((a: any, b: any, meta: any = new WeakMap()) =>
+    comparator(a, b, meta)) as EqualityComparator<Meta>;
+}

package/src/maps.ts

@@ -0,0 +1,66 @@
+import { createIsCircular } from './utils';
+
+import type { InternalEqualityComparator } from './utils';
+
+/**
+ * Whether the `Map`s are equal in value.
+ */
+export function areMapsEqual(
+  a: Map<any, any>,
+  b: Map<any, any>,
+  isEqual: InternalEqualityComparator<any>,
+  meta: any,
+): boolean {
+  let isValueEqual = a.size === b.size;
+
+  if (!isValueEqual) {
+    return false;
+  }
+
+  if (!a.size) {
+    return true;
+  }
+
+  // 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 =
+          isEqual(aKey, bKey, indexA, matchIndexB, a, b, meta) &&
+          isEqual(aValue, bValue, aKey, bKey, a, b, meta))
+      ) {
+        matchedIndices[matchIndexB] = true;
+      }
+
+      matchIndexB++;
+    });
+
+    indexA++;
+    isValueEqual = hasMatch;
+  });
+
+  return isValueEqual;
+}
+
+/**
+ * Whether the `Map`s are equal in value, including circular references.
+ */
+export const areMapsEqualCircular = createIsCircular(areMapsEqual);

package/src/objects.ts

@@ -0,0 +1,61 @@
+import { createIsCircular } from './utils';
+
+import type { InternalEqualityComparator } from './utils';
+
+interface Dictionary<Value> {
+  [key: string]: Value;
+}
+
+const OWNER = '_owner';
+const { hasOwnProperty } = Object.prototype;
+
+/**
+ * Whether the objects are equal in value.
+ */
+export function areObjectsEqual(
+  a: Dictionary<any>,
+  b: Dictionary<any>,
+  isEqual: InternalEqualityComparator<any>,
+  meta: any,
+): boolean {
+  const keysA = Object.keys(a);
+
+  let index = keysA.length;
+
+  if (Object.keys(b).length !== index) {
+    return false;
+  }
+
+  let key: string;
+
+  // 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) {
+    key = keysA[index];
+
+    if (key === OWNER) {
+      const reactElementA = !!a.$$typeof;
+      const reactElementB = !!b.$$typeof;
+
+      if ((reactElementA || reactElementB) && reactElementA !== reactElementB) {
+        return false;
+      }
+    }
+
+    if (
+      !hasOwnProperty.call(b, key) ||
+      !isEqual(a[key], b[key], key, key, a, b, meta)
+    ) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Whether the objects are equal in value, including circular references.
+ */
+export const areObjectsEqualCircular = createIsCircular(areObjectsEqual);

package/src/regexps.ts

@@ -0,0 +1,11 @@
+/**
+ * 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;
+}

package/src/sets.ts

@@ -0,0 +1,61 @@
+import { createIsCircular } from './utils';
+
+import type { InternalEqualityComparator } from './utils';
+
+/**
+ * Whether the `Set`s are equal in value.
+ */
+export function areSetsEqual(
+  a: Set<any>,
+  b: Set<any>,
+  isEqual: InternalEqualityComparator<any>,
+  meta: any,
+): boolean {
+  let isValueEqual = a.size === b.size;
+
+  if (!isValueEqual) {
+    return false;
+  }
+
+  if (!a.size) {
+    return true;
+  }
+
+  // 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 = isEqual(aValue, bValue, aKey, bKey, a, b, meta))
+      ) {
+        matchedIndices[matchIndex] = true;
+      }
+
+      matchIndex++;
+    });
+
+    isValueEqual = hasMatch;
+  });
+
+  return isValueEqual;
+}
+
+/**
+ * Whether the `Set`s are equal in value, including circular references.
+ */
+export const areSetsEqualCircular = createIsCircular(areSetsEqual);

package/src/utils.ts

@@ -0,0 +1,128 @@
+export type InternalEqualityComparator<Meta> = (
+  a: any,
+  b: any,
+  indexOrKeyA: any,
+  indexOrKeyB: any,
+  parentA: any,
+  parentB: any,
+  meta: Meta,
+) => boolean;
+
+export type EqualityComparator<Meta> = Meta extends undefined
+  ? <A, B>(a: A, b: B, meta?: Meta) => boolean
+  : <A, B>(a: A, b: B, meta: Meta) => boolean;
+
+export type EqualityComparatorCreator<Meta> = (
+  fn: EqualityComparator<Meta>,
+) => InternalEqualityComparator<Meta>;
+
+export type NativeEqualityComparator = <A, B>(a: A, b: B) => boolean;
+
+export type TypeEqualityComparator<Type, Meta> = (
+  a: Type,
+  b: Type,
+  isEqual: InternalEqualityComparator<Meta>,
+  meta: Meta,
+) => boolean;
+
+/**
+ * Default equality comparator pass-through, used as the standard `isEqual` creator for
+ * use inside the built comparator.
+ */
+export function createDefaultIsNestedEqual<Meta>(
+  comparator: EqualityComparator<Meta>,
+): InternalEqualityComparator<Meta> {
+  return function isEqual<A, B>(
+    a: A,
+    b: B,
+    indexOrKeyA: any,
+    indexOrKeyB: any,
+    parentA: any,
+    parentB: any,
+    meta: Meta,
+  ) {
+    return comparator(a, b, meta);
+  };
+}
+
+/**
+ * Wrap the provided `areItemsEqual` method to manage the circular cache, allowing
+ * for circular references to be safely included in the comparison without creating
+ * stack overflows.
+ */
+export function createIsCircular<
+  AreItemsEqual extends TypeEqualityComparator<any, any>,
+>(areItemsEqual: AreItemsEqual): AreItemsEqual {
+  return function isCircular(
+    a: any,
+    b: any,
+    isEqual: InternalEqualityComparator<WeakMap<any, any>>,
+    cache: WeakMap<any, any>,
+  ) {
+    if (!a || !b || typeof a !== 'object' || typeof b !== 'object') {
+      return areItemsEqual(a, b, isEqual, cache);
+    }
+
+    const cachedA = cache.get(a);
+    const cachedB = cache.get(b);
+
+    if (cachedA && cachedB) {
+      return cachedA === b && cachedB === a;
+    }
+
+    cache.set(a, b);
+    cache.set(b, a);
+
+    const result = areItemsEqual(a, b, isEqual, cache);
+
+    cache.delete(a);
+    cache.delete(b);
+
+    return result;
+  } as AreItemsEqual;
+}
+
+/**
+ * Targeted shallow merge of two objects.
+ *
+ * @NOTE
+ * This exists as a tinier compiled version of the `__assign` helper that
+ * `tsc` injects in case of `Object.assign` not being present.
+ */
+export function merge<A extends object, B extends object>(a: A, b: B): A & B {
+  const merged: Record<string, any> = {};
+
+  for (const key in a) {
+    merged[key] = a[key];
+  }
+
+  for (const key in b) {
+    merged[key] = b[key];
+  }
+
+  return merged as A & B;
+}
+
+/**
+ * Whether the value is a plain object.
+ *
+ * @NOTE
+ * This is a same-realm compariosn only.
+ */
+export function isPlainObject(value: any): boolean {
+  return value.constructor === Object || value.constructor == null;
+}
+
+/**
+ * When the value is `Promise`-like, aka "then-able".
+ */
+export function isPromiseLike(value: any): boolean {
+  return typeof value.then === 'function';
+}
+
+/**
+ * Whether the values passed are strictly equal or both NaN.
+ */
+export function sameValueZeroEqual(a: any, b: any): boolean {
+  return a === b || (a !== a && b !== b);
+}