deeper
deeper
is a library for structurally comparing the equality of JavaScript
values. It supports recursive / cyclical data structures, is written to avoid
try / catch / throw (for speed), and has no dependencies by default.
If you're running Node 0.12+ or io.js, deeper
will use the built-in
Buffer.equals()
. If you're running an older version of Node and you install
Ben Noordhuis's
buffertools into a project
using deeper
, it will use that to speed up comparison of Buffers. This used
to be installed as an optional dependency, but it gets in the way of
browserification and also makes using deeper
in your own projects harder, so
I changed it to just try to use it if it's there.
It has some optimizations, but stresses correctness over raw speed (unless
you're testing objects with lots of Buffers attached to them, in which case it
plus buffertools
is likely to be the fastest general-purpose deep-comparison
tool available).
The core algorithm is based on those used by Node's assertion library and the implementation of cycle detection in isEqual in Underscore.js.
I like to think the documentation is pretty OK.
installation
npm install deeper
usage
// vanillavar deepEqual = if ! console;
details
Copied from the source, here are the details of deeper
's algorithm:
===
only tests objects and functions by reference.null
is an object. Any pairs of identical entities failing this test are therefore objects (includingnull
), which need to be recursed into and compared attribute by attribute.- Since the only entities to get to this test must be objects, if
a
orb
is not an object, they're clearly not the same. All unfiltereda
andb
getting past this are objects (includingnull
). null
is an object, butnull === null.
All unfiltereda
andb
are non-nullObjects
.- Buffers need to be special-cased because they live partially on the wrong side of the C++ / JavaScript barrier. Still, calling this on structures that can contain Buffers is a bad idea, because they can contain multiple megabytes of data and comparing them byte-by-byte is hella expensive.
- It's much faster to compare dates by numeric value (
.getTime()
) than by lexical value. - Compare
RegExps
by their components, not the objects themselves. - Treat argumens objects like arrays. The parts of an arguments list most
people care about are the arguments themselves, not
callee
, which you shouldn't be looking at anyway. - Objects are more complex:
- Ensure that
a
andb
are on the same constructor chain. - Ensure that
a
andb
have the same number of own properties (which is whatObject.keys()
returns). - Ensure that cyclical references don't blow up the stack.
- Ensure that all the key names match (faster).
- Ensure that all of the associated values match, recursively (slower).
- Ensure that
(somewhat untested) assumptions:
- Functions are only considered identical if they unify to the same reference. To anything else is to invite the wrath of the halting problem.
- V8 is smart enough to optimize treating an Array like any other kind of object.
- Users of this function are cool with mutually recursive data structures that are otherwise identical being treated as the same.
license
BSD. Go nuts.