{"id":"l-at-1-2","courseId":"advanced-typescript","lang":"en","kind":"lesson","summary":"Predict when TypeScript accepts one type where another is expected, including excess property checks and function parameters, so assignability errors stop surprising you.","html":"

Here is a function from Cartwheel’s checkout client and a call that surprises people coming from Java or C#:

\n
TypeScript
type Money = { amountCents: number; currency: string };\n\nfunction formatMoney(m: Money): string {\n  return `${(m.amountCents / 100).toFixed(2)} ${m.currency}`;\n}\n\nconst tent = { sku: 'TENT-2P', name: 'Two-person tent', amountCents: 18900, currency: 'USD' };\nformatMoney(tent); // compiles: \"189.00 USD\"
\n

tent was never declared as Money. It is a product. TypeScript accepts it anyway, because TypeScript does not ask what something is called. It asks whether it has the right shape. This is structural typing, and once you see it clearly, most “why does this compile?” moments go away.

\n

Types are sets of values

\n

The most useful mental model for this whole course: a type is a set of values. string is the set of all strings. 'USD' is the set with one value in it. 'USD' | 'EUR' has two.

\n

Assignability is the subset relation. A value of type A can go where B is expected when every A is also a B. Every 'USD' is a string, so 'USD' is assignable to string. Not every string is 'USD', so the reverse needs a check.

\n

Object types work the same way, with a twist that trips people up. { id: number } is the set of all values that have a numeric id. { id: number; status: string } adds a second condition, so fewer values qualify. More properties means a smaller set. That is why a full Order can be passed where { id: number } is expected: it is in the smaller set, so it is in the bigger one too.

\n
\n Two nested-set diagrams. Left: unknown contains string, which contains the union of USD and EUR, which contains USD. Right: an object with id contains an object with id and status, which contains a full Order. Every value in an inner set also belongs to the sets around it.\n \n unknown\n \n string\n \n 'USD' | 'EUR'\n \n 'USD'\n \n { id }\n \n { id, status }\n \n Order\n id, status, total…\n
Assignability is the subset relation: narrower types fit inside wider ones
\n

Two special types sit at the edges. unknown is the set of every value: anything is assignable to it, and you must check before using it. never is the empty set: it is assignable to everything (the empty set is a subset of every set), and nothing is assignable to it. You will lean on both later in the course. any is not a set at all; it switches checking off in both directions, which is why one stray any can quietly poison everything it touches.

\n

Excess property checks: the one exception

\n

If extra properties are fine, why does this fail?

\n
TypeScript
type Order = { id: number; status: string };\nfunction save(order: Order) {}\n\nsave({ id: 1001, stauts: 'processing' });\n// Error: Object literal may only specify known properties, but 'stauts'\n// does not exist in type 'Order'. Did you mean to write 'status'?
\n

This is an excess property check, a deliberate heuristic layered on top of structural typing. When you write an object literal directly where a type is expected, the literal is “fresh”: nothing else can ever see it, so an extra property can only be a typo. TypeScript flags it.

\n

The check only applies to fresh literals:

\n
TypeScript
const draft = { id: 1001, status: 'processing', stauts: 'oops' };\nsave(draft); // compiles: draft is not fresh
\n\n

Functions: parameters flip the direction

\n

For functions, return types follow the usual rule, but parameters go the other way. A handler that accepts any CheckoutEvent can stand in for one that only needs PaymentFailed. The reverse is unsafe: a handler that only understands PaymentFailed would crash on a shipped event. Under strict (specifically strictFunctionTypes), TypeScript rejects it:

\n
TypeScript
type PaymentFailed = { type: 'payment-failed'; reason: string };\ntype OrderShipped = { type: 'order-shipped'; carrier: string };\ntype CheckoutEvent = PaymentFailed | OrderShipped;\n\ntype Listener = { onEvent: (e: CheckoutEvent) => void };\n\nconst failuresOnly = { onEvent: (e: PaymentFailed) => console.log(e.reason.toUpperCase()) };\nconst l: Listener = failuresOnly;\n// Error: Type '{ onEvent: (e: PaymentFailed) => void; }' is not assignable to type 'Listener'.\n//   Types of property 'onEvent' are incompatible.
\n

Fewer parameters are also fine: (e) => {} and () => {} both fit (e: CheckoutEvent, at: Date) => void, because a function is allowed to ignore arguments. That is why orders.forEach((o) => …) works even though forEach passes three arguments.

\n

The method-syntax loophole

\n

Now write the same type with method syntax:

\n
TypeScript
interface Listener {\n  onEvent(e: CheckoutEvent): void; // method syntax\n}\nconst l: Listener = failuresOnly; // compiles!
\n

Parameters of methods declared this way are checked bivariantly, even under strict. TypeScript keeps this on purpose so that everyday patterns, such as treating an Array<Dog> as an Array<Animal>, keep compiling. The cost is that the unsafe listener above is accepted.

\n\n

When you want names to matter

\n

Sometimes structural typing is too generous. An OrderId and a CustomerId are both number, so nothing stops you swapping them. The fix is to make the shapes differ, which is what branded types do in Branded Types and Exhaustive Checks. For now, the rule of thumb is enough: if two things have the same shape, TypeScript considers them the same thing.

\n

The exercise below fixes the listener loophole in Cartwheel’s event bus. Next, you will see how TypeScript narrows a wide type inside a function, the other half of working with sets.

\n","toc":[{"id":"sec-1","text":"Types are sets of values","level":2},{"id":"sec-2","text":"Excess property checks: the one exception","level":2},{"id":"sec-3","text":"Functions: parameters flip the direction","level":2},{"id":"sec-4","text":"The method-syntax loophole","level":3},{"id":"sec-5","text":"When you want names to matter","level":2}],"takeaways":["TypeScript compares shapes, not names; any value with the required properties is assignable, whatever its type is called.","Read a type as the set of values it allows; an object type with more required properties describes a smaller set.","Excess property checks only apply to fresh object literals, which is why passing a variable with an extra field compiles.","Function parameters are checked in the opposite direction, but methods declared with method syntax are checked bivariantly, so prefer property syntax for callbacks."],"further":[{"title":"Type Compatibility","url":"https://www.typescriptlang.org/docs/handbook/type-compatibility.html"},{"title":"strictFunctionTypes","url":"https://www.typescriptlang.org/tsconfig/strictFunctionTypes.html"}],"quiz":[{"q":"

Does this compile?

\n
TypeScript
type Money = { amountCents: number; currency: string };\nconst product = { sku: 'TENT-2P', amountCents: 18900, currency: 'USD' };\nconst price: Money = product;
\n","options":[{"text":"Yes, because product has every property Money requires and extra properties are allowed on a non-fresh value.","why":"Correct. product is a variable, not a fresh literal, so the excess sku is not checked; the shape matches."},{"text":"No, because product was never declared as a Money.","why":"TypeScript is structural; it never asks what a value was declared as, only whether its shape fits."},{"text":"No, because sku is an excess property.","why":"Excess property checks only run on object literals written directly where the type is expected. Through a variable, extra fields are fine."}],"answer":0},{"q":"

Thinking of types as sets of values, which statement is true?

","options":[{"text":"{ id: number; status: string } is a bigger set than { id: number }.","why":"Each required property is an extra condition a value must meet, so adding one shrinks the set, not grows it."},{"text":"never contains every value, which is why it is assignable to everything.","why":"never is the empty set. It is assignable to everything because the empty set is a subset of every set."},{"text":"'EUR' is a subset of string, so a 'EUR' is assignable to string but not the reverse.","why":"Correct. Assignability is the subset relation; a wider set cannot flow into a narrower one without a check."},{"text":"unknown and any are both the empty set.","why":"unknown is the set of all values. any is not a set at all; it turns checking off in both directions."}],"answer":2},{"q":"

Why does this compile under strict?

\n
TypeScript
type CheckoutEvent = { type: 'paid' } | { type: 'shipped'; carrier: string };\ninterface Listener { onEvent(e: CheckoutEvent): void }\nconst l: Listener = { onEvent: (e: { type: 'shipped'; carrier: string }) => {} };
\n","options":[{"text":"Because arrow functions are never checked against interfaces.","why":"Arrow functions are checked like any other function. The leniency comes from how onEvent is declared."},{"text":"Because onEvent uses method syntax, and method parameters are checked bivariantly even with strictFunctionTypes.","why":"Correct. Writing onEvent: (e: CheckoutEvent) => void instead makes the parameter check strict and rejects this listener."},{"text":"Because a union parameter accepts any of its members.","why":"The listener must handle every member of the union. Accepting only one member is unsafe, which strict checking would catch."}],"answer":1},{"q":"

Which call is rejected by an excess property check?

","options":[{"text":"ship(order) where order is a variable with an extra notes field","why":"Variables are not fresh, so their extra properties are not checked."},{"text":"ship({ ...order, notes: 'gift' }) where Order has no notes field","why":"Correct. A literal with a spread is still a fresh object literal, and notes is written directly in it, so it is flagged. (Extra fields that arrive through ...order itself are not checked.)"},{"text":"ship(order as Order) where order has an extra notes field","why":"A type assertion tells the compiler to trust you, which skips the excess check entirely."}],"answer":1}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type PaymentFailed = { type: 'payment-failed'; orderId: number; reason: string };\ntype OrderShipped = { type: 'order-shipped'; orderId: number; carrier: string };\ntype CheckoutEvent = PaymentFailed | OrderShipped;\n\n// Cartwheel's checkout event bus.\ninterface CheckoutListener {\n onEvent(event: CheckoutEvent): void;\n}\n\nconst listeners: CheckoutListener[] = [];\nconst seen: string[] = [];\n\nfunction subscribe(listener: CheckoutListener): void {\n listeners.push(listener);\n}\n\nfunction emit(event: CheckoutEvent): void {\n for (const l of listeners) l.onEvent(event);\n}\n\n// Handles every event: must keep compiling.\nsubscribe({ onEvent: (e) => { seen.push(`${e.type}:${e.orderId}`); } });\n\n// A listener that takes no arguments at all: must keep compiling too.\nsubscribe({ onEvent: () => { seen.push('ping'); } });\n\n// ---- Type tests (do not edit) ----\n// This listener only understands PaymentFailed; an OrderShipped event would\n// crash it (e.reason is undefined). Subscribing it must be a type error.\nconst failuresOnly = { onEvent: (e: PaymentFailed) => { seen.push(e.reason.toUpperCase()); } };\n// @ts-expect-error: a PaymentFailed-only listener cannot receive every CheckoutEvent\nconst unsafe: CheckoutListener = failuresOnly;\n\nemit({ type: 'order-shipped', orderId: 1042, carrier: 'DHL' });\nconsole.log(seen);\n"},"solution":{"ts":"type PaymentFailed = { type: 'payment-failed'; orderId: number; reason: string };\ntype OrderShipped = { type: 'order-shipped'; orderId: number; carrier: string };\ntype CheckoutEvent = PaymentFailed | OrderShipped;\n\n// Cartwheel's checkout event bus.\n// Property syntax: the parameter is checked strictly (contravariantly).\ninterface CheckoutListener {\n onEvent: (event: CheckoutEvent) => void;\n}\n\nconst listeners: CheckoutListener[] = [];\nconst seen: string[] = [];\n\nfunction subscribe(listener: CheckoutListener): void {\n listeners.push(listener);\n}\n\nfunction emit(event: CheckoutEvent): void {\n for (const l of listeners) l.onEvent(event);\n}\n\n// Handles every event: must keep compiling.\nsubscribe({ onEvent: (e) => { seen.push(`${e.type}:${e.orderId}`); } });\n\n// A listener that takes no arguments at all: must keep compiling too.\nsubscribe({ onEvent: () => { seen.push('ping'); } });\n\n// ---- Type tests (do not edit) ----\n// This listener only understands PaymentFailed; an OrderShipped event would\n// crash it (e.reason is undefined). Subscribing it must be a type error.\nconst failuresOnly = { onEvent: (e: PaymentFailed) => { seen.push(e.reason.toUpperCase()); } };\n// @ts-expect-error: a PaymentFailed-only listener cannot receive every CheckoutEvent\nconst unsafe: CheckoutListener = failuresOnly;\n\nemit({ type: 'order-shipped', orderId: 1042, carrier: 'DHL' });\nconsole.log(seen);\n"},"checks":[{"id":"types","typecheck":true},{"id":"still-delivers","test":"return seen.includes('order-shipped:1042') && seen.includes('ping');"}],"title":"Close the listener loophole","prompt":"

CheckoutListener declares onEvent with method syntax, so TypeScript checks its parameter bivariantly and happily accepts failuresOnly, a listener that would crash on an OrderShipped event. Change how onEvent is declared (not its parameter type) so that assigning failuresOnly to a CheckoutListener is a type error, while the two existing subscribe calls keep compiling and the shipped event still reaches them.

\n","hints":["The fix is one line inside the interface.","Method syntax is name(arg: T): void. Property syntax is name: (arg: T) => void.","Write onEvent: (event: CheckoutEvent) => void;."],"explanation":"

With method syntax, strictFunctionTypes does not apply, so a listener that accepts only PaymentFailed passes as one that accepts every CheckoutEvent. Declared as a property with a function type, the parameter is checked contravariantly: the listener must accept at least everything the bus can send. (e) => … gets its parameter type from context and () => … ignores the argument, so both keep compiling. The @ts-expect-error line now has a real error to expect.

\n","checkLabels":{"types":"The file type-checks with zero errors: the unsafe listener is rejected","still-delivers":"Both safe listeners still receive the shipped event"}},"words":759,"readMinutes":4}