Structural typing

An object fits if it has the right properties

In JavaScript, a function that reads user.name works with any object that has a name. It doesn't care what else the object holds, or where it came from:

function greet(user) {
  return `Hi, ${user.name}`;
}

console.log(greet({ name: "Asha", email: "asha@example.com" }));
console.log(greet({ name: "Ravi" }));

Lines 1 to 3 make a greet function that reads user.name. Line 5 passes an object with a name and an email, and prints Hi, Asha. Line 6 passes an object with only a name, and prints Hi, Ravi. Both work, because both objects have a name (Object basics covers objects and properties).

TypeScript checks this the same way. Here is the function with a type for its parameter:

1type User = { name: string };2 3function greet(user: User) {4  return `Hi, ${user.name}`;5}6 7const asha = { name: "Asha", email: "asha@example.com", cartItems: 2 };8//    ^?9console.log(greet(asha));

Line 1 is a type alias: type User = … gives the name User to an object type, a list of the properties an object must have and the type of each (the Object types lesson covers writing them). Here the list has one entry, a name that is a string (text). Line 3 says greet takes a User.

Line 7 makes asha without saying it's a User. The query on line 8 shows the type TypeScript worked out from the value: an object with a name, an email, and a number of cartItems. Line 9 passes it to greet. There are no errors, and it prints Hi, Asha.

TypeScript never asked whether asha was declared as a User. It asked one question: does asha have a name that is text? It does, so it fits. The extra email and cartItems don't matter.

This way of checking is called structural typing. The "structure", or shape, of a type is the list of its property names and their types. TypeScript compares shapes, not names. You may also hear it called duck typing, from the saying "if it walks like a duck and quacks like a duck, it's a duck".

Shapes, not names

A type's name is only a label for its shape. So two types with different names and the same properties are the same type to TypeScript:

1type Customer = { name: string; email: string };2type Subscriber = { name: string; email: string };3 4function sendNewsletter(subscriber: Subscriber) {5  return `Sending news to ${subscriber.email}`;6}7 8const asha: Customer = { name: "Asha", email: "asha@example.com" };9console.log(sendNewsletter(asha));

Lines 1 and 2 make two types, Customer and Subscriber, each with a name and an email. Line 4 says sendNewsletter takes a Subscriber. Line 8 makes asha a Customer. Line 9 passes the customer where a subscriber goes. There are no errors, and it prints Sending news to asha@example.com.

An interface is another way to name an object type. You write interface Customer { … } with the properties inside, instead of type Customer = { … }. The Type aliases & interfaces lesson compares the two. For this lesson, the point is that TypeScript compares interfaces by shape too:

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

Lines 1 to 4 make an interface called Customer. Line 6 makes a type alias called Contact with the same two properties. Line 8 makes a Customer, and line 9 stores it in a Contact variable. The query on line 10 shows const contact: Contact, there are no errors, and line 11 prints asha@example.com.

When one type fits another

When a value fits a type, TypeScript says it is assignable to that type: allowed to be stored in a variable of that type, or passed to a parameter of that type. To decide, TypeScript goes through the type's list, one property at a time:

1. Does the value have a property with this name? If not, the property is missing.
2. Does that property's type fit the type the list says? If not, the two are incompatible.
3. Once every property on the list is checked, anything else on the value is ignored.

Try it. The code below has a CartItem type with a name and a price, and an addToCart function that takes one. Type the inside of the cake object on line 7, and watch what TypeScript says about the call on line 8:

1type CartItem = { name: string; price: number };2 3function addToCart(item: CartItem) {4  console.log(`Added ${item.name} for $${item.price}`);5}6 7const cake = { name: "Cake", price: 4 };8addToCart(cake);

Each suggestion tests one step of the list. Remove the price, and the call gets an error. The message has two lines. The first, Argument of type '{ name: string; }' is not assignable to parameter of type 'CartItem', means "this value doesn't fit the parameter". The second line says why: Property 'price' is missing. With price: "4", the second line becomes Types of property 'price' are incompatible: the price is there, but its type is wrong. Renaming name to title makes name missing, because names have to match exactly. An extra inStock, or the same properties in a different order, change nothing.

The table below sums up the tries. Read each row as: this cake object, does it fit CartItem, and why.

The check has a direction. A Product with a name, a price, and a stock count fits where a CartItem goes, because it has everything a cart item needs. A CartItem doesn't fit where a Product goes, because it has no stock. Press each button to change line 7, and compare what the type needs with what the value has:

1type Product = { name: string; price: number; stock: number };2type CartItem = { name: string; price: number };3 4const tea: Product = { name: "Tea", price: 3, stock: 9 };5const cake: CartItem = { name: "Cake", price: 4 };6 7const item: CartItem = tea;

tea into CartItem and tea into { name: string } fit: the type asks for less than tea has. cake into Product gets Property 'stock' is missing in type 'CartItem' but required in type 'Product'. tea into { price: string } gets Types of property 'price' are incompatible, because the price is a number and the type wants text. tea into { name: string } also shows that a type doesn't need a name at all: an object type written in place is compared the same way.

Extra properties are fine

Extra properties being fine is what makes structural typing useful in frontend code. Data from a server usually has more fields than any one function needs:

1type AvatarUser = { name: string; avatarUrl: string };2 3function avatarAlt(user: AvatarUser) {4  return `Photo of ${user.name}`;5}6 7const reply = {8  id: 42,9  name: "Asha",10  email: "asha@example.com",11  avatarUrl: "/avatars/asha.png",12  joined: "2024-03-01",13};14console.log(avatarAlt(reply));

Line 1 says an AvatarUser has a name and an avatar address. Line 3 says avatarAlt takes one. Lines 7 to 13 are a user as a server might send it, with five fields. Line 14 passes the whole reply. It has the two fields AvatarUser needs, so there are no errors, and it prints Photo of Asha. You don't have to copy the two fields into a new object first.

The check goes inside nested objects too, with the same rule at every level:

1type Order = { id: number; customer: { name: string } };2 3const reply = { id: 7, customer: { name: "Asha", email: "asha@example.com" }, total: 12 };4const order: Order = reply;5//    ^?6console.log(order.customer.name);

Line 1 says an Order has an id and a customer, and the customer has a name. Line 3's reply has an extra total, and its customer has an extra email. Line 4 stores it as an Order, and the query on line 5 shows const order: Order. Both levels have what the type needs, so there are no errors, and line 6 prints Asha.

The type doesn't remove the extras. They're still on the object when the code runs. The type only decides what you may read through that name:

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

Line 1 says a Contact has only a name. Line 9 passes asha, who also has an email. Inside the function, line 4 lists the object's real property names with Object.keys and prints name, email: the email is there. Line 5 reads contact.email, and TypeScript marks it, on purpose: Property 'email' does not exist on type 'Contact'. That means "the type you gave this parameter doesn't list an email, so I can't promise there is one". Run it anyway, and line 5 prints asha@example.com.

There is one place where extra properties do get an error: an object you write right where the type is expected, like inside the call itself:

1type User = { name: string };2 3function greet(user: User) {4  return `Hi, ${user.name}`;5}6 7console.log(greet({ name: "Asha", email: "asha@example.com" }));

This is the overview's greet, but line 7 writes the object inside the call instead of passing a variable. TypeScript marks the email, on purpose: Object literal may only specify known properties, and 'email' does not exist in type 'User'. An object literal is an object written out with braces, like { name: "Asha" }. When it goes straight into a typed spot, nothing else can ever read its extra properties, so TypeScript guesses the extra is a mistake, often a typo. The code still prints Hi, Asha. The next lesson, Excess property checks, is all about this extra check.

Comparing with nominal typing

Many languages, like Java and C#, use nominal typing. "Nominal" means "by name": a value fits a type only if it was declared with that type's name, or with a type that says it extends it. TypeScript doesn't work that way, even for classes (Class basics covers JavaScript classes):

1class Product {2  name: string;3  price: number;4 5  constructor(name: string, price: number) {6    this.name = name;7    this.price = price;8  }9}10 11function priceTag(product: Product) {12  return `${product.name}: $${product.price}`;13}14 15console.log(priceTag(new Product("Tea", 3)));16console.log(priceTag({ name: "Cake", price: 4 }));

Lines 1 to 9 make a Product class with a name and a price. Line 11 says priceTag takes a Product. Line 15 passes a real Product, made with new, and prints Tea: $3. Line 16 passes a plain object that was never made by the class. It has a name and a price, so it fits too, and prints Cake: $4. In Java, line 16 would be an error. (A class with private members is the exception; a later lesson, public, private, protected & #private, covers it. Classes in TypeScript covers the class syntax.)

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

TypeScript works this way because JavaScript code passes plain objects around everywhere: replies from servers, options for functions, props in components. Checking shapes describes that code as it is.

Structural typing has one cost. When two kinds of value have the same shape, TypeScript can't tell them apart. IDs are the usual example:

1type UserId = string;2type ProductId = string;3 4function loadUser(id: UserId) {5  return `Loading user ${id}`;6}7 8const productId: ProductId = "p-7";9console.log(loadUser(productId));

Lines 1 and 2 make two type aliases, UserId and ProductId. Line 4 says loadUser takes a UserId. Line 8 makes a product ID, and line 9 passes it to loadUser by mistake. There are no errors, and it prints Loading user p-7. A type alias doesn't make a new type. Both names mean string, and a string goes where a string goes.

To keep them apart, give them different shapes. One way is to wrap each ID in an object with a kind property that must hold one exact text:

1type UserId = { kind: "user"; value: string };2type ProductId = { kind: "product"; value: string };3 4function loadUser(id: UserId) {5  return `Loading user ${id.value}`;6}7 8const productId: ProductId = { kind: "product", value: "p-7" };9console.log(loadUser(productId));

In line 1, kind: "user" means the kind property must be exactly the text "user", not any string (the Literal types lesson covers this). Line 2 does the same with "product". Now the two shapes differ, and line 9 gets an error, on purpose: Types of property 'kind' are incompatible, and below it, Type '"product"' is not assignable to type '"user"'. The mix-up is caught before the code runs. A later lesson, Branded types, shows a way to keep IDs apart while they stay plain strings when the code runs.

One product card, two sources of data

A shop shows the same product card on the catalog page and in search results. The two lists come from different places, so their objects have different extra fields. With structural typing, one card function takes both:

1type CardProduct = { name: string; price: number; imageUrl: string };2 3function productCard(product: CardProduct) {4  return `${product.name} ($${product.price}) ${product.imageUrl}`;5}6 7const fromCatalog = { id: 1, name: "Tea", price: 3, imageUrl: "/img/tea.png", stock: 9 };8const fromSearch = { name: "Cake", price: 4, imageUrl: "/img/cake.png", score: 0.92 };9 10console.log(productCard(fromCatalog));11console.log(productCard(fromSearch));

Line 1 lists the three things a card shows: a name, a price, and an image address. Line 7 is a catalog product, with an id and a stock as well. Line 8 is a search result, with a score that says how well it matched. Lines 10 and 11 pass both. Each has the three properties a card needs, so there are no errors, and the code prints Tea ($3) /img/tea.png and Cake ($4) /img/cake.png.

Now say the search service stops sending images:

1type CardProduct = { name: string; price: number; imageUrl: string };2 3function productCard(product: CardProduct) {4  return `${product.name} ($${product.price}) ${product.imageUrl}`;5}6 7const fromSearch = { name: "Cake", price: 4, score: 0.92 };8 9console.log(productCard(fromSearch));

Line 7's search result has no imageUrl. TypeScript marks line 9, on purpose: Property 'imageUrl' is missing. Plain JavaScript would draw a card with the image address undefined, and the code prints Cake ($4) undefined. Listing only what a function uses, as CardProduct does, keeps it open to every object that has those properties, and still catches the ones that don't.

Common mix-ups

• "An object has to be declared as a type to fit it." No. asha was never declared as a User, and it fits, because it has a name.
• "Extra properties are always an error." No. Extras on a variable are fine. Only an object literal written right where the type is expected gets the extra check, which the next lesson covers.
• "Two types with different names are different types." No. Customer and Subscriber have the same shape, so they're interchangeable.
• "A type alias makes a new type." No. type UserId = string is just another name for string, so any string fits it, including a product ID.
• "If A fits B, then B fits A." No. A Product fits where a CartItem goes, but a CartItem has no stock, so it doesn't fit where a Product goes.
• "The type removes the extra properties." No. Types are gone when the code runs. The object keeps every property; the type only limits what you may read through that name.
• "Classes are compared by name, as in Java." No. A plain object with the same properties fits a class type, unless the class has private members.

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 Shopper = { name: string };

function welcome(shopper: Shopper) {
  return `Welcome back, ${shopper.name}`;
}

const asha = { name: "Asha", cartItems: 3, vip: true };
console.log(welcome(asha));

1type Shopper = { name: string };2 3function welcome(shopper: Shopper) {4  return `Welcome back, ${shopper.name}`;5}6 7const asha = { name: "Asha", cartItems: 3, vip: true };8console.log(welcome(asha)); // no error: asha has a name

type Address = { street: string; city: string; zip: string };

function shippingLabel(address: Address) {
  return `${address.street}, ${address.city} ${address.zip}`;
}

const home = { street: "12 Park Road", city: "Pune" };
console.log(shippingLabel(home));

1type Address = { street: string; city: string; zip: string };2 3function shippingLabel(address: Address) {4  return `${address.street}, ${address.city} ${address.zip}`;5}6 7const home = { street: "12 Park Road", city: "Pune", zip: "411001" };8console.log(shippingLabel(home));

1type CartItem = { name: string; price: number };2 3function lineText(item: CartItem) {4  return `${item.name}: $${item.price}`;5}6 7const reply = { title: "Tea", cost: 3 };8console.log(lineText(reply));

1type CartItem = { name: string; price: number };2 3function lineText(item: CartItem) {4  return `${item.name}: $${item.price}`;5}6 7const reply = { title: "Tea", cost: 3 };8const item = { name: reply.title, price: reply.cost };9console.log(lineText(item));

1type User = { name: string; email: string };2type Product = { name: string; price: number };3 4function userTag(user: User) {5  return `[${user.name}]`;6}7 8function productTag(product: Product) {9  return `[${product.name}]`;10}11 12const asha: User = { name: "Asha", email: "asha@example.com" };13const tea: Product = { name: "Tea", price: 3 };14console.log(userTag(asha), productTag(tea));

1type User = { name: string; email: string };2type Product = { name: string; price: number };3 4function nameTag(thing: { name: string }) {5  return `[${thing.name}]`;6}7 8const asha: User = { name: "Asha", email: "asha@example.com" };9const tea: Product = { name: "Tea", price: 3 };10console.log(nameTag(asha), nameTag(tea));

1type UserId = string;2type ProductId = string;3 4function removeFromWishlist(id: ProductId) {5  return `Removing product ${id}`;6}7 8const userId: UserId = "u-42";9console.log(removeFromWishlist(userId));

1type UserId = { kind: "user"; value: string };2type ProductId = { kind: "product"; value: string };3 4function removeFromWishlist(id: ProductId) {5  return `Removing product ${id.value}`;6}7 8const userId: UserId = { kind: "user", value: "u-42" };9console.log(removeFromWishlist(userId));

type Product = { name: string; price: number; stock: number };
type CartItem = { name: string; price: number };

const tea: Product = { name: "Tea", price: 3, stock: 9 };
const cake: CartItem = { name: "Cake", price: 4 };
const first: CartItem = tea;
const second: Product = cake;

1type Product = { name: string; price: number; stock: number };2type CartItem = { name: string; price: number };3 4const tea: Product = { name: "Tea", price: 3, stock: 9 };5const cake: CartItem = { name: "Cake", price: 4 };6const first: CartItem = tea;7const second: Product = { ...cake, stock: 0 };8console.log(second.stock);

Check your understanding

For each question, go through the type's list one property at a time: is it there, and does its type fit? The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• TypeScript compares shapes, not names. A value fits a type when it has every property the type lists, each with a type that fits.
• A value doesn't have to be declared as a type to fit it, and the order of properties doesn't matter.
• Extra properties on a variable are fine. The type only limits what you may read; the extras are still there when the code runs.
• The check has a direction: a bigger shape fits a smaller one, not the other way round.
• Two types with the same shape are interchangeable, and a type alias like UserId = string is just another name.
• To keep look-alike values apart, give them different shapes, like a kind property.

Coming next: Excess property checks. It explains why an object literal with an extra property gets an error while the same object in a variable doesn't, and how that catches typos.