Support declaring multiple setter overloads

[peterflynn]

🔍 Search Terms

setter overload, multiple setter signatures, multiple setter input types

✅ 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

TypeScript allows declaring multiple different argument signatures for a function, i.e. "function overloads": https://www.typescriptlang.org/docs/handbook/2/functions.html#function-overloads.

We should be able to do the same for property setters, since they are modeled much like a function taking a single argument.

(Note that unlike some other languages, TypeScript's overloads are only bare type signatures: there is only a single method body implementation shared by all of them, making this a pure typechecking feature with no impact on the generated runtime code. This proposal works the same way, just extending this syntax from functions/methods to setters as well).

📃 Motivating Example

A setter might want to separate different types of inputs for improved clarity of documentation:

/**
 * Set startTime to a specific timestamp, specified as a Date object or number of ms since epoch.
 */
set startTime(date: Date | number);

/**
 * Set startTime to the start of the most recent activity matching the given category name.
 */
set startTime(category: string);

set startTime(dateOrCategory: Date | number | string) {
    // ...
}

Note that these differ not just in documentation but also in the value argument's name, which often appears in generated docs output too.

💻 Use Cases

Although setter overloads are necessarily less versatile than function overloads with multiple parameters, some of the same rationales for the overload feature still apply to setters – as seen in the example above.

Workaround
As with functions before overloading is supported, the workaround is just to glom all the docs together with some additional verbiage, e.g.:

/**
 * Set startTime:
 * - If given a Date object or number of ms, sets to a specific timestamp.
 * - If given a category name string, sets to the start of the most recent activity matching that name.
 */
set startTime(dateOrCategory: Date | number | string) {
    // ...
}

[RyanCavanaugh]

Just my opinion, but this seems like terrible API design if there are so many possible coercions. What are some libraries that do this?

[peterflynn]

@RyanCavanaugh Sometimes setters are treated essentially as a way to inline construct a new value, so they may wind up offering just as many different overload choices as a constructor method would.

The original DOM API example motivating #43662 is one example of that pattern, albeit not complex enough to need overloads in that case. But the actual property value (as seen in the getter) is a CSSStyleDeclaration object, yet you pass the setter a string which is essentially used to construct one for you. If there was more than one way to construct a CSSStyleDeclaration object, then you might find yourself wanting overloads for a setter like that one.

As to why you might want a setter to act more like a constructor... developer convenience feels like one motivation. Wanting an API where you can't ever create free-floating "orphan" instances of the thing being constructed could be another.