Typescript: Add type operators that can answer "given function type T, what is the type of its return value when arguments P are passed in?"

[lazytype]

Search Terms

overload infer function operator arguments parameters return

Suggestion

// Already possible
type ValueForKey<T, K extends keyof T> = T[K];

// Proposal
type Callable = (...args: any[]) => any;
type ValueForArguments<T extends Callable, A extends paramsof T> = T(...A);

Use Cases

This is a proposal that would help with overloaded function issues like #26591 and would help my type testing library be able to support checks like expectTypeOf(fn).toBeCallableWith(args).

Note that though ValueForKey could be implemented as:

type ValueForKey<T, K extends keyof T> = 
  T extends {[Key in K]: infer U} ? U : never;

The following will only work for non-overloaded functions:

type ValueForArguments<T extends Callable, P extends Parameters<T>> = 
  T extends (...args: P) => infer R ? R : never;

since both the inference from Parameters<T> and the type definition will only consider one of the overloads.

What I'm asking is not for inference to consider multiple overloads, which would be nice but might complexify the implementation of type inference, but direct support for paramsof and T(A1, A2, ...A) type syntax which behaves correctly with overloaded functions.

Examples

interface OverloadedFunction {
  (arg: number): number;
  (arg: string): string;
}

// `number`
type Result1 = OverloadedFunction(number);

// `number | string`
type Result2 = OverloadedFunction(number | string);

// `[number] | [string]`
type Result3 = paramsof OverloadedFunction;

// `number | string`
type Result4 = OverloadedFunction(...paramsof OverloadedFunction)

Also

Given the above, it would also make sense to have something like

type Newable = new (...args: any[]) => any;
type ValueForArguments<T extends Newable, A extends paramsof new T> = new T(...A);

where new T takes the constructor type of T and turns it into a function type

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.

[lazytype]

Note that though ValueForKey could be implemented as:

```ts
type ValueForKey =
T extends {[Key in K]: infer U} ? U : never;

I have to rescind that statement as I found an example that doesn't currently work.

type Test = {
    x: boolean;
    [K: string]: number | boolean;
}

let boolean: ValueForKey<Test, 'x'> = true;

// @ts-expect-error
boolean = 42

// Type 'boolean' is not assignable to type 'never'.(2322)
let shouldBeNumberOrBoolean: ValueForKey<Test, 'y'> = true
    ^^^^^^^^^^^^^^^^^^^^^^^

// Type 'number' is not assignable to type 'never'.(2322)
shouldBeNumberOrBoolean = 42;
^^^^^^^^^^^^^^^^^^^^^^^

let numberOrBoolean: Test['y'] = true;

numberOrBoolean = 42;

The implication being that T[...] syntax provides unique semantics that cannot be produced in other ways.

[HitalloExiled]

That was as close as I got to a solution using the current state.

It works in most cases.
But has several problems in overloads with optional parameters.

type Calleable = (...args: any[]) => any;
type CallOverloads<T> = T extends
{
    (...args: infer A1):  infer R1,
    (...args: infer A2):  infer R2,
    (...args: infer A3):  infer R3,
    (...args: infer A4):  infer R4,
}
    ? [A1, (...args: A1) => R1] | [A2, (...args: A2) => R2] | [A3, (...args: A3) => R3] | [A4, (...args: A4) => R4]
    : T extends
    {
        (...args: infer A1): infer R1,
        (...args: infer A2): infer R2,
        (...args: infer A3): infer R3,
    }
        ? [A1, (...args: A1) => R1] | [A2, (...args: A2) => R2] | [A3, (...args: A3) => R3]
        : T extends
        {
            (...args: infer A1): infer R1,
            (...args: infer A2): infer R2,
        }
            ? [A1, (...args: A1) => R1] | [A2, (...args: A1) => R2]
            : T extends (...args: infer A1) => infer R1
                ? [A1, (...args: A1) => R1]
                : never;
type Overload<T extends Calleable, TArgs> = Extract<CallOverloads<T>, [TArgs, any]>[1];
type ParameterOverloads<T extends Calleable> = CallOverloads<T>[0];

type TFN1 =
{
    (): void,
    (value: string): number,
    (value: number): boolean,
    (value: number, options: object): object,
}

type T01 = Overload<TFN1, []> // (): void
type T02 = Overload<TFN1, [string]> // (value: string): number
type T03 = Overload<TFN1, [number]> // (value: number): boolean
type T04 = Overload<TFN1, [number, object]> // (value: number, options: object): object
type T05 = ParameterOverloads<TFN1> // [] | [value: string] | [value: number] | [value: number, options: object]

type TFN2 =
{
    (): void,
    (value: boolean): string,
    (value: number, options?: object): object,
}

type T11 = Overload<TFN2, []> // (): void
type T13 = Overload<TFN2, [number, object | undefined]> // never

// Works, but hard to reproduce when the types is provided based on user input
type T12 = Overload<TFN2, [number, object?]> // (value: number, options?: object): object
declare function call<TArgs extends ParameterOverloads<TFN2>>(...args: TArgs): ReturnType<Overload<TFN2, TArgs>>;

call(); // void
call(true) // string
call(1, {}) // never
call(1, undefined) // never

[lazytype]

Here's another use-case:
Actual:

function usesOverloadedFunction<T>(arg: T) // : inferred return type is whatever the last overload of
// `overloadedFunction` is when applied to `...args: [T]`. 
{
  return overloadedFunction(arg);
}

Expected:

function usesOverloadedFunction<T>(arg: T) // : infers `(typeof overloadedFunction)(T)`
{
  return overloadedFunction(arg);
}

[KilianKilmister]

Would love to see a solution to this. this is one of the reasons why i don't like to work with the standard NodeJS EventEmitter. these often easily have 10+ overloads for all the eventnames which were all manually typed. That's great when you are trying to harcode an event, but any kind of elegant type inference impossible at the moment.

Specific example are [events.on] and [events.once] they are two to-level function for interacting with emitters easily via promises, eg.

event.once(emitter, name[, options]) // => return a Promise
event.on(emitter, name[, options]) // => return an AsyncIterable

Both of them are great when you are using a lot of async/await, it saves all the annoying callback nesting when you have to wait for some init/close-event like the net.Server listening and close. it results in some realy nice, linear code.
but typescript can't give you any completion help for any events that are present on any emitter, which really makes these two function cumbersome to use if your not very familiar with the emitter

server.listen(8124)
await once(server, 'listening')

server.close()
await once(server, 'close')

A solution to this migth also be a stepping stone for problems related to generic functions, smarter ReturnType and bind(...args) operations. I would love to finally be able to use Currying accurately with generics.

[jcalz]

duplicate of #26043 but that one was closed as a duplicate of #6606 which was ultimately declined; not sure about this one