muggle-deep-equal

muggle-deep-equal

A simple and generic implementation of deep equal using Iterables.

Used in muggle-assert, the assertion library for muggle

Goals

• Generic and predictable behavior
• Simple and readable source code
• Fully tested

Installation

$ npm install muggle-deep-equal

Example

const deepEqual = require('muggle-deep-equal')

// primitives are compared with ===
deepEqual('penguin', 'penguin') // returns true
deepEqual(100, 50) // returns false
deepEqual(1, true) // returns false

deepEqual([1, 2, 3, 4], [1, 2, 3, 4]) // returns true

deepEqual(
  {
    array: [1, 2, 3],
    object: {
      animal: 'penguin'
    }
  },
  {
    array: [1, 2, 3],
    object: {
      animal: 'penguin'
    }
  }
) // returns true

// if either string or array was different, deepEqual would return false

What's deep equal?

If two objects are deeply equal, then their actual data are equal rather than just their reference. It's useful for comparing separate instances of arrays and objects for example.

In muggle-deep-equal, equality is determined by these rules (in order):

1. If either value is a primitive, then equality is determined using strict equality ===

• String, Number, Boolean, Function, Symbol, undefined, or null
• NaN is considered equal to NaN

2. Both objects must have the same class.

• object1.constructor.name === object2.constructor.name

3. If either object is an Iterable, then equality is determined by checking that both contain the same values in the same order.

• Values are compared by applying these deep equal rules recursively.
• Every index is compared 1 at a time in order using the iterator protocol
• Rules #4 and #5 aren't applied to iterables

4. Both objects must have the same properties and values.

• Compared by applying these deep equal rules recursively on every value using a for...in loop

5. Both objects must return the same string representation from object.toString()

• This allows many other objects to be compared as expected such as Error, Date, and RegExp