fast-equals 1.6.3 → 2.0.3

package/BUILD.md

@@ -0,0 +1,37 @@
+# Reproducing a build
+
+## Clone version
+
+```
+git clone https://github.com/planttheidea/fast-equals.git
+cd fast-equals
+git checkout {version}
+```
+
+Replace `{version}` above with the appropriate package version. If you want to compare a version older than `1.6.2`, you'll need to use a commit hash directly.
+
+## Install
+
+```
+yarn install
+```
+
+We use `yarn` for our package management, so to ensure that exact dependencies you should also use it.
+
+## Build artifacts
+
+```
+yarn run build
+```
+
+**NOTE**: To get an exact checksum match with the versions released on npm, it may be necessary to change line endings. For example, on Linux you might run:
+
+```
+unix2dos dist/fast-equals.min.js
+```
+
+## Get checksum
+
+```
+sha256sum dist/fast-equals.min.js
+```

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # fast-equals CHANGELOG
 
+## 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
+
+- There are longer `fast-equals/es`, `fast-equals/lib`, `fast-equals/mjs` locations
+  - Instead, there are 3 builds in `dist` for different consumption types:
+    - `fast-equals.js` (UMD / `browser`)
+    - `fast-equals.esm.js` (ESM / `module`)
+    - `fast-equals.cjs.js` (CommonJS / `main`)
+- 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
+
+- Rewritten completely in TypeScript
+- Improve speed of `Map` / `Set` comparisons
+- Improve speed of React element comparisons
+
+#### Fixes
+
+- Consider pure objects (`Object.create(null)`) to be plain objects
+- Fix typings for `createCustomEqual`
+
 ## 1.6.3
 
 - Check the size of the iterable before converting to arrays

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,69 +19,62 @@ Starting with version `1.5.0`, circular objects are supported for both deep and
 
 ## Table of contents
 
-- [Usage](#usage)
-- [Importing](#importing)
-- [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)
+      - [shallowEqual](#shallowequal)
+      - [sameValueZeroEqual](#samevaluezeroequal)
+      - [circularDeepEqual](#circulardeepequal)
+      - [circularShallowEqual](#circularshallowequal)
+      - [createCustomEqual](#createcustomequal)
+  - [Benchmarks](#benchmarks)
+  - [Development](#development)
 
 ## Usage
 
-You can either import the full object:
+You can either import the individual functions desired:
 
 ```javascript
-import fe from "fast-equals";
+import { deepEqual } from 'fast-equals';
 
-console.log(fe.deep({ foo: "bar" }, { foo: "bar" })); // true
+console.log(deepEqual({ foo: 'bar' }, { foo: 'bar' })); // true
 ```
 
-Or the individual imports desired:
+Or if you want to import all functions under a namespace:
 
 ```javascript
-import { deepEqual } from "fast-equals";
+import * as fe from 'fast-equals';
 
-console.log(deepEqual({ foo: "bar" }, { foo: "bar" })); // true
+console.log(fe.deep({ foo: 'bar' }, { foo: 'bar' })); // true
 ```
 
-## Importing
+#### Specific builds
 
-ESM in browsers:
+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:
 
-```javascript
-import fe from "fast-equals";
-```
+- ESM => `fast-equals/dist/fast-equals.esm.js`
+  - For older `nodejs` versions that do not allow ESM with file extensions other than `.mjs` => `fast-equals/dist/fast-equals.mjs`
+- CommonJS => `fast-equals/dist/fast-equals.cjs.js`
+- UMD => `fast-equals/dist/fast-equals.js`
 
-ESM in NodeJS:
+There is also a pre-minified version of the UMD build available:
 
-```javascript
-import fe from "fast-equals/mjs";
-```
-
-CommonJS:
-
-```javascript
-const fe = require("fast-equals").default;
-```
+- Minified UMD => `fast-equals/dist/fast-equals.min.js`
 
 ## Available methods
 
 #### deepEqual
 
-_Aliased on the default export as `fe.deep`_
-
 Performs a deep equality comparison on the two objects passed and returns a boolean representing the value equivalency of the objects.
 
 ```javascript
-import { deepEqual } from "fast-equals";
+import { deepEqual } from 'fast-equals';
 
-const objectA = { foo: { bar: "baz" } };
-const objectB = { foo: { bar: "baz" } };
+const objectA = { foo: { bar: 'baz' } };
+const objectB = { foo: { bar: 'baz' } };
 
 console.log(objectA === objectB); // false
 console.log(deepEqual(objectA, objectB)); // true
@@ -89,18 +82,16 @@ console.log(deepEqual(objectA, objectB)); // true
 
 #### shallowEqual
 
-_Aliased on the default export as `fe.shallow`_
-
 Performs a shallow equality comparison on the two objects passed and returns a boolean representing the value equivalency of the objects.
 
 ```javascript
-import { shallowEqual } from "fast-equals";
+import { shallowEqual } from 'fast-equals';
 
-const nestedObject = { bar: "baz" };
+const nestedObject = { bar: 'baz' };
 
 const objectA = { foo: nestedObject };
 const objectB = { foo: nestedObject };
-const objectC = { foo: { bar: "baz" } };
+const objectC = { foo: { bar: 'baz' } };
 
 console.log(objectA === objectB); // false
 console.log(shallowEqual(objectA, objectB)); // true
@@ -109,18 +100,16 @@ console.log(shallowEqual(objectA, objectC)); // false
 
 #### sameValueZeroEqual
 
-_Aliased on the default export as `fe.sameValueZero`_
-
 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`.
 
 ```javascript
-import { sameValueZeroEqual } from "fast-equals";
+import { sameValueZeroEqual } from 'fast-equals';
 
-const mainObject = { foo: NaN, bar: "baz" };
+const mainObject = { foo: NaN, bar: 'baz' };
 
-const objectA = "baz";
+const objectA = 'baz';
 const objectB = NaN;
-const objectC = { foo: NaN, bar: "baz" };
+const objectC = { foo: NaN, bar: 'baz' };
 
 console.log(sameValueZeroEqual(mainObject.bar, objectA)); // true
 console.log(sameValueZeroEqual(mainObject.foo, objectB)); // true
@@ -129,8 +118,6 @@ console.log(sameValueZeroEqual(mainObject, objectC)); // false
 
 #### circularDeepEqual
 
-_Aliased on the default export as `fe.circularDeep`_
-
 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.
 
 ```javascript
@@ -138,71 +125,71 @@ function Circular(value) {
   this.me = {
     deeply: {
       nested: {
-        reference: this
-      }
+        reference: this,
+      },
     },
-    value
+    value,
   };
 }
 
-console.log(circularDeepEqual(new Circular("foo"), new Circular("foo"))); // true
-console.log(circularDeepEqual(new Circular("foo"), new Circular("bar"))); // false
+console.log(circularDeepEqual(new Circular('foo'), new Circular('foo'))); // true
+console.log(circularDeepEqual(new Circular('foo'), new Circular('bar'))); // false
 ```
 
 #### circularShallowEqual
 
-_Aliased on the default export as `fe.circularShallow`_
-
 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.
 
 ```javascript
-const array = ["foo"];
+const array = ['foo'];
 
 array.push(array);
 
-console.log(circularShallowEqual(array, ["foo", array])); // true
+console.log(circularShallowEqual(array, ['foo', array])); // true
 console.log(circularShallowEqual(array, [array])); // false
 ```
 
 #### createCustomEqual
 
-_Aliased on the default export as `fe.createCustom`_
-
 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.
 
 The signature is as follows:
 
-```javascript
-createCustomEqual(deepEqual: function) => (objectA: any, objectB: any, meta: any) => boolean;
+```typescript
+type EqualityComparator = (a: any, b: any, meta?: any) => boolean;
+type EqualityComparatorCreator = (
+  deepEqual: EqualityComparator,
+) => EqualityComparator;
+
+function createCustomEqual(
+  createIsEqual?: EqualityComparatorCreator,
+): EqualityComparator;
 ```
 
-The `meta` parameter 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` 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.
 
 An example for a custom equality comparison that also checks against values in the meta object:
 
 ```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)
-    );
-  };
-});
+import { createCustomEqual } from 'fast-equals';
+
+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";
+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.0`, 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`
@@ -215,30 +202,31 @@ All benchmarks were performed on an i7 8-core Arch Linux laptop with 16GB of mem
 
 |                            | Operations / second |
 | -------------------------- | ------------------- |
-| **fast-equals**            | **148,083**         |
-| nano-equal                 | 114,146             |
-| shallow-equal-fuzzy        | 99,097              |
-| fast-deep-equal            | 98,452              |
-| react-fast-compare         | 96,650              |
-| **fast-equals (circular)** | **80,575**          |
-| underscore.isEqual         | 62,572              |
-| deep-equal                 | 47,260              |
-| lodash.isEqual             | 24,315              |
-| deep-eql                   | 23,962              |
-| assert.deepStrictEqual     | 1,370               |
+| **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):
 
-- `nano-equal` does not strictly compare object property structure, array length, or object type, nor `SameValueZero` equality for dates
-- `shallow-equal-fuzzy` does not strictly compare object type or regexp values, nor `SameValueZero` equality for dates
+- `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
 - `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
+- `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
-- `deep-equal` does not support `NaN` and does not strictly compare object type, or date / regexp values, nor uses `SameValueZero` equality for dates
-- `deep-eql` does not support `SameValueZero` equality for zero equality (positive and negative zero are not equal)
-- `assert.deepStrictEqual` does not support `NaN` or `SameValueZero` equality for 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 `lodash` 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
 
@@ -246,12 +234,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 `clean:dist`, `clean:es`, `clean:mjs`, and `clean:lib` scripts
-- clean:dist => run `rimraf` on the `dist` folder
-- clean:es => run `rimraf` on the `es` folder
-- clean:lib => run `rimraf` on the `lib` folder
-- clean:mjs => run `rimraf` on the `mjs` folder
-- copy:mjs => copy all files from `es` folder to `mjs` folder (for node ESM consumption)
+- clean => run `rimraf` on the `dist` folder
 - dev => start webpack playground App
 - dist => run `build`
 - lint => run ESLint on all files in `src` folder (also runs on `dev` script)
@@ -261,5 +244,3 @@ Standard practice, clone the repo and `npm i` to get the dependencies. The follo
 - 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
-- transpile:es => run Babel on all files, in `src` folder (transpiled to `es` folder without transpilation of ES2015 export syntax)
-- transpile:lib => run Babel on all files in `src` folder (transpiled to `lib` folder)