Symbol.equal - a way to define the weak equals operator on objects

aclaymore · September 13, 2026, 1:26am

Some previous related discussions:

Add a symbol to allow extending and modifying the equality check

opened 04:22AM - 02 Mar 21 UTC

I feel this is ripe for a symbol that allows extending and modifying the equalit…y check. Library precedent is rather lacking (unless you consider [Fantasy Land's Setoid spec](https://github.com/fantasyland/fantasy-land#setoid) 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`](https://hackage.haskell.org/package/base-4.12.0.0/docs/Data-Eq.html) 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](https://github.com/isiahmeadows/clean-assert/blob/master/lib/match.js#L246-L312). 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](https://github.com/isiahmeadows/clean-assert/blob/master/lib/match.js#L314-L383). 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

Topic		Replies	Views
Symbol.equal protocol 💡 Ideas	3	479	December 24, 2020
Proposal: Object.isEqual() - Deep Structural Equality for ECMAScript 🦋 Proposals	29	453	May 4, 2026
JSON.equals(x, y) 💡 Ideas	8	324	April 19, 2024
Proposal: Object.equals and hashCode 🦋 Proposals proposal	3	393	July 20, 2023
Array.prototype.equals 💡 Ideas	2	488	July 23, 2019

Symbol.equal - a way to define the weak equals operator on objects

Related topics