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 fast-deep-equal
instead.
import isShallowEqual from '@wordpress/is-shallow-equal';
import fastDeepEqual from 'fast-deep-equal/es6'; // deep comparison
let object = { a: 1 };
isShallowEqual( [ { a: 1 } ], [ { a: 1 } ] );
// ⇒ false
fastDeepEqual( [ { 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…
- …consider non-primitive yet referentially-equal members values as equal.
- Eliminates
is-equal-shallow
as an option.
- Eliminates
- …offer a single function through which to interface, regardless of value type.
- Eliminates
shallow-equal
as an option.
- Eliminates
- …be barebones; only providing the basic functionality of shallow equality.
- Eliminates
shallow-equals
as an option.
- Eliminates
- …anticipate and optimize for referential sameness as equal.
- Eliminates
is-equal-shallow
andshallow-equals
as options.
- Eliminates
- …be intended for use in non-Facebook projects.
- Eliminates
fbjs/lib/shallowEqual
as an option.
- Eliminates
- …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.