# fast-equals

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 ~1.8kB when minified and gzipped. The following types are handled out-of-the-box: - Plain objects (including `react` elements and `Arguments`) - Arrays - Typed Arrays - `Date` objects - `RegExp` objects - `Map` / `Set` iterables - `Promise` objects - 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. ## Table of contents - [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) - [strictDeepEqual](#strictdeepequal) - [strictShallowEqual](#strictshallowequal) - [strictCircularDeepEqual](#strictcirculardeepequal) - [strictCircularShallowEqual](#strictcircularshallowequal) - [createCustomEqual](#createcustomequal) - [Recipes](#recipes) - [Benchmarks](#benchmarks) - [Development](#development) ## Usage ```ts import { deepEqual } from 'fast-equals'; 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: - 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). ## Available methods ### deepEqual 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'; const objectA = { foo: { bar: 'baz' } }; const objectB = { foo: { bar: 'baz' } }; console.log(objectA === objectB); // false 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`: ```ts 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. ```ts import { shallowEqual } from 'fast-equals'; const nestedObject = { bar: 'baz' }; const objectA = { foo: nestedObject }; const objectB = { foo: nestedObject }; const objectC = { foo: { bar: 'baz' } }; console.log(objectA === objectB); // false console.log(shallowEqual(objectA, objectB)); // true 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`. ```ts import { sameValueZeroEqual } from 'fast-equals'; const mainObject = { foo: NaN, bar: 'baz' }; const objectA = 'baz'; const objectB = NaN; const objectC = { foo: NaN, bar: 'baz' }; console.log(sameValueZeroEqual(mainObject.bar, objectA)); // true console.log(sameValueZeroEqual(mainObject.foo, objectB)); // true 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. ```ts function Circular(value) { this.me = { deeply: { nested: { reference: this, }, }, value, }; } console.log(circularDeepEqual(new Circular('foo'), new Circular('foo'))); // true 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. ```ts const array = ['foo']; array.push(array); console.log(circularShallowEqual(array, ['foo', array])); // true console.log(circularShallowEqual(array, [array])); // false ``` ### strictDeepEqual Performs the same comparison as `deepEqual` but performs a strict comparison of the objects. In this includes: - Checking symbol properties - Checking non-enumerable properties in object comparisons - Checking full descriptor of properties on the object to match - Checking non-index properties on arrays - Checking non-key properties on `Map` / `Set` objects ```ts const array = [{ foo: 'bar' }]; const otherArray = [{ foo: 'bar' }]; array.bar = 'baz'; otherArray.bar = 'baz'; console.log(strictDeepEqual(array, otherArray)); // true; console.log(strictDeepEqual(array, [{ foo: 'bar' }])); // false; ``` ### strictShallowEqual Performs the same comparison as `shallowEqual` 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 - Checking non-index properties on arrays - Checking non-key properties on `Map` / `Set` objects ```ts const array = ['foo']; const otherArray = ['foo']; array.bar = 'baz'; otherArray.bar = 'baz'; console.log(strictDeepEqual(array, otherArray)); // true; console.log(strictDeepEqual(array, ['foo'])); // false; ``` ### strictCircularDeepEqual Performs the same comparison as `circularDeepEqual` but performs a strict comparison of the objects. In this includes: - Checking `Symbol` properties on the object - Checking non-enumerable properties in object comparisons - Checking full descriptor of properties on the object to match - Checking non-index properties on arrays - Checking non-key properties on `Map` / `Set` objects ```ts function Circular(value) { this.me = { deeply: { nested: { reference: this, }, }, value, }; } const first = new Circular('foo'); Object.defineProperty(first, 'bar', { enumerable: false, value: 'baz', }); const second = new Circular('foo'); Object.defineProperty(second, 'bar', { enumerable: false, value: 'baz', }); console.log(circularDeepEqual(first, second)); // true 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: - Checking non-enumerable properties in object comparisons - Checking full descriptor of properties on the object to match - Checking non-index properties on arrays - Checking non-key properties on `Map` / `Set` objects ```ts const array = ['foo']; const otherArray = ['foo']; array.push(array); otherArray.push(otherArray); array.bar = 'baz'; otherArray.bar = 'baz'; console.log(circularShallowEqual(array, otherArray)); // true 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. The signature is as follows: ```ts interface Cache { delete(key: Key): boolean; get(key: Key): Value | undefined; set(key: Key, value: any): any; } interface ComparatorConfig { areArraysEqual: TypeEqualityComparator; areDatesEqual: TypeEqualityComparator; areMapsEqual: TypeEqualityComparator, Meta>; areObjectsEqual: TypeEqualityComparator, Meta>; arePrimitiveWrappersEqual: TypeEqualityComparator< boolean | string | number, Meta >; areRegExpsEqual: TypeEqualityComparator; areSetsEqual: TypeEqualityComparator, Meta>; areTypedArraysEqual: TypeEqualityComparatory; } function createCustomEqual(options: { circular?: boolean; createCustomConfig?: ( defaultConfig: ComparatorConfig, ) => Partial>; createInternalComparator?: ( compare: (a: A, b: B, state: State) => boolean, ) => ( a: any, b: any, indexOrKeyA: any, indexOrKeyB: any, parentA: any, parentB: any, state: State, ) => boolean; createState?: () => { cache?: Cache; meta?: Meta }; strict?: boolean; }): (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). _**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._ #### 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. - [Legacy environment support for `RegExp` comparators](./recipes/legacy-regexp-support.md) - [Explicit property check](./recipes/explicit-property-check.md) - [Using `meta` in comparison](./recipes//using-meta-in-comparison.md) - [Comparing non-standard properties](./recipes/non-standard-properties.md) - [Strict property descriptor comparison](./recipes/strict-property-descriptor-check.md) - [Legacy environment support for circualr equal comparators](./recipes/legacy-circular-equal-support.md) ## Benchmarks All benchmarks were performed on an i9-11900H Ubuntu Linux 22.04 laptop with 64GB of memory using NodeJS version `16.14.2`, and are based on averages of running comparisons based deep equality on the following object types: - Primitives (`String`, `Number`, `null`, `undefined`) - `Function` - `Object` - `Array` - `Date` - `RegExp` - `react` elements - A mixed object with a combination of all the above types ```bash Testing mixed objects equal... ┌─────────┬─────────────────────────────────┬────────────────┐ │ (index) │ Package │ Ops/sec │ ├─────────┼─────────────────────────────────┼────────────────┤ │ 0 │ 'fast-equals' │ 1249567.730326 │ │ 1 │ 'fast-deep-equal' │ 1182463.587514 │ │ 2 │ 'react-fast-compare' │ 1152487.319161 │ │ 3 │ 'shallow-equal-fuzzy' │ 1092360.712389 │ │ 4 │ 'fast-equals (circular)' │ 676669.92003 │ │ 5 │ 'underscore.isEqual' │ 429430.837497 │ │ 6 │ 'lodash.isEqual' │ 237915.684734 │ │ 7 │ 'fast-equals (strict)' │ 181386.38032 │ │ 8 │ 'fast-equals (strict circular)' │ 156779.745875 │ │ 9 │ 'deep-eql' │ 139155.099209 │ │ 10 │ 'deep-equal' │ 1026.527229 │ └─────────┴─────────────────────────────────┴────────────────┘ Testing mixed objects not equal... ┌─────────┬─────────────────────────────────┬────────────────┐ │ (index) │ Package │ Ops/sec │ ├─────────┼─────────────────────────────────┼────────────────┤ │ 0 │ 'fast-equals' │ 3255824.097237 │ │ 1 │ 'react-fast-compare' │ 2654721.726058 │ │ 2 │ 'fast-deep-equal' │ 2582218.974752 │ │ 3 │ 'fast-equals (circular)' │ 2474303.26566 │ │ 4 │ 'fast-equals (strict)' │ 1088066.604881 │ │ 5 │ 'fast-equals (strict circular)' │ 949253.614181 │ │ 6 │ 'nano-equal' │ 939170.554148 │ │ 7 │ 'underscore.isEqual' │ 738852.197879 │ │ 8 │ 'lodash.isEqual' │ 307306.622212 │ │ 9 │ 'deep-eql' │ 156250.110401 │ │ 10 │ 'assert.deepStrictEqual' │ 22839.454561 │ │ 11 │ 'deep-equal' │ 4034.45114 │ └─────────┴─────────────────────────────────┴────────────────┘ ``` 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)`) - `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 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 Standard practice, clone the repo and `npm i` to get the dependencies. The following npm scripts are available: - 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 - 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 - prepublish:compile => run `lint`, `test:coverage`, `transpile:lib`, `transpile:es`, and `dist` scripts - start => run `dev` - 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

	Stars	Issues	Version	Updated	Created
check-equal	4	1	1.0.7	3 years ago	4 years ago
fast-deep-equal	1,705	27	3.1.3	3 years ago	6 years ago
fast-equals	356	0	5.0.1	2 months ago	6 years ago
lodash.isequal	56,419	507	4.5.0	6 years ago	10 years ago

check-equal vs fast-deep-equal vs fast-equals vs lodash.isequal

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Sick of boring JavaScript newsletters?

Downloads in past