fast-equals

What is fast-equals?

The fast-equals package is a high-performance deep equality checking library that provides functions to determine if two values are deeply equal. It is optimized for speed and can handle complex data structures, including objects, arrays, dates, and more.

What are fast-equals's main functionalities?

deepEqual

Checks if two values are deeply equal, meaning all their nested properties are equal.

const { deepEqual } = require('fast-equals');
console.log(deepEqual({ foo: 'bar' }, { foo: 'bar' })); // true

shallowEqual

Checks if two values are shallowly equal, meaning their immediate properties are equal without checking nested objects.

const { shallowEqual } = require('fast-equals');
console.log(shallowEqual({ foo: 'bar' }, { foo: 'bar' })); // true

circularDeepEqual

Checks if two values are deeply equal, including when they have circular references.

const { circularDeepEqual } = require('fast-equals');
const objectA = { foo: 'bar' };
objectA.self = objectA;
const objectB = { foo: 'bar' };
objectB.self = objectB;
console.log(circularDeepEqual(objectA, objectB)); // true

circularShallowEqual

Checks if two values are shallowly equal, including when they have circular references.

const { circularShallowEqual } = require('fast-equals');
const arrayA = ['foo', 'bar'];
arrayA.push(arrayA);
const arrayB = ['foo', 'bar'];
arrayB.push(arrayB);
console.log(circularShallowEqual(arrayA, arrayB)); // true

sameValueZeroEqual

Checks if two values are equal according to the SameValueZero comparison algorithm, which treats NaN as equal to NaN and -0 as equal to +0.

const { sameValueZeroEqual } = require('fast-equals');
console.log(sameValueZeroEqual(NaN, NaN)); // true

Other packages similar to fast-equals

lodash.isequal

Lodash's isEqual function is a popular utility for performing deep equality checks. It is part of the larger Lodash library, which offers a wide range of utilities for working with arrays, objects, and other data types. Compared to fast-equals, lodash.isequal may be slower but is part of a well-established utility library with a large user base.

deep-equal

The deep-equal package provides functions for deep equality checking. It is less optimized for performance compared to fast-equals but offers a simple API for checking deep equality between two values.

ramda

Ramda is a functional programming library that includes a deep equality checking function called equals. Ramda's approach is more functional and immutable compared to fast-equals, and it is designed to work well in a functional programming context.

README

fast-equals

Perform blazing fast equality comparisons (either deep or shallow) on two objects passed. It has no dependencies, and is ~1.1Kb when minified and gzipped.

Unlike most equality validation libraries, the following types are handled out-of-the-box:

• NaN
• Date objects
• RegExp objects
• Map / Set iterables

You can also create a custom nested comparator, for specific scenarios (see below).

Table of contents

• Usage
• Available methods
  • deepEqual
  • shallowEqual
  • createCustomEqual
• Benchmarks
• Development

Usage

You can either import the full object:

import fe from 'fast-equals';

console.log(fe.deep({foo: 'bar'}, {foo: 'bar'})); // true

Or the individual imports desired:

import {deepEqual} from 'fast-equals';

console.log(deepEqual({foo: 'bar'}, {foo: 'bar'})); // true

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.

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

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.

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

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.

A common use case for this is to handle circular objects (which fast-equals does not handle by default). Example:

import {createCustomEqual} from 'fast-equals';
import decircularize from 'decircularize';

const isDeepEqualCircular = createCustomEqual((comparator) => {
  return (objectA, objectB) => {
    return comparator(decircularize(objectA), decircularize(objectB));
  };
});

const objectA = {};
const objectB = {};

objectA.a = objectA;
objectA.b = objectB;

objectB.a = objectA;
objectB.b = objectB;

console.log(isDeepEqualCircular(objectA, objectB)); // true

Benchmarks

All benchmarks are based on averages of running comparisons based on the following data types:

• Primitives (String, Number, null, undefined)
• Functions
• Objects
• Arrays
• Dates
• RegExps
• A mixed object with a combination of all the above types

	Operations / second	Relative margin of error
fast-equals	190,315	0.57%
nano-equal	123,255	0.76%
fast-deep-equal	102,990	0.50%
shallow-equal-fuzzy	83,553	0.47%
underscore.isEqual	51,321	0.51%
deep-equal	32,694	0.80%
lodash.isEqual	25,872	0.59%
deep-eql	14,804	0.81%
assert.deepStrictEqual	448	1.42%

Caveats that impact the benchmark:

• fast-deep-equal does not support NaN
• nano-equal does not strictly compare object property structure, array length, or object type
• shallow-equal-fuzzy does not strictly compare object type or regexp values
• deep-equal does not support NaN and does not strictly compare object type, or date / regexp values
• assert.deepStrictEqual does not support NaN

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. Maps and Sets were excluded from the benchmark entirely because no library other than lodash supported their comparison.

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 unminified dist version with source map and NODE_ENV=development via webpack
• build:minified => build minified dist version with NODE_ENV=production via webpack
• clean => run clean:dist, clean:es, 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
• dev => start webpack playground App
• dist => run build and build:minified scripts
• lint => run ESLint on all files in src folder (also runs on dev script)
• lint:fix => run lint script, but with auto-fixer
• prepublish =>
• 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
• 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)

Changelog

1.0.3

• Make Map and Set comparisons more explicit