@wordpress/is-shallow-equal

What is @wordpress/is-shallow-equal?

@wordpress/is-shallow-equal is a utility package used to perform shallow equality checks between two values. It is commonly used in scenarios where you need to determine if two objects or arrays are equivalent in terms of their immediate properties or elements, without performing a deep comparison.

What are @wordpress/is-shallow-equal's main functionalities?

Shallow Equality Check for Objects

This feature allows you to check if two objects are shallowly equal, meaning their properties are the same and have the same values. The code sample demonstrates how to use the package to compare two objects.

const isShallowEqual = require('@wordpress/is-shallow-equal');

const obj1 = { a: 1, b: 2 };
const obj2 = { a: 1, b: 2 };
const obj3 = { a: 1, b: 3 };

console.log(isShallowEqual(obj1, obj2)); // true
console.log(isShallowEqual(obj1, obj3)); // false

Shallow Equality Check for Arrays

This feature allows you to check if two arrays are shallowly equal, meaning they contain the same elements in the same order. The code sample demonstrates how to use the package to compare two arrays.

const isShallowEqual = require('@wordpress/is-shallow-equal');

const arr1 = [1, 2, 3];
const arr2 = [1, 2, 3];
const arr3 = [1, 2, 4];

console.log(isShallowEqual(arr1, arr2)); // true
console.log(isShallowEqual(arr1, arr3)); // false

Other packages similar to @wordpress/is-shallow-equal

shallowequal

shallowequal is a popular package for performing shallow equality checks. It is similar to @wordpress/is-shallow-equal in functionality, providing a straightforward way to compare objects and arrays for shallow equality. It is widely used in React applications to optimize rendering by preventing unnecessary updates.

lodash.isequal

lodash.isequal is a utility from the Lodash library that performs deep equality checks. While it offers more comprehensive comparison capabilities than @wordpress/is-shallow-equal, it can be overkill for scenarios where only shallow equality is needed. It is more versatile but may have a larger footprint due to its deep comparison nature.

react-fast-compare

react-fast-compare is a fast and lightweight deep comparison library optimized for React. Although it provides deep comparison, it is often used in place of shallow equality checks when performance is critical. It differs from @wordpress/is-shallow-equal by offering deep comparison capabilities.

README

Is Shallow Equal

A function for performing a shallow comparison between two objects or arrays. Two values have shallow equality when all of their members are strictly equal to the corresponding member of the other.

Usage

The default export of @wordpress/is-shallow-equal is a function which accepts two objects or arrays:

import isShallowEqual from '@wordpress/is-shallow-equal';

isShallowEqual( { a: 1 }, { a: 1, b: 2 } );
// ⇒ false

isShallowEqual( { a: 1 }, { a: 1 } );
// ⇒ true

isShallowEqual( [ 1 ], [ 1, 2 ] );
// ⇒ false

isShallowEqual( [ 1 ], [ 1 ] );
// ⇒ true

You can import a specific implementation if you already know the types of values you are working with:

import { isShallowEqualArrays } from '@wordpress/is-shallow-equal';
import { isShallowEqualObjects } from '@wordpress/is-shallow-equal';

Shallow comparison differs from deep comparison by the fact that it compares members from each as being strictly equal to the other, meaning that arrays and objects will be compared by their references, not by their values (see also Object Equality in JavaScript.) In situations where nested objects must be compared by value, consider using Lodash's isEqual instead.

import isShallowEqual from '@wordpress/is-shallow-equal';
import { isEqual } from 'lodash'; // deep comparison

let object = { a: 1 };

isShallowEqual( [ { a: 1 } ], [ { a: 1 } ] );
// ⇒ false

isEqual( [ { a: 1 } ], [ { a: 1 } ] );
// ⇒ true

isShallowEqual( [ object ], [ object ] );
// ⇒ true

Rationale

Shallow equality utilities are already a dime a dozen. Since these operations are often at the core of critical hot code paths, the WordPress contributors had specific requirements that were found to only be partially satisfied by existing solutions.

In particular, it should…

1. …consider non-primitive yet referentially-equal members values as equal.
   • Eliminates is-equal-shallow as an option.
2. …offer a single function through which to interface, regardless of value type.
   • Eliminates shallow-equal as an option.
3. …be barebones; only providing the basic functionality of shallow equality.
   • Eliminates shallow-equals as an option.
4. …anticipate and optimize for referential sameness as equal.
   • Eliminates is-equal-shallow and shallow-equals as options.
5. …be intended for use in non-Facebook projects.
   • Eliminates fbjs/lib/shallowEqual as an option.
6. …be the most performant implementation.
   • See Benchmarks.

Benchmarks

The following results were produced under Node v10.15.3 (LTS) on a MacBook Pro (Late 2016) 2.9 GHz Intel Core i7.

@wordpress/is-shallow-equal (type specific) (object, equal) x 4,519,009 ops/sec ±1.09% (90 runs sampled) >@wordpress/is-shallow-equal (type specific) (object, same) x 795,527,700 ops/sec ±0.24% (93 runs sampled) >@wordpress/is-shallow-equal (type specific) (object, unequal) x 4,841,640 ops/sec ±0.94% (93 runs sampled) >@wordpress/is-shallow-equal (type specific) (array, equal) x 106,393,795 ops/sec ±0.16% (94 runs sampled) >@wordpress/is-shallow-equal (type specific) (array, same) x 800,741,511 ops/sec ±0.22% (95 runs sampled) >@wordpress/is-shallow-equal (type specific) (array, unequal) x 49,178,977 ops/sec ±1.99% (82 runs sampled)

@wordpress/is-shallow-equal (object, equal) x 4,449,367 ops/sec ±0.31% (91 runs sampled) >@wordpress/is-shallow-equal (object, same) x 796,677,179 ops/sec ±0.23% (94 runs sampled) >@wordpress/is-shallow-equal (object, unequal) x 4,989,529 ops/sec ±0.30% (91 runs sampled) >@wordpress/is-shallow-equal (array, equal) x 44,840,546 ops/sec ±1.18% (89 runs sampled) >@wordpress/is-shallow-equal (array, same) x 794,344,723 ops/sec ±0.24% (91 runs sampled) >@wordpress/is-shallow-equal (array, unequal) x 49,860,115 ops/sec ±1.73% (85 runs sampled)

shallowequal (object, equal) x 3,702,126 ops/sec ±0.87% (92 runs sampled) >shallowequal (object, same) x 796,649,597 ops/sec ±0.21% (92 runs sampled) >shallowequal (object, unequal) x 4,027,885 ops/sec ±0.31% (96 runs sampled) >shallowequal (array, equal) x 1,684,977 ops/sec ±0.37% (94 runs sampled) >shallowequal (array, same) x 794,287,091 ops/sec ±0.26% (91 runs sampled) >shallowequal (array, unequal) x 1,738,554 ops/sec ±0.29% (91 runs sampled)

shallow-equal (type specific) (object, equal) x 4,669,656 ops/sec ±0.34% (92 runs sampled) >shallow-equal (type specific) (object, same) x 799,610,214 ops/sec ±0.20% (95 runs sampled) >shallow-equal (type specific) (object, unequal) x 4,908,591 ops/sec ±0.49% (93 runs sampled) >shallow-equal (type specific) (array, equal) x 104,711,254 ops/sec ±0.65% (91 runs sampled) >shallow-equal (type specific) (array, same) x 798,454,281 ops/sec ±0.29% (94 runs sampled) >shallow-equal (type specific) (array, unequal) x 48,764,338 ops/sec ±1.48% (84 runs sampled)

is-equal-shallow (object, equal) x 5,068,750 ops/sec ±0.28% (92 runs sampled) >is-equal-shallow (object, same) x 17,231,997 ops/sec ±0.42% (92 runs sampled) >is-equal-shallow (object, unequal) x 5,524,878 ops/sec ±0.41% (92 runs sampled) >is-equal-shallow (array, equal) x 1,067,063 ops/sec ±0.40% (92 runs sampled) >is-equal-shallow (array, same) x 1,074,356 ops/sec ±0.20% (94 runs sampled) >is-equal-shallow (array, unequal) x 1,758,859 ops/sec ±0.44% (92 runs sampled)

shallow-equals (object, equal) x 8,380,550 ops/sec ±0.31% (90 runs sampled) >shallow-equals (object, same) x 27,583,073 ops/sec ±0.60% (91 runs sampled) >shallow-equals (object, unequal) x 8,954,268 ops/sec ±0.71% (92 runs sampled) >shallow-equals (array, equal) x 104,437,640 ops/sec ±0.22% (96 runs sampled) >shallow-equals (array, same) x 141,850,542 ops/sec ±0.25% (93 runs sampled) >shallow-equals (array, unequal) x 47,964,211 ops/sec ±1.51% (84 runs sampled)

fbjs/lib/shallowEqual (object, equal) x 3,366,709 ops/sec ±0.35% (93 runs sampled) >fbjs/lib/shallowEqual (object, same) x 794,825,194 ops/sec ±0.24% (94 runs sampled) >fbjs/lib/shallowEqual (object, unequal) x 3,612,268 ops/sec ±0.37% (94 runs sampled) >fbjs/lib/shallowEqual (array, equal) x 1,613,800 ops/sec ±0.23% (90 runs sampled) >fbjs/lib/shallowEqual (array, same) x 794,861,384 ops/sec ±0.24% (93 runs sampled) >fbjs/lib/shallowEqual (array, unequal) x 1,648,398 ops/sec ±0.77% (92 runs sampled)

You can run the benchmarks yourselves by cloning the repository, installing dependencies, and running the benchmark/index.js script:

git clone https://github.com/WordPress/gutenberg.git
npm install
npm run build:packages
node ./packages/is-shallow-equal/benchmark

Contributing to this package

This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main contributor guide.