fast-equals 6.0.0-rc.1 → 6.0.0

package/README.md

@@ -1,12 +1,7 @@
-# fast-equals
+> fast-equals
 
-<img src="https://img.shields.io/badge/build-passing-brightgreen.svg"/>
-<img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg"/>
-<img src="https://img.shields.io/badge/license-MIT-blue.svg"/>
-
-Perform [blazing fast](#benchmarks) equality comparisons (either deep or shallow) on two objects passed, while also
-maintaining a high degree of flexibility for various implementation use-cases. It has no dependencies, and is ~2kB when
-minified and gzipped.
+Perform [blazing fast](#benchmarks) equality comparisons between two objects, while also allowing for flexibility for
+various use-cases. It has no dependencies, and is ~2kB when minified and gzipped.
 
 The following types are handled out-of-the-box:
 
@@ -16,36 +11,43 @@ The following types are handled out-of-the-box:
 - `Date` objects
 - `RegExp` objects
 - `Map` / `Set` iterables
-- `Promise` objects
+- `Promise` objects and then-ables
 - Primitive wrappers (`new Boolean()` / `new Number()` / `new String()`)
 - Custom class instances, including subclasses of native classes
 
-Methods are available for deep, shallow, or referential equality comparison. In addition, you can opt into support for
-circular objects, or performing a "strict" comparison with unconventional property definition, or both. You can also
-customize any specific type comparison based on your application's use-cases.
-
-## Table of contents
-
-- [fast-equals](#fast-equals)
-  - [Table of contents](#table-of-contents)
-  - [Usage](#usage)
-    - [Specific builds](#specific-builds)
-  - [Available methods](#available-methods)
-    - [deepEqual](#deepequal)
-      - [Comparing `Map`s](#comparing-maps)
-    - [shallowEqual](#shallowequal)
-    - [sameValueEqual](#samevalueequal)
-    - [circularDeepEqual](#circulardeepequal)
-    - [circularShallowEqual](#circularshallowequal)
-    - [strictDeepEqual](#strictdeepequal)
-    - [strictShallowEqual](#strictshallowequal)
-    - [strictCircularDeepEqual](#strictcirculardeepequal)
-    - [strictCircularShallowEqual](#strictcircularshallowequal)
-    - [createCustomEqual](#createcustomequal)
-      - [getUnsupportedCustomComparator](#getunsupportedcustomcomparator)
-      - [Recipes](#recipes)
-  - [Benchmarks](#benchmarks)
-  - [Development](#development)
+Methods are available for deep, shallow, [`SameValue`](http://ecma-international.org/ecma-262/7.0/#sec-samevalue),
+[`SameValueZero`](http://ecma-international.org/ecma-262/7.0/#sec-samevaluezero), or
+[strict equality](https://262.ecma-international.org/7.0/#sec-strict-equality-comparison) comparison. In addition, you
+can opt into support for circular objects, or performing a "strict" comparison with unconventional property definition,
+or both. You can also customize any specific type comparison based on your application's use-cases.
+
+By default, npm should resolve the correct build of the package based on your consumption (ESM vs CommonJS). However, if
+you want to force use of a specific build, they can be located here:
+
+- ESM => `fast-equals/dist/es/index.mjs`
+- CommonJS => `fast-equals/dist/cjs/index.cjs`
+
+If you are having any problems, want to request a new feature, or have any questions,
+[please file an issue](https://github.com/planttheidea/fast-equals/issues).
+
+- [Usage](#usage)
+- [Available methods](#available-methods)
+  - [deepEqual](#deepequal)
+    - [Comparing `Map`s](#comparing-maps)
+  - [shallowEqual](#shallowequal)
+  - [sameValueEqual](#samevalueequal)
+  - [sameValueZeroEqual](#samevaluezeroequal)
+  - [strictEqual](#strictequal)
+  - [circularDeepEqual](#circulardeepequal)
+  - [circularShallowEqual](#circularshallowequal)
+  - [strictDeepEqual](#strictdeepequal)
+  - [strictShallowEqual](#strictshallowequal)
+  - [strictCircularDeepEqual](#strictcirculardeepequal)
+  - [strictCircularShallowEqual](#strictcircularshallowequal)
+  - [createCustomEqual](#createcustomequal)
+    - [getUnsupportedCustomComparator](#getunsupportedcustomcomparator)
+    - [Recipes](#recipes)
+- [Benchmarks](#benchmarks)
 
 ## Usage
 
@@ -55,19 +57,6 @@ import { deepEqual } from 'fast-equals';
 console.log(deepEqual({ foo: 'bar' }, { foo: 'bar' })); // true
 ```
 
-### Specific builds
-
-By default, npm should resolve the correct build of the package based on your consumption (ESM vs CommonJS). However, if
-you want to force use of a specific build, they can be located here:
-
-- ESM => `fast-equals/dist/esm/index.mjs`
-- CommonJS => `fast-equals/dist/cjs/index.cjs`
-- UMD => `fast-equals/dist/umd/index.js`
-- Minified UMD => `fast-equals/dist/min/index.js`
-
-If you are having issues loading a specific build type,
-[please file an issue](https://github.com/planttheidea/fast-equals/issues).
-
 ## Available methods
 
 ### deepEqual
@@ -99,7 +88,7 @@ deepEqual(mapA, mapB);
 ```
 
 To support true deep equality of all contents, `fast-equals` will perform a deep equality comparison for key and value
-parirs. Therefore, the above would be `true`.
+pairs. Therefore, the above would be `true`.
 
 ### shallowEqual
 
@@ -143,9 +132,9 @@ console.log(sameValueEqual(mainObject.foo, objectB)); // true
 console.log(sameValueEqual(mainObject, objectC)); // false
 ```
 
-**NOTE**: In environments that support
+_**NOTE**: In environments that support
 [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is),
-`sameValueEqual` is just a re-export of that method.
+`sameValueEqual` is just a re-export of that method._
 
 ### sameValueZeroEqual
 
@@ -170,6 +159,33 @@ console.log(sameValueEqual(mainObject.foo, objectB)); // true
 console.log(sameValueEqual(mainObject, objectC)); // false
 ```
 
+### strictEqual
+
+Performs a [Strict Equality](https://262.ecma-international.org/7.0/#sec-strict-equality-comparison) comparison on the
+two objects passed and returns a boolean representing the referential equality of the objects. In simple terms, this
+means:
+
+- `+0` and `-0` are equal
+- `NaN` is not equal to `NaN`
+- All other items are based on referential equality (`a === b`)
+
+```ts
+import { strictEqual } from 'fast-equals';
+
+const mainObject = { foo: NaN, bar: 'baz' };
+
+const objectA = 'baz';
+const objectB = NaN;
+const objectC = { foo: NaN, bar: 'baz' };
+
+console.log(sameValueEqual(mainObject.bar, objectA)); // true
+console.log(sameValueEqual(mainObject.foo, objectB)); // false
+console.log(sameValueEqual(mainObject, objectC)); // false
+```
+
+_**NOTE**: This is mainly a convenience function, such as needing a default functional equality comparator. Naturally,
+it is faster to simply compare `a === b`. :)_
+
 ### circularDeepEqual
 
 Performs the same comparison as `deepEqual` but supports circular objects. It is slower than `deepEqual`, so only use if
@@ -328,21 +344,21 @@ interface Cache<Key extends object, Value> {
 }
 
 interface ComparatorConfig<Meta> {
-  areArrayBuffersEcqual: TypeEqualityComparator<ArrayBuffer, Meta>;
-  areArraysEcqual: TypeEqualityComparator<any[], Meta>;
-  areDataViewsEqual: TypeEqualityComparator<DataView, Meta>;
-  areDatesEqual: TypeEqualityComparator<Date, Meta>;
-  areErrorsEqual: TypeEqualityComparator<Error, Meta>;
-  areFunctionsEqual: TypeEqualityComparator<(...args: any[]) => any, Meta>;
-  areMapsEqual: TypeEqualityComparator<Map<any, any>, Meta>;
-  areNumbersEqual: TypeEqualityComparator<number, Meta>;
-  areObjectsEqual: TypeEqualityComparator<Record<string, any>, Meta>;
-  arePrimitiveWrappersEqual: TypeEqualityComparator<Boolean | Number | String, Meta>;
-  areRegExpsEqual: TypeEqualityComparator<RegExp, Meta>;
-  areSetsEqual: TypeEqualityComparator<Set<any>, Meta>;
-  areTypedArraysEqual: TypeEqualityComparator<TypedArray, Meta>;
-  areUrlsEqual: TypeEqualityComparator<URL, Meta>;
-  getUnsupportedCustomComparator: <Type>(a: Type, b: Type, tag: string) => TypeEqualityComparator<Type, Meta>;
+  areArrayBuffersEqual: EqualityComparator<Meta>;
+  areArraysEqual: EqualityComparator<Meta>;
+  areDataViewsEqual: EqualityComparator<Meta>;
+  areDatesEqual: EqualityComparator<Meta>;
+  areErrorsEqual: EqualityComparator<Meta>;
+  areFunctionsEqual: EqualityComparator<Meta>;
+  areMapsEqual: EqualityComparator<Meta>;
+  areNumbersEqual: EqualityComparator<Meta>;
+  areObjectsEqual: EqualityComparator<Meta>;
+  arePrimitiveWrappersEqual: EqualityComparator<Meta>;
+  areRegExpsEqual: EqualityComparator<Meta>;
+  areSetsEqual: EqualityComparator<Meta>;
+  areTypedArraysEqual: EqualityComparator<Meta>;
+  areUrlsEqual: EqualityComparator<Meta>;
+  getUnsupportedCustomComparator: <Type>(a: Type, b: Type, state: State<Meta>, tag: string) => EqualityComparator<Meta>;
 }
 
 function createCustomEqual<Meta>(options: {
@@ -381,7 +397,7 @@ to the problem you are solving, they can offer guidance of how to structure your
 - [Using `meta` in comparison](./recipes//using-meta-in-comparison.md)
 - [Comparing non-standard properties](./recipes/non-standard-properties.md)
 - [Strict property descriptor comparison](./recipes/strict-property-descriptor-check.md)
-- [Legacy environment support for circualr equal comparators](./recipes/legacy-circular-equal-support.md)
+- [Legacy environment support for circular equal comparators](./recipes/legacy-circular-equal-support.md)
 - [Custom comparator support](./recipes/special-objects.md)
 
 ## Benchmarks
@@ -491,20 +507,3 @@ All of these have the potential of inflating the respective library's numbers in
 the closest apples-to-apples comparison I could create of a reasonable sample size. It should be noted that `react`
 elements can be circular objects, however simple elements are not; I kept the `react` comparison very basic to allow it
 to be included.
-
-## Development
-
-Standard practice, clone the repo and `npm i` to get the dependencies. The following npm scripts are available:
-
-- benchmark => run benchmark tests against other equality libraries
-- build => build `main`, `module`, and `browser` distributables with `rollup`
-- clean => run `rimraf` on the `dist` folder
-- dev => start `vite` playground App
-- dist => run `build`
-- lint => run ESLint on all files in `src` folder (also runs on `dev` script)
-- lint:fix => run `lint` script, but with auto-fixer
-- prepublish:compile => run `lint`, `test:coverage`, `transpile:lib`, `transpile:es`, and `dist` scripts
-- start => run `dev`
-- test => run AVA with NODE_ENV=test on all files in `test` folder
-- test:coverage => run same script as `test` with code coverage calculation via `nyc`
-- test:watch => run same script as `test` but keep persistent watcher

package/dist/cjs/index.cjs

@@ -75,6 +75,18 @@ Object.is
 function sameValueZeroEqual(a, b) {
     return a === b || (a !== a && b !== b);
 }
+/**
+ * Whether the values passed are equal based on a
+ * [Strict Equality Comparison](https://262.ecma-international.org/7.0/#sec-strict-equality-comparison) basis.
+ * Simplified, this maps to if the two values are referentially equal to one another (`a === b`).
+ *
+ * @note
+ * This is mainly available as a convenience function, such as being a default when a function to determine equality between
+ * two objects is used.
+ */
+function strictEqual(a, b) {
+    return a === b;
+}
 /**
  * Whether the array buffers are equal in value.
  */
@@ -115,12 +127,6 @@ function areDatesEqual(a, b) {
 function areErrorsEqual(a, b) {
     return a.name === b.name && a.message === b.message && a.cause === b.cause && a.stack === b.stack;
 }
-/**
- * Whether the functions passed are equal in value.
- */
-function areFunctionsEqual(a, b) {
-    return a === b;
-}
 /**
  * Whether the `Map`s are equal in value.
  */
@@ -170,10 +176,6 @@ function areMapsEqual(a, b, state) {
     }
     return true;
 }
-/**
- * Whether the numbers are equal in value.
- */
-const areNumbersEqual = sameValueEqual;
 /**
  * Whether the objects are equal in value.
  */
@@ -368,8 +370,8 @@ function createEqualityComparator(config) {
         // 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.
+        // use-case. If someone is creating a subclass from a native class, it will be
+        // handled with the string tag comparison.
         if (constructor === Object) {
             return areObjectsEqual(a, b, state);
         }
@@ -398,14 +400,14 @@ function createEqualityComparator(config) {
         if (Array.isArray(a)) {
             return areArraysEqual(a, b, state);
         }
-        // Since this is a custom object, capture the string tag to determing its type.
+        // Since this is a custom object, capture the string tag to determining its type.
         // This is reasonably performant in modern environments like v8 and SpiderMonkey.
         const tag = toString.call(a);
         const supportedComparator = supportedComparatorMap[tag];
         if (supportedComparator) {
             return supportedComparator(a, b, state);
         }
-        const unsupportedCustomComparator = getUnsupportedCustomComparator && getUnsupportedCustomComparator(a, b, tag);
+        const unsupportedCustomComparator = getUnsupportedCustomComparator && getUnsupportedCustomComparator(a, b, state, tag);
         if (unsupportedCustomComparator) {
             return unsupportedCustomComparator(a, b, state);
         }
@@ -430,9 +432,9 @@ function createEqualityComparatorConfig({ circular, createCustomConfig, strict,
         areDataViewsEqual,
         areDatesEqual: areDatesEqual,
         areErrorsEqual: areErrorsEqual,
-        areFunctionsEqual: areFunctionsEqual,
+        areFunctionsEqual: strictEqual,
         areMapsEqual: strict ? combineComparators(areMapsEqual, areObjectsEqualStrict) : areMapsEqual,
-        areNumbersEqual: areNumbersEqual,
+        areNumbersEqual: sameValueEqual,
         areObjectsEqual: strict ? areObjectsEqualStrict : areObjectsEqual,
         arePrimitiveWrappersEqual: arePrimitiveWrappersEqual,
         areRegExpsEqual: areRegExpsEqual,
@@ -512,6 +514,7 @@ function createSupportedComparatorMap({ areArrayBuffersEqual, areArraysEqual, ar
         '[object Arguments]': areObjectsEqual,
         '[object Array]': areArraysEqual,
         '[object ArrayBuffer]': areArrayBuffersEqual,
+        '[object AsyncGeneratorFunction]': areFunctionsEqual,
         '[object BigInt]': areNumbersEqual,
         '[object BigInt64Array]': areTypedArraysEqual,
         '[object BigUint64Array]': areTypedArraysEqual,
@@ -626,4 +629,5 @@ exports.shallowEqual = shallowEqual;
 exports.strictCircularDeepEqual = strictCircularDeepEqual;
 exports.strictCircularShallowEqual = strictCircularShallowEqual;
 exports.strictDeepEqual = strictDeepEqual;
+exports.strictEqual = strictEqual;
 exports.strictShallowEqual = strictShallowEqual;

package/dist/cjs/index.d.cts

@@ -27,92 +27,75 @@ interface State<Meta> {
      */
     readonly strict: boolean;
 }
-interface CircularState<Meta> extends State<Meta> {
-    readonly cache: Cache<any, any>;
-}
-interface DefaultState<Meta> extends State<Meta> {
-    readonly cache: undefined;
-}
-interface Dictionary<Value = any> {
-    [key: string | symbol]: Value;
-    $$typeof?: any;
-}
 interface ComparatorConfig<Meta> {
     /**
      * Whether the array buffers passed are equal in value. In strict mode, this includes
      * additional properties added to the array.
      */
-    areArrayBuffersEqual: TypeEqualityComparator<any, Meta>;
+    areArrayBuffersEqual: EqualityComparator<Meta>;
     /**
      * Whether the arrays passed are equal in value. In strict mode, this includes
      * additional properties added to the array.
      */
-    areArraysEqual: TypeEqualityComparator<any, Meta>;
+    areArraysEqual: EqualityComparator<Meta>;
     /**
      * Whether the data views passed are equal in value.
      */
-    areDataViewsEqual: TypeEqualityComparator<any, Meta>;
+    areDataViewsEqual: EqualityComparator<Meta>;
     /**
      * Whether the dates passed are equal in value.
      */
-    areDatesEqual: TypeEqualityComparator<any, Meta>;
+    areDatesEqual: EqualityComparator<Meta>;
     /**
      * Whether the errors passed are equal in value.
      */
-    areErrorsEqual: TypeEqualityComparator<any, Meta>;
+    areErrorsEqual: EqualityComparator<Meta>;
     /**
      * Whether the functions passed are equal in value.
      */
-    areFunctionsEqual: TypeEqualityComparator<any, Meta>;
+    areFunctionsEqual: EqualityComparator<Meta>;
     /**
      * Whether the maps passed are equal in value. In strict mode, this includes
      * additional properties added to the map.
      */
-    areMapsEqual: TypeEqualityComparator<any, Meta>;
+    areMapsEqual: EqualityComparator<Meta>;
     /**
      * Whether the numbers passed are equal in value.
      */
-    areNumbersEqual: TypeEqualityComparator<any, Meta>;
+    areNumbersEqual: EqualityComparator<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>;
+    areObjectsEqual: EqualityComparator<Meta>;
     /**
      * Whether the primitive wrappers passed are equal in value.
      */
-    arePrimitiveWrappersEqual: TypeEqualityComparator<any, Meta>;
+    arePrimitiveWrappersEqual: EqualityComparator<Meta>;
     /**
      * Whether the regexps passed are equal in value.
      */
-    areRegExpsEqual: TypeEqualityComparator<any, Meta>;
+    areRegExpsEqual: EqualityComparator<Meta>;
     /**
      * Whether the sets passed are equal in value. In strict mode, this includes
      * additional properties added to the set.
      */
-    areSetsEqual: TypeEqualityComparator<any, Meta>;
+    areSetsEqual: EqualityComparator<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>;
+    areTypedArraysEqual: EqualityComparator<Meta>;
     /**
      * Whether the URLs passed are equal in value.
      */
-    areUrlsEqual: TypeEqualityComparator<any, Meta>;
+    areUrlsEqual: EqualityComparator<Meta>;
     /**
      * Get a custom comparator based on the objects passed.
      */
-    getUnsupportedCustomComparator: ((a: any, b: any, tag: string) => TypeEqualityComparator<any, Meta> | undefined) | undefined;
+    getUnsupportedCustomComparator: ((a: any, b: any, state: State<Meta>, tag: string) => EqualityComparator<Meta> | undefined) | undefined;
 }
-type CreateCustomComparatorConfig<Meta> = (config: ComparatorConfig<Meta>) => Partial<ComparatorConfig<Meta>>;
-type CreateState<Meta> = () => {
-    cache?: Cache<any, any> | undefined;
-    meta?: Meta;
-};
-type EqualityComparator<Meta> = <A, B>(a: A, b: B, state: State<Meta>) => boolean;
-type AnyEqualityComparator<Meta> = (a: any, b: any, state: State<Meta>) => boolean;
-type EqualityComparatorCreator<Meta> = (fn: EqualityComparator<Meta>) => InternalEqualityComparator<Meta>;
+type EqualityComparator<Meta> = (a: any, b: any, state: State<Meta>) => boolean;
 type InternalEqualityComparator<Meta> = (a: any, b: any, indexOrKeyA: any, indexOrKeyB: any, parentA: any, parentB: any, state: State<Meta>) => boolean;
 type PrimitiveWrapper = Boolean | Number | String;
 /**
@@ -120,7 +103,6 @@ type PrimitiveWrapper = Boolean | Number | String;
  * classes.
  */
 type TypedArray = BigInt64Array | BigUint64Array | Float32Array | Float64Array | Int8Array | Int16Array | Int32Array | Uint16Array | Uint32Array | Uint8Array | Uint8ClampedArray;
-type TypeEqualityComparator<Type, Meta = undefined> = (a: Type, b: Type, state: State<Meta>) => boolean;
 interface CustomEqualCreatorOptions<Meta> {
     /**
      * Whether circular references should be supported. It causes the
@@ -131,9 +113,9 @@ interface CustomEqualCreatorOptions<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.
+     * or a superset of the default methods.
      */
-    createCustomConfig?: CreateCustomComparatorConfig<Meta>;
+    createCustomConfig?: (config: ComparatorConfig<Meta>) => Partial<ComparatorConfig<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
@@ -146,7 +128,10 @@ interface CustomEqualCreatorOptions<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>;
+    createState?: () => {
+        cache?: Cache<any, any> | undefined;
+        meta?: Meta;
+    };
     /**
      * Whether the equality comparison is strict, meaning it matches
      * all properties (including symbols and non-enumerable properties)
@@ -170,6 +155,16 @@ declare const sameValueEqual: (value1: any, value2: any) => boolean;
  * are either positive or negative zero.
  */
 declare function sameValueZeroEqual(a: any, b: any): boolean;
+/**
+ * Whether the values passed are equal based on a
+ * [Strict Equality Comparison](https://262.ecma-international.org/7.0/#sec-strict-equality-comparison) basis.
+ * Simplified, this maps to if the two values are referentially equal to one another (`a === b`).
+ *
+ * @note
+ * This is mainly available as a convenience function, such as being a default when a function to determine equality between
+ * two objects is used.
+ */
+declare function strictEqual(a: any, b: any): boolean;
 
 /**
  * Whether the items passed are deeply-equal in value.
@@ -215,5 +210,5 @@ declare const strictCircularShallowEqual: <A, B>(a: A, b: B) => boolean;
  */
 declare function createCustomEqual<Meta = undefined>(options?: CustomEqualCreatorOptions<Meta>): <A, B>(a: A, b: B) => boolean;
 
-export { circularDeepEqual, circularShallowEqual, createCustomEqual, deepEqual, sameValueEqual, sameValueZeroEqual, shallowEqual, strictCircularDeepEqual, strictCircularShallowEqual, strictDeepEqual, strictShallowEqual };
-export type { AnyEqualityComparator, Cache, CircularState, ComparatorConfig, CreateCustomComparatorConfig, CreateState, CustomEqualCreatorOptions, DefaultState, Dictionary, EqualityComparator, EqualityComparatorCreator, InternalEqualityComparator, PrimitiveWrapper, State, TypeEqualityComparator, TypedArray };
+export { circularDeepEqual, circularShallowEqual, createCustomEqual, deepEqual, sameValueEqual, sameValueZeroEqual, shallowEqual, strictCircularDeepEqual, strictCircularShallowEqual, strictDeepEqual, strictEqual, strictShallowEqual };
+export type { Cache, ComparatorConfig, CustomEqualCreatorOptions, EqualityComparator, InternalEqualityComparator, PrimitiveWrapper, State, TypedArray };

package/dist/es/index.d.mts

@@ -27,92 +27,75 @@ interface State<Meta> {
      */
     readonly strict: boolean;
 }
-interface CircularState<Meta> extends State<Meta> {
-    readonly cache: Cache<any, any>;
-}
-interface DefaultState<Meta> extends State<Meta> {
-    readonly cache: undefined;
-}
-interface Dictionary<Value = any> {
-    [key: string | symbol]: Value;
-    $$typeof?: any;
-}
 interface ComparatorConfig<Meta> {
     /**
      * Whether the array buffers passed are equal in value. In strict mode, this includes
      * additional properties added to the array.
      */
-    areArrayBuffersEqual: TypeEqualityComparator<any, Meta>;
+    areArrayBuffersEqual: EqualityComparator<Meta>;
     /**
      * Whether the arrays passed are equal in value. In strict mode, this includes
      * additional properties added to the array.
      */
-    areArraysEqual: TypeEqualityComparator<any, Meta>;
+    areArraysEqual: EqualityComparator<Meta>;
     /**
      * Whether the data views passed are equal in value.
      */
-    areDataViewsEqual: TypeEqualityComparator<any, Meta>;
+    areDataViewsEqual: EqualityComparator<Meta>;
     /**
      * Whether the dates passed are equal in value.
      */
-    areDatesEqual: TypeEqualityComparator<any, Meta>;
+    areDatesEqual: EqualityComparator<Meta>;
     /**
      * Whether the errors passed are equal in value.
      */
-    areErrorsEqual: TypeEqualityComparator<any, Meta>;
+    areErrorsEqual: EqualityComparator<Meta>;
     /**
      * Whether the functions passed are equal in value.
      */
-    areFunctionsEqual: TypeEqualityComparator<any, Meta>;
+    areFunctionsEqual: EqualityComparator<Meta>;
     /**
      * Whether the maps passed are equal in value. In strict mode, this includes
      * additional properties added to the map.
      */
-    areMapsEqual: TypeEqualityComparator<any, Meta>;
+    areMapsEqual: EqualityComparator<Meta>;
     /**
      * Whether the numbers passed are equal in value.
      */
-    areNumbersEqual: TypeEqualityComparator<any, Meta>;
+    areNumbersEqual: EqualityComparator<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>;
+    areObjectsEqual: EqualityComparator<Meta>;
     /**
      * Whether the primitive wrappers passed are equal in value.
      */
-    arePrimitiveWrappersEqual: TypeEqualityComparator<any, Meta>;
+    arePrimitiveWrappersEqual: EqualityComparator<Meta>;
     /**
      * Whether the regexps passed are equal in value.
      */
-    areRegExpsEqual: TypeEqualityComparator<any, Meta>;
+    areRegExpsEqual: EqualityComparator<Meta>;
     /**
      * Whether the sets passed are equal in value. In strict mode, this includes
      * additional properties added to the set.
      */
-    areSetsEqual: TypeEqualityComparator<any, Meta>;
+    areSetsEqual: EqualityComparator<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>;
+    areTypedArraysEqual: EqualityComparator<Meta>;
     /**
      * Whether the URLs passed are equal in value.
      */
-    areUrlsEqual: TypeEqualityComparator<any, Meta>;
+    areUrlsEqual: EqualityComparator<Meta>;
     /**
      * Get a custom comparator based on the objects passed.
      */
-    getUnsupportedCustomComparator: ((a: any, b: any, tag: string) => TypeEqualityComparator<any, Meta> | undefined) | undefined;
+    getUnsupportedCustomComparator: ((a: any, b: any, state: State<Meta>, tag: string) => EqualityComparator<Meta> | undefined) | undefined;
 }
-type CreateCustomComparatorConfig<Meta> = (config: ComparatorConfig<Meta>) => Partial<ComparatorConfig<Meta>>;
-type CreateState<Meta> = () => {
-    cache?: Cache<any, any> | undefined;
-    meta?: Meta;
-};
-type EqualityComparator<Meta> = <A, B>(a: A, b: B, state: State<Meta>) => boolean;
-type AnyEqualityComparator<Meta> = (a: any, b: any, state: State<Meta>) => boolean;
-type EqualityComparatorCreator<Meta> = (fn: EqualityComparator<Meta>) => InternalEqualityComparator<Meta>;
+type EqualityComparator<Meta> = (a: any, b: any, state: State<Meta>) => boolean;
 type InternalEqualityComparator<Meta> = (a: any, b: any, indexOrKeyA: any, indexOrKeyB: any, parentA: any, parentB: any, state: State<Meta>) => boolean;
 type PrimitiveWrapper = Boolean | Number | String;
 /**
@@ -120,7 +103,6 @@ type PrimitiveWrapper = Boolean | Number | String;
  * classes.
  */
 type TypedArray = BigInt64Array | BigUint64Array | Float32Array | Float64Array | Int8Array | Int16Array | Int32Array | Uint16Array | Uint32Array | Uint8Array | Uint8ClampedArray;
-type TypeEqualityComparator<Type, Meta = undefined> = (a: Type, b: Type, state: State<Meta>) => boolean;
 interface CustomEqualCreatorOptions<Meta> {
     /**
      * Whether circular references should be supported. It causes the
@@ -131,9 +113,9 @@ interface CustomEqualCreatorOptions<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.
+     * or a superset of the default methods.
      */
-    createCustomConfig?: CreateCustomComparatorConfig<Meta>;
+    createCustomConfig?: (config: ComparatorConfig<Meta>) => Partial<ComparatorConfig<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
@@ -146,7 +128,10 @@ interface CustomEqualCreatorOptions<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>;
+    createState?: () => {
+        cache?: Cache<any, any> | undefined;
+        meta?: Meta;
+    };
     /**
      * Whether the equality comparison is strict, meaning it matches
      * all properties (including symbols and non-enumerable properties)
@@ -170,6 +155,16 @@ declare const sameValueEqual: (value1: any, value2: any) => boolean;
  * are either positive or negative zero.
  */
 declare function sameValueZeroEqual(a: any, b: any): boolean;
+/**
+ * Whether the values passed are equal based on a
+ * [Strict Equality Comparison](https://262.ecma-international.org/7.0/#sec-strict-equality-comparison) basis.
+ * Simplified, this maps to if the two values are referentially equal to one another (`a === b`).
+ *
+ * @note
+ * This is mainly available as a convenience function, such as being a default when a function to determine equality between
+ * two objects is used.
+ */
+declare function strictEqual(a: any, b: any): boolean;
 
 /**
  * Whether the items passed are deeply-equal in value.
@@ -215,5 +210,5 @@ declare const strictCircularShallowEqual: <A, B>(a: A, b: B) => boolean;
  */
 declare function createCustomEqual<Meta = undefined>(options?: CustomEqualCreatorOptions<Meta>): <A, B>(a: A, b: B) => boolean;
 
-export { circularDeepEqual, circularShallowEqual, createCustomEqual, deepEqual, sameValueEqual, sameValueZeroEqual, shallowEqual, strictCircularDeepEqual, strictCircularShallowEqual, strictDeepEqual, strictShallowEqual };
-export type { AnyEqualityComparator, Cache, CircularState, ComparatorConfig, CreateCustomComparatorConfig, CreateState, CustomEqualCreatorOptions, DefaultState, Dictionary, EqualityComparator, EqualityComparatorCreator, InternalEqualityComparator, PrimitiveWrapper, State, TypeEqualityComparator, TypedArray };
+export { circularDeepEqual, circularShallowEqual, createCustomEqual, deepEqual, sameValueEqual, sameValueZeroEqual, shallowEqual, strictCircularDeepEqual, strictCircularShallowEqual, strictDeepEqual, strictEqual, strictShallowEqual };
+export type { Cache, ComparatorConfig, CustomEqualCreatorOptions, EqualityComparator, InternalEqualityComparator, PrimitiveWrapper, State, TypedArray };

package/dist/es/index.mjs

@@ -73,6 +73,18 @@ Object.is
 function sameValueZeroEqual(a, b) {
     return a === b || (a !== a && b !== b);
 }
+/**
+ * Whether the values passed are equal based on a
+ * [Strict Equality Comparison](https://262.ecma-international.org/7.0/#sec-strict-equality-comparison) basis.
+ * Simplified, this maps to if the two values are referentially equal to one another (`a === b`).
+ *
+ * @note
+ * This is mainly available as a convenience function, such as being a default when a function to determine equality between
+ * two objects is used.
+ */
+function strictEqual(a, b) {
+    return a === b;
+}
 /**
  * Whether the array buffers are equal in value.
  */
@@ -113,12 +125,6 @@ function areDatesEqual(a, b) {
 function areErrorsEqual(a, b) {
     return a.name === b.name && a.message === b.message && a.cause === b.cause && a.stack === b.stack;
 }
-/**
- * Whether the functions passed are equal in value.
- */
-function areFunctionsEqual(a, b) {
-    return a === b;
-}
 /**
  * Whether the `Map`s are equal in value.
  */
@@ -168,10 +174,6 @@ function areMapsEqual(a, b, state) {
     }
     return true;
 }
-/**
- * Whether the numbers are equal in value.
- */
-const areNumbersEqual = sameValueEqual;
 /**
  * Whether the objects are equal in value.
  */
@@ -366,8 +368,8 @@ function createEqualityComparator(config) {
         // 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.
+        // use-case. If someone is creating a subclass from a native class, it will be
+        // handled with the string tag comparison.
         if (constructor === Object) {
             return areObjectsEqual(a, b, state);
         }
@@ -396,14 +398,14 @@ function createEqualityComparator(config) {
         if (Array.isArray(a)) {
             return areArraysEqual(a, b, state);
         }
-        // Since this is a custom object, capture the string tag to determing its type.
+        // Since this is a custom object, capture the string tag to determining its type.
         // This is reasonably performant in modern environments like v8 and SpiderMonkey.
         const tag = toString.call(a);
         const supportedComparator = supportedComparatorMap[tag];
         if (supportedComparator) {
             return supportedComparator(a, b, state);
         }
-        const unsupportedCustomComparator = getUnsupportedCustomComparator && getUnsupportedCustomComparator(a, b, tag);
+        const unsupportedCustomComparator = getUnsupportedCustomComparator && getUnsupportedCustomComparator(a, b, state, tag);
         if (unsupportedCustomComparator) {
             return unsupportedCustomComparator(a, b, state);
         }
@@ -428,9 +430,9 @@ function createEqualityComparatorConfig({ circular, createCustomConfig, strict,
         areDataViewsEqual,
         areDatesEqual: areDatesEqual,
         areErrorsEqual: areErrorsEqual,
-        areFunctionsEqual: areFunctionsEqual,
+        areFunctionsEqual: strictEqual,
         areMapsEqual: strict ? combineComparators(areMapsEqual, areObjectsEqualStrict) : areMapsEqual,
-        areNumbersEqual: areNumbersEqual,
+        areNumbersEqual: sameValueEqual,
         areObjectsEqual: strict ? areObjectsEqualStrict : areObjectsEqual,
         arePrimitiveWrappersEqual: arePrimitiveWrappersEqual,
         areRegExpsEqual: areRegExpsEqual,
@@ -510,6 +512,7 @@ function createSupportedComparatorMap({ areArrayBuffersEqual, areArraysEqual, ar
         '[object Arguments]': areObjectsEqual,
         '[object Array]': areArraysEqual,
         '[object ArrayBuffer]': areArrayBuffersEqual,
+        '[object AsyncGeneratorFunction]': areFunctionsEqual,
         '[object BigInt]': areNumbersEqual,
         '[object BigInt64Array]': areTypedArraysEqual,
         '[object BigUint64Array]': areTypedArraysEqual,
@@ -614,4 +617,4 @@ function createCustomEqual(options = {}) {
     return createIsEqual({ circular, comparator, createState, equals, strict });
 }
 
-export { circularDeepEqual, circularShallowEqual, createCustomEqual, deepEqual, sameValueEqual, sameValueZeroEqual, shallowEqual, strictCircularDeepEqual, strictCircularShallowEqual, strictDeepEqual, strictShallowEqual };
+export { circularDeepEqual, circularShallowEqual, createCustomEqual, deepEqual, sameValueEqual, sameValueZeroEqual, shallowEqual, strictCircularDeepEqual, strictCircularShallowEqual, strictDeepEqual, strictEqual, strictShallowEqual };

package/index.d.ts

@@ -27,92 +27,75 @@ interface State<Meta> {
      */
     readonly strict: boolean;
 }
-interface CircularState<Meta> extends State<Meta> {
-    readonly cache: Cache<any, any>;
-}
-interface DefaultState<Meta> extends State<Meta> {
-    readonly cache: undefined;
-}
-interface Dictionary<Value = any> {
-    [key: string | symbol]: Value;
-    $$typeof?: any;
-}
 interface ComparatorConfig<Meta> {
     /**
      * Whether the array buffers passed are equal in value. In strict mode, this includes
      * additional properties added to the array.
      */
-    areArrayBuffersEqual: TypeEqualityComparator<any, Meta>;
+    areArrayBuffersEqual: EqualityComparator<Meta>;
     /**
      * Whether the arrays passed are equal in value. In strict mode, this includes
      * additional properties added to the array.
      */
-    areArraysEqual: TypeEqualityComparator<any, Meta>;
+    areArraysEqual: EqualityComparator<Meta>;
     /**
      * Whether the data views passed are equal in value.
      */
-    areDataViewsEqual: TypeEqualityComparator<any, Meta>;
+    areDataViewsEqual: EqualityComparator<Meta>;
     /**
      * Whether the dates passed are equal in value.
      */
-    areDatesEqual: TypeEqualityComparator<any, Meta>;
+    areDatesEqual: EqualityComparator<Meta>;
     /**
      * Whether the errors passed are equal in value.
      */
-    areErrorsEqual: TypeEqualityComparator<any, Meta>;
+    areErrorsEqual: EqualityComparator<Meta>;
     /**
      * Whether the functions passed are equal in value.
      */
-    areFunctionsEqual: TypeEqualityComparator<any, Meta>;
+    areFunctionsEqual: EqualityComparator<Meta>;
     /**
      * Whether the maps passed are equal in value. In strict mode, this includes
      * additional properties added to the map.
      */
-    areMapsEqual: TypeEqualityComparator<any, Meta>;
+    areMapsEqual: EqualityComparator<Meta>;
     /**
      * Whether the numbers passed are equal in value.
      */
-    areNumbersEqual: TypeEqualityComparator<any, Meta>;
+    areNumbersEqual: EqualityComparator<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>;
+    areObjectsEqual: EqualityComparator<Meta>;
     /**
      * Whether the primitive wrappers passed are equal in value.
      */
-    arePrimitiveWrappersEqual: TypeEqualityComparator<any, Meta>;
+    arePrimitiveWrappersEqual: EqualityComparator<Meta>;
     /**
      * Whether the regexps passed are equal in value.
      */
-    areRegExpsEqual: TypeEqualityComparator<any, Meta>;
+    areRegExpsEqual: EqualityComparator<Meta>;
     /**
      * Whether the sets passed are equal in value. In strict mode, this includes
      * additional properties added to the set.
      */
-    areSetsEqual: TypeEqualityComparator<any, Meta>;
+    areSetsEqual: EqualityComparator<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>;
+    areTypedArraysEqual: EqualityComparator<Meta>;
     /**
      * Whether the URLs passed are equal in value.
      */
-    areUrlsEqual: TypeEqualityComparator<any, Meta>;
+    areUrlsEqual: EqualityComparator<Meta>;
     /**
      * Get a custom comparator based on the objects passed.
      */
-    getUnsupportedCustomComparator: ((a: any, b: any, tag: string) => TypeEqualityComparator<any, Meta> | undefined) | undefined;
+    getUnsupportedCustomComparator: ((a: any, b: any, state: State<Meta>, tag: string) => EqualityComparator<Meta> | undefined) | undefined;
 }
-type CreateCustomComparatorConfig<Meta> = (config: ComparatorConfig<Meta>) => Partial<ComparatorConfig<Meta>>;
-type CreateState<Meta> = () => {
-    cache?: Cache<any, any> | undefined;
-    meta?: Meta;
-};
-type EqualityComparator<Meta> = <A, B>(a: A, b: B, state: State<Meta>) => boolean;
-type AnyEqualityComparator<Meta> = (a: any, b: any, state: State<Meta>) => boolean;
-type EqualityComparatorCreator<Meta> = (fn: EqualityComparator<Meta>) => InternalEqualityComparator<Meta>;
+type EqualityComparator<Meta> = (a: any, b: any, state: State<Meta>) => boolean;
 type InternalEqualityComparator<Meta> = (a: any, b: any, indexOrKeyA: any, indexOrKeyB: any, parentA: any, parentB: any, state: State<Meta>) => boolean;
 type PrimitiveWrapper = Boolean | Number | String;
 /**
@@ -120,7 +103,6 @@ type PrimitiveWrapper = Boolean | Number | String;
  * classes.
  */
 type TypedArray = BigInt64Array | BigUint64Array | Float32Array | Float64Array | Int8Array | Int16Array | Int32Array | Uint16Array | Uint32Array | Uint8Array | Uint8ClampedArray;
-type TypeEqualityComparator<Type, Meta = undefined> = (a: Type, b: Type, state: State<Meta>) => boolean;
 interface CustomEqualCreatorOptions<Meta> {
     /**
      * Whether circular references should be supported. It causes the
@@ -131,9 +113,9 @@ interface CustomEqualCreatorOptions<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.
+     * or a superset of the default methods.
      */
-    createCustomConfig?: CreateCustomComparatorConfig<Meta>;
+    createCustomConfig?: (config: ComparatorConfig<Meta>) => Partial<ComparatorConfig<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
@@ -146,7 +128,10 @@ interface CustomEqualCreatorOptions<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>;
+    createState?: () => {
+        cache?: Cache<any, any> | undefined;
+        meta?: Meta;
+    };
     /**
      * Whether the equality comparison is strict, meaning it matches
      * all properties (including symbols and non-enumerable properties)
@@ -170,6 +155,16 @@ declare const sameValueEqual: (value1: any, value2: any) => boolean;
  * are either positive or negative zero.
  */
 declare function sameValueZeroEqual(a: any, b: any): boolean;
+/**
+ * Whether the values passed are equal based on a
+ * [Strict Equality Comparison](https://262.ecma-international.org/7.0/#sec-strict-equality-comparison) basis.
+ * Simplified, this maps to if the two values are referentially equal to one another (`a === b`).
+ *
+ * @note
+ * This is mainly available as a convenience function, such as being a default when a function to determine equality between
+ * two objects is used.
+ */
+declare function strictEqual(a: any, b: any): boolean;
 
 /**
  * Whether the items passed are deeply-equal in value.
@@ -215,5 +210,5 @@ declare const strictCircularShallowEqual: <A, B>(a: A, b: B) => boolean;
  */
 declare function createCustomEqual<Meta = undefined>(options?: CustomEqualCreatorOptions<Meta>): <A, B>(a: A, b: B) => boolean;
 
-export { circularDeepEqual, circularShallowEqual, createCustomEqual, deepEqual, sameValueEqual, sameValueZeroEqual, shallowEqual, strictCircularDeepEqual, strictCircularShallowEqual, strictDeepEqual, strictShallowEqual };
-export type { AnyEqualityComparator, Cache, CircularState, ComparatorConfig, CreateCustomComparatorConfig, CreateState, CustomEqualCreatorOptions, DefaultState, Dictionary, EqualityComparator, EqualityComparatorCreator, InternalEqualityComparator, PrimitiveWrapper, State, TypeEqualityComparator, TypedArray };
+export { circularDeepEqual, circularShallowEqual, createCustomEqual, deepEqual, sameValueEqual, sameValueZeroEqual, shallowEqual, strictCircularDeepEqual, strictCircularShallowEqual, strictDeepEqual, strictEqual, strictShallowEqual };
+export type { Cache, ComparatorConfig, CustomEqualCreatorOptions, EqualityComparator, InternalEqualityComparator, PrimitiveWrapper, State, TypedArray };

package/package.json

@@ -7,7 +7,7 @@
   "bugs": {
     "url": "https://github.com/planttheidea/fast-equals/issues"
   },
-  "description": "A blazing fast equality comparison, either shallow or deep",
+  "description": "A blazing-fast equality comparison utility for a variety of use-cases",
   "devDependencies": {
     "@planttheidea/build-tools": "^2.0.0",
     "@types/lodash": "^4.17.21",
@@ -17,7 +17,7 @@
     "@types/react-dom": "^19.2.3",
     "@typescript-eslint/eslint-plugin": "^8.50.0",
     "@typescript-eslint/parser": "^8.50.0",
-    "@vitest/coverage-v8": "^4.0.15",
+    "@vitest/coverage-v8": "^4.0.16",
     "cli-table3": "^0.6.5",
     "decircularize": "^1.0.0",
     "deep-eql": "^5.0.2",
@@ -42,7 +42,7 @@
     "typescript-eslint": "^8.50.0",
     "underscore": "^1.13.7",
     "vite": "^7.3.0",
-    "vitest": "^4.0.15"
+    "vitest": "^4.0.16"
   },
   "engines": {
     "node": ">=6.0.0"
@@ -109,5 +109,5 @@
   "sideEffects": false,
   "type": "module",
   "types": "./index.d.ts",
-  "version": "6.0.0-rc.1"
+  "version": "6.0.0"
 }