fast-equals 2.0.0 → 2.0.4

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # fast-equals CHANGELOG
 
+## 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

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.
 
@@ -171,26 +189,23 @@ An example for a custom equality comparison that also checks against values in t
 ```javascript
 import { createCustomEqual } from 'fast-equals';
 
-const isDeepEqualOrFooMatchesMeta = createCustomEqual(deepEqual => {
-  return (objectA, objectB, meta) => {
-    return (
-      objectA.foo === meta ||
-      objectB.foo === meta ||
-      deepEqual(objectA, objectB, meta)
-    );
-  };
-});
+const isDeepEqualOrFooMatchesMeta = createCustomEqual(
+  (deepEqual) => (objectA, objectB, meta) =>
+    objectA.foo === meta ||
+    objectB.foo === meta ||
+    deepEqual(objectA, objectB, meta),
+);
 
 const objectA = { foo: 'bar' };
 const objectB = { foo: 'baz' };
 const meta = 'bar';
 
-console.log(isDeepEqualOrFooMatchesMeta(objectA, objectB)); // true
+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`
@@ -203,20 +218,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
@@ -226,7 +242,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