fast-equals 4.0.3 → 5.0.0-beta.0

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;
+}

package/src/index.ts

@@ -1,121 +1,225 @@
 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, merge, sameValueZeroEqual } from './utils';
-
+import {
+  areArraysEqual,
+  areDatesEqual,
+  areMapsEqual,
+  areObjectsEqual,
+  areObjectsEqualStrict,
+  arePrimitiveWrappersEqual,
+  areRegExpsEqual,
+  areSetsEqual,
+} from './equals';
 import type {
-  BaseCircularMeta,
-  CreateComparatorCreatorOptions,
+  CircularState,
+  ComparatorConfig,
+  CreateCustomComparatorConfig,
+  CreateState,
+  DefaultState,
   EqualityComparator,
-  GetComparatorOptions,
-} from '../index.d';
+} from './internalTypes';
+import {
+  combineComparators,
+  createInternalComparator,
+  createIsCircular,
+  sameValueZeroEqual,
+} from './utils';
 
 export { sameValueZeroEqual };
 
-const DEFAULT_CONFIG: CreateComparatorCreatorOptions<undefined> = Object.freeze(
-  {
+interface DefaultEqualCreatorOptions<Meta> {
+  comparator?: EqualityComparator<Meta>;
+  circular?: boolean;
+  strict?: boolean;
+}
+
+interface CustomEqualCreatorOptions<Meta>
+  extends DefaultEqualCreatorOptions<Meta> {
+  createCustomConfig?: CreateCustomComparatorConfig<Meta>;
+  createInternalComparator?: typeof createInternalComparator;
+  createState?: CreateState<Meta>;
+}
+
+function createComparatorConfig<Meta>({
+  circular,
+  strict,
+}: DefaultEqualCreatorOptions<Meta>) {
+  const config: ComparatorConfig<Meta> = {
     areArraysEqual,
     areDatesEqual,
     areMapsEqual,
     areObjectsEqual,
+    arePrimitiveWrappersEqual,
     areRegExpsEqual,
     areSetsEqual,
-    createIsNestedEqual: createDefaultIsNestedEqual,
-  },
-);
-const DEFAULT_CIRCULAR_CONFIG: CreateComparatorCreatorOptions<BaseCircularMeta> =
-  Object.freeze({
-    areArraysEqual: areArraysEqualCircular,
-    areDatesEqual,
-    areMapsEqual: areMapsEqualCircular,
-    areObjectsEqual: areObjectsEqualCircular,
-    areRegExpsEqual,
-    areSetsEqual: areSetsEqualCircular,
-    createIsNestedEqual: createDefaultIsNestedEqual,
+  };
+
+  if (strict) {
+    config.areArraysEqual = areObjectsEqual;
+    config.areMapsEqual = combineComparators(areMapsEqual, areObjectsEqual);
+    config.areObjectsEqual = areObjectsEqualStrict;
+    config.areSetsEqual = combineComparators(areSetsEqual, areObjectsEqual);
+  }
+
+  if (circular) {
+    config.areArraysEqual = createIsCircular(config.areArraysEqual);
+    config.areMapsEqual = createIsCircular(config.areMapsEqual);
+    config.areObjectsEqual = createIsCircular(config.areObjectsEqual);
+    config.areSetsEqual = createIsCircular(config.areSetsEqual);
+  }
+
+  return config;
+}
+
+function createDefaultEqualCreator(
+  options: DefaultEqualCreatorOptions<undefined> = {},
+) {
+  const config = createComparatorConfig(options);
+  const isEqual = createComparator(config);
+  const isEqualComparator =
+    options.comparator || createInternalComparator(isEqual);
+  const strict = !!options.strict;
+
+  if (options.circular) {
+    return function equals<A, B>(a: A, b: B): boolean {
+      return isEqual(a, b, {
+        cache: new WeakMap(),
+        equals: isEqualComparator,
+        meta: undefined,
+        strict,
+      });
+    };
+  }
+
+  const state = Object.freeze({
+    cache: undefined,
+    equals: isEqualComparator,
+    meta: undefined,
+    strict,
   });
 
-const isDeepEqual = createComparator(DEFAULT_CONFIG);
+  return function equals<A, B>(a: A, b: B): boolean {
+    return isEqual(a, b, state);
+  };
+}
 
 /**
  * Whether the items passed are deeply-equal in value.
  */
-export function deepEqual<A, B>(a: A, b: B): boolean {
-  return isDeepEqual(a, b, undefined);
-}
+export const deepEqual = createDefaultEqualCreator();
 
-const isShallowEqual = createComparator(
-  merge(DEFAULT_CONFIG, { createIsNestedEqual: () => sameValueZeroEqual }),
-);
+/**
+ * Whether the items passed are deeply-equal in value based on strict comparison.
+ */
+export const strictDeepEqual = createDefaultEqualCreator({ strict: true });
 
 /**
- * Whether the items passed are shallowly-equal in value.
+ * Whether the items passed are deeply-equal in value, including circular references.
  */
-export function shallowEqual<A, B>(a: A, b: B): boolean {
-  return isShallowEqual(a, b, undefined);
-}
+export const circularDeepEqual = createDefaultEqualCreator({ circular: true });
 
-const isCircularDeepEqual = createComparator(DEFAULT_CIRCULAR_CONFIG);
+/**
+ * Whether the items passed are deeply-equal in value, including circular references,
+ * based on strict comparison.
+ */
+export const strictCircularDeepEqual = createDefaultEqualCreator({
+  circular: true,
+  strict: true,
+});
 
 /**
- * Whether the items passed are deeply-equal in value, including circular references.
+ * Whether the items passed are shallowly-equal in value.
  */
-export function circularDeepEqual<A, B>(a: A, b: B): boolean {
-  return isCircularDeepEqual(a, b, new WeakMap());
-}
+export const shallowEqual = createDefaultEqualCreator({
+  comparator: sameValueZeroEqual,
+});
 
-const isCircularShallowEqual = createComparator(
-  merge(DEFAULT_CIRCULAR_CONFIG, {
-    createIsNestedEqual: () => sameValueZeroEqual,
-  }),
-);
+/**
+ * Whether the items passed are shallowly-equal in value based on strict comparison
+ */
+export const strictShallowEqual = createDefaultEqualCreator({
+  comparator: sameValueZeroEqual,
+  strict: true,
+});
 
 /**
  * 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());
-}
+export const circularShallowEqual = createDefaultEqualCreator({
+  comparator: sameValueZeroEqual,
+  circular: true,
+});
 
 /**
- * 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.
+ * Whether the items passed are shallowly-equal in value, including circular references,
+ * based on strict comparison.
  */
-export function createCustomEqual<Meta = undefined>(
-  getComparatorOptions: GetComparatorOptions<Meta>,
-): EqualityComparator<Meta> {
-  return createComparator<Meta>(
-    merge(DEFAULT_CONFIG, getComparatorOptions(DEFAULT_CONFIG as any)),
-  );
-}
+export const strictCircularShallowEqual = createDefaultEqualCreator({
+  comparator: sameValueZeroEqual,
+  circular: true,
+  strict: true,
+});
 
 /**
- * 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.
+ * 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
- * `WeakMap` out of the box.
+ * `RegExp.prototype.flags` 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>;
+export function createCustomEqual<Meta>(
+  options: CustomEqualCreatorOptions<Meta> = {},
+) {
+  const {
+    comparator,
+    createInternalComparator: createCustomInternalComparator,
+    createCustomConfig,
+    createState,
+  } = options;
+
+  const baseConfig = createComparatorConfig(options);
+  const config = createCustomConfig
+    ? Object.assign({}, baseConfig, createCustomConfig(baseConfig))
+    : baseConfig;
+  const isEqualCustom = comparator || createComparator(config);
+  const isEqualCustomComparator = createCustomInternalComparator
+    ? createCustomInternalComparator(isEqualCustom)
+    : createInternalComparator(isEqualCustom);
+  const strict = !!options.strict;
+
+  if (createState) {
+    return function isEqual<A, B>(a: A, b: B, metaOverride?: Meta): boolean {
+      const customState = createState(isEqualCustom);
+
+      return isEqualCustom(a, b, {
+        cache: customState.cache || new WeakMap(),
+        equals: customState.equals || isEqualCustomComparator,
+        // @ts-expect-error - inferred `Meta` may be undefined, which is okay
+        meta: metaOverride !== undefined ? metaOverride : customState.meta,
+        strict: customState.strict !== undefined ? customState.strict : strict,
+      });
+    };
+  }
+
+  if (options.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,
+      } as CircularState<Meta>);
+    };
+  }
+
+  const state = Object.freeze({
+    cache: undefined,
+    equals: isEqualCustomComparator,
+    meta: undefined,
+    strict,
+  });
+
+  return function equals<A, B>(a: A, b: B): boolean {
+    return isEqualCustom(a, b, state as DefaultState<Meta>);
+  };
 }

package/src/internalTypes.ts

@@ -0,0 +1,74 @@
+export interface BaseCircular
+  extends Pick<WeakMap<any, any>, 'delete' | 'get'> {
+  set(key: object, value: any): any;
+}
+
+export type State<Meta> = CircularState<Meta> | DefaultState<Meta>;
+
+export interface CircularState<Meta> {
+  readonly cache: BaseCircular;
+  readonly equals: InternalEqualityComparator<Meta>;
+  meta: Meta;
+  readonly strict: boolean;
+}
+
+export interface DefaultState<Meta> {
+  readonly cache: undefined;
+  readonly equals: InternalEqualityComparator<Meta>;
+  meta: Meta;
+  readonly strict: boolean;
+}
+
+export interface Dictionary<Value = any> {
+  [key: string | symbol]: Value;
+  $$typeof?: any;
+}
+
+export interface ComparatorConfig<Meta> {
+  areArraysEqual: TypeEqualityComparator<any, Meta>;
+  areDatesEqual: TypeEqualityComparator<any, Meta>;
+  areMapsEqual: TypeEqualityComparator<any, Meta>;
+  areObjectsEqual: TypeEqualityComparator<any, Meta>;
+  arePrimitiveWrappersEqual: TypeEqualityComparator<any, Meta>;
+  areRegExpsEqual: TypeEqualityComparator<any, Meta>;
+  areSetsEqual: TypeEqualityComparator<any, Meta>;
+}
+
+export type CreateCustomComparatorConfig<Meta> = (
+  config: ComparatorConfig<Meta>,
+) => Partial<ComparatorConfig<Meta>>;
+
+export type CreateState<Meta> = (
+  comparator: EqualityComparator<Meta>,
+) => Partial<State<Meta>>;
+
+export type EqualityComparator<Meta> = <A, B>(
+  a: A,
+  b: B,
+  state: State<Meta>,
+) => boolean;
+export type AnyEqualityComparator<Meta> = (
+  a: any,
+  b: any,
+  state: State<Meta>,
+) => boolean;
+
+export type EqualityComparatorCreator<Meta> = (
+  fn: EqualityComparator<Meta>,
+) => InternalEqualityComparator<Meta>;
+
+export type InternalEqualityComparator<Meta> = (
+  a: any,
+  b: any,
+  indexOrKeyA: any,
+  indexOrKeyB: any,
+  parentA: any,
+  parentB: any,
+  state: State<Meta>,
+) => boolean;
+
+export type TypeEqualityComparator<Type, Meta = undefined> = (
+  a: Type,
+  b: Type,
+  state: State<Meta>,
+) => boolean;