Excess property checks

A typo caught in a new object

A settings page lets a shopper pick a theme and a text size. The code passes the choices to a function as one object. One property name has a typo: fontSise instead of fontSize. Here is what plain JavaScript does:

function applySettings(settings) {
  const size = settings.fontSize ?? 14;
  console.log(`${settings.theme} theme, ${size}px text`);
}

applySettings({ theme: "dark", fontSise: 18 });

Line 1 starts a function that takes a settings object. Line 2 reads settings.fontSize, and the ?? (nullish coalescing) uses 14 when it's missing. Line 3 prints the theme and the size. Line 6 calls the function with fontSise: 18. The object has no fontSize, so it prints dark theme, 14px text. The shopper asked for 18 and got 14, and nothing warned anyone.

Now the same code in TypeScript, with a type for the settings:

1type Settings = { theme: string; fontSize?: number };2 3function applySettings(settings: Settings) {4  const size = settings.fontSize ?? 14;5  console.log(`${settings.theme} theme, ${size}px text`);6}7 8applySettings({ theme: "dark", fontSise: 18 });

Line 1 makes a type called Settings: a theme that is text, and a fontSize that is a number. The ? after fontSize means it can be left out (Object types covers this). Line 3 says applySettings takes a Settings. Line 8 is the call, and TypeScript marks it, on purpose here, because it's the bug:

• Object literal may only specify known properties, but 'fontSise' does not exist in type 'Settings' means "this new object has a property that Settings doesn't list". An object literal is an object you write out with curly braces, like { theme: "dark" }.
• Did you mean to write 'fontSize'? is TypeScript's guess at the fix: the listed name closest to the one you wrote.

The code still runs and prints dark theme, 14px text; the error is a warning for you. Fix the name on line 8, and it prints dark theme, 18px text.

This is an excess property check. "Excess" means extra: more than the type asks for. In the Structural typing lesson, extra properties were fine. An object only needed the properties its type lists. That's still true for most objects. But an object you write right where a type is expected gets this one extra check.

Fresh object literals

An object literal is called fresh while it's still the object you just wrote, before it's stored anywhere. A fresh object meets a type in four common places. Each one here has the extra property qty on purpose:

1type CartItem = { name: string; price: number };2 3const tea: CartItem = { name: "Tea", price: 3, qty: 2 };4 5function addToCart(item: CartItem) {6  return item.name;7}8addToCart({ name: "Cake", price: 4, qty: 1 });9 10function freeGift(): CartItem {11  return { name: "Mint", price: 0, qty: 1 };12}13 14const cart: CartItem[] = [{ name: "Jam", price: 5, qty: 3 }];

Line 1 makes a CartItem type with a name and a price. Then:

1. Line 3 writes an object into a variable with a type, const tea: CartItem.
2. Line 8 writes an object as an argument to addToCart, which takes a CartItem.
3. Line 11 returns an object from freeGift, which says it gives back a CartItem.
4. Line 14 writes an object inside an array of CartItems.

All four get the same error: 'qty' does not exist in type 'CartItem'. Delete qty from any line with Edit & run, and that line's error disappears.

The check also reaches inside. An object written inside another fresh object is fresh too:

1type Order = { id: number; customer: { name: string; email: string } };2 3const order: Order = {4  id: 7,5  customer: { name: "Asha", emial: "asha@example.com" },6};

Line 1 says an Order has an id and a customer with a name and an email. Line 3 starts an order. Line 5 writes the customer with emial. TypeScript reports line 5 and asks Did you mean to write 'email'? The order on line 3 isn't marked, because its own two properties are right.

Catching typos

The check helps most with names that can be left out. A missing optional property is allowed, so without this check a misspelled one would be silently ignored. Type a name for the second property on line 3, and watch the list under the code:

1type Settings = { theme: string; fontSize?: number };2 3const settings: Settings = { theme: "dark", fontSise: 18 };4console.log(settings.fontSize ?? 14);

fontSize is the only name that has no error, and then line 4 prints 18. A name close to a real one, like fontsize, gets a Did you mean suggestion. A name that isn't close to anything, like zoom or size, gets the shorter message with no suggestion. With every wrong name, line 4 prints 14, because the 18 sits under a name nothing reads.

The table below shows the two messages. Read each row as: the kind of extra name, what TypeScript says, and its error number.

What if the misspelled property is one the type needs? Here fontSize has no ?:

1type Settings = { theme: string; fontSize: number };2 3const settings: Settings = { theme: "dark", fontSise: 18 };

Line 1 says every Settings needs a fontSize. Line 3 has fontSise instead. You might expect Property 'fontSize' is missing. TypeScript reports the extra name instead, with the same Did you mean to write 'fontSize'?, which points straight at the fix. Once you fix the name, both problems are gone.

When the check doesn't apply

The check only runs on a fresh object. Once the object is stored somewhere first, it's an ordinary value, and the usual rule from Structural typing applies: it must have what the type needs, and extra properties are fine. Press each button to get the same settings to applySettings a different way:

1type Settings = { theme: string; fontSize?: number };2 3function applySettings(settings: Settings) {4  const size = settings.fontSize ?? 14;5  console.log(`${settings.theme} theme, ${size}px text`);6}7 8applySettings({ theme: "dark", fontSise: 18 });

Written in the call and A variable with a type both write the object right where Settings is expected, so both get the error. From a variable stores it in saved with no type first: no error, and the code prints dark theme, 14px text. With as Settings uses a type assertion: as Settings after a value tells TypeScript "treat this as a Settings, I know what I'm doing", and the check is skipped. Only Typo fixed prints dark theme, 18px text.

Why the difference? A fresh object written in the call can only ever be read as a Settings, so nothing could use fontSise. A stored object is different: other code could read saved.fontSise, so its extra properties might be on purpose. TypeScript only flags extras where they can't be anything but a mistake.

Properties copied in with a spread, ..., aren't checked either:

1type Settings = { theme: string; fontSize?: number };2 3const saved = { fontSise: 18 };4//    ^?5const settings: Settings = { theme: "dark", ...saved };6console.log(settings.fontSize ?? 14);

Line 3 stores { fontSise: 18 } in saved. The query on line 4 shows its type, { fontSise: number; }, typo and all. Line 5 writes a fresh object with a theme and copies in everything from saved. TypeScript only checks the properties written by hand, so there's no error, and line 6 prints 14.

One more check works on variables too. When every property of a type is optional, TypeScript calls it a weak type, and an object must share at least one property with it:

1type ButtonOptions = { color?: string; size?: number };2 3function buttonClass(options: ButtonOptions) {4  return `btn btn-${options.color ?? "grey"}`;5}6 7const options = { colour: "red" };8console.log(buttonClass(options));

Line 1 makes ButtonOptions, where both properties have a ?. Line 7 stores { colour: "red" }, spelled the British way. Line 8 passes it in. options comes from a variable, but TypeScript still reports Type '{ colour: string; }' has no properties in common with type 'ButtonOptions': an object with none of the listed names can't be what you meant. Run it anyway and it prints btn btn-grey. If the object also had a size, it would share one property, and the colour typo would get through.

The table below sums up the section. Read each row as: how the object gets to the type, whether it's checked for extras, and why.

Allowing extra properties on purpose

Sometimes the extra property is not a typo. A shop sends analytics events (small records of what shoppers do) to a tracking service, and one event needs a product ID the type doesn't list:

1type TrackedEvent = { name: string };2 3function track(event: TrackedEvent) {4  console.log(JSON.stringify(event));5}6 7track({ name: "add_to_cart", productId: "p-7" });

Line 1 says a TrackedEvent has a name. Line 3 starts track, and line 4 prints the event as text with JSON.stringify (JSON covers it). Line 7 sends productId, and TypeScript reports 'productId' does not exist in type 'TrackedEvent'. This time the property is wanted. The best fix is to say so in the type:

1type TrackedEvent = { name: string; productId?: string };2 3function track(event: TrackedEvent) {4  console.log(JSON.stringify(event));5}6 7track({ name: "add_to_cart", productId: "p-7" });8track({ name: "add_to_cart", prodcutId: "p-8" });

Line 1 adds productId?: string. Line 7 now has no error, and line 4 prints {"name":"add_to_cart","productId":"p-7"}. The check still protects you: line 8 misspells it as prodcutId, and TypeScript asks Did you mean to write 'productId'?

When the extra names really can't be known ahead of time, the type can say "any other name is fine, as long as its value is text". That's an index signature, and the next lesson, Index signatures & Record, is about them:

1type TrackedEvent = { name: string; [detail: string]: string };2 3function track(event: TrackedEvent) {4  console.log(JSON.stringify(event));5}6 7track({ name: "add_to_cart", productId: "p-7" });8track({ name: "search", query: "green tea" });

Line 1 adds [detail: string]: string: any property name, with a string value. Lines 7 and 8 send different details, productId and query, and neither is an error. The price of this freedom: a typo like prodcutId would be allowed too.

The table below compares the ways to make the error go away. Read each row as: what you do, what TypeScript still checks, and when to use it.

Options for a product search

Option objects are where this check helps most. A search box builds a link from a search word and a few optional settings. Every setting can be left out, so a misspelled one would quietly do nothing:

1type SearchOptions = { query: string; sortBy?: string; limit?: number };2 3function searchUrl(options: SearchOptions) {4  const limit = options.limit ?? 20;5  return `/search?q=${options.query}&limit=${limit}`;6}7 8console.log(searchUrl({ query: "tea", limt: 5 }));

Line 1 says a search has a query, and may have a sortBy and a limit. Line 4 uses 20 results when no limit is given. Line 5 builds the link. Line 8 asks for 5 results but writes limt. TypeScript asks Did you mean to write 'limit'? Run it anyway and it prints /search?q=tea&limit=20: the shopper gets 20 results instead of 5.

1type SearchOptions = { query: string; sortBy?: string; limit?: number };2 3function searchUrl(options: SearchOptions) {4  const limit = options.limit ?? 20;5  return `/search?q=${options.query}&limit=${limit}`;6}7 8console.log(searchUrl({ query: "tea", limit: 5 }));

Only line 8 changed: limit: 5. The error is gone, and it prints /search?q=tea&limit=5.

Common mix-ups

• "Objects can never have extra properties in TypeScript." No. Only a fresh object literal is checked for extras. An object from a variable can have as many extras as it likes, as long as it has what the type needs.
• "Storing the object in a variable first is the way to allow an extra property." No. It hides the check without saying why. Add the property to the type, so typos in it are still caught.
• "as Settings checks the object more strictly." No. A type assertion tells TypeScript to trust you, and it skips the excess property check.
• "TypeScript lists every extra property at once." No. It reports the first extra property in an object. Fix that one, and it shows the next.
• "The error removes the extra property." No. The types are gone when the code runs, and the object keeps every property. That's why the overview still prints 14px: the 18 is there, under the wrong name.
• "Spread objects are checked too." No. Only properties you write by hand in the literal are checked. Ones copied in with ... get through.

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; avatarUrl?: string };

const profile: Profile = { name: "Asha", avatarURL: "/avatars/asha.png" };
console.log(profile.avatarUrl ?? "/avatars/default.png");

1type Profile = { name: string; avatarUrl?: string };2 3const profile: Profile = { name: "Asha", avatarUrl: "/avatars/asha.png" };4console.log(profile.avatarUrl ?? "/avatars/default.png");

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

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

const home = { street: "12 Park Road", city: "Pune", floor: 2 };
console.log(shipTo(home));
console.log(shipTo({ street: "4 Lake View", city: "Goa", floor: 1 }));

1type Address = { street: string; city: string };2 3function shipTo(address: Address) {4  return `${address.street}, ${address.city}`;5}6 7const home = { street: "12 Park Road", city: "Pune", floor: 2 };8console.log(shipTo(home)); // fine: home is a variable9console.log(shipTo({ street: "4 Lake View", city: "Goa", floor: 1 })); // line 9: floor is extra

1type ToastOptions = { message: string; durationMs?: number };2 3function toastText(options: ToastOptions) {4  const seconds = (options.durationMs ?? 3000) / 1000;5  return `${options.message} (${seconds}s)`;6}7 8console.log(toastText({ message: "Saved", duration: 5000 }));

1type ToastOptions = { message: string; durationMs?: number };2 3function toastText(options: ToastOptions) {4  const seconds = (options.durationMs ?? 3000) / 1000;5  return `${options.message} (${seconds}s)`;6}7 8console.log(toastText({ message: "Saved", durationMs: 5000 }));

1type TrackedEvent = { name: string };2 3function describe(event: TrackedEvent) {4  return event.name;5}6 7console.log(describe({ name: "add_to_cart", productId: "p-7" }));

1type TrackedEvent = { name: string; productId?: string };2 3function describe(event: TrackedEvent) {4  return `${event.name} ${event.productId ?? ""}`.trim();5}6 7console.log(describe({ name: "add_to_cart", productId: "p-7" }));

1type Settings = { theme: string; fontSize?: number };2 3const fromStorage = { fontSise: 18 };4const settings: Settings = { theme: "dark", ...fromStorage };5console.log(settings.fontSize ?? 14);

1type Settings = { theme: string; fontSize?: number };2 3const fromStorage: { fontSize?: number } = { fontSize: 18 };4const settings: Settings = { theme: "dark", ...fromStorage };5console.log(settings.fontSize ?? 14);

1type ButtonOptions = { color?: string; size?: number };2 3function buttonClass(options: ButtonOptions) {4  return `btn btn-${options.color ?? "grey"}`;5}6 7const options = { colour: "red" };8console.log(buttonClass(options));

1type ButtonOptions = { color?: string; size?: number };2 3function buttonClass(options: ButtonOptions) {4  return `btn btn-${options.color ?? "grey"}`;5}6 7const options = { color: "red" };8console.log(buttonClass(options));

Check your understanding

For each question, ask where the object was written: right where the type is expected, or somewhere else first. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• An object literal written right where a type is expected is fresh, and may only have the properties that type lists.
• The check runs for typed variables, arguments, return values, array items, and objects nested inside them.
• A name close to a listed one gets Did you mean to write …? (2561); any other extra name gets 2353.
• Objects from variables, properties from a spread, and objects marked with as skip the check.
• A type whose properties are all optional also needs at least one shared property, even from a variable.
• To allow an extra property, add it to the type. Use an index signature only when the names can't be known.

Coming next: Index signatures & Record. It types objects whose property names you don't know ahead of time, like lookup tables and dictionaries.