deep-equal-diagnostics 3.0.0

This package provides the deepStrictEqual() function, which fully meets the specification implied by the built-in assert.deepStrictEqual(), except that NaN is strictly equal to NaN. However, deepStrictEqual() is over 10 times faster than assert.deepStrictEqual()at the latter's best (it's best when not throwing exceptions).

The reason you want deepStrictEqual() is for its correctness, as proven by extensive testing, its speed, and its concise reporting of why deep-strict-equality fails when it does.

Many very popular deep equality packages have been examined, and few do well on this package's test suite. Those that claim they go very fast don't do well either. Limiting scope to fairly correct packages, this package is fastest so far.

This package no longer supports testing for deep copies. Such support has been farmed out to the deep-copy-diagnostics package. You need this package if you want to know exactly if and why a deep-copy algorithm fails. Basically the deepEquivalent() function of this package is much better than assert.deepStrictEqual() as it is aware of more things such as getters/setters, property descriptors, and has improved handling of circular/duplicate references.

Usage

npm install deep-equal-diagnostics
const {deepStrictEqual} = require('deep-equal-diagnostics');

if(deepStrictEqual(x,y))
{   
    // Statement that x and y are deeply equal.    
    
    console.log(deepStrictEqual.message);  
}
else
{
    // Very clear and exact reason why x and y 
    // are not deeply equal.
    
    console.log(deepStrictEqual.message); 
    
    // Examine the two sub-objects where strict
    // equality failed if you want.  
    
    const {source, target} = deepStrictEqual.pair;
      
}

OK! That's it. Read on only if you want.

Exports

|export|description| |---|---| |deepStrictEqual(x,y)| tests for deep strict equality|

Testing is Extensive

See the Tests folder

Contrast deepStrictEqual() with assert.deepStrictEqual()

On false returns, assert.deepStrictEqual()'s error message consists of two large dumps of the source and target. You then have to trace the dump from beginning to end to find the path of the error. If there is a circular reference problem where circular references do not correspond, then forget about it because you won't be able to decipher the dumps.

Say you have two objects x = Object.create(new Boolean(true) and y = Object.create(x) then assert.deepStrictEqual(x,y) gives the dump, which isn't very informative.

generatedMessage: true,
  code: 'ERR_ASSERTION',
  actual: Boolean {},
  expected: Boolean {},
  operator: 'deepStrictEqual'

Contrast that to what deepStrictEqual gives you.

Inequality found at top:
    Err 4: source is Boolean[Object(2)] while target is Boolean[Object(3)]

This tells you, the placement in the object tree where the error arose: at the top. You will always get the path to the error. Also, you know the source error object is an object two degrees away from Boolean.prototype and the target error object is three degrees away from Boolean.prototype in the inheritance chain.

Facts about the Specs of assert.deepStrictEqual()

Internal prototypes are checked, so that if corresponding objects don't have the same internal prototype then strict equality fails. Most packages fail to check internal prototypes.

The enumerable flag of corresponding properties are checked and if not the same then strict equality fails. The writable, and configurable flags are not examined. Whether properties are value based or getter/setter based are not examined.

Corresponding functions must be reference equal. Other data types need not be reference equal: this includes WeakSets and WeakMaps.

The 'stack' property of Error classes are not examined.

Consider two corresponding paths down the object trees. If both have circular references then they must have the same position and length. Only one having a circular reference is not a reason to reject strict-equality. Many packages either do not handle circular references or handle them incorrectly.

Duplicate references are not examined.

For emphasis, ALL objects are examined: this means secondary objects and prototypes. This is mentioned because many packages don't acknowledge the existence of such objects and so may actually throw exceptions when encountering them. A secondary object is an object created with Object.create().

For emphasis, properties of the built-in data-types are examined. Mentioned because many packages don't do this. For example, if x is a Set and x.a = something, the value of a and its counterpart must be examined.

Version History

|Version|Published|| |---|---|---| |1.0.0|11-8-2021|| |3.0.0|4-24-2022|deepStrictEqual() is now fully assert.deepStrictEqual() compliant but much faster. No longer checks property descriptors or getters/setters as this is non-compliant. | |3.0.1|4-29-2022|corrected typo $path[mapKey[${n}]] --> ${path}[mapKey[${n}]] package.json fatal error fixed|