Intersection types

One object with both sets of properties

A site shows a small card for each user: their name and their email. Your code already has a type for each half. A Profile has a name, and a Contact has an email. The card needs both. You could write a third type that repeats every property, but TypeScript lets you combine the two you have:

1type Profile = { name: string };2type Contact = { email: string };3type UserCard = Profile & Contact;4 5const asha: UserCard = { name: "Asha", email: "asha@example.com" };6console.log(asha.name);7console.log(asha.email);8//               ^?

Lines 1 and 2 are two small type aliases: names for object types. Line 3 uses &, which you met briefly in Type aliases & interfaces. Profile & Contact is read "Profile and Contact", and it means a value that is both at the same time. This is called an intersection type, and the & sign makes it.

Line 5 makes asha, a UserCard, with a name and an email. Lines 6 and 7 print Asha and asha@example.com. The query on line 8 asks what TypeScript knows about email: (property) email: string. The email came from Contact, and TypeScript found it through the &. There are no errors.

& means and: every property from both

An intersection is most useful as a parameter type: the function can use every property from both types. Here a function shows a user card, and is called twice. The second call gets an error on purpose:

1type Profile = { name: string };2type Contact = { email: string };3 4function showCard(user: Profile & Contact) {5  return `${user.name} <${user.email}>`;6}7 8console.log(showCard({ name: "Ravi", email: "ravi@example.com" }));9console.log(showCard({ name: "Asha" }));

Line 4 says showCard takes a user that is a Profile & Contact. Line 5 can read user.name and user.email, because the type promises both. Line 8 passes both, and prints Ravi <ravi@example.com>. Line 9 passes only a name, so TypeScript marks it:

• Argument of type '{ name: string; }' is not assignable to parameter of type 'Profile & Contact' means "the value you passed doesn't fit what the function asks for". An argument is a value you pass to a function.
• The next line of the message says why: Property 'email' is missing in type '{ name: string; }' but required in type 'Contact'. The object passes the Profile part and fails the Contact part.

Run it anyway, and line 9 prints Asha <undefined>: the card a user would see without the check.

You already know the other way to combine two types: the union Profile | Contact, read "Profile or Contact". The two signs look alike and mean opposite things. Try both: type a different type on line 3, and watch the list under the code as you type.

1type Profile = { name: string };2type Contact = { email: string };3type UserCard = Profile & Contact;4 5const asha: UserCard = { name: "Asha", email: "asha@example.com" };6console.log(asha.name, asha.email);

With Profile & Contact there are no errors. With Profile | Contact, line 5 is still fine, because the object is a Profile. But line 6 gets two errors: a UserCard might be only a Contact, with no name, or only a Profile, with no email. With just Profile or just Contact, the object on line 5 has a property the type doesn't know. And each extra & { … } adds one more thing the object must have.

The table below puts the two signs side by side. Read each row as a question, then each sign's answer.

The name "intersection" comes from that last row. Think of all the objects that fit Profile, and all the objects that fit Contact. The intersection is the objects in both groups. That's fewer objects, and each one has more properties.

Mixing in shared fields

Data from a server often has the same few fields on every record: an id, and when it was created and changed. Instead of writing them into every type, you write them once, as small types, and add them where they're needed with &. This is called mixing in fields:

1type WithId = { id: number };2type Timestamps = { createdAt: string; updatedAt: string };3 4type Todo = WithId & Timestamps & { title: string; done: boolean };5type Note = WithId & Timestamps & { text: string };6 7function lastChange(item: WithId & Timestamps) {8  return `#${item.id} changed on ${item.updatedAt}`;9}10 11const todo: Todo = { id: 1, title: "Buy milk", done: false, createdAt: "Oct 1", updatedAt: "Oct 2" };12const note: Note = { id: 9, text: "Oat milk?", createdAt: "Oct 3", updatedAt: "Oct 3" };13console.log(lastChange(todo));14console.log(lastChange(note));

Line 1 is WithId: just an id. Line 2 is Timestamps: the two dates. Line 4 makes a Todo from three parts: an id, the timestamps, and its own title and done. Line 5 makes a Note from the same two shared parts and its own text.

The shared parts help functions too. Line 7's lastChange takes anything that is WithId & Timestamps, so lines 13 and 14 can pass it a to-do or a note. They print #1 changed on Oct 2 and #9 changed on Oct 3. A Todo has more properties than lastChange asks for, and that's fine: a variable with extra properties still fits.

Now build a to-do's type one part at a time. The object on line 5 stays the same; only the type on line 3 changes:

1type WithId = { id: number };2type Timestamps = { createdAt: string };3type Todo = { title: string; done: boolean };4 5const todo: Todo = { id: 1, title: "Buy milk", done: false };6console.log(todo.title);

Each part you mix in adds properties the object must have. Just the fields is too few: the object's id is unknown. & WithId matches the object exactly. & WithId & Timestamps asks for a createdAt the object doesn't have.

JavaScript has its own ways to mix objects together while the code runs, and TypeScript types them with intersections. Object.assign(target, …sources) copies every property of the sources into the target object and gives the target back (the Mixins lesson uses it):

1type Profile = { name: string };2type Contact = { email: string };3 4const profile: Profile = { name: "Asha" };5const contact: Contact = { email: "asha@example.com" };6 7const card = Object.assign({}, profile, contact);8//    ^?9console.log(card.name, card.email);

Lines 4 and 5 make a profile and a contact. Line 7 copies both into a new empty object. The query on line 8 shows TypeScript's answer: const card: Profile & Contact. TypeScript's own description of Object.assign says it returns the intersection of its arguments' types. Line 9 prints Asha asha@example.com.

When both types name the same property

So far, the two parts of each intersection had different properties. What if both have a property with the same name? Then the value must fit both property types at once. When one type is narrower, the narrower one wins:

1type Button = { label: string; variant: string };2type DangerButton = Button & { variant: "danger" };3 4const deleteButton: DangerButton = { label: "Delete", variant: "danger" };5console.log(deleteButton.variant);6//                       ^?

Line 1 says any Button has a variant that is a string. Line 2 adds a part where variant is the exact text "danger": a literal type, a type with one value. The only value that is a string and is "danger" is "danger". The query on line 6 confirms it: (property) variant: "danger". Line 5 prints danger.

Now two types that disagree. A site reads users from its database, where an id is a number. Its login service also describes users, but there an id is a string. Combining them goes wrong, on purpose here:

1type DbUser = { id: number; name: string };2type AuthUser = { id: string; email: string };3type SessionUser = DbUser & AuthUser;4 5const asha: SessionUser = { id: 7, name: "Asha", email: "asha@example.com" };6console.log(asha.id);7//               ^?

Line 3 combines the two, and TypeScript says nothing: the type itself is allowed. The trouble shows up on line 5, when you make a session user: Type 'number' is not assignable to type 'never'. The query on line 7 shows why: (property) id: never.

never is the type with no values at all. The id must be a number and a string at the same time, and no value is both. So any value you put there gets an error. When the code runs, the types are gone, and line 6 prints 7.

Sometimes the whole object type becomes never, not only one property. That happens when the clashing property holds literal types, like a status that is exactly "loading" or exactly "done":

1type Loading = { status: "loading" };2type Done = { status: "done" };3 4type LoadingAndDone = Loading & Done;5//   ^?6type IdText = string & number;7//   ^?

Lines 1 and 2 describe two states of a request. Line 4 asks for a request that is loading and done at once. The query on line 5 says type LoadingAndDone = never: no object can be in both states, so TypeScript drops the whole type. Line 6 does the same with two basic types. Nothing is a string and a number, so the query on line 7 says never too.

Intersections vs extends

Interfaces have their own way to build on other types: extends, from Type aliases & interfaces. An interface is another way to name an object type, and interface B extends A means "B has everything A has, plus what B adds". When nothing clashes, it gives the same result as &:

1type Profile = { name: string };2type Contact = { email: string };3 4type UserCard = Profile & Contact;5interface UserCardShape extends Profile, Contact {}6 7const asha: UserCard = { name: "Asha", email: "asha@example.com" };8const same: UserCardShape = asha;9console.log(same.email);

Line 4 builds UserCard with &. Line 5 builds UserCardShape with extends, from the same two parts; the empty {} means it adds nothing of its own. Line 8 stores a UserCard in a UserCardShape with no error, because the shapes match. Line 9 prints asha@example.com.

The difference shows up with a clash. Here are the database and login users again, combined with extends:

1type DbUser = { id: number; name: string };2type AuthUser = { id: string; email: string };3 4interface SessionUser extends DbUser, AuthUser {}

This time TypeScript marks line 4, the type itself, on purpose here: Interface 'SessionUser' cannot simultaneously extend types 'DbUser' and 'AuthUser'. "Simultaneously" means "at the same time": the two parents disagree, and the next line of the message names the property, id. You find out where the mistake is, not later, when someone makes an object.

& can do one thing extends can't: combine a union. Here a request is loading or done, and either way it has a url. Line 6 tries it with an interface, and gets an error on purpose:

1type Loading = { status: "loading" };2type Done = { status: "done"; items: string[] };3type Status = Loading | Done;4 5type TodoRequest = Status & { url: string };6interface TodoRequestShape extends Status { url: string }7 8const request: TodoRequest = { status: "loading", url: "/todos" };9console.log(request.status, request.url);

Line 3 names the union Status. Line 5 adds a url with &, which works: each choice gets a url. Line 6 says An interface can only extend an object type or intersection of object types with statically known members. "Statically known members" means properties TypeScript knows before the code runs. A union has two possible sets, so it isn't one. Line 9 prints loading /todos.

The table below compares the two. Read each row as a question, then each way's answer.

A simple rule: for object types you name and build on, use interface … extends, so clashes are reported where they are. Use & where extends can't go: unions, a quick combination in a parameter, or types that aren't objects.

Adding server fields to a saved draft

A blog editor saves a draft post. The server keeps the title and body, and adds its own fields: an id and the time it saved the draft. The save function's return type says exactly that:

1type Draft = { title: string; body: string };2type Saved = { id: number; savedAt: string };3 4function saveDraft(draft: Draft): Draft & Saved {5  return { ...draft, id: 42, savedAt: "10:30" };6}7 8const post = saveDraft({ title: "Hello", body: "My first post" });9console.log(`${post.title} saved as #${post.id} at ${post.savedAt}`);

Line 1 is what the user writes. Line 2 is what the server adds. Line 4 says saveDraft takes a Draft and returns a Draft & Saved. Line 5 builds that with spread: ...draft copies the title and body (the Spread and rest lesson covers ...), and the two server fields are added after. Line 9 prints Hello saved as #42 at 10:30.

The return type also checks the function. Here line 5 forgets the time, on purpose:

1type Draft = { title: string; body: string };2type Saved = { id: number; savedAt: string };3 4function saveDraft(draft: Draft): Draft & Saved {5  return { ...draft, id: 42 };6}7 8const post = saveDraft({ title: "Hello", body: "My first post" });9console.log(`${post.title} saved at ${post.savedAt}`);

TypeScript marks line 5: Type '{ id: number; title: string; body: string; }' is not assignable to type 'Draft & Saved', and the next line of the message says Property 'savedAt' is missing. Without the check, line 9 would print Hello saved at undefined.

Common mix-ups

& is only a type. It tells TypeScript what a value has, and it's removed before the code runs. To combine two real objects, you still use JavaScript:

1type Profile = { name: string };2type Contact = { email: string };3 4const profile: Profile = { name: "Asha" };5const contact: Contact = { email: "asha@example.com" };6 7const both = { ...profile, ...contact };8console.log(Object.keys(both));

Lines 4 and 5 make two objects. Line 7 copies both into a new one with spread. Line 8 prints its keys, name and email. Writing Profile & Contact somewhere would never do this copying for you.

• "& keeps only the properties both types share." No. A Profile & Contact has every property of both. "Only what both share" is what you can read from a union.
• "& joins two objects together." No. It's a type, removed before the code runs. Spread or Object.assign joins real objects.
• "An intersection with a clash is an error." No. TypeScript accepts the type, and the clashing property becomes never. You see an error only when you make a value.
• "The second type's property replaces the first." No. Both stay, and the value must fit both: string and "danger" leave only "danger".
• "string & number is a value that is text or a number." No. That's string | number. Nothing is both, so string & number is never.
• "& and extends are the same thing." No. They match when nothing clashes, but extends reports a clash on the type, and only & can combine a union.

Practice exercises

Each exercise is TypeScript. When you fix code, press Edit & run on the starter code: the errors update as you type, and the console shows what it prints. Try a guess first, then use the hints.

type Profile = { name: string; city: string };
type Contact = { email: string };

const ravi: Profile & Contact = { name: "Ravi", email: "ravi@example.com" };

1type Profile = { name: string; city: string };2type Contact = { email: string };3 4const ravi: Profile & Contact = { name: "Ravi", city: "Pune", email: "ravi@example.com" };

1type Settings = { theme: string } & { fontSize: number };2 3const settings: Settings = { theme: "dark", fontSize: 16 };4const size = settings.fontSize;

1type Settings = { theme: string } & { fontSize: number };2 3const settings: Settings = { theme: "dark", fontSize: 16 };4const size = settings.fontSize;5//    ^?

1type WithId = { id: number };2type Product = { name: string; price: number };3type SavedProduct = Product;4 5const tea: SavedProduct = { id: 7, name: "Tea", price: 3 };6console.log(`#${tea.id} ${tea.name} $${tea.price}`);

1type WithId = { id: number };2type Product = { name: string; price: number };3type SavedProduct = Product & WithId;4 5const tea: SavedProduct = { id: 7, name: "Tea", price: 3 };6console.log(`#${tea.id} ${tea.name} $${tea.price}`);

1type Shirt = { size: string } & { size: "S" | "M" | "L" };2 3const shirt: Shirt = { size: "M" };4const size = shirt.size;

1type Shirt = { size: string } & { size: "S" | "M" | "L" };2 3const shirt: Shirt = { size: "M" };4const size = shirt.size;5//    ^?

type DbUser = { id: number; name: string };
type AuthUser = { id: string; email: string };
type SessionUser = DbUser & AuthUser;

const asha: SessionUser = { id: 7, name: "Asha", email: "asha@example.com" };
console.log(asha.id);

1type DbUser = { id: number; name: string };2type AuthUser = { authId: string; email: string };3type SessionUser = DbUser & AuthUser;4 5const asha: SessionUser = { id: 7, authId: "u-7", name: "Asha", email: "asha@example.com" };6console.log(asha.id, asha.authId);

1type Button = { label: string; variant: string };2type IconButton = Button & { variant: number; icon: string };3 4const save: IconButton = { label: "Save", variant: 1, icon: "disk" };

1type Button = { label: string; variant: string };2interface IconButton extends Button { icon: string }3 4const save: IconButton = { label: "Save", variant: "icon", icon: "disk" };5console.log(save.variant);

Check your understanding

For each question, ask two things: what must a value have to fit the type, and what does the code do when it runs, after the types are gone? The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A & B is a value that is an A and a B at once. For objects, it has every property of both.
• | means one or the other; & means both. A union lets more objects in; an intersection asks more of each one.
• Small types like WithId and Timestamps can be mixed into many types, and Object.assign returns an intersection.
• When both parts have the same property, the value must fit both types. A narrower type wins.
• When the property types can't both be true, the property becomes never, and the error appears only when you make a value.
• interface … extends reports a clash on the type itself; & can also combine unions and other types.

Coming next: Declaration merging. Interfaces with the same name join together, which is how libraries let you add to their types, like the browser's Window.