24

So i was going through the documentation on typescript and am not able to get my head around this concept.

So the documentation states :-

In instantiations of a distributive conditional type T extends U ? X : Y, references to T within the conditional type are resolved to individual constituents of the union type (i.e. T refers to the individual constituents after the conditional type is distributed over the union type). Furthermore, references to T within X have an additional type parameter constraint U (i.e. T is considered assignable to U within X).

I cannot understand the part T refers to the individual constituents after the conditional type is distributed over the union type.

Can anyone please explain this to me. An example of the same would be highly appreciated, the one in the documentation is not very clear to me.

Improve this question

2 Answers 2

Reset to default
60

Hmm, I just read through the documentation and it makes sense to me... I don't know if I can explain it any better than that, but let's go through it. In what follows, and ...x..., means "some expression in which x might appear".

Conditional types in which the checked type is a naked type parameter are called distributive conditional types.

In this case, a type parameter means a generic type parameter, and a naked type parameter is a type expression where the type parameter appears alone and is not part of some more complex type expression. And the checked type is the type appearing before extends. Let's see some examples:

  • type A<T> = string extends T ? "yes" : "no" This is not a distributive conditional type. The checked type is string, which is not a generic type parameter.
  • type B<T> = {x: T} extends {x: number} ? "yes" : "no" This is not a distributive conditional type. The checked type is {x: T}, which has the type parameter T in it, but is not a naked type parameter.
  • type C<T> = T extends string ? "yes" : "no" This is a distributive conditional type; the checked type is T, which is a naked generic type parameter.

Distributive conditional types are automatically distributed over union types during instantiation. For example, an instantiation of T extends U ? X : Y with the type argument A | B | C for T is resolved as (A extends U ? X : Y) | (B extends U ? X : Y) | (C extends U ? X : Y).

This is the essence of what a distributive property does. If you have a type alias F<T> defined to be a distributive conditional type, as in:

type F<T> = T extends ...T... ? ...T... : ...T...

Then F<T> will distribute over unions, meaning that for any types A and B, the type F<A | B> will be equivalent to the type F<A> | F<B>

In instantiations of a distributive conditional type T extends U ? X : Y, references to T within the conditional type are resolved to individual constituents of the union type (i.e. T refers to the individual constituents after the conditional type is distributed over the union type).

This is the part that confused you, but it's just explaining how the distribution works. It's saying that to evaluate F<A | B>, you should evaluate F<A> | F<B>. So for F<A>, you take F<T> = T extends ...T... ? ...T... : ...T... and plug in A for T (to get A extends ...A... ? ...A... : ...A...), and then plug in B for T (to get B extends ...B... ? ...B... : ...B...), and then unite them.

Let's go through a concrete example:

type D<T> = T extends string ? T : "nope"

What is this:

type E = D<"a" | "b" | 0 | true>

Well, here's how not to do it:

type E = ("a" | "b" | 0 | true) extends string ? ("a" | "b" | 0 | true) : "nope" //👎

type E = "nope" //👎

I just plugged "a" | "b" | 0 | true into T without distributing, and that's wrong. Here's how to do it correctly:

type E = D<"a"> | D<"b"> | D<0> | D<true> //👍

type E = ("a" extends string ? "a" : "nope") |
         ("b" extends string ? "b" : "nope") |
         (0 extends string ? 0 : "nope") |
         (true extends string ? true : "nope") //👍

type E = ("a") | ("b") | ("nope") | ("nope") //👍

type E = "a" | "b" | "nope" //👍

See, we took the "individual constituents of the union" and replaced T with each one of them in turn.

Okay, I hope that makes more sense now. Good luck!

Improve this answer
Sign up to request clarification or add additional context in comments.

4 Comments

A very through explanation, always a pleasure to read your stuff :)
I think jcalz must re-write the whole Typescript documentation with his own Stackoverflow answers, it'll be more understandable in the end :)
But why are conditionals distributive? Is it a consequence or a design? And is the "nakedness" or more specifically a lack of thereof an explicit implementation choice or are boxed versions of the type e.g. [T] extends any computationally so different, that they "break" the distribution? Was it easier to resolve each of the union members separately than try to go into the condition branches?
It's a feature and an explicit implementation choice. Personally I would have preferred for distributive/non-distributive conditional types to be selected by some more explicit syntax. I think they did it this way so that conditional types that act on generics would be "naturally" distributed over unions, and that introducing more syntax would just confuse people... but I'm not privy to the details of the design choice, more than what's documented in GitHub. 🤷‍♂️
6

Within a distributive conditional type (let's say type BoxIfObject<T> = T extends object ? Array<T> : T;) when the type is applied to a union (let's say number | { a : string }), it's as if the conditional type is applied to each constituent of the union and thus within the conditional type T will in turn refer to each constituent of the union (so T will first be number and then T will be { a : string })

So when we apply BoxIfObject<number | { a : string }>, T will never refer to the whole union number | { a : string } but to each of it's constituents in turn. Basically BoxIfObject<number | { a : string }> = BoxIfObject<number> | BoxIfObject<{ a : string }> = number | Array<{ a : string }

Improve this answer

2 Comments

This seems fine but as i was going through the documentation the word after in phrase T refers to the individual constituents after the conditional type is distributed over the union type is italicized does that hold any significance ?
@AmolGupta I can't speak to the choice of italics .... but it seems consistent with what I wrote, when (ie after) instantiation occurs T will be in turn each constituent of the union.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.