Repository: TypeScript
Issue: Distribute union types over generic function application
Labels: Suggestion,Awaiting More Feedback

# Suggestion

<!--
  Please fill in each section completely. Thank you!
-->

## 🔍 Search Terms

<!--
  💡 Did you know? TypeScript has over 2,000 open suggestions!
  🔎 Please search thoroughly before logging new feature requests as most common ideas already have a proposal in progress.
  The "Common Feature Requests" section of the FAQ lists many popular requests: https://github.com/Microsoft/TypeScript/wiki/FAQ#common-feature-requests

  Replace the text below:
-->

generic union distribute function mapped

## ✅ Viability Checklist

<!--
   Suggestions that don't meet all these criteria are very, very unlikely to be accepted.
   We always recommend reviewing the TypeScript design goals before investing time writing
   a proposal for ideas outside the scope of the project.
-->
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, new syntax sugar for JS, etc.)
* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).


## ⭐ Suggestion

It should be possible to call a generic function with a union as input and separately resolve the generics for each member of the union. This mimics the way generic types can be distributed over a union.

## 📃 Motivating Example

<!--
  If you were announcing this feature in a blog post, what's a short explanation that shows
  a developer why this feature improves the language?
-->

Consider this simple example ([playground](https://www.typescriptlang.org/play?ts=4.9.4&ssl=4&ssc=60&pln=1&pc=1#code/C4TwDgpgBAggPAFQHxQLxQBQEMBcUECUaKCA3FAPQVRYB2IUokUAlrQG5YBOLdwUAe1r4AUADMArrQDGwFkKhiBAxEmx54yIgG8AviIAmEaQBtu0aUIDO-XLDgBGFAB97AJiSlxy7AXJUoCC4uAS4NRxd3FBYrKFoBWysrFgBzWiwAIxNoYAF7ByhXDyA)):
```typescript
type A<T> = (a: T) => T; // any type invariant on T
function foo<T>(a: A<T>) {}
declare const a: A<1> | A<2>;
foo(a); // error: A<1> | A<2> is not assignable to A<1 | 2>
```

The function `foo` is perfectly capable of handling an input of either `A<1>` or `A<2>`, but Typescript will not allow you to execute it on the _union_ of those types. That is because it tries to find a single instantiation for T that works, but there is none, because the type `A<T>` is not covariant.

In the case that `foo` had an output, `foo: <T>(a: A<T>) => B<T>`, for input of `A<1> | A<2>` the output type would be `B<1> | B<2>`, much the same as how distributing over a union works in a type expression like `X extends A<infer T> ? B<T> : never`;

## 💻 Use Cases

<!--
  What do you want to use this for?
  What shortcomings exist with current approaches?
  What workarounds are you using in the meantime?
-->

This is one of a few issues that make non-covariant types a little bit second-class to work with in Typescript. And some of the other issues might be very hard to resolve, like how to type "An array of `A<T>` where each element can have a different `T`" without using `any`. But in comparison, I don't think this one requires any deep thought for the desired behavior, and while the implementation might be tricky I don't think it requires any truly new capabilities.

Workarounds:
1. For a function where `T` doesn't appear in the output, like `<T>(a: A<T>) => void`, can be typed as `(a: A<any>) => void`. Then it works with unions as input. However, that introduces `any`s into the typechecking of the function's implementation, which don't need to be there. Instead, you can explicitly specify `foo<any>(x)` when calling the function. But if the function has other generics, that will make it so they also have to be explicitly specified instead of inferred.
2. For a function where `T` _does_ appear in the output, like `<T>(a: A<T>) => B<T>` where `A<T>` and `B<T>` are both invariant, I am not aware of any workaround except casting. Using `any` leaks into the output type and therefore the rest of your code. Even casting in that situation is more brittle than usual, as changes to the input union type or to the definition of the function's output type will both be lost.