Distributive conditionals

The rule, stated precisely

Why does this matter? Because every union-level utility type — Exclude, Extract, Filter — works because of this rule, and every wrong IsNever or IsString predicate breaks because of it. When the type being checked in a conditional is a naked type parameter — T extends ..., where T appears alone, not wrapped in anything — and T is instantiated with a union, the conditional distributes: it is applied to each member of the union independently, and the results are unioned back together.

type ToArray<T> = T extends unknown ? T[] : never;

type A = ToArray<string | number>;
//   ^? type A = string[] | number[]
//   NOT (string | number)[]  — distribution split the union first

The compiler rewrites ToArray<string | number> as ToArray<string> | ToArray<number> = string[] | number[]. The check runs once per member.

Opting out: wrap the parameter

Distribution only triggers for a naked parameter. Wrap it in a one-element tuple and the union is checked as a single whole:

type IsString<T> = [T] extends [string] ? true : false;

type B = IsString<string | number>;
//   ^? type B = false   ("string | number" is not assignable to string — checked as a whole)

// Without the wrap, distribution gives a surprising union:
type IsStringNaked<T> = T extends string ? true : false;
type C = IsStringNaked<string | number>;
//   ^? type C = boolean   (true | false — distributed: string->true, number->false)

Notice C is boolean. That is true | false — distribution produced true for the string member and false for the number member, then unioned them. This is the single most common distribution surprise: a predicate that should answer “yes or no about the whole type” instead answers per-member and collapses to boolean.

never is the empty union

never is the type with zero members — the empty union. Distributing a conditional over zero members produces zero results, and the union of nothing is never:

type Wrap<T> = T extends unknown ? T[] : never;

type D = Wrap<never>;
//   ^? type D = never   (NOT never[] — there were no members to map over)

This is the famous “conditional over never yields never” gotcha. Wrap<never> is not never[]; the conditional never runs at all because there is nothing to distribute over. To force evaluation when you genuinely want to test for never, opt out of distribution:

type IsNever<T> = [T] extends [never] ? true : false;

type E = IsNever<never>;
//   ^? type E = true    (wrapped: the empty union IS assignable to [never])

Rebuilding the standard library with distribution

Exclude and Extract are pure distribution — three tokens each:

type MyExclude<T, U> = T extends U ? never : T;   // drop members of T assignable to U
type MyExtract<T, U> = T extends U ? T : never;   // keep members of T assignable to U
type MyNonNullable<T> = T extends null | undefined ? never : T;

type F = MyExclude<"a" | "b" | "c", "a">;
//   ^? type F = "b" | "c"
//   distributed: "a"->never, "b"->"b", "c"->"c"; never drops out of the union

The key insight: distribution maps each member to either itself or never, and never disappears when unioned (X | never = X). That is the whole mechanism behind filtering a union — map the unwanted members to never and they vanish. You can build a general filter the same way:

type FilterByKind<T, K> = T extends { kind: K } ? T : never;
type Events = { kind: "click"; x: number } | { kind: "key"; code: string };
type G = FilterByKind<Events, "click">;
//   ^? type G = { kind: "click"; x: number }