Just another suggestion (with Symbol)

[MAZ01001]

I think of a possible implementation like Symbol.toPrimitive, similar to #65 but slightly different...

Click to collapse

/**
 * possible new JSDoc for classes: <at>operator [RESULT_TYPE] [OTHER_TYPE] OPERATOR [DESCRIPTION]
 * ~ RESULT_TYPE takes priority over OTHER_TYPE if only one of the two is specified; both are optional
 *
 * @operator {boolean}          == → returns a boolean for `self==other` (other can be anything)
 * @operator {number}           +U → returns a number  for `+self`
 * @operator {number}  {number} *  → returns a number  for `self*other` when other is a number
 * @operator {number}  {number} /  → returns a number  for `self/other` when other is a number
 */
class Example(){
    /** @type {unknown} example property */test;

    /**
     * overrides all operator behaviour with this object (called just before `Symbol.toPrimitive`/type coercion)
     * @param {string} operator - JS operator
     * @param {unknown} other - other object, `undefined` is used for unary operators
     */
    [Symbol.oOverload](operator, other){
        switch(operator){
            // numerics
            case "+U": return +this.test;       // use `Symbol.toPrimitive` with hint number if not implemented here
            case "-U": return -this.test;       // use `Symbol.invert` if not implemented here
            case "+": return this.test+other;   // use `Symbol.oAdd` if not implemented here
            case "-": return this.test-other;   // use `Symbol.oSub` if not implemented here
            case "*": return this.test*other;   // use `Symbol.oMul` if not implemented here
            case "/": return this.test/other;   // use `Symbol.oDiv` if not implemented here
            case "**": return this.test**other; // use `Symbol.oPow` if not implemented here
            case "%": return this.test%other;   // use `Symbol.oMod` if not implemented here
            case "++": return ++this.test;      // use `Symbol.increment` if not implemented here
            case "--": return --this.test;      // use `Symbol.decrement` if not implemented here
            // bitwise
            case "~": return ~this.test;          // use `Symbol.binNOT` if not implemented here
            case "&": return this.test&other;     // use `Symbol.binAND` if not implemented here
            case "|": return this.test|other;     // use `Symbol.binOR` if not implemented here
            case "^": return this.test^other;     // use `Symbol.binXOR` if not implemented here
            case "<<": return this.test<<other;   // use `Symbol.binLShift` if not implemented here
            case ">>": return this.test>>other;   // use `Symbol.binRShift` if not implemented here
            case ">>>": return this.test>>>other; // use `Symbol.binURShift` if not implemented here
            // comparison
            case "==": return this.test==other; // use `Symbol.comparison` if not implemented here
            case "<": return this.test<other;   // use `Symbol.comparison` if not implemented here
            case ">": return this.test>other;   // use `Symbol.comparison` if not implemented here
            case "<=": return this.test<=other; // use boolean inverse of `>` if not implemented here
            case ">=": return this.test>=other; // use boolean inverse of `<` if not implemented here
            // assign
            case "=": return this.test=other; // use `Symbol.assign` if not implemented here
            // assign numerics
            case "+=": return this.test+=other;   // use `+`  then `=` if not implemented here
            case "-=": return this.test-=other;   // use `-`  then `=` if not implemented here
            case "*=": return this.test*=other;   // use `*`  then `=` if not implemented here
            case "/=": return this.test/=other;   // use `/`  then `=` if not implemented here
            case "**=": return this.test**=other; // use `**` then `=` if not implemented here
            case "%=": return this.test%=other;   // use `%`  then `=` if not implemented here
            // assign bitwise
            case "&=": return this.test&=other;     // use `&`   then `=` if not implemented here
            case "|=": return this.test|=other;     // use `|`   then `=` if not implemented here
            case "^=": return this.test^=other;     // use `^`   then `=` if not implemented here
            case "<<=": return this.test<<=other;   // use `<<`  then `=` if not implemented here
            case ">>=": return this.test>>=other;   // use `>>`  then `=` if not implemented here
            case ">>>=": return this.test>>>=other; // use `>>>` then `=` if not implemented here
        }
        return Symbol.oOverloadAbort; // override not implemented ~ continue with `Symbol.toPrimitive`/type coercion
        // ! without explicit return, `undefined` is used as if it were intentionally returned
    }

    // more specific overrides can be used if only some functionality needs to be custom-tailored

    // --- bitwise ---

    /**
     * used if `~` operator is not overridden by `Symbol.oOverload`
     * @returns {unknown}
     */
    [Symbol.binNOT](){ return ~this.test; }

    /**
     * used if `&` operator is not overridden by `Symbol.oOverload`
     * @param {unknown} other
     * @returns {unknown}
     */
    [Symbol.binAND](other){ return this.test&other; }

    /**
     * used if `|` operator is not overridden by `Symbol.oOverload`
     * @param {unknown} other
     * @returns {unknown}
     */
    [Symbol.binOR](other){ return this.test|other; }

    /**
     * used if `^` operator is not overridden by `Symbol.oOverload`
     * @param {unknown} other
     * @returns {unknown}
     */
    [Symbol.binXOR](other){ return this.test^other; }

    /**
     * used if `<<` operator is not overridden by `Symbol.oOverload`
     * @param {unknown} other
     * @returns {unknown}
     */
    [Symbol.binLShift](other){ return this.test<<other; }

    /**
     * used if `>>` operator is not overridden by `Symbol.oOverload`
     * @param {unknown} other
     * @returns {unknown}
     */
    [Symbol.binRShift](other){ return this.test>>other; }

    /**
     * used if `>>>` operator is not overridden by `Symbol.oOverload`
     * @param {unknown} other
     * @returns {unknown}
     */
    [Symbol.binURShift](other){ return this.test>>>other; }

    // --- numeric ---

    /**
     * used if (unary) `-` operator is not overridden by `Symbol.oOverload`
     * @returns {unknown}
     */
    [Symbol.invert](){ return -this.test; }

    /**
     * used if `+` operator is not overridden by `Symbol.oOverload`
     * @param {unknown} other
     * @returns {unknown}
     */
    [Symbol.oAdd](other){ return this.test+other; }

    /**
     * used if `-` operator is not overridden by `Symbol.oOverload`
     * @param {unknown} other
     * @returns {unknown}
     */
    [Symbol.oSub](other){ return this.test-other; }

    /**
     * used if `*` operator is not overridden by `Symbol.oOverload`
     * @param {unknown} other
     * @returns {unknown}
     */
    [Symbol.oMul](other){ return this.test*other; }

    /**
     * used if `/` operator is not overridden by `Symbol.oOverload`
     * @param {unknown} other
     * @returns {unknown}
     */
    [Symbol.oDiv](other){ return this.test/other; }

    /**
     * used if `**` operator is not overridden by `Symbol.oOverload`
     * @param {unknown} other
     * @returns {unknown}
     */
    [Symbol.oPow](other){ return this.test**other; }

    /**
     * used if `%` operator is not overridden by `Symbol.oOverload`
     * @param {unknown} other
     * @returns {unknown}
     */
    [Symbol.oMod](other){ return this.test%other; }

    /**
     * used if `++` operator is not overridden by `Symbol.oOverload`
     * @returns {unknown}
     */
    [Symbol.increment](){ return ++this.test; }

    /**
     * used if `--` operator is not overridden by `Symbol.oOverload`
     * @returns {unknown}
     */
    [Symbol.decrement](){ return --this.test; }

    // --- other ---

    /**
     * used if `=` operator is not overridden by `Symbol.oOverload`
     * @param {unknown} value
     * @returns {unknown}
     */
    [Symbol.assign](value){ return this.test = value; }

    /**
     * used for internal comparisons like {@linkcode Array.sort} and fallback if comparison operators are not overridden in `Symbol.oOverload`
     * @param {unknown} other
     * @returns {-1|0|1} if {@linkcode other} is larger: `-1`, is smaller: `1`, is equal: `0`
     */
    [Symbol.comparison](other){
        if(this.test===other)return 0;
        if(this.test<other)return -1;
        return 1;
    }

    /**
     * used for coercion to boolean (before `Symbol.toPrimitive`)
     * @returns {boolean} if this obj is truthy or not
     */
    [Symbol.toBoolean](){ return Boolean(this.test); }

    /**
     * used for numeric property access/assign (after testing if that property exists on this object and failing)
     * @param {number|bigint} index - indexed property
     * @param {boolean} assign - `true` when assigning to that property
     * @param {unknown} other - value for assignment
     * @returns {unknown}
     */
    [Symbol.indexAccess](index, assign, other){
        if(assign)return this.test[index] = other;
        return this.test[index];
    }
}

The unary + and - operators are specified as +U and -U, so no other parameter is needed to distinguish them from + and - in Symbol.oOverload and JSDoc.

---

So, for any A # B where A is an object and # is an operator, do:

1. if A is an Object
   1. if A[Symbol.oOverload] is a function that exists in A
      1. set tmp to A[Symbol.oOverload]("#", B)
      2. if tmp is not Symbol.oOverloadAbort

         • use tmp

   2. if a more specific method like Symbol.comparison exists in A

      • use the result of that specific method

   3. if changing operator is possible (like += to + and =)

      • go back to step 1.1 with new operator/s

2. continue with Symbol.toPrimitve/type coercion

And, for any # A where # is an operato,r do:

1. if A is an Object
   1. if A[Symbol.oOverload] is a function that exists in A
      1. set tmp to A[Symbol.oOverload]("#", undefined)
      2. if tmp is not Symbol.oOverloadAbort

         • use tmp

   2. if a more specific method like Symbol.increment exists in A

      • use the result of that specific method

   3. if changing operator is possible (like ++ to += with 1)

      • go back to step 1.1 with new operator/s

2. continue with Symbol.toPrimitve/type coercion

Also, A++ is the same as ++A but evaluated after the expression A is in (if any), same for A--.
So, for example, A++*B => A*B,++A (exec in that order, but this expression itself returns the result of A*B not ++A).

---

IMO, instead of making boolean operators overrideable, a Symbol.toBoolean method that evaluates the (current) truthiness of the object would be better.
And the boolean assignments &&= and ||= would use Symbol.toBoolean and assign (via override from Symbol.oOverload or Symbol.assign) accordingly.

Also, the Symbol.comparison can be used internally without needing to give Array.sort a compare function.

I agree that strict equals and the nullish coalescing operators/assignment should not be overrideable.
Along with the others listed like , and ().

---

The main benefit is that it does not break older code, can be easily type-checked (especially when using JSDoc), and should not be too hard to implement.
It also does not add more syntax to the language, except the suggested JSDoc tag.

PS: I don't have deep knowledge of JS engines, so I don't truly know how hard it would be to add support for this :P

PPS: Of course, the symbol names can be changed; after all, naming things is hard ^^

[FrameMuse]

It's cool, but afaik the main concerns are 1. "performance" and 2. "its affect to other proposals" 3. existing valueOf and such.

1. As you showed Symbol.oOverload being assigned in a class (which is the main use-case IMO), it means it can be assigned to any object at any time, which means the js should be checking for overload every single time it does any overloadable operation - which basically means a general inevitable performance degradation. That's why original proposal is about a switch (with keyword) that enables overload of operators. Of course I may be a bit incorrect in this since so-called "engine optimizations" exist, but it only adds up problems.
2. This proposal without being withdrawn was blocking other proposals since all the proposals are generally considered altogether.
3. Consider this expression A + B, where A has valueOf, but also may have Symbol.oOverload, what should be prioritized?

As you can see, even with your simple proposal, it's still very complex to implement and many problems to be solved on its way.

Here's the link to the Withdrawing reason:
https://github.com/tc39/notes/blob/main/meetings/2023-11/november-28.md#withdrawing-operator-overloading

Basically, they say right now it, doesn't really worth implementing it.

EDIT:

I was wrong about 1st point, the original idea came from this:

Daniel Ehrenberg: So a goal of the operator overloading proposal that I proposed was to avoid this injection of operator semantics into code that wasn’t locally expecting it

But I think the point still has a weight.

---

For enthusiasts

Anyway, it doesn't mean no one should keep working on this proposal or it is banned - no, generally majority respect its comeback if anyone willing to work on it.

You can present your new proposal to the committee. Make sure you to thought through problems, try to solve them and overweigh implementation cost against benefits.

---

Personally, I would like to implement this proposal in TS first as an addon to see problems we will face and only then coming to committee with a proposal, otherwise we will face the same reaction from implementors. In other words, we need some practical confirmation that has strong benefits rather than theoretical, IMHO.

[MAZ01001]

I see...

3. Consider this expression A + B, where A has valueOf, but also may have Symbol.oOverload, what should be prioritized?

The Symbol.oOverload takes priority since valueOf and toString are called after Symbol.toPrimitive as part of type coercion:

[...] All type coercion algorithms look up this symbol on objects for the method that accepts a preferred type and returns a primitive representation of the object, before falling back to using the object's valueOf() and toString() methods.

-- MDN: Symbol.toPrimitive

---

There is no doubt that this would impact performance, especially with more complex overloads, but other languages surely have the same challenge, right? Or maybe since languages like C++ are fully compiled before running, the performance impact is less noticeable?

It could also be defined that for things like ++, there is no second try with +=1, and it just continues with Symbol.toPrimitive/type coercion ~

Maybe to test this feature, it could be implemented and activated via "use operator overload"; at the beginning of a file (to enable it just for this file) like strict mode.
For testing how big of a performance impact it has with code that does not use it and code that uses it a lot...

But I agree that this can be put to the side for now if it's blocking other proposals that may be more important (or easier to implement) ~
I'd believe that introducing operator overloading only now into a dynamic language like JS is difficult.

[...] It would be very hard to implement efficiently, especially with the scoping/safety features.

[...] Daniel Ehrenberg proposed withdrawing operator overloading, which may clear the way for proposals such as Decimal [...]

Operator overloading may be re-introduced to TC39 in the future (especially if implementers' perception of the cost/benefit tradeoff changes), but the committee currently does not expect to spend time investigating operator overloading.

-- Speaker's Summary of Key Points
-- Conclusion

[FrameMuse]

There is no doubt that this would impact performance, especially with more complex overloads, but other languages surely have the same challenge, right? Or maybe since languages like C++ are fully compiled before running, the performance impact is less noticeable?

Probably, but don't forget about Python...

Maybe to test this feature, it could be implemented and activated via "use operator overload"; at the beginning of a file (to enable it just for this file) like strict mode.

Uh, yeah sure it can be implemented, but not by JS engine implementors since they already showed their unwillingness to do so. So as I mentioned, it should be implemented as an addon to JS/TS first. (It actually already kind of was developed, but it seems to not work anymore - too old)

I believe something like "use operator overload" is a must. I can go even further in this proposal by suggesting a scoped overloaded operators:

{
  "use operator overload"
  vector1 += vector2
}

This would help if you have many complex operations that would look simpler with overloading applied.