Support declaring multiple setter overloads

🔍 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) {
    // ...
}

Review the proposed setter overload syntax and motivating example in the issue. Determine how multiple setter signatures should be type-checked while preserving one implementation and unchanged JavaScript output; done means the feature is supported without changing existing runtime behavior.