Add a symbol to allow extending and modifying the equality check

[dead-claudia]

I feel this is ripe for a symbol that allows extending and modifying the equality check. Library precedent is rather lacking (unless you consider Fantasy Land's Setoid spec and its implementers as precedent), but there is a common .equals idiom that's emerged that I've noticed.

For language precedent, it's pretty strong. Here's a few right off the top of my head:

• Java: public boolean equals(Object other)
• C++: boolean operator==(T other)
• Rust: std::cmp::Eq<T>, used by its == operator
• Haskell: Data.Eq

For naming, I propose Symbol.equals. This goes along with the idiom most are already using. And for standard library containers:

• Error objects: identical name and message and deep equal own expando properties. Stack should not be considered for the purposes of this.
• RegExp objects: identical pattern and equivalent flags (/gi and /ig are considered equivalent).
• Arrays: identical length and deep-equal entries, but ignore expando properties
• Maps: size is identical, each key of this is deep-equal with a key in other and their corresponding entries are also deep-equal
  • The idea is that these should be compared deeply in the same way objects are, just instead of string equality, it's deep object equality.
  • Algorithm note: I've tried to distill that into something sufficiently fast here. Either you'll need to encode similar in the spec or leave it implementation-defined for reasonable performance.
• Sets: size is identical and every key in this is deep-equal with a key in other
  • The idea is that these should be compared deeply in the same way objects are, just instead of string equality, it's deep object equality.
  • Algorithm note: I've tried to distill that into something sufficiently fast here. Either you'll need to encode similar in the spec or leave it implementation-defined for reasonable performance.
• Array buffers, shared array buffers, and array buffer views: equal byte data
• Promises: identical status and deep-equal value if settled, reference identity if pending

The default behavior should still of course be the standard algorithm, and it's left implied that types of course also need to be equal.

---

I could also see HTML wanting to hook into this as well:

• Event: detail deep-equal, eventPhase and mutable properties ignored, all other properties identical
• Node: children deep-equal
• Element: attributes and children deep-equal
• CharacterData: data equal
• Range: equivalent contents
• Request: equivalent target/headers/etc.
• And so on

[ljharb]

The stage 1 proposal is about investigating a problem space; it makes sense to me that we’d need a generic protocol to be able to solve this problem for all objects, not just built-ins.

[dead-claudia]

@ljharb I'm aware. This can be revisited later if it's too premature.