fast-equals 4.0.2 → 5.0.0-beta.0

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;

package/src/utils.ts

@@ -1,31 +1,48 @@
 import {
+  AnyEqualityComparator,
+  BaseCircular,
+  CircularState,
+  Dictionary,
   EqualityComparator,
   InternalEqualityComparator,
+  State,
   TypeEqualityComparator,
-} from '../index.d';
+} from './internalTypes';
+
+const { getOwnPropertyNames, getOwnPropertySymbols } = Object;
+const { hasOwnProperty } = Object.prototype;
+
+export function combineComparators<Meta>(
+  comparatorA: AnyEqualityComparator<Meta>,
+  comparatorB: AnyEqualityComparator<Meta>,
+) {
+  return function isEqual<A, B>(a: A, b: B, state: State<Meta>) {
+    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.
  */
-export function createDefaultIsNestedEqual<Meta>(
-  comparator: EqualityComparator<Meta>,
+export function createInternalComparator<Meta>(
+  compare: EqualityComparator<Meta>,
 ): InternalEqualityComparator<Meta> {
-  return function isEqual<A, B>(
-    a: A,
-    b: B,
+  return function (
+    a: any,
+    b: any,
     _indexOrKeyA: any,
     _indexOrKeyB: any,
     _parentA: any,
     _parentB: any,
-    meta: Meta,
+    state: State<Meta>,
   ) {
-    return comparator(a, b, meta);
+    return compare(a, b, state);
   };
 }
 
 /**
- * Wrap the provided `areItemsEqual` method to manage the circular cache, allowing
+ * Wrap the provided `areItemsEqual` method to manage the circular state, allowing
  * for circular references to be safely included in the comparison without creating
  * stack overflows.
  */
@@ -35,13 +52,14 @@ export function createIsCircular<
   return function isCircular(
     a: any,
     b: any,
-    isEqual: InternalEqualityComparator<WeakMap<any, any>>,
-    cache: WeakMap<any, any>,
+    state: CircularState<BaseCircular>,
   ) {
     if (!a || !b || typeof a !== 'object' || typeof b !== 'object') {
-      return areItemsEqual(a, b, isEqual, cache);
+      return areItemsEqual(a, b, state);
     }
 
+    const { cache } = state;
+
     const cachedA = cache.get(a);
     const cachedB = cache.get(b);
 
@@ -52,7 +70,7 @@ export function createIsCircular<
     cache.set(a, b);
     cache.set(b, a);
 
-    const result = areItemsEqual(a, b, isEqual, cache);
+    const result = areItemsEqual(a, b, state);
 
     cache.delete(a);
     cache.delete(b);
@@ -61,47 +79,22 @@ export function createIsCircular<
   } 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;
+export function getStrictProperties(
+  object: Dictionary,
+): Array<string | symbol> {
+  return (getOwnPropertyNames(object) as Array<string | symbol>).concat(
+    getOwnPropertySymbols(object),
+  );
 }
 
-/**
- * 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';
-}
+export const hasOwn =
+  Object.hasOwn ||
+  ((object: Dictionary, property: number | string | symbol) =>
+    hasOwnProperty.call(object, property));
 
 /**
  * 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);
+  return a || b ? a === b : a === b || (a !== a && b !== b);
 }