Unions and intersections

One-of versus all-of

When you reach for | or &, ask yourself: can the caller provide one thing, or must they provide everything? The answer determines which operator you need — and using the wrong one compiles fine while silently breaking type safety.

A union A | B describes a value that is either an A or a B. You do not know which one statically, so the only members the checker lets you touch are the ones present in both.

An intersection A & B describes a value that is simultaneously an A and a B. It has every member of both, because it must satisfy both contracts at once.

type Circle = { kind: "circle"; radius: number };
type Square = { kind: "square"; side: number };

type Shape = Circle | Square;
//   ^? type Shape = Circle | Square

function describe(s: Shape) {
  s.kind;
  // ^? (property) kind: "circle" | "square"   — common to both, OK
  s.radius;
  // Error: Property 'radius' does not exist on type 'Shape'.
  //   Property 'radius' does not exist on type 'Square'.
}

kind exists on both members, so it is reachable and its type is the union of the two literal types. radius exists only on Circle, so on the union it is unreachable until you narrow (next lesson). This is the whole reason narrowing exists.

Intersection merges object members

For object types, A & B is a new type carrying all properties of both. It is the natural way to “add fields” to a shape.

type WithId = { id: string };
type WithTimestamps = { createdAt: Date; updatedAt: Date };

type Entity = WithId & WithTimestamps;

const row: Entity = { id: "u1", createdAt: new Date(), updatedAt: new Date() };
//    ^? const row: Entity
// Drop any one field and the checker complains:
const bad: Entity = { id: "u1", createdAt: new Date() };
// Error: Property 'updatedAt' is missing in type
//   '{ id: string; createdAt: Date; }' but required in type 'WithTimestamps'.

If both sides declare the same property with compatible types, the result keeps it. If they declare the same property with incompatible types, the merged property collapses to never — see below.

Incompatible primitives intersect to never

never is the empty type — the set of zero values. No value can be both a string and a number at the same time, so the checker reduces the impossible intersection to never:

type Impossible = string & number;
//   ^? type Impossible = never

type AlsoNever = "a" & "b";
//   ^? type AlsoNever = never

This is silent. It does not error at the type alias — it errors only when you later try to assign something to it, because nothing is assignable to never:

const x: string & number = "hi";
// Error: Type 'string' is not assignable to type 'never'.

The dangerous version hides inside object intersections. If two object types share a key whose value types are disjoint, only that property becomes never, and the object type as a whole still looks usable:

type A = { status: "active"; v: number };
type B = { status: "archived"; v: number };

type Both = A & B;
//   ^? type Both = A & B
type S = Both["status"];
//   ^? type S = never   — "active" & "archived" is impossible

Both is uninhabitable, but you only discover it when you try to construct a value or read status. This is the classic trap of reaching for & when you meant a union.

Behaviour at function parameters

A function typed to accept a union must handle every member, so its body may use only common members. A function typed to accept an intersection is easier to satisfy inside the body (more members guaranteed) but harder to call (the argument must be both):

declare function logUnion(x: number | string): void;
logUnion(1);        // OK
logUnion("a");      // OK

declare function logBoth(x: { a: 1 } & { b: 2 }): void;
logBoth({ a: 1 });
// Error: Property 'b' is missing in type '{ a: 1; }'
//   but required in type '{ b: 2; }'.
logBoth({ a: 1, b: 2 }); // OK

Note the asymmetry in assignability: a number is assignable to number | string (a part fits the whole-or), but you cannot pass a partial object to an & parameter (the whole-and demands everything).

interface extends versus A & B

Both compose object shapes, but they are not interchangeable. interface Child extends Parent {} checks for conflicts eagerly and errors at declaration. Intersection defers and silently produces never on conflict:

interface Base { v: string }
interface Wrong extends Base { v: number }
// Error: Interface 'Wrong' incorrectly extends interface 'Base'.
//   Types of property 'v' are incompatible. Type 'number' is not assignable to type 'string'.

type AlsoWrong = Base & { v: number };
//   ^? type AlsoWrong = Base & { v: number }   — no error here…
type V = AlsoWrong["v"];
//   ^? type V = never   — …the conflict surfaces only when you read it

Prefer extends for nominal “is-a” hierarchies that you want validated at the declaration site; reach for & to mix orthogonal, conflict-free aspects (mixins, “add timestamps”, “add an id”). For unions that vary by a tag, you will model them as discriminated unions later in this unit.