TypeScript Intersection Types: Combine Types with &

An intersection type, written A & B, describes a value that is an A and a B at the same time. For object types that means the value has every property of both. It is how you combine existing types without writing the properties out again.

type Person = { name: string; email: string };
type Employee = { employeeId: number; team: string };

type Staff = Person & Employee; // has all four properties

const ada: Staff = { name: "Ada", email: "ada@example.com", employeeId: 7, team: "compilers" };

function badge(s: Staff): string {
  return `${s.name} (#${s.employeeId}, ${s.team})`;
}

console.log(badge(ada)); // Ada (#7, compilers)

// @ts-expect-error: Type '{ name: string; email: string; employeeId: number; }' is not assignable to type 'Staff'.
const partial: Staff = { name: "Alan", email: "alan@example.com", employeeId: 8 };

The second object leaves out team, so it is compile error TS2322, and the next line of the message says Property 'team' is missing ... but required in type 'Employee'. A Staff value can be passed anywhere a Person or an Employee is expected.

Combining Object Types

& works with any mix of type aliases, interfaces and inline object types, and with generic type parameters. That last case is where it is hard to replace: a function that adds properties to whatever object it receives can say so precisely.

function withMeta<T extends object>(obj: T, author: string): T & { author: string; savedAt: string } {
  return { ...obj, author, savedAt: "2024-03-15T10:30:00.000Z" };
}

const note = withMeta({ title: "Draft", words: 120 }, "ada");
// type: { title: string; words: number } & { author: string; savedAt: string }

console.log(note.title, note.words, note.author); // Draft 120 ada
console.log(note.savedAt);                         // 2024-03-15T10:30:00.000Z

The caller keeps the exact type of what it passed in (title, words) plus the two added properties. An interface ... extends cannot express "whatever T is, plus these", because an interface cannot extend a type parameter.

Conflicting Properties Become never

When both sides declare the same property, the property's type is the intersection of the two. If those types have no value in common, the property becomes never, and the compiler says nothing until you try to create a value:

// This does not compile: id cannot be a string and a number at once
type WithStringId = { id: string; name: string };
type WithNumberId = { id: number };

type Account = WithStringId & WithNumberId; // no error on this line

const r: Account = { id: "u1", name: "Ada" };
console.log(r);

index.ts(7,22): error TS2322: Type 'string' is not assignable to type 'never'.

The error points at the object, not at the type that caused it, which makes these bugs slow to trace. Hovering r.id in the editor shows its type: never. When the conflicting property is a literal tag, as in type Shape = { kind: "circle" } & { kind: "square" }, TypeScript goes further and reduces the whole intersection to never. Reading a property of such a value then explains why: Property 'kind' does not exist on type 'never'. The intersection 'Shape' was reduced to 'never' because property 'kind' has conflicting types in some constituents.

interface ... extends catches the same conflict at the declaration instead, with error TS2430. That is the main practical difference between the two; the interface vs type page compares them side by side.

Compatible Overlaps Narrow the Property

If the two property types do overlap, the result is the overlap. That is useful, not an error:

type Editable = { id: string | number; tags: string[] };
type Stored = { id: string; createdAt: string };

type Doc = Editable & Stored; // id: (string | number) & string, which is string

const doc: Doc = { id: "d1", tags: ["draft"], createdAt: "2024-03-15" };
console.log(doc.id.toUpperCase()); // D1: id is a string, so string methods are allowed

type Letters = "a" | "b" | "c";
type Later = "b" | "c" | "d";
type Both = Letters & Later; // "b" | "c": what the two unions have in common

const shared: Both[] = ["b", "c"];
console.log(shared); // [ 'b', 'c' ]

The second half shows what & does to unions: it keeps the members both sides have in common. Thinking of types as sets of values makes this predictable. A | B is the union of the two sets, A & B is their overlap, and an overlap with nothing in it is never.

Intersection vs Union

The names come from set theory, and they feel backwards when applied to object properties:

An intersection of object types has more properties precisely because it allows fewer values: only objects that have everything.

Intersection vs extends

For combining a few object type aliases, & is idiomatic and fine. For a type built from many parts, or a public API type, extends gives earlier errors and cheaper type checks.

Intersections with Primitives: Branding

Intersecting a primitive with an object type does not produce never: string & { readonly __brand: "UserId" } is a string that carries an extra, compile-time-only marker. No real string has that property, which is exactly the point: only code that deliberately asserts the brand can create one, so a plain string or an OrderId can no longer be passed where a UserId is expected. That technique has its own page, branded types.