fast-equals 5.0.0-beta.5 → 5.0.0

package/src/equals.ts

@@ -1,5 +1,10 @@
 import { getStrictProperties, hasOwn, sameValueZeroEqual } from './utils';
-import type { Dictionary, State, TypedArray } from './internalTypes';
+import type {
+  Dictionary,
+  PrimitiveWrapper,
+  State,
+  TypedArray,
+} from './internalTypes';
 
 const OWNER = '_owner';
 
@@ -39,47 +44,56 @@ export function areMapsEqual(
   b: Map<any, any>,
   state: State<any>,
 ): boolean {
-  let isValueEqual = a.size === b.size;
+  if (a.size !== b.size) {
+    return false;
+  }
+
+  const matchedIndices: Record<number, true> = {};
+  const aIterable = a.entries();
+
+  let index = 0;
+  let aResult: IteratorResult<[any, any]>;
+  let bResult: IteratorResult<[any, any]>;
 
-  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.
+  while ((aResult = aIterable.next())) {
+    if (aResult.done) {
+      break;
+    }
+
+    const bIterable = b.entries();
 
-    const matchedIndices: Record<number, true> = {};
+    let hasMatch = false;
+    let matchIndex = 0;
 
-    let indexA = 0;
+    while ((bResult = bIterable.next())) {
+      if (bResult.done) {
+        break;
+      }
 
-    a.forEach((aValue, aKey) => {
-      if (!isValueEqual) {
-        return;
+      const [aKey, aValue] = aResult.value;
+      const [bKey, bValue] = bResult.value;
+
+      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;
       }
 
-      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;
-    });
+      matchIndex++;
+    }
+
+    if (!hasMatch) {
+      return false;
+    }
+
+    index++;
   }
 
-  return isValueEqual;
+  return true;
 }
 
 /**
@@ -98,7 +112,7 @@ export function areObjectsEqual(
     return false;
   }
 
-  let property: string | symbol;
+  let property: string;
 
   // Decrementing `while` showed faster results than either incrementing or
   // decrementing `for` loop and than an incrementing `while` loop. Declarative
@@ -192,7 +206,10 @@ export function areObjectsEqualStrict(
 /**
  * Whether the primitive wrappers passed are equal in value.
  */
-export function arePrimitiveWrappersEqual(a: Date, b: Date): boolean {
+export function arePrimitiveWrappersEqual(
+  a: PrimitiveWrapper,
+  b: PrimitiveWrapper,
+): boolean {
   return sameValueZeroEqual(a.valueOf(), b.valueOf());
 }
 
@@ -211,44 +228,61 @@ export function areSetsEqual(
   b: Set<any>,
   state: State<any>,
 ): boolean {
-  let isValueEqual = a.size === b.size;
+  if (a.size !== b.size) {
+    return false;
+  }
 
-  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> = {};
+  const aIterable = a.values();
 
-    const matchedIndices: Record<number, true> = {};
+  let aResult: IteratorResult<any>;
+  let bResult: IteratorResult<any>;
 
-    a.forEach((aValue, aKey) => {
-      if (!isValueEqual) {
-        return;
-      }
+  while ((aResult = aIterable.next())) {
+    if (aResult.done) {
+      break;
+    }
 
-      let hasMatch = false;
-      let matchIndex = 0;
+    const bIterable = b.values();
+
+    let hasMatch = false;
+    let matchIndex = 0;
+
+    while ((bResult = bIterable.next())) {
+      if (bResult.done) {
+        break;
+      }
 
-      b.forEach((bValue, bKey) => {
-        if (
-          !hasMatch &&
-          !matchedIndices[matchIndex] &&
-          (hasMatch = state.equals(aValue, bValue, aKey, bKey, a, b, state))
-        ) {
-          matchedIndices[matchIndex] = true;
-        }
+      if (
+        !hasMatch &&
+        !matchedIndices[matchIndex] &&
+        (hasMatch = state.equals(
+          aResult.value,
+          bResult.value,
+          aResult.value,
+          bResult.value,
+          a,
+          b,
+          state,
+        ))
+      ) {
+        matchedIndices[matchIndex] = true;
+      }
 
-        matchIndex++;
-      });
+      matchIndex++;
+    }
 
-      isValueEqual = hasMatch;
-    });
+    if (!hasMatch) {
+      return false;
+    }
   }
 
-  return isValueEqual;
+  return true;
 }
 
+/**
+ * Whether the TypedArray instances are equal in value.
+ */
 export function areTypedArraysEqual(a: TypedArray, b: TypedArray) {
   let index = a.length;
 

package/src/index.ts

@@ -1,10 +1,11 @@
-import { createComparator, createComparatorConfig } from './comparator';
-import type {
-  CircularState,
-  CustomEqualCreatorOptions,
-  DefaultState,
-} from './internalTypes';
-import { createInternalComparator, sameValueZeroEqual } from './utils';
+import {
+  createEqualityComparatorConfig,
+  createEqualityComparator,
+  createInternalEqualityComparator,
+  createIsEqual,
+} from './comparator';
+import type { CustomEqualCreatorOptions } from './internalTypes';
+import { sameValueZeroEqual } from './utils';
 
 export { sameValueZeroEqual };
 export * from './internalTypes';
@@ -37,23 +38,23 @@ export const strictCircularDeepEqual = createCustomEqual({
  * Whether the items passed are shallowly-equal in value.
  */
 export const shallowEqual = createCustomEqual({
-  comparator: sameValueZeroEqual,
+  createInternalComparator: () => sameValueZeroEqual,
 });
 
 /**
  * Whether the items passed are shallowly-equal in value based on strict comparison
  */
 export const strictShallowEqual = createCustomEqual({
-  comparator: sameValueZeroEqual,
   strict: true,
+  createInternalComparator: () => sameValueZeroEqual,
 });
 
 /**
  * Whether the items passed are shallowly-equal in value, including circular references.
  */
 export const circularShallowEqual = createCustomEqual({
-  comparator: sameValueZeroEqual,
   circular: true,
+  createInternalComparator: () => sameValueZeroEqual,
 });
 
 /**
@@ -61,8 +62,8 @@ export const circularShallowEqual = createCustomEqual({
  * based on strict comparison.
  */
 export const strictCircularShallowEqual = createCustomEqual({
-  comparator: sameValueZeroEqual,
   circular: true,
+  createInternalComparator: () => sameValueZeroEqual,
   strict: true,
 });
 
@@ -74,66 +75,21 @@ export const strictCircularShallowEqual = createCustomEqual({
  * support for legacy environments that do not support expected features like
  * `RegExp.prototype.flags` out of the box.
  */
-export function createCustomEqual<Meta>(
+export function createCustomEqual<Meta = undefined>(
   options: CustomEqualCreatorOptions<Meta> = {},
 ) {
   const {
-    circular,
-    comparator,
+    circular = false,
     createInternalComparator: createCustomInternalComparator,
     createState,
-    strict: baseStrict = false,
+    strict = false,
   } = options;
 
-  const config = createComparatorConfig<Meta>(options);
-  const isEqualCustom = createComparator(config);
-  const isEqualCustomComparator =
-    comparator ||
-    (createCustomInternalComparator
-      ? createCustomInternalComparator(isEqualCustom)
-      : createInternalComparator(isEqualCustom));
+  const config = createEqualityComparatorConfig<Meta>(options);
+  const comparator = createEqualityComparator(config);
+  const equals = createCustomInternalComparator
+    ? createCustomInternalComparator(comparator)
+    : createInternalEqualityComparator(comparator);
 
-  if (createState) {
-    return function isEqual<A, B>(
-      a: A,
-      b: B,
-      metaOverride?: Meta | undefined,
-    ): boolean {
-      const {
-        cache = circular ? new WeakMap() : undefined,
-        equals = isEqualCustomComparator,
-        meta,
-        strict = baseStrict,
-      } = createState!(isEqualCustom);
-
-      return isEqualCustom(a, b, {
-        cache,
-        equals,
-        meta: metaOverride !== undefined ? metaOverride : meta,
-        strict,
-      } as CircularState<Meta>);
-    };
-  }
-
-  if (circular) {
-    return function equals<A, B>(a: A, b: B): boolean {
-      return isEqualCustom(a, b, {
-        cache: new WeakMap(),
-        equals: isEqualCustomComparator,
-        meta: undefined as Meta,
-        strict: baseStrict,
-      } as CircularState<Meta>);
-    };
-  }
-
-  const state = Object.freeze({
-    cache: undefined,
-    equals: isEqualCustomComparator,
-    meta: undefined,
-    strict: baseStrict,
-  });
-
-  return function equals<A, B>(a: A, b: B): boolean {
-    return isEqualCustom(a, b, state as DefaultState<Meta>);
-  };
+  return createIsEqual({ circular, comparator, createState, equals, strict });
 }

package/src/internalTypes.ts

@@ -1,22 +1,40 @@
-export interface BaseCircular
-  extends Pick<WeakMap<any, any>, 'delete' | 'get'> {
-  set(key: object, value: any): any;
+/**
+ * Cache used to store references to objects, used for circular
+ * reference checks.
+ */
+export interface Cache<Key extends object, Value> {
+  delete(key: Key): boolean;
+  get(key: Key): Value | undefined;
+  set(key: Key, value: any): any;
 }
 
-export type State<Meta> = CircularState<Meta> | DefaultState<Meta>;
-
-export interface CircularState<Meta> {
-  readonly cache: BaseCircular;
+export interface State<Meta> {
+  /**
+   * Cache used to identify circular references
+   */
+  readonly cache: Cache<any, any> | undefined;
+  /**
+   * Method used to determine equality of nested value.
+   */
   readonly equals: InternalEqualityComparator<Meta>;
+  /**
+   * Additional value that can be used for comparisons.
+   */
   meta: Meta;
+  /**
+   * Whether the equality comparison is strict, meaning it matches
+   * all properties (including symbols and non-enumerable properties)
+   * with equal shape of descriptors.
+   */
   readonly strict: boolean;
 }
 
-export interface DefaultState<Meta> {
+export interface CircularState<Meta> extends State<Meta> {
+  readonly cache: Cache<any, any>;
+}
+
+export interface DefaultState<Meta> extends State<Meta> {
   readonly cache: undefined;
-  readonly equals: InternalEqualityComparator<Meta>;
-  meta: Meta;
-  readonly strict: boolean;
 }
 
 export interface Dictionary<Value = any> {
@@ -25,13 +43,42 @@ export interface Dictionary<Value = any> {
 }
 
 export interface ComparatorConfig<Meta> {
+  /**
+   * Whether the arrays passed are equal in value. In strict mode, this includes
+   * additional properties added to the array.
+   */
   areArraysEqual: TypeEqualityComparator<any, Meta>;
+  /**
+   * Whether the dates passed are equal in value.
+   */
   areDatesEqual: TypeEqualityComparator<any, Meta>;
+  /**
+   * Whether the maps passed are equal in value. In strict mode, this includes
+   * additional properties added to the map.
+   */
   areMapsEqual: TypeEqualityComparator<any, Meta>;
+  /**
+   * Whether the objects passed are equal in value. In strict mode, this includes
+   * non-enumerable properties added to the map, as well as symbol properties.
+   */
   areObjectsEqual: TypeEqualityComparator<any, Meta>;
+  /**
+   * Whether the primitive wrappers passed are equal in value.
+   */
   arePrimitiveWrappersEqual: TypeEqualityComparator<any, Meta>;
+  /**
+   * Whether the regexps passed are equal in value.
+   */
   areRegExpsEqual: TypeEqualityComparator<any, Meta>;
+  /**
+   * Whether the sets passed are equal in value. In strict mode, this includes
+   * additional properties added to the set.
+   */
   areSetsEqual: TypeEqualityComparator<any, Meta>;
+  /**
+   * Whether the typed arrays passed are equal in value. In strict mode, this includes
+   * additional properties added to the typed array.
+   */
   areTypedArraysEqual: TypeEqualityComparator<any, Meta>;
 }
 
@@ -39,9 +86,10 @@ export type CreateCustomComparatorConfig<Meta> = (
   config: ComparatorConfig<Meta>,
 ) => Partial<ComparatorConfig<Meta>>;
 
-export type CreateState<Meta> = (
-  comparator: EqualityComparator<Meta>,
-) => Partial<State<Meta>>;
+export type CreateState<Meta> = () => {
+  cache?: Cache<any, any> | undefined;
+  meta?: Meta;
+};
 
 export type EqualityComparator<Meta> = <A, B>(
   a: A,
@@ -68,6 +116,21 @@ export type InternalEqualityComparator<Meta> = (
   state: State<Meta>,
 ) => boolean;
 
+// We explicitly check for primitive wrapper types
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type PrimitiveWrapper = Boolean | Number | String;
+
+/**
+ * Type which encompasses possible instances of TypedArray
+ * classes.
+ *
+ * **NOTE**: This does not include `BigInt64Array` and
+ * `BitUint64Array` because those are part of ES2020 and
+ * not supported by certain TS configurations. If using
+ * either in `areTypedArraysEqual`, you can cast the
+ * instance as `TypedArray` and it will work as expected,
+ * because runtime checks will still work for those classes.
+ */
 export type TypedArray =
   | Float32Array
   | Float64Array
@@ -86,12 +149,37 @@ export type TypeEqualityComparator<Type, Meta = undefined> = (
 ) => boolean;
 
 export interface CustomEqualCreatorOptions<Meta> {
+  /**
+   * Whether circular references should be supported. It causes the
+   * comparison to be slower, but for objects that have circular references
+   * it is required to avoid stack overflows.
+   */
   circular?: boolean;
-  comparator?: EqualityComparator<Meta>;
+  /**
+   * Create a custom configuration of type-specific equality comparators.
+   * This receives the default configuration, which allows either replacement
+   * or supersetting of the default methods.
+   */
   createCustomConfig?: CreateCustomComparatorConfig<Meta>;
-  createInternalComparator?: <Meta>(
+  /**
+   * Create a custom internal comparator, which is used as an override to the
+   * default entry point for nested value equality comparisons. This is often
+   * used for doing custom logic for specific types (such as handling a specific
+   * class instance differently than other objects) or to incorporate `meta` in
+   * the comparison. See the recipes for examples.
+   */
+  createInternalComparator?: (
     compare: EqualityComparator<Meta>,
   ) => InternalEqualityComparator<Meta>;
+  /**
+   * Create a custom `state` object passed between the methods. This allows for
+   * custom `cache` and/or `meta` values to be used.
+   */
   createState?: CreateState<Meta>;
+  /**
+   * Whether the equality comparison is strict, meaning it matches
+   * all properties (including symbols and non-enumerable properties)
+   * with equal shape of descriptors.
+   */
   strict?: boolean;
 }

package/src/utils.ts

@@ -1,10 +1,8 @@
 import {
   AnyEqualityComparator,
-  BaseCircular,
+  Cache,
   CircularState,
   Dictionary,
-  EqualityComparator,
-  InternalEqualityComparator,
   State,
   TypeEqualityComparator,
 } from './internalTypes';
@@ -24,26 +22,6 @@ export function combineComparators<Meta>(
   };
 }
 
-/**
- * Default equality comparator pass-through, used as the standard `isEqual` creator for
- * use inside the built comparator.
- */
-export function createInternalComparator<Meta>(
-  compare: EqualityComparator<Meta>,
-): InternalEqualityComparator<Meta> {
-  return function (
-    a: any,
-    b: any,
-    _indexOrKeyA: any,
-    _indexOrKeyB: any,
-    _parentA: any,
-    _parentB: any,
-    state: State<Meta>,
-  ) {
-    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
@@ -55,7 +33,7 @@ export function createIsCircular<
   return function isCircular(
     a: any,
     b: any,
-    state: CircularState<BaseCircular>,
+    state: CircularState<Cache<any, any>>,
   ) {
     if (!a || !b || typeof a !== 'object' || typeof b !== 'object') {
       return areItemsEqual(a, b, state);