Typescript: Allow using type parameters and return types with overloaded class constructors

[rdhelms]

Search Terms

Generic Class Constructor Declaration Overloads Type Parameters

Suggestion

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

// 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:

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

Ideally, maybe something like this for narrowing by type parameters:

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:

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.

[rdhelms]

I also wanted to provide a possible response for a point that @RyanCavanaugh made here, https://github.com/microsoft/TypeScript/issues/10860#issuecomment-246456721, where he points out that there is ambiguity in how to specify a class's type parameter vs the constructor's type parameter (e.g. new SomeClass<T>() could either be specifying the class type parameter or the constructor type parameter)

My suggestion would be that users should not be allowed to define both class-level and constructor-level type parameters. Essentially, a class-level type parameter would be a shorthand way of specifying the type parameters for all constructor overloads, but if a type parameter on one or more constructor overloads is specified, then the class's type parameter essentially becomes T extends Constructor1Param | Constructor2Param | Constructor3Param | ...etc (or similar to however function overloads with different type parameters are handled)

I'm more than happy to be pointed towards alternative ways of accomplishing the above cases!

[jcalz]

Workaround: build the closest thing you can with a regular generic class and rename it out of the way. Then make a type and a value of the desired name of the desired types and use type assertions where necessary:

class _Example<T extends string | undefined> {
    constructor(blah?: T) { }
}
type Example<T extends string | undefined> = _Example<T>;
const Example = _Example as {
    new(): Example<undefined>;
    new <T extends string>(requiredThing: T): Example<T>;
}

new Example()          // Ok
new Example<'hello'>()  // error, expected 1 argument

and

class _Example<T extends string | number | undefined> {
    prop: T;
    constructor(prop?: T);
    constructor(prop: T) {
        this.prop = prop;
    }
}

type Example<T extends string | number | undefined> = _Example<T>;
const Example = _Example as {
    new(): Example<string | number | undefined>;
    new(prop: string): Example<string>;
    new(prop: number): Example<number>;
}

new Example().prop  // string | number | undefined  
new Example("a").prop  // string
new Example(1).prop // number

Playground link

[rdhelms]

Thanks @jcalz - this is a nice summary of how to work with trickier construct signatures.

Would you agree though that being able to accomplish the above through the class's own type would be preferable to creating a constant that is imitating that class?

It certainly won't be intuitive to users when they see a class's type shown as const Example when they know it to be a class.

And if a workaround like you provided is already possible, it seems likely that this could also be accomplished under the hood 🤞🏻

[jcalz]

Would you agree though that being able to accomplish the above through the class's own type would be preferable to creating a constant that is imitating that class?

Sure

It certainly won't be intuitive to users when they see a class's type shown as const Example when they know it to be a class.

Maybe, but do note that most of the built-in constructors are declared with type definitions like this and nobody seems to care much. Write new Array and see what IntelliSense tells you about Array. I get something like this: var Array: ArrayConstructor and not class Array.

[rdhelms]

Wow that's enlightening about ArrayConstructor. It's interesting how 'Go to Definition' on Array manages to go to the interface Array and not the declared var or ArrayConstructor...but its construct signatures are indeed overloaded through ArrayConstructor...

I can roll with this for now, but I would love if someday class could handle all this itself 🙂

Great examples - thanks for providing those!

[rdhelms]

So actually...I don't think I'm going to be able to use the workaround 🙁 because users of the library whose types I'm working on expect to be able to do class CustomExample extends Example {} (to borrow the example classes from above).

By abstracting the class' constructor behavior to a const, we successfully made new work as we would want...but it breaks anything trying to extend the original class with an error Base constructors must all have the same return type.

[fatcerberus]

do note that most of the built-in constructors are declared with type definitions like this and nobody seems to care much

I don't care when writing code, that's true, but I do start to care when I do a Peek Definition on types like these to, e.g., see available methods. It often takes me to the wrong half of the definition and the two halves don't always seem to be kept together. Promise being a good example of that.

[poseidonCore]

Do remember that there is some capacity to do this already, but as pointed out, it is encumbered by the aforementioned problem of adding typing to the constructor [Type parameters cannot appear on a constructor declaration.(1092)]:

TSPlayground

class VariClass<T extends string|number> { 
  prop?: T extends string ? string : number;
    constructor(prop?: T) {
        // implementation
    }
}

var vs = new VariClass<string>()
var ps = vs.prop //:string

var vn = new VariClass<number>()
var pn = vn.prop //:number

[rdhelms]

Ok - so I'm back to thinking that the workaround by @jcalz can accomplish what I want to do, but I wanted to provide some additional observations after noticing some limitations and helpful patterns:

Here's an example of what I initially wanted to do:

declare namespace Test {
    interface Example<T extends object = object> {
        someProp: T
    }
    const Example: {
        new(): Example
        new <T extends object>(): Example<Partial<T>>
        new <T extends object>(someProp: T): Example<T>
    }
}

const example1 = new Test.Example()
example1.someProp       // object 👍🏻

const example2 = new Test.Example<{ numberThing: number }>()
example2.someProp.numberThing   // number | undefined 👍🏻

const example3 = new Test.Example<{ stringThing: string }>({ stringThing: 'hello' })
example3.someProp.stringThing   // string 👍🏻


// The following attempt will throw 'Base constructors must all have the same return type.'
class Child<T extends object = object> extends Test.Example<T> {
    someChildProp = 'stuff'
}

The goal with the above was to accomplish something similar to what can be done with functions like this:

declare namespace FuncTest {
    function someFunc(): object
    function someFunc<T extends object>(): Partial<T>
    function someFunc<T extends object>(val: T): T
}

const func1 = FuncTest.someFunc()   // object
const func2 = FuncTest.someFunc<{ thing1: string }>()    // Partial<{ thing1: string }>
const func3 = FuncTest.someFunc({ thing2: 200 })    // { thing2: number }

It's the difference between the "Have type parameter but no function parameter" and the "Have type parameter AND function parameter" cases that doesn't seem to be possible when dealing with overloaded construct signatures.

So, instead I settled for removing the middle construct signature - effectively forcing the user to pass the constructor parameter when the type parameter is provided. There is no "Partial" case any more. This is arguably totally fine, and it just means the user will possibly need to make assertions to accomplish what would have otherwise been possible via a type parameter.

[rdhelms]

Also, I think it would be great to add an example somewhere to the documentation that displays this "separate instance type and constructor type" pattern that we've been talking about. I've found this setup below to be pretty powerful (in ambient contexts, anyway), but it took some mental hoop jumping to understand the idea of having an interface with the same name as a const, and the opportunity that it provides:

    interface SomeClassName {
        // All instance props and methods go here
    }
    const SomeClassName: {
        // All static props and methods AND overloaded construct signatures go here
        new(): SomeClassName
    }