Union and intersection types

What it is and why it exists

A union type represents alternatives. A string | number value may be a string or a number, and a caller may supply either. Until the receiver identifies the member, it can perform only operations that are safe for every possible value.

An intersection type represents requirements that must all hold. Identified & Timestamped requires one value to have both identity and time fields. It composes independent capabilities and object fragments without requiring an inheritance relationship between their declarations.

The two operators solve different static-modeling problems: a union describes a choice, while an intersection accumulates constraints. Function inputs, parse results, state machines, and event payloads often use unions; permissions, metadata, and reusable capabilities often use intersections.

TypeScript decides compatibility through structural typing . A value can satisfy several declarations at once when it has the required structure, so a union is an inclusive “or,” not an exclusive choice.

Don’t treat unions and intersections as runtime containers. They are erased during compilation: they create no tag, copy no property, and validate no external data. Type declarations must agree with real object construction and runtime checks.

How it works

For ordinary types, it helps to approximate a type as a set of possible values. A | B contains values belonging to A or B, so it is usually wider; A & B contains only values belonging to both, so it is usually narrower. This model explains assignment direction and never, although special types such as any break the simple set intuition.

An expression of type A can be assigned to A | B because the union accepts more possibilities. The reverse usually fails because an A | B value might satisfy only B. An A & B expression can be assigned separately to A and B because it already meets both requirements.

An object union doesn’t automatically become an object with every field optional. { email: string } | { phone: string } means that at least one structure matches, and one runtime object may match both. Use a discriminated union to preserve relationships between fields instead of making every field optional.

Intersections aren’t limited to objects. string & "ready" narrows to the literal type "ready", while string & number has no ordinary value and becomes never. Object intersections are simply their most common use in a structural type system.

Safe operations on a union

When a variable is string | number, the compiler must account for both members. Both have toString(), so it can be called directly. Only strings have toUpperCase() and only numbers have toFixed(), so those operations require narrowing first.

A “common member” means a property and use that the checker can prove safe, not merely a repeated property name. If two members have functions with the same name but incompatible parameter contracts, knowing that the property exists doesn’t make a call safe.

The following table summarizes both compositions from a consumer’s point of view:

Narrowing and discriminated unions

Narrowing removes union members using runtime facts. typeof, instanceof, equality, in, and custom type predicates supply different evidence. A check must reflect the runtime value honestly; a type assertion supplies no evidence.

An object union works best when every member shares one literal discriminant. Both status: "paid" and status: "failed" exist at runtime and let the compiler narrow the whole object together with its payload. This pattern is a discriminated union .

Once every member has been handled, the remaining value has type never, the bottom type . Passing a default branch’s value to a function that accepts never turns a future unhandled member into a compile error.

This exhaustiveness guarantee covers only a union the compiler already trusts. JSON, message queues, and JavaScript callers can supply arbitrary values, so external data must still be validated from unknown before entering a discriminated union.

Intersections, overlapping properties, and runtime values

An object intersection accumulates constraints on one value. If A requires id: string and B requires createdAt: Date, then A & B requires both fields. The type alias itself doesn’t produce an object containing them.

Compatible overlapping properties narrow further. For example, { mode: string } & { mode: "safe" } has mode: "safe". Incompatible overlapping properties intersect to never, as in { id: string } & { id: number }.

A property conflict doesn’t use object spread order to choose the “last value.” JavaScript object spread does overwrite repeated names, but that is a runtime evaluation rule. An intersection requires the final value to satisfy both static constraints. Confusing the two often leads to an unsafe as A & B.

Inspect overlapping keys and their meanings before composing third-party types. If the domain truly replaces a field, remove the old constraint with Omit before adding the new one. If two fields mean different things, rename them instead of asserting over the conflict.

Examples

The next four programs cover a primitive union, a discriminated union, an object intersection, and a union with shared intersection context. Each was checked in strict mode with TypeScript 6.0.3 and actually executed with local tsx.

Narrowing a union

An identifier can arrive as a numeric database key or an external string. The function identifies the member with typeof before calling methods specific to that member.

The numeric branch can call padStart() because toString() has already produced a string. The string branch needs no assertion: after the previous branch returns, only string remains in the control flow.

This union says that two input representations are accepted; it doesn’t decide whether both forms can identify the same customer. Deduplication, ranges, and empty strings are domain rules that the function or an outer validator must still handle explicitly.

Keeping state and payload correlated with a discriminant

Each payment state carries its own required payload. After the switch checks status, it can access the corresponding field directly, while the default branch proves that the current union is exhausted.

type PaymentState =
  | { status: "pending"; attempt: number }
  | { status: "paid"; receipt: string }
  | { status: "failed"; reason: string };

function assertNever(value: never): never {
  throw new Error(`Unhandled payment: ${JSON.stringify(value)}`);
}

function summarize(state: PaymentState): string {
  switch (state.status) {
    case "pending":
      return `pending attempt ${state.attempt}`;
    case "paid":
      return `paid with ${state.receipt}`;
    case "failed":
      return `failed: ${state.reason}`;
    default:
      return assertNever(state);
  }
}

const states: PaymentState[] = [
  { status: "pending", attempt: 2 },
  { status: "paid", receipt: "rcpt-81" },
  { status: "failed", reason: "card expired" },
];

for (const state of states) {
  console.log(summarize(state));
}

pending attempt 2
paid with rcpt-81
failed: card expired

If you add { status: "refunded"; reference: string } without adding a case, state in the default branch is no longer never. TypeScript reports an error at assertNever(state).

Changing the model to { status: "pending" | "paid" | "failed"; attempt?: number; receipt?: string; reason?: string } loses the correlation. That type permits paid without a receipt and permits contradictory fields on the same value.

Combining independent capabilities with an intersection

A subscriber satisfies both the identity and preference contracts. A function receiving Subscriber can safely use fields from both sides because the caller must provide the complete intersection.

type HasIdentity = {
  id: string;
  email: string;
};

type HasPreferences = {
  locale: "en" | "zh";
  digest: boolean;
};

type Subscriber = HasIdentity & HasPreferences;

function deliveryLabel(subscriber: Subscriber): string {
  const schedule = subscriber.digest ? "daily" : "off";
  return `${subscriber.id}:${subscriber.locale}:${schedule}`;
}

const subscriber: Subscriber = {
  id: "acct-17",
  email: "[email protected]",
  locale: "zh",
  digest: true,
};

console.log(deliveryLabel(subscriber));
console.log(Object.keys(subscriber).sort().join(","));

acct-17:zh:daily
digest,email,id,locale

The second output line comes from the actual object’s keys, not from the Subscriber type. Removing email from the object literal causes a compile error; removing the type alias doesn’t change any runtime object.

These contracts have no overlapping keys, so the composition is direct. If both sides declare locale in a real project, first confirm that their types and meanings agree, then choose whether to keep the intersection, rename the fields, or reshape the object explicitly.

Adding shared context to every union member

An import result still preserves two payloads through a discriminant, but every member must also carry batchId. The parentheses form the union first, and the outer intersection applies batch context to all its members.

type ImportResult = (
  | { kind: "accepted"; records: number }
  | { kind: "rejected"; errors: string[] }
) & { batchId: string };

function report(result: ImportResult): string {
  if (result.kind === "accepted") {
    return `${result.batchId}:accepted:${result.records}`;
  }

  return `${result.batchId}:rejected:${result.errors.join("|")}`;
}

const results: ImportResult[] = [
  { kind: "accepted", records: 18, batchId: "batch-4" },
  {
    kind: "rejected",
    errors: ["missing email", "invalid locale"],
    batchId: "batch-5",
  },
];

for (const result of results) {
  console.log(report(result));
}

batch-4:accepted:18
batch-5:rejected:missing email|invalid locale

batchId is available before narrowing because every path through the union has that intersection constraint. records and errors remain member-specific and become available only after checking kind.

The parentheses state the grouping and make the shared context’s scope visible to a maintainer. If the common part grows, give it a name instead of copying the same fields into every union member.

Pitfalls

Treating a union as a property collection

Fix: add a stable literal discriminant and narrow first. If both fields must always exist, the model needs an intersection or one complete object type, not a union.

Simulating distinct states with optional fields

Fix: define one complete member per state and distinguish them with the same literal field. Use ? only when a field is genuinely optional within that member.

Assuming & merges runtime objects

Fix: create the real value through an explicit object literal, reviewed spread, or constructor, then let the compiler check the result. Don’t use as A & B as an object-merge operation.

Ignoring overlapping intersection conflicts

Fix: review the overlap of keyof before composing types. When replacing a field, use Omit<Old, "id"> & NewId to state the intention and add tests for the runtime conversion.

Swallowing new members in a generic default branch

Fix: assign the remainder to never or pass it to assertNever(). Validate unknown external values before they enter the union instead of mixing them into static state handling through a default branch.

Asserting a union at an external boundary

Fix: put the parse result into unknown immediately, verify a non-null object, the exact discriminant, and the required fields for that member, then return the domain union. Give parse failures and unknown discriminants explicit outcomes.

Further reading

• TypeScript Handbook: Everyday Types
• TypeScript Handbook: Object Types
• TypeScript Handbook: Narrowing
• TypeScript Handbook: Discriminated unions