From 407af7b31ed010e23f8654b9ff598d7a6367e021 Mon Sep 17 00:00:00 2001 From: Tony Quetano Date: Sun, 5 Dec 2021 17:38:59 -0800 Subject: [PATCH 1/3] add documentation about deep equality of keys in `Map` --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index cd3d6e8..31befe7 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ Starting with version `1.5.0`, circular objects are supported for both deep and - [Specific builds](#specific-builds) - [Available methods](#available-methods) - [deepEqual](#deepequal) + - [Note](#note) - [shallowEqual](#shallowequal) - [sameValueZeroEqual](#samevaluezeroequal) - [circularDeepEqual](#circulardeepequal) @@ -80,6 +81,19 @@ console.log(objectA === objectB); // false console.log(deepEqual(objectA, objectB)); // true ``` +##### Note + +`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. From bedfdd6a99a8faba79fe286c600e8452e6218c8d Mon Sep 17 00:00:00 2001 From: Tony Quetano Date: Sun, 5 Dec 2021 17:41:09 -0800 Subject: [PATCH 2/3] add piece in `circularDeepEqual` --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 31befe7..29ed33d 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Starting with version `1.5.0`, circular objects are supported for both deep and - [Specific builds](#specific-builds) - [Available methods](#available-methods) - [deepEqual](#deepequal) - - [Note](#note) + - [Comparing `Map`s](#comparing-maps) - [shallowEqual](#shallowequal) - [sameValueZeroEqual](#samevaluezeroequal) - [circularDeepEqual](#circulardeepequal) @@ -81,7 +81,7 @@ console.log(objectA === objectB); // false console.log(deepEqual(objectA, objectB)); // true ``` -##### Note +##### 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`: @@ -150,6 +150,8 @@ console.log(circularDeepEqual(new Circular('foo'), new Circular('foo'))); // tru console.log(circularDeepEqual(new Circular('foo'), new Circular('bar'))); // false ``` +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. From 16b8b29823bbb26c4ecbe19a48e369ee07835a7b Mon Sep 17 00:00:00 2001 From: Tony Quetano Date: Sun, 5 Dec 2021 17:41:52 -0800 Subject: [PATCH 3/3] improve hierarchy --- README.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 29ed33d..d418969 100644 --- a/README.md +++ b/README.md @@ -22,15 +22,15 @@ Starting with version `1.5.0`, circular objects are supported for both deep and - [fast-equals](#fast-equals) - [Table of contents](#table-of-contents) - [Usage](#usage) - - [Specific builds](#specific-builds) + - [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) + - [deepEqual](#deepequal) + - [Comparing `Map`s](#comparing-maps) + - [shallowEqual](#shallowequal) + - [sameValueZeroEqual](#samevaluezeroequal) + - [circularDeepEqual](#circulardeepequal) + - [circularShallowEqual](#circularshallowequal) + - [createCustomEqual](#createcustomequal) - [Benchmarks](#benchmarks) - [Development](#development) @@ -52,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: @@ -67,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. @@ -81,7 +81,7 @@ console.log(objectA === objectB); // false console.log(deepEqual(objectA, objectB)); // true ``` -##### Comparing `Map`s +#### 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`: @@ -94,7 +94,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`. -#### shallowEqual +### shallowEqual Performs a shallow equality comparison on the two objects passed and returns a boolean representing the value equivalency of the objects. @@ -112,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`. @@ -130,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. @@ -152,7 +152,7 @@ console.log(circularDeepEqual(new Circular('foo'), new Circular('bar'))); // fal Just as with `deepEqual`, [both keys and values are compared for deep equality](#comparing-maps). -#### circularShallowEqual +### 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. @@ -165,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.