fast-equals 2.0.1 → 3.0.0

package/CHANGELOG.md

@@ -1,12 +1,54 @@
 # fast-equals CHANGELOG
 
+## 3.0.0
+
+### Breaking changes
+
+When creating a custom equality comparator via `createCustomEqual`, the equality method has an expanded contract:
+
+```ts
+// Before
+type EqualityComparator = (objectA: any, objectB: any, meta: any) => boolean;
+
+// After
+type InternalEqualityComparator = (
+  objectA: any,
+  objectB: any,
+  indexOrKeyA: any,
+  indexOrKeyB: any,
+  parentA: any,
+  parentB: any,
+  meta: any,
+) => boolean;
+```
+
+If you have a custom equality comparator, you can ignore the differences by just passing additional `undefined` parameters, or you can use the parameters to further improve / clarify the logic.
+
+- Add [#57](https://github.com/planttheidea/fast-equals/pull/57) - support additional metadata for custom equality comparators
+
+## 2.0.4
+
+- Fix [#58](https://github.com/planttheidea/fast-equals/issues/58) - duplicate entries in `Map` / `Set` can create false equality success
+- [#60](https://github.com/planttheidea/fast-equals/issues/60) - Add documentation for key equality of `Map` being a part of `deepEqual`
+
+## 2.0.3
+
+- Fix [#50](https://github.com/planttheidea/fast-equals/pull/50) - copy-pasta in cacheable check
+
+## 2.0.2
+
+- Optimize iterables comparisons to not double-iterate
+- Optimize loop-based comparisons for speed
+- Improve cache handling in circular handlers
+- Improve stability of memory by reducing variable instantiation
+
 ## 2.0.1
 
 - Fix [#41](https://github.com/planttheidea/fast-equals/pull/41) - prevent `.rpt2_cache` directory from being published for better CI environment support (thanks [@herberttn](https://github.com/herberttn))
 
 ## 2.0.0
 
-#### Breaking changes
+### Breaking changes
 
 - There are longer `fast-equals/es`, `fast-equals/lib`, `fast-equals/mjs` locations
   - Instead, there are 3 builds in `dist` for different consumption types:
@@ -16,13 +58,13 @@
 - There is no default export anymore, only the previously-existing named exports
   - To get all into a namespace, use `import * as fe from 'fast-equals`
 
-#### Updates
+### Updates
 
 - Rewritten completely in TypeScript
 - Improve speed of `Map` / `Set` comparisons
 - Improve speed of React element comparisons
 
-#### Fixes
+### Fixes
 
 - Consider pure objects (`Object.create(null)`) to be plain objects
 - Fix typings for `createCustomEqual`
@@ -122,3 +164,7 @@
 ## 1.0.0
 
 - Initial release
+
+```
+
+```

package/README.md

@@ -4,7 +4,7 @@
 <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. It has no dependencies, and is ~1.3kB when minified and gzipped.
+Perform [blazing fast](#benchmarks) equality comparisons (either deep or shallow) on two objects passed. It has no dependencies, and is ~1kB when minified and gzipped.
 
 Unlike most equality validation libraries, the following types are handled out-of-the-box:
 
@@ -19,17 +19,20 @@ Starting with version `1.5.0`, circular objects are supported for both deep and
 
 ## Table of contents
 
-- [Usage](#usage)
-  - [Specific builds](#specific-builds)
-- [Available methods](#available-methods)
-  - [deepEqual](#deepequal)
-  - [shallowEqual](#shallowequal)
-  - [sameValueZeroEqual](#samevaluezeroequal)
-  - [circularDeepEqual](#circulardeepequal)
-  - [circularShallowEqual](#circularshallowequal)
-  - [createCustomEqual](#createcustomequal)
-- [Benchmarks](#benchmarks)
-- [Development](#development)
+- [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)
+    - [sameValueZeroEqual](#samevaluezeroequal)
+    - [circularDeepEqual](#circulardeepequal)
+    - [circularShallowEqual](#circularshallowequal)
+    - [createCustomEqual](#createcustomequal)
+  - [Benchmarks](#benchmarks)
+  - [Development](#development)
 
 ## Usage
 
@@ -49,7 +52,7 @@ import * as fe from 'fast-equals';
 console.log(fe.deep({ foo: 'bar' }, { foo: 'bar' })); // true
 ```
 
-#### Specific builds
+### Specific builds
 
 There are three builds, an ESM build for modern build systems / runtimes, a CommonJS build for traditional NodeJS environments, and a UMD build for legacy implementations. The ideal one will likely be chosen for you automatically, however if you want to use a specific build you can always import it directly:
 
@@ -64,7 +67,7 @@ There is also a pre-minified version of the UMD build available:
 
 ## Available methods
 
-#### deepEqual
+### deepEqual
 
 Performs a deep equality comparison on the two objects passed and returns a boolean representing the value equivalency of the objects.
 
@@ -78,7 +81,20 @@ console.log(objectA === objectB); // false
 console.log(deepEqual(objectA, objectB)); // true
 ```
 
-#### shallowEqual
+#### 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`:
+
+```javascript
+const mapA = new Map([[{ foo: 'bar' }, { baz: 'quz' }]]);
+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`.
+
+### shallowEqual
 
 Performs a shallow equality comparison on the two objects passed and returns a boolean representing the value equivalency of the objects.
 
@@ -96,7 +112,7 @@ console.log(shallowEqual(objectA, objectB)); // true
 console.log(shallowEqual(objectA, objectC)); // false
 ```
 
-#### sameValueZeroEqual
+### 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`.
 
@@ -114,7 +130,7 @@ console.log(sameValueZeroEqual(mainObject.foo, objectB)); // true
 console.log(sameValueZeroEqual(mainObject, objectC)); // false
 ```
 
-#### circularDeepEqual
+### 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.
 
@@ -134,7 +150,9 @@ console.log(circularDeepEqual(new Circular('foo'), new Circular('foo'))); // tru
 console.log(circularDeepEqual(new Circular('foo'), new Circular('bar'))); // false
 ```
 
-#### circularShallowEqual
+Just as with `deepEqual`, [both keys and values are compared for deep equality](#comparing-maps).
+
+### 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.
 
@@ -147,7 +165,7 @@ console.log(circularShallowEqual(array, ['foo', array])); // true
 console.log(circularShallowEqual(array, [array])); // false
 ```
 
-#### createCustomEqual
+### createCustomEqual
 
 Creates a custom equality comparator that will be used on nested values in the object. Unlike `deepEqual` and `shallowEqual`, this is a partial-application function that will receive the internal comparator and should return a function that compares two objects.
 
@@ -155,16 +173,19 @@ The signature is as follows:
 
 ```typescript
 type EqualityComparator = (a: any, b: any, meta?: any) => boolean;
+type InternalEqualityComparator = (a: any, b: any, indexOrKeyA: any, indexOrKeyB: any, parentA: any, parentB: any, meta: any) => boolean;
 type EqualityComparatorCreator = (
   deepEqual: EqualityComparator,
-) => EqualityComparator;
+) => InternalEqualityComparator;
 
 function createCustomEqual(
   createIsEqual?: EqualityComparatorCreator,
 ): EqualityComparator;
 ```
 
-The `meta` parameter in `EqualityComparator` is whatever you want it to be. It will be passed through to all equality checks, and is meant specifically for use with custom equality methods. For example, with the `circularDeepEqual` and `circularShallowEqual` methods, it is used to pass through a cache of processed objects.
+The `meta` parameter in `EqualityComparator` and `InternalEqualityComparator` is whatever you want it to be. It will be passed through to all equality checks, and is meant specifically for use with custom equality methods. For example, with the `circularDeepEqual` and `circularShallowEqual` methods, it is used to pass through a cache of processed objects.
+
+_**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._
 
 An example for a custom equality comparison that also checks against values in the meta object:
 
@@ -172,11 +193,10 @@ An example for a custom equality comparison that also checks against values in t
 import { createCustomEqual } from 'fast-equals';
 
 const isDeepEqualOrFooMatchesMeta = createCustomEqual(
-  (deepEqual) => (objectA, objectB, meta) => (
+  (deepEqual) => (objectA, objectB, indexOrKeyA, indexOrKeyB,  parentA, parentB, meta) =>
     objectA.foo === meta ||
     objectB.foo === meta ||
-    deepEqual(objectA, objectB, meta)
-  )
+    deepEqual(objectA, objectB, meta),
 );
 
 const objectA = { foo: 'bar' };
@@ -188,7 +208,7 @@ console.log(isDeepEqualOrFooMatchesMeta(objectA, objectB, meta)); // true
 
 ## Benchmarks
 
-All benchmarks were performed on an i7 8-core Arch Linux laptop with 16GB of memory using NodeJS version `10.15.3`, and are based on averages of running comparisons based deep equality on the following object types:
+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:
 
 - Primitives (`String`, `Number`, `null`, `undefined`)
 - `Function`
@@ -201,20 +221,21 @@ All benchmarks were performed on an i7 8-core Arch Linux laptop with 16GB of mem
 
 |                            | Operations / second |
 | -------------------------- | ------------------- |
-| **fast-equals**            | **142,730**         |
-| nano-equal                 | 115,530             |
-| shallow-equal-fuzzy        | 102,633             |
-| fast-deep-equal            | 102,335             |
-| react-fast-compare         | 100,036             |
-| **fast-equals (circular)** | **79,589**          |
-| underscore.isEqual         | 63,390              |
-| deep-equal                 | 48,783              |
-| lodash.isEqual             | 24,456              |
-| deep-eql                   | 24,196              |
-| assert.deepStrictEqual     | 1,382               |
+| **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                 |
 
 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
 - `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
@@ -224,7 +245,7 @@ Caveats that impact the benchmark (and accuracy of comparison):
 - `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. `Map`s, `Promise`s, and `Set`s were excluded from the benchmark entirely because no library other than `deep-eql` fully supported their comparison. The same logic applies to `react` elements (which can be circular objects), but simple elements are non-circular objects so 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