Repository: TypeScript
Issue: Allow using type parameters and return types with overloaded class constructors
Labels: Suggestion,Awaiting More Feedback

<!-- 🚨 STOP 🚨 𝗦𝗧𝗢𝗣 🚨 𝑺𝑻𝑶𝑷 🚨

Half of all issues filed here are duplicates, answered in the FAQ, or not appropriate for the bug tracker.

Please help us by doing the following steps before logging an issue:
  * Search: https://github.com/Microsoft/TypeScript/search?type=Issues
  * Read the FAQ, especially the "Common Feature Requests" section: https://github.com/Microsoft/TypeScript/wiki/FAQ

-->

## Search Terms
Generic Class Constructor Declaration Overloads Type Parameters

<!-- List of keywords you searched for before creating this issue. Write them down here so that others can find this suggestion more easily -->

## Suggestion

<!-- A summary of what you'd like to see added or changed -->
This is partially a request to revisit some of the discussion from here:
https://github.com/microsoft/TypeScript/issues/10860
But it's also to provide some examples of cases that are difficult/impossible to type using classes today.

A class may frequently assign different types to its properties depending on how it was instantiated. While we can type those properties as unions of all their possible types (or even use completely separate classes), it would be amazing if we could "narrow" a class's type based on how it was instantiated.

We CAN handle this type of complexity with regular function overloads, because the relevant call signature is narrowed by both function parameters and type parameters. Class constructors, however, only pay attention to the parameters being passed and can't have type parameters.

## Use Cases

<!--
What do you want to use this for?
What shortcomings exist with current approaches?
-->
```ts
// Using type parameters with overloaded generic function
function func(): void;
function func<T extends string>(requiredThing: T): void
function func(requiredThing?: string) { }
func()              // Ok
func<'hello'>()     // Expects 1 argument, as expected

// Attempting to use type parameters with overloaded class constructor
class Example<T> {
    constructor()
    constructor(blah: T)    // How do we connect this to the presence of T?
    constructor(blah?: T) {}
}
new Example()           // Ok
new Example<'hello'>()  // We want this to expect 1 argument somehow
```

As was also discussed in https://github.com/microsoft/TypeScript/issues/10860, return types on a constructor could theoretically represent narrowed versions of the instance type. Currently there's not an easy way to narrow a property's type based on how the class was instantiated:
```ts
class Example {
    prop?: string | number

    constructor()    // When this is used, prop should be string | number | undefined
    constructor(prop: string)    // When this is used, prop should be string
    constructor(prop: number) // When this is used, prop should be number
    constructor(prop?: string | number) {
        // implementation
    }
}
```

## Examples

<!-- Show how this would be used and what the behavior would be -->
Ideally, maybe something like this for narrowing by type parameters:
```ts
class Example {
    constructor()
    constructor<T extends string>(blah: T)
    constructor(blah?: string) {}
}
new Example()           // Ok
new Example<'hello'>()  // Would expect 1 argument
```

And maybe something like this for return types:
```ts
interface IExampleString extends Example {
    prop: string
}
interface IExampleNumber extends Example {
    prop: number
}
class Example {
    prop?: string | number

    constructor()    // When this is used, prop should be string | number | undefined
    constructor(prop: string): IExampleString    // When this is used, prop should be string
    constructor(prop: number): IExampleNumber    // When this is used, prop should be number
    constructor(prop?: string | number) {
        // implementation
    }
}
```

## Checklist

My suggestion meets these guidelines:

* [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [x] This wouldn't change the runtime behavior of existing JavaScript code
* [x] This could be implemented without emitting different JS based on the types of the expressions
* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).