fast-equals 5.3.3-beta.1 → 5.3.4

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 Tony Quetano
+Copyright (c) 2025 Tony Quetano
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -4,7 +4,9 @@
 <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 (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.
 
 The following types are handled out-of-the-box:
 
@@ -18,7 +20,9 @@ The following types are handled out-of-the-box:
 - 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.
+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
 
@@ -53,20 +57,23 @@ 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:
+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).
+If you are having issues loading a specific build type,
+[please file an issue](https://github.com/planttheidea/fast-equals/issues).
 
 ## Available methods
 
 ### deepEqual
 
-Performs a deep equality comparison on the two objects passed and returns a boolean representing the value equivalency of the objects.
+Performs a deep equality comparison on the two objects passed and returns a boolean representing the value equivalency
+of the objects.
 
 ```ts
 import { deepEqual } from 'fast-equals';
@@ -80,7 +87,9 @@ console.log(deepEqual(objectA, objectB)); // true
 
 #### Comparing `Map`s
 
-`Map` objects support complex keys (objects, Arrays, etc.), however [the spec for key lookups in `Map` are based on `SameZeroValue`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map#key_equality). If the spec were followed for comparison, the following would always be `false`:
+`Map` objects support complex keys (objects, Arrays, etc.), however
+[the spec for key lookups in `Map` are based on `SameZeroValue`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map#key_equality).
+If the spec were followed for comparison, the following would always be `false`:
 
 ```ts
 const mapA = new Map([[{ foo: 'bar' }, { baz: 'quz' }]]);
@@ -89,11 +98,13 @@ const mapB = new Map([[{ foo: 'bar' }, { baz: 'quz' }]]);
 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`.
+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`.
 
 ### shallowEqual
 
-Performs a shallow equality comparison on the two objects passed and returns a boolean representing the value equivalency of the objects.
+Performs a shallow equality comparison on the two objects passed and returns a boolean representing the value
+equivalency of the objects.
 
 ```ts
 import { shallowEqual } from 'fast-equals';
@@ -111,7 +122,9 @@ console.log(shallowEqual(objectA, objectC)); // false
 
 ### sameValueZeroEqual
 
-Performs a [`SameValueZero`](http://ecma-international.org/ecma-262/7.0/#sec-samevaluezero) comparison on the two objects passed and returns a boolean representing the value equivalency of the objects. In simple terms, this means either strictly equal or both `NaN`.
+Performs a [`SameValueZero`](http://ecma-international.org/ecma-262/7.0/#sec-samevaluezero) comparison on the two
+objects passed and returns a boolean representing the value equivalency of the objects. In simple terms, this means
+either strictly equal or both `NaN`.
 
 ```ts
 import { sameValueZeroEqual } from 'fast-equals';
@@ -129,7 +142,8 @@ console.log(sameValueZeroEqual(mainObject, objectC)); // false
 
 ### circularDeepEqual
 
-Performs the same comparison as `deepEqual` but supports circular objects. It is slower than `deepEqual`, so only use if you know circular objects are present.
+Performs the same comparison as `deepEqual` but supports circular objects. It is slower than `deepEqual`, so only use if
+you know circular objects are present.
 
 ```ts
 function Circular(value) {
@@ -151,7 +165,8 @@ Just as with `deepEqual`, [both keys and values are compared for deep equality](
 
 ### circularShallowEqual
 
-Performs the same comparison as `shallowequal` but supports circular objects. It is slower than `shallowEqual`, so only use if you know circular objects are present.
+Performs the same comparison as `shallowequal` but supports circular objects. It is slower than `shallowEqual`, so only
+use if you know circular objects are present.
 
 ```ts
 const array = ['foo'];
@@ -245,7 +260,8 @@ console.log(circularDeepEqual(first, new Circular('foo'))); // false
 
 ### strictCircularShallowEqual
 
-Performs the same comparison as `circularShallowEqual` but performs a strict comparison of the objects. In this includes:
+Performs the same comparison as `circularShallowEqual` but performs a strict comparison of the objects. In this
+includes:
 
 - Checking non-enumerable properties in object comparisons
 - Checking full descriptor of properties on the object to match
@@ -268,7 +284,9 @@ console.log(circularShallowEqual(array, ['foo', array])); // false
 
 ### createCustomEqual
 
-Creates a custom equality comparator that will be used on nested values in the object. Unlike `deepEqual` and `shallowEqual`, this is a factory method that receives the default options used internally, and allows you to override the defaults as needed. This is generally for extreme edge-cases, or supporting legacy environments.
+Creates a custom equality comparator that will be used on nested values in the object. Unlike `deepEqual` and
+`shallowEqual`, this is a factory method that receives the default options used internally, and allows you to override
+the defaults as needed. This is generally for extreme edge-cases, or supporting legacy environments.
 
 The signature is as follows:
 
@@ -286,10 +304,7 @@ interface ComparatorConfig<Meta> {
   areFunctionsEqual: TypeEqualityComparator<(...args: any[]) => any, Meta>;
   areMapsEqual: TypeEqualityComparator<Map<any, any>, Meta>;
   areObjectsEqual: TypeEqualityComparator<Record<string, any>, Meta>;
-  arePrimitiveWrappersEqual: TypeEqualityComparator<
-    boolean | string | number,
-    Meta
-  >;
+  arePrimitiveWrappersEqual: TypeEqualityComparator<boolean | string | number, Meta>;
   areRegExpsEqual: TypeEqualityComparator<RegExp, Meta>;
   areSetsEqual: TypeEqualityComparator<Set<any>, Meta>;
   areTypedArraysEqual: TypeEqualityComparator<TypedArray, Meta>;
@@ -299,36 +314,33 @@ interface ComparatorConfig<Meta> {
 
 function createCustomEqual<Meta>(options: {
   circular?: boolean;
-  createCustomConfig?: (
-    defaultConfig: ComparatorConfig<Meta>,
-  ) => Partial<ComparatorConfig<Meta>>;
+  createCustomConfig?: (defaultConfig: ComparatorConfig<Meta>) => Partial<ComparatorConfig<Meta>>;
   createInternalComparator?: (
     compare: <A, B>(a: A, b: B, state: State<Meta>) => boolean,
-  ) => (
-    a: any,
-    b: any,
-    indexOrKeyA: any,
-    indexOrKeyB: any,
-    parentA: any,
-    parentB: any,
-    state: State<Meta>,
-  ) => boolean;
+  ) => (a: any, b: any, indexOrKeyA: any, indexOrKeyB: any, parentA: any, parentB: any, state: State<Meta>) => boolean;
   createState?: () => { cache?: Cache; meta?: Meta };
   strict?: 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).
+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).
 
-_**NOTE**: `Map` implementations compare equality for both keys and value. When using a custom comparator and comparing equality of the keys, the iteration index is provided as both `indexOrKeyA` and `indexOrKeyB` to help use-cases where ordering of keys matters to equality._
+_**NOTE**: `Map` implementations compare equality for both keys and value. When using a custom comparator and comparing
+equality of the keys, the iteration index is provided as both `indexOrKeyA` and `indexOrKeyB` to help use-cases where
+ordering of keys matters to equality._
 
 #### unknownTagComparators
 
-If you want to compare objects that have a custom `@@toStringTag`, you can provide a map of the custom tags you want to support via the `unknownTagComparators` option. See [this recipe]('./recipes/special-objects.md) for an example.
+If you want to compare objects that have a custom `@@toStringTag`, you can provide a map of the custom tags you want to
+support via the `unknownTagComparators` option. See [this recipe]('./recipes/special-objects.md) for an example.
 
 #### Recipes
 
-Some recipes have been created to provide examples of use-cases for `createCustomEqual`. Even if not directly applicable to the problem you are solving, they can offer guidance of how to structure your solution.
+Some recipes have been created to provide examples of use-cases for `createCustomEqual`. Even if not directly applicable
+to the problem you are solving, they can offer guidance of how to structure your solution.
 
 - [Legacy environment support for `RegExp` comparators](./recipes/legacy-regexp-support.md)
 - [Explicit property check](./recipes/explicit-property-check.md)
@@ -340,7 +352,8 @@ Some recipes have been created to provide examples of use-cases for `createCusto
 
 ## Benchmarks
 
-All benchmarks were performed on an i9-11900H Ubuntu Linux 24.04 laptop with 64GB of memory using NodeJS version `20.17.0`, 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 24.04 laptop with 64GB of memory using NodeJS version
+`20.17.0`, and are based on averages of running comparisons based deep equality on the following object types:
 
 - Primitives (`String`, `Number`, `null`, `undefined`)
 - `Function`
@@ -353,60 +366,98 @@ All benchmarks were performed on an i9-11900H Ubuntu Linux 24.04 laptop with 64G
 
 ```bash
 Testing mixed objects equal...
-┌─────────┬─────────────────────────────────┬────────────────┐
-│ (index) │ Package                         │ Ops/sec        │
-├─────────┼─────────────────────────────────┼────────────────┤
-│ 0       │ 'fast-equals'                   │ 1256867.529926 │
-│ 1       │ 'fast-deep-equal'               │ 1207041.997437 │
-│ 2       │ 'shallow-equal-fuzzy'           │ 1142536.391324 │
-│ 3       │ 'react-fast-compare'            │ 1140373.249605 │
-│ 4       │ 'dequal/lite'                   │ 708240.354044  │
-│ 5       │ 'dequal'                        │ 704655.931143  │
-│ 6       │ 'fast-equals (circular)'        │ 595853.718756  │
-│ 7       │ 'underscore.isEqual'            │ 433596.570863  │
-│ 8       │ 'assert.deepStrictEqual'        │ 310595.198662  │
-│ 9       │ 'lodash.isEqual'                │ 232192.454526  │
-│ 10      │ 'fast-equals (strict)'          │ 175941.250843  │
-│ 11      │ 'fast-equals (strict circular)' │ 154606.328398  │
-│ 12      │ 'deep-eql'                      │ 136052.484375  │
-│ 13      │ 'deep-equal'                    │ 854.061311     │
-└─────────┴─────────────────────────────────┴────────────────┘
+┌────────────────────────────────────────┬────────────────┐
+│ Name                                   │ Ops / sec      │
+├────────────────────────────────────────┼────────────────┤
+│ fast-equals (passed)                   │ 1407749.173253 │
+├────────────────────────────────────────┼────────────────┤
+│ fast-deep-equal (passed)               │ 1280048.665876 │
+├────────────────────────────────────────┼────────────────┤
+│ react-fast-compare (passed)            │ 1246487.311854 │
+├────────────────────────────────────────┼────────────────┤
+│ shallow-equal-fuzzy (passed)           │ 1214706.618885 │
+├────────────────────────────────────────┼────────────────┤
+│ nano-equal (failed)                    │ 940867.156604  │
+├────────────────────────────────────────┼────────────────┤
+│ dequal/lite (passed)                   │ 761363.455047  │
+├────────────────────────────────────────┼────────────────┤
+│ dequal (passed)                        │ 750171.073217  │
+├────────────────────────────────────────┼────────────────┤
+│ fast-equals (circular) (passed)        │ 737965.55573   │
+├────────────────────────────────────────┼────────────────┤
+│ underscore.isEqual (passed)            │ 483891.274261  │
+├────────────────────────────────────────┼────────────────┤
+│ assert.deepStrictEqual (passed)        │ 453773.568213  │
+├────────────────────────────────────────┼────────────────┤
+│ lodash.isEqual (passed)                │ 286143.874795  │
+├────────────────────────────────────────┼────────────────┤
+│ fast-equals (strict) (passed)          │ 210515.955319  │
+├────────────────────────────────────────┼────────────────┤
+│ fast-equals (strict circular) (passed) │ 182784.610131  │
+├────────────────────────────────────────┼────────────────┤
+│ deep-eql (passed)                      │ 158366.491816  │
+├────────────────────────────────────────┼────────────────┤
+│ deep-equal (passed)                    │ 918.529727     │
+└────────────────────────────────────────┴───────────────
 
 Testing mixed objects not equal...
-┌─────────┬─────────────────────────────────┬────────────────┐
-│ (index) │ Package                         │ Ops/sec        │
-├─────────┼─────────────────────────────────┼────────────────┤
-│ 0       │ 'fast-equals'                   │ 3795307.779634 │
-│ 1       │ 'fast-deep-equal'               │ 2987150.35694  │
-│ 2       │ 'react-fast-compare'            │ 2733075.404272 │
-│ 3       │ 'fast-equals (circular)'        │ 2311547.685659 │
-│ 4       │ 'dequal/lite'                   │ 1156909.54415  │
-│ 5       │ 'dequal'                        │ 1151209.161878 │
-│ 6       │ 'fast-equals (strict)'          │ 1102248.247412 │
-│ 7       │ 'fast-equals (strict circular)' │ 1020639.089577 │
-│ 8       │ 'nano-equal'                    │ 1009557.685012 │
-│ 9       │ 'underscore.isEqual'            │ 770286.698227  │
-│ 10      │ 'lodash.isEqual'                │ 296338.570457  │
-│ 11      │ 'deep-eql'                      │ 152741.182224  │
-│ 12      │ 'assert.deepStrictEqual'        │ 20163.203513   │
-│ 13      │ 'deep-equal'                    │ 3519.448516    │
-└─────────┴─────────────────────────────────┴────────────────┘
+┌────────────────────────────────────────┬────────────────┐
+│ Name                                   │ Ops / sec      │
+├────────────────────────────────────────┼────────────────┤
+│ fast-equals (passed)                   │ 4608308.851367 │
+├────────────────────────────────────────┼────────────────┤
+│ fast-deep-equal (passed)               │ 3407711.655124 │
+├────────────────────────────────────────┼────────────────┤
+│ react-fast-compare (passed)            │ 3272226.526599 │
+├────────────────────────────────────────┼────────────────┤
+│ fast-equals (circular) (passed)        │ 3259611.548677 │
+├────────────────────────────────────────┼────────────────┤
+│ fast-equals (strict) (passed)          │ 1642777.096261 │
+├────────────────────────────────────────┼────────────────┤
+│ fast-equals (strict circular) (passed) │ 1416054.558291 │
+├────────────────────────────────────────┼────────────────┤
+│ dequal/lite (passed)                   │ 1331215.970586 │
+├────────────────────────────────────────┼────────────────┤
+│ dequal (passed)                        │ 1301010.914786 │
+├────────────────────────────────────────┼────────────────┤
+│ shallow-equal-fuzzy (failed)           │ 1205019.5157   │
+├────────────────────────────────────────┼────────────────┤
+│ nano-equal (passed)                    │ 1057016.193582 │
+├────────────────────────────────────────┼────────────────┤
+│ underscore.isEqual (passed)            │ 917363.620713  │
+├────────────────────────────────────────┼────────────────┤
+│ lodash.isEqual (passed)                │ 381357.861375  │
+├────────────────────────────────────────┼────────────────┤
+│ deep-eql (passed)                      │ 184651.960191  │
+├────────────────────────────────────────┼────────────────┤
+│ assert.deepStrictEqual (passed)        │ 20607.926681   │
+├────────────────────────────────────────┼────────────────┤
+│ deep-equal (passed)                    │ 3687.588699    │
+└────────────────────────────────────────┴────────────────┘
 ```
 
 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)`)
+- `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
+- `deep-equal` does not support `NaN` and does not strictly compare object type, or date / regexp values, nor uses
+  `SameValueZero` equality for dates
 - `fast-deep-equal` does not support `NaN` or `SameValueZero` equality for dates
-- `nano-equal` does not strictly compare object property structure, array length, or object type, nor `SameValueZero` equality for dates
-- `react-fast-compare` does not support `NaN` or `SameValueZero` equality for dates, and does not compare `function` equality
+- `nano-equal` does not strictly compare object property structure, array length, or object type, nor `SameValueZero`
+  equality for dates
+- `react-fast-compare` does not support `NaN` or `SameValueZero` equality for dates, and does not compare `function`
+  equality
 - `shallow-equal-fuzzy` does not strictly compare object type or regexp values, nor `SameValueZero` equality for dates
 - `underscore.isEqual` does not support `SameValueZero` equality for primitives or dates
 
-All of these have the potential of inflating the respective library's numbers in comparison to `fast-equals`, but it was 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.
+All of these have the potential of inflating the respective library's numbers in comparison to `fast-equals`, but it was
+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
 
@@ -415,7 +466,7 @@ Standard practice, clone the repo and `npm i` to get the dependencies. The follo
 - 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 webpack playground App
+- 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

package/dist/cjs/comparator.d.cts

@@ -0,0 +1,58 @@
+import type {
+  ComparatorConfig,
+  CreateState,
+  CustomEqualCreatorOptions,
+  EqualityComparator,
+  InternalEqualityComparator,
+} from './internalTypes.d.cts';
+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 declare function createEqualityComparator<Meta>({
+  areArraysEqual,
+  areDatesEqual,
+  areErrorsEqual,
+  areFunctionsEqual,
+  areMapsEqual,
+  areNumbersEqual,
+  areObjectsEqual,
+  arePrimitiveWrappersEqual,
+  areRegExpsEqual,
+  areSetsEqual,
+  areTypedArraysEqual,
+  areUrlsEqual,
+  unknownTagComparators,
+}: ComparatorConfig<Meta>): EqualityComparator<Meta>;
+/**
+ * Create the configuration object used for building comparators.
+ */
+export declare function createEqualityComparatorConfig<Meta>({
+  circular,
+  createCustomConfig,
+  strict,
+}: CustomEqualCreatorOptions<Meta>): ComparatorConfig<Meta>;
+/**
+ * Default equality comparator pass-through, used as the standard `isEqual` creator for
+ * use inside the built comparator.
+ */
+export declare function createInternalEqualityComparator<Meta>(
+  compare: EqualityComparator<Meta>,
+): InternalEqualityComparator<Meta>;
+/**
+ * Create the `isEqual` function used by the consuming application.
+ */
+export declare function createIsEqual<Meta>({
+  circular,
+  comparator,
+  createState,
+  equals,
+  strict,
+}: CreateIsEqualOptions<Meta>): <A, B>(a: A, b: B) => boolean;
+export {};