fast-equals 5.0.0-beta.6 → 5.0.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # fast-equals CHANGELOG
 
+## 5.0.1
+
+### Bugfixes
+
+- Fix reference to `metaOverride` in typings and documentation (holdover from temporary API in v5 beta)
+
 ## 5.0.0
 
 ### Breaking changes
@@ -24,6 +30,10 @@ To better facilitate strict comparisons, but also to allow for `meta` use separa
 
 You can create a custom circular equality comparator through `createCustomEqual` now by providing `circular: true` to the options.
 
+#### Custom `meta` values are no longer passed at callsite
+
+To use `meta` properties for comparisons, they must be returned in a `createState` method.
+
 #### Deep links have changed
 
 If you were deep-linking into a specific asset type (ESM / CJS / UMD), they have changed location.

package/README.md

@@ -165,6 +165,7 @@ console.log(circularShallowEqual(array, [array])); // false
 
 Performs the same comparison as `deepEqual` but performs a strict comparison of the objects. In this includes:
 
+- Checking symbol properties
 - Checking non-enumerable properties in object comparisons
 - Checking full descriptor of properties on the object to match
 - Checking non-index properties on arrays
@@ -309,7 +310,7 @@ function createCustomEqual<Meta>(options: {
   ) => boolean;
   createState?: () => { cache?: Cache; meta?: Meta };
   strict?: boolean;
-}): <A, B>(a: A, b: B, metaOverride?: Meta) => boolean;
+}): <A, B>(a: A, b: B) => boolean;
 ```
 
 Create a custom equality comparator. This allows complete control over building a bespoke equality method, in case your use-case requires a higher degree of performance, legacy environment support, or any other non-standard usage. The [recipes](#recipes) provide examples of use in different use-cases, but if you have a specific goal in mind and would like assistance feel free to [file an issue](https://github.com/planttheidea/fast-equals/issues).
@@ -329,7 +330,7 @@ Some recipes have been created to provide examples of use-cases for `createCusto
 
 ## Benchmarks
 
-All benchmarks were performed on an i7-8650U Ubuntu Linux laptop with 24GB of memory using NodeJS version `12.19.1`, and are based on averages of running comparisons based deep equality on the following object types:
+All benchmarks were performed on an i9-11900H Ubuntu Linux 22.04 laptop with 64GB of memory using NodeJS version `16.14.2`, and are based on averages of running comparisons based deep equality on the following object types:
 
 - Primitives (`String`, `Number`, `null`, `undefined`)
 - `Function`
@@ -340,23 +341,47 @@ All benchmarks were performed on an i7-8650U Ubuntu Linux laptop with 24GB of me
 - `react` elements
 - A mixed object with a combination of all the above types
 
-|                            | Operations / second |
-| -------------------------- | ------------------- |
-| **fast-equals**            | **153,880**         |
-| fast-deep-equal            | 144,035             |
-| react-fast-compare         | 130,324             |
-| nano-equal                 | 104,624             |
-| **fast-equals (circular)** | **97,610**          |
-| shallow-equal-fuzzy        | 83,946              |
-| underscore.isEqual         | 47,370              |
-| lodash.isEqual             | 25,053              |
-| deep-eql                   | 22,146              |
-| assert.deepStrictEqual     | 532                 |
-| deep-equal                 | 209                 |
+```bash
+Testing mixed objects equal...
+┌─────────┬─────────────────────────────────┬────────────────┐
+│ (index) │             Package             │    Ops/sec     │
+├─────────┼─────────────────────────────────┼────────────────┤
+│    0    │          'fast-equals'          │ 1249567.730326 │
+│    1    │        'fast-deep-equal'        │ 1182463.587514 │
+│    2    │      'react-fast-compare'       │ 1152487.319161 │
+│    3    │      'shallow-equal-fuzzy'      │ 1092360.712389 │
+│    4    │    'fast-equals (circular)'     │  676669.92003  │
+│    5    │      'underscore.isEqual'       │ 429430.837497  │
+│    6    │        'lodash.isEqual'         │ 237915.684734  │
+│    7    │     'fast-equals (strict)'      │  181386.38032  │
+│    8    │ 'fast-equals (strict circular)' │ 156779.745875  │
+│    9    │           'deep-eql'            │ 139155.099209  │
+│   10    │          'deep-equal'           │  1026.527229   │
+└─────────┴─────────────────────────────────┴────────────────┘
+
+Testing mixed objects not equal...
+┌─────────┬─────────────────────────────────┬────────────────┐
+│ (index) │             Package             │    Ops/sec     │
+├─────────┼─────────────────────────────────┼────────────────┤
+│    0    │          'fast-equals'          │ 3255824.097237 │
+│    1    │      'react-fast-compare'       │ 2654721.726058 │
+│    2    │        'fast-deep-equal'        │ 2582218.974752 │
+│    3    │    'fast-equals (circular)'     │ 2474303.26566  │
+│    4    │     'fast-equals (strict)'      │ 1088066.604881 │
+│    5    │ 'fast-equals (strict circular)' │ 949253.614181  │
+│    6    │          'nano-equal'           │ 939170.554148  │
+│    7    │      'underscore.isEqual'       │ 738852.197879  │
+│    8    │        'lodash.isEqual'         │ 307306.622212  │
+│    9    │           'deep-eql'            │ 156250.110401  │
+│   10    │    'assert.deepStrictEqual'     │  22839.454561  │
+│   11    │          'deep-equal'           │   4034.45114   │
+└─────────┴─────────────────────────────────┴────────────────┘
+```
 
 Caveats that impact the benchmark (and accuracy of comparison):
 
 - `Map`s, `Promise`s, and `Set`s were excluded from the benchmark entirely because no library other than `deep-eql` fully supported their comparison
+- `fast-deep-equal`, `react-fast-compare` and `nano-equal` throw on objects with `null` as prototype (`Object.create(null)`)
 - `assert.deepStrictEqual` does not support `NaN` or `SameValueZero` equality for dates
 - `deep-eql` does not support `SameValueZero` equality for zero equality (positive and negative zero are not equal)
 - `deep-equal` does not support `NaN` and does not strictly compare object type, or date / regexp values, nor uses `SameValueZero` equality for dates

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

@@ -1,12 +1,30 @@
+/**
+ * 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> {
@@ -20,13 +38,42 @@ export interface Dictionary<Value = any> {
     $$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 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>;
 }
 export type CreateCustomComparatorConfig<Meta> = (config: ComparatorConfig<Meta>) => Partial<ComparatorConfig<Meta>>;
@@ -39,12 +86,49 @@ export type AnyEqualityComparator<Meta> = (a: any, b: any, state: State<Meta>) =
 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/esm/types/internalTypes.d.ts

@@ -1,12 +1,30 @@
+/**
+ * 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> {
@@ -20,13 +38,42 @@ export interface Dictionary<Value = any> {
     $$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 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>;
 }
 export type CreateCustomComparatorConfig<Meta> = (config: ComparatorConfig<Meta>) => Partial<ComparatorConfig<Meta>>;
@@ -39,12 +86,49 @@ export type AnyEqualityComparator<Meta> = (a: any, b: any, state: State<Meta>) =
 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/min/types/internalTypes.d.ts

@@ -1,12 +1,30 @@
+/**
+ * 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> {
@@ -20,13 +38,42 @@ export interface Dictionary<Value = any> {
     $$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 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>;
 }
 export type CreateCustomComparatorConfig<Meta> = (config: ComparatorConfig<Meta>) => Partial<ComparatorConfig<Meta>>;
@@ -39,12 +86,49 @@ export type AnyEqualityComparator<Meta> = (a: any, b: any, state: State<Meta>) =
 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/internalTypes.d.ts

@@ -1,12 +1,30 @@
+/**
+ * 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> {
@@ -20,13 +38,42 @@ export interface Dictionary<Value = any> {
     $$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 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>;
 }
 export type CreateCustomComparatorConfig<Meta> = (config: ComparatorConfig<Meta>) => Partial<ComparatorConfig<Meta>>;
@@ -39,12 +86,49 @@ export type AnyEqualityComparator<Meta> = (a: any, b: any, state: State<Meta>) =
 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/index.d.ts

@@ -46,9 +46,9 @@ export declare const strictCircularShallowEqual: <A, B>(a: A, b: B) => boolean;
  *
  * 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.
+ * support for legacy environments that cannot polyfill for modern features expected by
+ * `fast-equals`, such as `WeakMap` or `RegExp.prototype.flags`.
  */
-export declare function createCustomEqual<Meta>(
+export declare function createCustomEqual<Meta = undefined>(
   options?: CustomEqualCreatorOptions<Meta>,
-): <A, B>(a: A, b: B, metaOverride?: Meta) => boolean;
+): <A, B>(a: A, b: B) => boolean;

package/package.json

@@ -11,43 +11,43 @@
     "@rollup/plugin-replace": "^5.0.2",
     "@rollup/plugin-terser": "^0.4.0",
     "@rollup/plugin-typescript": "^11.0.0",
-    "@types/jest": "^29.2.5",
+    "@types/jest": "^29.5.0",
     "@types/lodash": "^4.14.184",
-    "@types/node": "^18.14.2",
+    "@types/node": "^18.15.3",
     "@types/ramda": "^0.28.23",
     "@types/react": "^18.0.28",
     "@types/react-dom": "^18.0.11",
-    "@typescript-eslint/eslint-plugin": "^5.54.0",
-    "@typescript-eslint/parser": "^5.54.0",
+    "@typescript-eslint/eslint-plugin": "^5.55.0",
+    "@typescript-eslint/parser": "^5.55.0",
     "decircularize": "^1.0.0",
     "deep-eql": "^4.1.0",
     "deep-equal": "^2.0.5",
-    "eslint": "^8.35.0",
+    "eslint": "^8.36.0",
     "eslint-friendly-formatter": "^4.0.1",
     "eslint-webpack-plugin": "^4.0.0",
     "fast-deep-equal": "^3.1.3",
     "html-webpack-plugin": "^5.5.0",
     "in-publish": "^2.0.0",
-    "jest": "^29.4.3",
-    "jest-environment-jsdom": "^29.4.3",
+    "jest": "^29.5.0",
+    "jest-environment-jsdom": "^29.5.0",
     "jest-expect-message": "^1.1.3",
     "lodash": "^4.17.21",
     "nano-equal": "^2.0.2",
     "prettier": "^2.8.4",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "react-fast-compare": "^3.2.0",
-    "release-it": "^15.6.1",
-    "rollup": "^3.17.3",
+    "react-fast-compare": "^3.2.1",
+    "release-it": "^15.9.0",
+    "rollup": "^3.19.1",
     "shallow-equal-fuzzy": "^0.0.2",
-    "tinybench": "^2.3.1",
+    "tinybench": "^2.4.0",
     "ts-jest": "^29.0.3",
     "ts-loader": "^9.4.2",
     "typescript": "^4.9.5",
     "underscore": "^1.13.4",
-    "webpack": "^5.75.0",
+    "webpack": "^5.76.2",
     "webpack-cli": "^5.0.1",
-    "webpack-dev-server": "^4.11.1"
+    "webpack-dev-server": "^4.13.0"
   },
   "engines": {
     "node": ">=6.0.0"
@@ -109,5 +109,5 @@
   "sideEffects": false,
   "type": "module",
   "types": "./index.d.ts",
-  "version": "5.0.0-beta.6"
+  "version": "5.0.1"
 }

package/src/internalTypes.ts

@@ -1,3 +1,7 @@
+/**
+ * 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;
@@ -5,9 +9,23 @@ export interface Cache<Key extends object, Value> {
 }
 
 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;
 }
 
@@ -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>;
 }
 
@@ -73,6 +120,17 @@ export type InternalEqualityComparator<Meta> = (
 // 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
@@ -91,11 +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;
+  /**
+   * 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;
 }