Allow deepEqual to use a custom comparator

[forty]

deep-eql, the underlying library doing deep equality supports passing a custom comparator https://github.com/chaijs/deep-eql/blob/main/index.js#L87

Exposing it in chai would be super useful. This idea has been mentioned in several comments (especially on issue about loose equality, which is one use case for it) for example #644 (comment) (2016) but I did not find a proper ticket for it.

Syntax:

expect({a: 1}).to.eql({b: 2}, 'nooo why fail??', comparator);
expect({a: 1}, 'nooo why fail??').to.eql({b: 2}, comparator);
// maybe
expect({a: 1}, 'nooo why fail??').usingComparator(comparator).to.eql({b: 2});

// assert style
 assert.deepEqual({ tea: 'green' }, { tea: 'green' }, comparator);

Example use case: interval

const comparator = (left, right) => {
   if(right && typeof right == 'object' && typeof right.__interval' === 'number' && typeof right.__value === number){
      // right is of the form {__value: 100, __interval: 5}, use custom comparison
      if(typeof left !== 'number){
         return false;
      } else {
         return Math.abs(right.__value - left) < right.__interval
      } 
   } else {
      return null; // use default comparison
   }
}
assert.deepEqual({ amount: 103}, { amount: {__value: 100, __interval: 5} }, comparator);

(ugly example to make it clear how that would work, but it'd certainly be more elegant with an IntervalComparison class for example which would work the same)

[forty]

I had a quick look at the code, and unless I'm mistaken, that doesn't seem horribly hard to do (but I only looked very quickly tbh), at least for the simple expect and assert syntax (which to be frank is all that matters to me, I hate.expect.syntax.with.a.passion but from my understanding of the code, the easiest is to implement it for both interfaces anyway)

[forty]

One step further (or maybe it'd be the first step as it doesn't involve changing the API) could be to be able to change the default comparator

chai.config.defaultComparator = comparator;

which would be even more useful

[koddsson]

Hey @forty; I'm not sure if we're able to land this in 5.0 but I think we can do this in a way that it's not a breaking change so it could be done in a minor version after 5.0.

A pull request with this feature would help tremendously but otherwise it's just a matter of time until someone has the time to pick this up to work on.

[forty]

@koddsson thank you for you answer. I just pushed a MR to implement this on the 5.x.x branch. Thanks in advance for your feedback.

[koddsson]

I think we can close this now that the linked PR is merged? Feel free to re-open if not.

[olsonpm]

This seems useful but the docs don't mention this functionality. Is that being considered in a separate PR ?