Experimental TypeScript fork with operator overloading and overload dispatch—documenting a working implementation

[adrianstephens]

🔍 Search Terms

operator overload, operator, overload, dispatch, runtime dispatch

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

🧠 Summary

This issue documents a working fork of TypeScript—published as @isopodlabs/typescript—that implements two long-requested features:

• Operator Overloading: Transforms expressions like a + b into method calls (a.add(b)) based on operand types.
• Function Overload Dispatch: Rewrites calls to overloaded functions using mangled names based on argument types.

I had to check a box above in order to post this, but in reality both features rely on type-dependent emit, which has historically been considered out-of-scope for TypeScript. This fork is intended as a proof of concept to explore whether such transformations can be implemented safely, predictably, and in a way that aligns with TypeScript’s broader goals.

---

🔍 Motivation

Operator overloading and overload dispatch are frequently requested, especially in domains like:

• Vector math and geometry
• Symbolic computation
• DSLs and fluent APIs
• Game engines and physics simulations

Current workarounds (e.g., method chaining, manual overload resolution) are verbose and error-prone. This fork demonstrates that these features can be implemented without breaking existing code, without introducing runtime ambiguity, and with full reproducibility via CLI flags.

---

⚙️ Implementation Overview

The fork introduces two compiler options:

• operatorOverloading: Enables transformation of operator expressions into method calls.
• functionOverloadDispatch: Enables mangling and dispatch of overloaded functions based on argument types.

Operator Overloading

• Uses a fixed mapping from operators to method names (+ → add, - → sub, etc.).
• Resolves overloads at compile time using the type checker.
• Falls back to standard behavior if no matching method is found.

Function Overload Dispatch

• Generates mangled names for each overload (foo(x: number) → foo$n).
• Rewrites calls based on argument types.
• Supports overloads for operator methods as well.

Full documentation and examples are available in the README.

---

🧪 Type-Dependent Emit: A Reconsideration

TypeScript’s design goals discourage type-dependent emit to avoid:

• Runtime behavior changes based on types
• Hidden transformations that break predictability
• Incompatibility with JavaScript semantics

This implementation attempts to sidestep those concerns:

• No runtime type checks: All transformations are compile-time only.
• No new JS semantics: Transformed code is valid, readable JavaScript.
• Fully opt-in: Requires explicit compiler flags.
• Reproducible and transparent: CLI-driven builds with no ambient leakage.

I recognize that type-dependent emit is a sensitive topic, but I hope this fork can serve as a concrete example to evaluate whether the objections still hold in this specific context.

---

🙏 Closing Thoughts

This issue is not a feature request for upstream inclusion, but an invitation to examine a working implementation that explores a long-standing community interest. I welcome critique, discussion, and feedback on the design tradeoffs—and I’m open to learning where this approach may fall short of TypeScript’s goals.

📃 Motivating Example

• Operator Overloading: Transforms expressions like a + b into method calls (a.add(b)) based on operand types.
• Function Overload Dispatch: Rewrites calls to overloaded functions using mangled names based on argument types.

💻 Use Cases

1. What do you want to use this for?
   Linear Algebra and arbitrary-precision arithmetic.
   Removing the cost of runtime dispatching on type when the compiler already knows the type
2. What shortcomings exist with current approaches?
   Using methods for operators is hard to read, error prone, ugly, etc.
3. What workarounds are you using in the meantime?
   I couldn't stomach the workarounds, so I made this :)

[jcalz]

Note: not a TS team member.

This is neat, but suggestions for operator/function overloading have been declined over and over again, and not for lack of a concrete implementation. I'd expect a new suggestion or discussion to provide links to existing issues, like #3442, #5407, #19859, #31611, #31842, #35589 (comment), #55198, et cetera. But I don't see any such references. Are you wanting to rehash the reasons why this is effectively a pre-declined feature? What kind of discussion, apart from "we're still not doing this" do you want to see from the TS team?

[MartinJohns]

in a way that aligns with TypeScript’s broader goals.

Type-dependent emit is not the only issue here, as per TypeScript Design Goals. This feature also goes against goal 7 and goal 9, and to some extent non-goal 7.

In general TypeScript aims to be only JavaScript with type information, so additional language features beyond the type system are out of the picture. What you compile is what you get, just without the type information. The only exception is down-level support (targeting older ES versions) and legacy features (enums and namespaces).

[adrianstephens]

@jcalz fair enough, I suppose 'frequently requested' could have been more explicit! But I also thought discussing all the reasons those other issues ultimately (or instantly) got rejected would've made this issue too long. This is a toe-in-the-water which I expect will be shot off, but I can afford to lose a toe or two.

The main difference from other proposals is that it's purely syntactic sugar, does not modify the output or behaviour of any existing (working) typescript, and allows for easy interoperation with JS and TS that doesn't use or enable this feature.

I'll admit that while I'd heard the phrase 'single file transpilation', I hadn't fully realised exactly what it was, so yeah. But there are other things that can't be done in a scenario where you don't have type information and this suggestion is both opt-in and compatible with manually doing what the syntax sugar does.

Are there other reasons for avoiding type-dependent emit, or it seems that those wanting to bypass the transpiler is why the rest of us can't have nice things.

In the end, I made this fork for me and posted here in case it could sway opinion. I'd love for these features (or something like them) to be added to the main fork, but my breath is un-held, and at least I can use these features that I wanted.

@MartinJohns
No - I don't think it goes against any design goals (the type-dependent emit is not one them).

7. Preserve runtime behavior of all JavaScript code.
   It's syntactic sugar - it doesn't change the runtime behaviour of anything,
8. Use a consistent, fully erasable, structural type system.
   I don't think 'erasable' here means search-and-replace types with blanks, I think it means removal of types by the transpiler.

Non-goal 7. Introduce behaviour that is likely to surprise users. Instead have due consideration for patterns adopted by other commonly-used languages.
I don't think operator overloading is surprising and is already adopted by many (most?) commonly-used languages. If anything, I'd say TS's lack is more surprising.

[MartinJohns]

7. Preserve runtime behavior of all JavaScript code.
It's syntactic sugar - it doesn't change the runtime behaviour of anything,

I have the JavaScript code a * b. With your suggestion this may compile to something completely different, so the runtime behavior of this code is not preserved.

8. Use a consistent, fully erasable, structural type system.
I don't think 'erasable' here means search-and-replace types with blanks, I think it means removal of types by the transpiler.

No idea where you see the difference. It essentially means that: remove all type information during compilation. See: https://github.com/microsoft/typescript/wiki/faq#what-is-type-erasure In the end it essentially is a "search and replace with blanks".

If anything, I'd say TS's lack is more surprising.

Because you expect TypeScript to be something it's not. It's meant as "JavaScript with types", and JavaScript does not have method or operator overloading. Being open to features as suggested will only lead to feature creep and reduce focus on the main part (the type checking). But that's just my two cents.

[jcalz]

I also thought discussing all the reasons those other issues ultimately (or instantly) got rejected would've made this issue too long.

Too long for what, given that presumably those reasons would be immediately brought up? The reasons in the existing issues apply here as well. I linked the most obvious showstopper above... prominently, I thought. I'll be more explicit and quote it here:

In #35589, @RyanCavanaugh said:

Let's say you write some code in a JavaScript file

var x = y + z;

If you paste that code into a TypeScript file, it means

var x = y + z;

This the fundamental promise of TypeScript: You can take some JavaScript code, put it in a TypeScript file, and it means the same thing meant before. I would argue it is the most important design principle we have, because it's the only reason JS -> TS migration is possible and the only reason JS <-> TS interop is sane.

This is why we don't have extension methods, even though it would be nice.
This is why we don't have operator overloading, even though it would be nice.
This is why we don't have exceptions on missing property access, even though it would be nice.
This is why we don't have automatic binding of this on class methods, even though it would be nice.
This is why we don't have native integers, even though it would be nice.
This is why we don't have exceptions on divide-by-zero, even though it would be nice.
This is why we don't have automatic prefixing of this. on class members, even though it would be very nice.

We've kept that promise on literally any random JS snippet you can think of, and while some JS code may have type errors, it does the same thing at runtime it does before. Changing your file extension from .js to .ts will not break your program.

That looks pretty definitive to me. If you want to see operator overloading in TypeScript, you need to introduce it to JavaScript first (e.g., the now withdrawn proposal at https://github.com/tc39/proposal-operator-overloading), and then TypeScript will end up supporting it (even downleveling so it could work with earlier JavaScript versions). That would be runtime dispatch, of course, but that's the only option that would align with TypeScript's design goals.

Anyway I expect we will just repeat ourselves after this, so I'll bow out unless there's something new I can think of to say.

[adrianstephens]

Ok, I see you both have strong objections, which I expected from the maintainers, but less so from users.

All I can say is that for my use cases these changes are more than nice and highly outweigh hypothetic downsides (hypothetical to me - not trying to dismiss your objections).

Pasting var x= y + z into typescript would be transformed only when y and z are known object types that have an add method, and you've enabled operator overloading. And in those cases var x = y + z would be an error and un-transpilable anyway.

Both of these features are trivial to support in tsc, but operator overloading is much harder for javascript, and static function dispatch is essentially impossible. These are big gains that tsc makes possible.

@MartinJohns I was using the general notion of type erasure rather than a specific implementation. I don't expect TypeScript to be something it's not, maybe just something a little more.

[MartinJohns]

I expected from the maintainers

Neither @jcalz nor me are maintainers. We're just noisy people who have been active here for a very long time and have a fairly good understanding of TypeScript.

[DanielRosenwasser]

It's not exactly that I would consider it a sensitive topic - it's that it's just all very firmly outside of our design goals. I always find it fun and interesting to play around with a proof of concept like this, so I appreciate that.

I'll try to give some rationale for how I think about a proposal like this, even beyond falling outside of the design goals. Here's a few examples of why new language behavior can be very subtle.

Let's take the following code:

export class Something {
    add(other: any): Something {
        return new Something();
    }

    toString() {
        return "Uhh..."
    }
}

console.log(new Something() + "hi!");

In this experimental fork, it results in the following JS:

export class Something {
    add(other) {
        return new Something();
    }
    toString() {
        return "Uhh...";
    }
}
console.log(new Something().add("hi!"));

Note, you get the same emit if you flip the operands which I didn't expect.

In existing code, most people expect this to just coerce to a string and concatenate. By adding a new method, we've changed the result. This might sound hypothetical, but it does create versioning hazards with code from external libraries.

It's also unclear what you would do with optional methods.

export function foo(weird: { add?(other: any): any }) {
    return weird + "hello!";
}

Is it disallowed? Which add do you pick? You can probably come up with new rules to get over this.

---

Here's an example where type information is lost through super-type aliasing, which introduces surprising behavior:

export class Foo {
    add(other) {
        return new Foo();
    }
}
export class Bar {
    add(other) {
        return new Bar();
    }
}
let x = new Foo();
let y = new Bar();
let z = y.add(x);

Here z relies on static dispatch of y's add method. This surprise is sometimes called "object slicing" in C++. It's even more surprising for a TypeScript user because all methods are virtually invoked in JavaScript. I understand why this happens in your fork, but this is pretty different from the rest of how TS layers on JS.

---

Let's start playing around with these features together and define an object with two add methods.

class Something {
    add(other: Something): Something {
        return new Something();
    }
    
    add(other: number): Something {
        return new Something();
    }
}

Now what happens when we try to add something generic with an add?

interface Addable<T extends Addable<T>> {
    add(other: unknown): T;
}

function f<T extends Addable<T>>(a: T, b: T) {
    return a + b;
}

f(new Something(), new Something());

It turns out this causes a crash, but I think you can see why this is not a simple problem to solve - generics heavily rely on type erasure in this system. There is no runtime that will look up the right add to invoke, and this implementation only relies on statically resolved functions and methods for these features. I'd argue f can't be compiled in a standalone way (e.g. as part of a library) because it needs to be compiled on a per-invocation basis (similarly to C++ templates). And even with access to its callers, you have to deal with the fact that there are structurally equivalent classes which will be compiled differently, non-mangled overloads in existing files, plain JavaScript callers who need to be considered, and come up with interoperability in the presence of all of that.

---

We've had a consistent position for over a decade avoiding type-driven emit and avoiding extending the language beyond erasable features. We have an ecosystem of tools that understand TypeScript, but which don't use type information, and we want them to still work well on TS code. Even if we wanted to, the type system can't be trusted in the first place (it's unsound), has lots of complexity around generics structural types, and has to exist in an existing JS ecosystem with a very specific kind of resolution model. It's not that there are not answers to each of the problems I've alluded to above - but the answers are all out of scope for features that were honestly out of scope to begin with! 😄

So this won't be something we'll add to TypeScript - but I don't think it's a bad idea to keep playing with the implementation if you want to go deeper and experiment!

[adrianstephens]

@DanielRosenwasser
I want to start by thanking you deeply for taking the time to look at this. I really didn't have any expectations beyond testing the water and your feedback has clarified the situation more than I've been able to glean from the other discussions I've seen on this list (maybe I'm just dim?). Having said that, I still think these features could be tweaked to work as expected and not run afoul of the design goals 99% of the time. Whether the remaining 1% (or 0.001%?) outweighs the benefits is obviously not my call.

Just to quickly address some of your feedback:
My brain said 'add is commutative - no need for a new method when you reverse operands'. Duh.
I suppose there could be a warning for having an add and a toString, but then I'd also think that'd be a common thing to want.

I can't tell what the super-type aliasing issue is; what was the input?

The crash is embarrassing :) Apparently sometimes a method's declaration is a MethodSignature instead of a MethodDeclararion, which I hadn't seen before. But yes, I can see how the static dispatch is problematic here. I suppose implementations of Addable would need to have an exactly matching add, which would do the usual dynamic dispatching.

Finally, many thanks again, and I will keep playing!

[MartinJohns]

not run afoul of the design goals 99% of the time.

I don't understand how you can still write this. Rewriting the code goes fundamentally against the design goals. And I don't see a possibility to support this feature without rewriting the code.

[snarbles2]

This issue is not a feature request for upstream inclusion, but an invitation to examine a working implementation that explores a long-standing community interest. I welcome critique, discussion, and feedback on the design tradeoffs—and I’m open to learning where this approach may fall short of TypeScript’s goals.

Unpopular opinion time. I'm one of those that laments the self-imposed limited scope of Typescript. I appreciate that it can create complications when feature (classes, decorators) are standardized in a way that departs from their prior typescript implementation, but I also imagine that their presence in typescript helped usher in the now-standardized features in the first place. For sure there's a lesson to be learned there, and maybe follow from the standard rather than lead the standard isn't the wrong lesson, but I would love to see a braver, more innovative variant of typescript. I'm not going to pretend I'd know how to walk that line, though.

The disclaimer is half on-the-mark ("not a feature request for upstream inclusion"), and half off-the-mark ("I’m open to learning where this approach may fall short of TypeScript’s goals"). It falls short of typescript's goals in a fundamental way and can't reasonably expect to ever be included. It's not surprising to see that it's not warmly welcomed, but my feeling is that ideas like this are worth exploring, and this is probably the best place to find the people with the right experience, knowledge, and insight to do that.

All a very long way of saying that, while I know such a feature will never land, I'm happy for the discussion.

---

The TC39 proposal for Javascript operator overloading has been withdrawn. However, I think it should still be consulted here. Having operator overloading become standardized should be the ideal end result (however improbable it may be), which means a proposal that gives consideration to how the feature will work in terms of Javascript code and the runtime should be very instructive.

[RyanCavanaugh]

Just to be clear, I don't mind this being posted, and definitely don't mind people experimenting. Experimenting is good!

This fork is intended as a proof of concept to explore whether such transformations can be implemented safely, predictably, and in a way that aligns with TypeScript’s broader goals

The answer is still no. The question has never been about whether type-directed emit is possible; that was never in doubt. The question is whether it's a good idea. It's not.

If you have type-directed emit:

• Emit becomes thousands of times slower
• Single-file transpile is broken
• 🚨 Generics don't work and fundamentally can't work in any reasonable way 🚨
• 🚨 You might get huge runtime surprises depending on very subtle differences in type inference 🚨
• 🚨🚨 as any stops working 🚨🚨

There's also the issue of frontrunning topics that should go through TC39. We got badly burned by this with class fields (hence the useDefineForClassFields flag, which is a nightmare), would have gotten burned by this with optional chaining (but didn't), and would absolutely get burned again with operator overloading (the odds that our semantics and TC39 semantics 100% align are approximately zero).

[GageSorrell]

If you have type-directed emit:

• Emit becomes thousands of times slower

Is this no longer an issue with version 7?

• 🚨 Generics don't work and fundamentally can't work in any reasonable way 🚨

I also question whether this is a serious "limitation" that warrants not implementing operator overloading.

The remaining issues seem serious enough to still not implement it, but I wonder if perhaps the native TS release gets us closer to a feasible implementation of operator overloading.

[jakebailey]

No, type-directed emit continues to be a non-goal. Note the date on that comment, long after we announced the port.