fast-equals 5.3.3 → 5.4.0

package/dist/umd/types/internalTypes.d.ts

@@ -1,157 +0,0 @@
-/**
- * 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 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 CircularState<Meta> extends State<Meta> {
-    readonly cache: Cache<any, any>;
-}
-export interface DefaultState<Meta> extends State<Meta> {
-    readonly cache: undefined;
-}
-export interface Dictionary<Value = any> {
-    [key: string | symbol]: Value;
-    $$typeof?: 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 errors passed are equal in value.
-     */
-    areErrorsEqual: TypeEqualityComparator<any, Meta>;
-    /**
-     * Whether the functions passed are equal in value.
-     */
-    areFunctionsEqual: 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 numbers passed are equal in value.
-     */
-    areNumbersEqual: 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>;
-    /**
-     * Whether the URLs passed are equal in value.
-     */
-    areUrlsEqual: TypeEqualityComparator<any, Meta>;
-    /**
-     * Whether two values with unknown `@@toStringTag` are equal in value. This comparator is
-     * called when no other comparator applies.
-     *
-     * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag
-     */
-    unknownTagComparators: Record<string, TypeEqualityComparator<any, Meta>> | undefined;
-}
-export type CreateCustomComparatorConfig<Meta> = (config: ComparatorConfig<Meta>) => Partial<ComparatorConfig<Meta>>;
-export type CreateState<Meta> = () => {
-    cache?: Cache<any, any> | undefined;
-    meta?: 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 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 | Int8Array | Int16Array | Int32Array | Uint16Array | Uint32Array | Uint8Array | Uint8ClampedArray;
-export type TypeEqualityComparator<Type, Meta = undefined> = (a: Type, b: Type, state: State<Meta>) => 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;
-    /**
-     * 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>;
-    /**
-     * 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/dist/umd/types/utils.d.ts

@@ -1,28 +0,0 @@
-import type { AnyEqualityComparator, Dictionary, State, TypeEqualityComparator } from './internalTypes.js';
-/**
- * Combine two comparators into a single comparators.
- */
-export declare function combineComparators<Meta>(comparatorA: AnyEqualityComparator<Meta>, comparatorB: AnyEqualityComparator<Meta>): <A, B>(a: A, b: B, state: State<Meta>) => boolean;
-/**
- * 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.
- */
-export declare function createIsCircular<AreItemsEqual extends TypeEqualityComparator<any, any>>(areItemsEqual: AreItemsEqual): AreItemsEqual;
-/**
- * Get the `@@toStringTag` of the value, if it exists.
- */
-export declare function getShortTag(value: any): string | undefined;
-/**
- * Get the properties to strictly examine, which include both own properties that are
- * not enumerable and symbol properties.
- */
-export declare function getStrictProperties(object: Dictionary): Array<string | symbol>;
-/**
- * Whether the object contains the property passed as an own property.
- */
-export declare const hasOwn: (o: object, v: PropertyKey) => boolean;
-/**
- * Whether the values passed are strictly equal or both NaN.
- */
-export declare function sameValueZeroEqual(a: any, b: any): boolean;

package/src/comparator.ts

@@ -1,376 +0,0 @@
-import {
-  areArraysEqual as areArraysEqualDefault,
-  areDatesEqual as areDatesEqualDefault,
-  areErrorsEqual as areErrorsEqualDefault,
-  areFunctionsEqual as areFunctionsEqualDefault,
-  areMapsEqual as areMapsEqualDefault,
-  areNumbersEqual as areNumbersEqualDefault,
-  areObjectsEqual as areObjectsEqualDefault,
-  areObjectsEqualStrict as areObjectsEqualStrictDefault,
-  arePrimitiveWrappersEqual as arePrimitiveWrappersEqualDefault,
-  areRegExpsEqual as areRegExpsEqualDefault,
-  areSetsEqual as areSetsEqualDefault,
-  areTypedArraysEqual as areTypedArraysEqualDefault,
-  areUrlsEqual as areUrlsEqualDefault,
-} from './equals.js';
-import type {
-  ComparatorConfig,
-  CreateState,
-  CustomEqualCreatorOptions,
-  EqualityComparator,
-  InternalEqualityComparator,
-  State,
-} from './internalTypes.js';
-import { combineComparators, createIsCircular, getShortTag } from './utils.js';
-
-const ARGUMENTS_TAG = '[object Arguments]';
-const BOOLEAN_TAG = '[object Boolean]';
-const DATE_TAG = '[object Date]';
-const ERROR_TAG = '[object Error]';
-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 URL_TAG = '[object URL]';
-
-const { isArray } = Array;
-const isTypedArray =
-  typeof ArrayBuffer !== 'undefined' && typeof ArrayBuffer.isView === 'function'
-    ? ArrayBuffer.isView
-    : null;
-const { assign } = Object;
-const getTag = Object.prototype.toString.call.bind(
-  Object.prototype.toString,
-) as (a: object) => string;
-
-interface CreateIsEqualOptions<Meta> {
-  circular: boolean;
-  comparator: EqualityComparator<Meta>;
-  createState: CreateState<Meta> | undefined;
-  equals: InternalEqualityComparator<Meta>;
-  strict: boolean;
-}
-
-/**
- * Create a comparator method based on the type-specific equality comparators passed.
- */
-export function createEqualityComparator<Meta>({
-  areArraysEqual,
-  areDatesEqual,
-  areErrorsEqual,
-  areFunctionsEqual,
-  areMapsEqual,
-  areNumbersEqual,
-  areObjectsEqual,
-  arePrimitiveWrappersEqual,
-  areRegExpsEqual,
-  areSetsEqual,
-  areTypedArraysEqual,
-  areUrlsEqual,
-  unknownTagComparators,
-}: ComparatorConfig<Meta>): EqualityComparator<Meta> {
-  /**
-   * compare the value of the two objects and return true if they are equivalent in values
-   */
-  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;
-    }
-
-    // If either of the items are nullish and fail the strictly equal check
-    // above, then they must be unequal.
-    if (a == null || b == null) {
-      return false;
-    }
-
-    const type = typeof a;
-
-    if (type !== typeof b) {
-      return false;
-    }
-
-    if (type !== 'object') {
-      if (type === 'number') {
-        return areNumbersEqual(a, b, state);
-      }
-
-      if (type === 'function') {
-        return areFunctionsEqual(a, b, state);
-      }
-
-      // If a primitive value that is not strictly equal, it must be unequal.
-      return false;
-    }
-
-    const constructor = a.constructor;
-
-    // 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.
-
-    // Constructors should match, otherwise there is potential for false positives
-    // between class and subclass or custom object and POJO.
-    if (constructor !== b.constructor) {
-      return false;
-    }
-
-    // `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 capturing the string tag.
-    if (constructor === Object) {
-      return areObjectsEqual(a, b, state);
-    }
-
-    // `isArray()` works on subclasses and is cross-realm, so we can avoid capturing
-    // the string tag or doing an `instanceof` check.
-    if (isArray(a)) {
-      return areArraysEqual(a, b, state);
-    }
-
-    // `isTypedArray()` works on all possible TypedArray classes, so we can avoid
-    // capturing the string tag or comparing against all possible constructors.
-    if (isTypedArray != null && isTypedArray(a)) {
-      return areTypedArraysEqual(a, b, state);
-    }
-
-    // Try to fast-path equality checks for other complex object types in the
-    // same realm to avoid capturing the string tag. Strict equality is used
-    // instead of `instanceof` because it is more performant for the common
-    // use-case. If someone is subclassing a native class, it will be handled
-    // with the string tag comparison.
-
-    if (constructor === Date) {
-      return areDatesEqual(a, b, state);
-    }
-
-    if (constructor === RegExp) {
-      return areRegExpsEqual(a, b, state);
-    }
-
-    if (constructor === Map) {
-      return areMapsEqual(a, b, state);
-    }
-
-    if (constructor === Set) {
-      return areSetsEqual(a, b, state);
-    }
-
-    // Since this is a custom object, capture the string tag to determing its type.
-    // This is reasonably performant in modern environments like v8 and SpiderMonkey.
-    const tag = getTag(a as object);
-
-    if (tag === DATE_TAG) {
-      return areDatesEqual(a, b, state);
-    }
-
-    // For RegExp, the properties are not enumerable, and therefore will give false positives if
-    // tested like a standard object.
-    if (tag === REG_EXP_TAG) {
-      return areRegExpsEqual(a, b, state);
-    }
-
-    if (tag === MAP_TAG) {
-      return areMapsEqual(a, b, state);
-    }
-
-    if (tag === SET_TAG) {
-      return areSetsEqual(a, b, state);
-    }
-
-    if (tag === OBJECT_TAG) {
-      // The exception for value comparison is custom `Promise`-like class instances. These should
-      // be 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 a URL tag, it should be tested explicitly. Like RegExp, the properties are not
-    // enumerable, and therefore will give false positives if tested like a standard object.
-    if (tag === URL_TAG) {
-      return areUrlsEqual(a, b, state);
-    }
-
-    // If an error tag, it should be tested explicitly. Like RegExp, the properties are not
-    // enumerable, and therefore will give false positives if tested like a standard object.
-    if (tag === ERROR_TAG) {
-      return areErrorsEqual(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 (tag === BOOLEAN_TAG || tag === NUMBER_TAG || tag === STRING_TAG) {
-      return arePrimitiveWrappersEqual(a, b, state);
-    }
-
-    if (unknownTagComparators) {
-      let unknownTagComparator = unknownTagComparators[tag];
-
-      if (!unknownTagComparator) {
-        const shortTag = getShortTag(a);
-
-        if (shortTag) {
-          unknownTagComparator = unknownTagComparators[shortTag];
-        }
-      }
-
-      // If the custom config has an unknown tag comparator that matches the captured tag or the
-      // @@toStringTag, it is the source of truth for whether the values are equal.
-      if (unknownTagComparator) {
-        return unknownTagComparator(a, b, state);
-      }
-    }
-
-    // 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 (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 false;
-  };
-}
-
-/**
- * Create the configuration object used for building comparators.
- */
-export function createEqualityComparatorConfig<Meta>({
-  circular,
-  createCustomConfig,
-  strict,
-}: CustomEqualCreatorOptions<Meta>): ComparatorConfig<Meta> {
-  let config = {
-    areArraysEqual: strict
-      ? areObjectsEqualStrictDefault
-      : areArraysEqualDefault,
-    areDatesEqual: areDatesEqualDefault,
-    areErrorsEqual: areErrorsEqualDefault,
-    areFunctionsEqual: areFunctionsEqualDefault,
-    areMapsEqual: strict
-      ? combineComparators(areMapsEqualDefault, areObjectsEqualStrictDefault)
-      : areMapsEqualDefault,
-    areNumbersEqual: areNumbersEqualDefault,
-    areObjectsEqual: strict
-      ? areObjectsEqualStrictDefault
-      : areObjectsEqualDefault,
-    arePrimitiveWrappersEqual: arePrimitiveWrappersEqualDefault,
-    areRegExpsEqual: areRegExpsEqualDefault,
-    areSetsEqual: strict
-      ? combineComparators(areSetsEqualDefault, areObjectsEqualStrictDefault)
-      : areSetsEqualDefault,
-    areTypedArraysEqual: strict
-      ? areObjectsEqualStrictDefault
-      : areTypedArraysEqualDefault,
-    areUrlsEqual: areUrlsEqualDefault,
-    unknownTagComparators: undefined,
-  };
-
-  if (createCustomConfig) {
-    config = assign({}, config, createCustomConfig(config));
-  }
-
-  if (circular) {
-    const areArraysEqual = createIsCircular(config.areArraysEqual);
-    const areMapsEqual = createIsCircular(config.areMapsEqual);
-    const areObjectsEqual = createIsCircular(config.areObjectsEqual);
-    const areSetsEqual = createIsCircular(config.areSetsEqual);
-
-    config = assign({}, config, {
-      areArraysEqual,
-      areMapsEqual,
-      areObjectsEqual,
-      areSetsEqual,
-    });
-  }
-
-  return config;
-}
-
-/**
- * Default equality comparator pass-through, used as the standard `isEqual` creator for
- * use inside the built comparator.
- */
-export function createInternalEqualityComparator<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);
-  };
-}
-
-/**
- * Create the `isEqual` function used by the consuming application.
- */
-export function createIsEqual<Meta>({
-  circular,
-  comparator,
-  createState,
-  equals,
-  strict,
-}: CreateIsEqualOptions<Meta>) {
-  if (createState) {
-    return function isEqual<A, B>(a: A, b: B): boolean {
-      const { cache = circular ? new WeakMap() : undefined, meta } =
-        createState();
-
-      return comparator(a, b, {
-        cache,
-        equals,
-        meta,
-        strict,
-      } as State<Meta>);
-    };
-  }
-
-  if (circular) {
-    return function isEqual<A, B>(a: A, b: B): boolean {
-      return comparator(a, b, {
-        cache: new WeakMap(),
-        equals,
-        meta: undefined as Meta,
-        strict,
-      } as State<Meta>);
-    };
-  }
-
-  const state = {
-    cache: undefined,
-    equals,
-    meta: undefined,
-    strict,
-  } as State<Meta>;
-
-  return function isEqual<A, B>(a: A, b: B): boolean {
-    return comparator(a, b, state);
-  };
-}