Repository: TypeScript
Issue: Add type operators that can answer "given function type T, what is the type of its return value when arguments P are passed in?"
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

<!-- List of keywords you searched for before creating this issue. Write them down here so that others can find this suggestion more easily -->
overload infer function operator arguments parameters return

## Suggestion

```ts
// 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](https://humeris.org/espresso-shot) be able to support checks like `expectTypeOf(fn).toBeCallableWith(args)`.

Note that though `ValueForKey` could be implemented as:
```ts
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:
```ts
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
```ts
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)
```

<!--
What do you want to use this for?
What shortcomings exist with current approaches?
-->



<!-- Show how this would be used and what the behavior would be -->

## Also
Given the above, it would also make sense to have something like
```ts
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](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).