Variance & assignability

One type standing in for another

A shop has plain products and products on sale. A sale product has everything a product has, a name and a price, plus a sale price. Can a sale product go where the code expects a product? And the other way round? Here is what TypeScript says:

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3 4function showPrice(product: Product) {5  console.log(`${product.name}: $${product.price}`);6}7 8const cake: SaleProduct = { name: "Cake", price: 4, salePrice: 3 };9showPrice(cake);10 11const tea: Product = { name: "Tea", price: 3 };12const teaOnSale: SaleProduct = tea;

Lines 1 and 2 describe the two types. Line 4's showPrice takes a Product. Line 8 makes a sale cake, and line 9 passes it to showPrice. That's fine: showPrice only reads a name and a price, and the cake has both. It prints Cake: $4.

Line 12 goes the other way: it stores a plain tea where a SaleProduct goes. TypeScript marks it, on purpose here: Property 'salePrice' is missing in type 'Product' but required in type 'SaleProduct'. In plain words: code that expects a sale product may read salePrice, and tea doesn't have one.

When a value of one type can go wherever another type is expected, TypeScript calls it assignable to that type, and the first type is a subtype of the second. The second, wider type is the supertype. SaleProduct is a subtype of Product. TypeScript decides this by comparing shapes, as Structural typing showed. Subtypes chain together, from specific to general:

The table below lists subtype pairs you meet in frontend code. Read each row as: a value of this type fits where that type goes, because…

That covers single values. This lesson asks the next question: what about types built from other types? Is a list of sale products a list of products? Is a function that gives back a sale product a function that gives back a product? Is a click handler for sale products a handler for products? The answer depends on whether the type inside goes in, comes out, or both. That rule has a name: variance.

Outputs keep the direction: covariance

Start with something that only hands values out. A loader is a function you call to get a product, the way a page loads one from a server. Loader<T> is a generic type: the blank T says what the loader gives back.

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3type Loader<T> = () => T;4 5const loadSale: Loader<SaleProduct> = () => ({ name: "Cake", price: 4, salePrice: 3 });6const loadProduct: Loader<Product> = loadSale;7console.log(loadProduct().name);8 9const loadAnySale: Loader<SaleProduct> = loadProduct;

Line 3 says a Loader<T> is a function that takes nothing and returns a T. Line 5 makes a loader of sale products. Line 6 stores it where a loader of products goes, and that's fine: whoever calls it expects a product and gets a sale product, which has everything a product has. Line 7 prints Cake.

Line 9 goes the other way, and TypeScript marks it on purpose: Type 'Loader<Product>' is not assignable to type 'Loader<SaleProduct>'. Its second line gives the reason: Property 'salePrice' is missing. Code that wants sale products would get a product with no sale price.

So Loader follows the direction of its T: SaleProduct fits where Product goes, and Loader<SaleProduct> fits where Loader<Product> goes. A type that keeps the direction is called covariant ("co" means "together": the two move together). Anything that only hands values out works this way:

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3 4const saleItems: readonly SaleProduct[] = [{ name: "Cake", price: 4, salePrice: 3 }];5const items: readonly Product[] = saleItems;6 7const saleReply: Promise<SaleProduct> = Promise.resolve(saleItems[0]);8const reply: Promise<Product> = saleReply;9console.log(items[0].name);

Line 4 makes a readonly list of sale products: a list nobody can push into or change through that name (Arrays and tuples covers readonly). Line 5 stores it as a read-only list of products. Line 7 makes a Promise of a sale product, and line 8 stores it as a promise of a product. Both are fine: you only read from them. Line 9 prints Cake.

Inputs flip the direction: contravariance

Now something that takes values in: a handler, the function a list calls when the shopper selects a product. The list decides what to pass. The handler only decides what it can accept. Try different handlers below:

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3type SelectHandler = (product: Product) => void;4 5function renderList(products: Product[], onSelect: SelectHandler) {6  onSelect(products[0]);7}8 9const handler = (item: Product) => console.log(item.price);10renderList([{ name: "Tea", price: 3 }], handler);

Line 3 describes a SelectHandler: a function that takes a Product. Line 5's renderList takes a list and a handler, and line 6 calls the handler with the first product. Line 9 is the handler, and line 10 passes it in.

• item: Product matches exactly. It prints 3.
• item: { name: string } asks for less than a product. Every product has a name, so this handler can deal with anything the list passes. No error, and it prints Tea.
• item: SaleProduct asks for more. TypeScript marks line 10: Argument of type '(item: SaleProduct) => void' is not assignable to parameter of type 'SelectHandler'. It means "this handler can't take everything the list may give it". Run it anyway, and the list passes tea, which has no sale price: it prints undefined.

For values and outputs, the narrower type fits. For inputs it's the other way: the handler with the wider parameter fits. (item: { name: string }) => void fits where (product: Product) => void goes, even though Product fits where { name: string } goes. The direction flips, so function parameters are called contravariant ("contra" means "against").

The checkbox in the playground turns off strictFunctionTypes, a check that strict turns on (tsconfig strictness lists it). Without it, TypeScript checks parameters both ways: a handler fits if its parameter fits the other one in either direction. This is called bivariance. Choose item: SaleProduct and untick the box: the error disappears, and the code still prints undefined. Keep strict on.

The browser's own events follow the same rule. A handler that accepts any Event fits every listener:

1function logEvent(event: Event) {2  console.log(`${event.type} happened`);3}4 5const button = document.createElement("button");6button.addEventListener("click", logEvent);7button.addEventListener("keydown", logEvent);8button.click();

Line 1's logEvent takes any Event. Line 6 uses it for clicks, where TypeScript knows the listener gets a MouseEvent. Line 7 uses it for key presses, which pass a KeyboardEvent. Both fit, because both are subtypes of Event, and logEvent only reads event.type. Line 8 clicks the button, and line 2 prints click happened. A handler that needs a MouseEvent would not fit the key listener (Typing events covers listeners).

Methods are checked both ways

strictFunctionTypes has one gap. An object type can describe a function member in two ways, and TypeScript checks them differently:

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3 4interface MethodProps { onSelect(product: Product): void }5interface PropertyProps { onSelect: (product: Product) => void }6 7const logSale = (item: SaleProduct) => console.log(item.salePrice);8const withMethod: MethodProps = { onSelect: logSale };9const withProperty: PropertyProps = { onSelect: logSale };10withMethod.onSelect({ name: "Tea", price: 3 });

Line 4 writes onSelect as a method: a name, brackets, and a return type. Line 5 writes it as a property whose type is a function type (Function types covers them). Line 7's logSale needs a sale product.

• Line 8 stores logSale as the method. No error: methods are still checked both ways, even with strict on.
• Line 9 stores the same function as the property. TypeScript marks it, on purpose: Type '(item: SaleProduct) => void' is not assignable to type '(product: Product) => void'.
• Line 10 calls the method with tea, and it prints undefined. Line 8 let the bug through.

Why leave methods out? The TypeScript team did it on purpose when strictFunctionTypes arrived, so that types with methods, like Array<T>, keep fitting the way people expect. The next section shows what that costs. For your own types, the fix is simple: write callbacks as properties with function types, like line 5, and you get the strict check.

The table below sums up the three cases. Read each row as: written this way, checked this way, so a sale-product handler gets…

Arrays and the unsafe write

A list of sale products fits where a list of products goes. That's handy for code that only reads the list. But a normal array can also be written to:

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3 4const saleItems: SaleProduct[] = [{ name: "Cake", price: 4, salePrice: 3 }];5const items: Product[] = saleItems;6items.push({ name: "Tea", price: 3 });7 8for (const item of saleItems) {9  console.log(`${item.name}: $${item.salePrice}`);10}

Line 4 makes a list of sale products. Line 5 stores it as Product[], and TypeScript allows it. Line 6 pushes tea, which is a fine Product. Lines 8 to 10 print each sale price: Cake: $3, then Tea: $undefined. There are no errors, and the sale list now holds something that isn't a sale product.

The reason is that line 5 doesn't copy the array. items and saleItems are two names for the same array (Objects and references explains this). Step through it:

1const saleItems = [{ name: "Cake", price: 4, salePrice: 3 }];Run2const items = saleItems;3items.push({ name: "Tea", price: 3 });4 5for (const item of saleItems) {6  console.log(`${item.name}: $${item.salePrice}`);7}

Arrays are treated as covariant even though they can be written to. That's unsound: TypeScript lets through code that can put a wrong value in a list. It's a choice that keeps everyday code easy, and object properties work the same way:

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3 4const saleSlot: { item: SaleProduct } = { item: { name: "Cake", price: 4, salePrice: 3 } };5const slot: { item: Product } = saleSlot;6slot.item = { name: "Tea", price: 3 };7console.log(saleSlot.item.salePrice);

Line 4 makes an object holding a sale cake. Line 5 stores it as an object holding any product. Line 6 puts tea in through slot, and line 7 prints undefined: the sale slot holds tea now. Again, no errors.

When code only needs to read a list, say so with readonly. A read-only list of sale products still fits where a read-only list of products goes, and the unsafe write becomes an error:

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3 4const saleItems: SaleProduct[] = [{ name: "Cake", price: 4, salePrice: 3 }];5const items: readonly Product[] = saleItems;6items.push({ name: "Tea", price: 3 });7console.log(items.length);

Line 5 stores the sale list as readonly Product[], and that's fine. Line 6's push is now an error, on purpose: Property 'push' does not exist on type 'readonly Product[]'. A read-only list has no methods that change it. readonly only exists in types, though: run the code anyway and line 7 prints 2. The check is what protects you.

in and out: writing the variance down

TypeScript works out the variance of each generic type from how its body uses the type parameter. Since TypeScript 4.7, you can also write it down, with out and in before the type parameter:

1type Loader<out T> = () => T;2type Handler<in T> = (value: T) => void;3 4interface Store<in out T> {5  get: () => T;6  set: (value: T) => void;7}

• Line 1: out T says T only comes out. A loader returns a T, so it's covariant.
• Line 2: in T says T only goes in. A handler takes a T, so it's contravariant.
• Line 4: in out T says both. Line 5's get hands a T out, and line 6's set takes one in, so a store is invariant: two stores fit only when they hold the same type.

An annotation is a claim, and TypeScript checks it against the body. Try each one on a store of sale products, which line 14 tries to use as a store of products:

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3 4interface Store<T> {5  get: () => T;6  set: (value: T) => void;7}8 9function makeStore<T>(value: T): Store<T> {10  return { get: () => value, set: (next) => { value = next; } };11}12 13const saleStore = makeStore<SaleProduct>({ name: "Cake", price: 4, salePrice: 3 });14const productStore: Store<Product> = saleStore;15productStore.set({ name: "Tea", price: 3 });16console.log(saleStore.get().salePrice);

With no annotation, or with the true in out T, line 14 gets an error, which is right: line 15 puts tea in the sale store, and line 16 prints undefined. With out T, line 4 gets Type 'Store<sub-T>' is not assignable to type 'Store<super-T>' as implied by variance annotation. sub-T and super-T are stand-ins for "some subtype" and "its supertype"; the message means "your annotation says a store of a subtype fits where a store of its supertype goes, but the body disagrees". Look at line 14 with out T: it isn't marked any more, because TypeScript trusts the annotation when it compares two stores. A wrong annotation hides the real bug.

A few rules about annotations:

• They go on type parameters of interfaces, classes, and type aliases for object or function types. A function's type parameter can't have one.
• TypeScript checks each one against the body, as the playground showed, and reports one that lets through more than the body is safe for. A stricter one, like in out T on a type that only hands T out, is allowed: the type then fits less than it could.
• They don't change what fits when TypeScript compares two shapes property by property. They're used as a shortcut when it compares two versions of the same generic type, like Store<SaleProduct> and Store<Product>.
• You rarely need them. They help a reader see how a parameter is used, and in very large or self-referencing types they make checking faster and more exact. Library authors use them most.

1function firstItem<out T>(items: T[]): T {2  return items[0];3}

Line 1 puts out on a function's type parameter. TypeScript says, on purpose here: 'out' modifier can only appear on a type parameter of a class, interface or type alias.

Props for a product list

A product list component takes its data and a callback as props: one object with everything the component needs. Variance decides how to write that type so callers can pass what they have, and mistakes still get caught:

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3 4type ProductListProps = {5  items: readonly Product[];6  onSelect: (product: Product) => void;7};8 9function renderProductList(props: ProductListProps) {10  for (const item of props.items) console.log(`Show ${item.name}`);11  props.onSelect(props.items[0]);12}13 14const saleItems: SaleProduct[] = [{ name: "Cake", price: 4, salePrice: 3 }];15renderProductList({ items: saleItems, onSelect: (item) => console.log(`Picked ${item.name}`) });16//                                               ^?

Line 5 types items as readonly Product[]: the component only reads the list, so any list of products, sale products included, can go in, and nothing can push into it. Line 6 types onSelect as a property with a function type, so strictFunctionTypes checks the callbacks people pass. Line 15 passes the sale list and a callback. The query on line 16 shows TypeScript gives the callback's item the type Product, from the props type. It prints Show Cake, then Picked Cake.

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3 4type ProductListProps = {5  items: readonly Product[];6  onSelect: (product: Product) => void;7};8 9function renderProductList(props: ProductListProps) {10  for (const item of props.items) console.log(`Show ${item.name}`);11  props.onSelect(props.items[0]);12}13 14const saleItems: SaleProduct[] = [{ name: "Cake", price: 4, salePrice: 3 }];15const pickSale = (item: SaleProduct) => console.log(item.salePrice);16renderProductList({ items: saleItems, onSelect: pickSale });

Lines 1 to 14 are the same. Line 15's pickSale needs a sale product, and line 16 passes it as onSelect. TypeScript marks line 16: Type '(item: SaleProduct) => void' is not assignable to type '(product: Product) => void'. The component promises only a Product, so a callback that needs a sale price doesn't fit. Had line 6 been a method, there would be no error.

Common mix-ups

The table below sums up the three kinds of variance. Read each row as: where the type parameter appears, what that's called, and what fits.

• "If a sale product fits, a list of sale products is always safe as a list of products." No. TypeScript allows it, but a push through the wider name puts a plain product in the sale list. Use readonly when you only read.
• "A handler for sale products works wherever a product handler goes." No. Inputs flip. The caller may pass any product, so the handler must accept any product, or something wider.
• "Methods and function properties are checked the same way." No. Methods are checked both ways even with strict. Write callbacks as properties with function types to get the strict check.
• "in and out let me pick any variance I like." No. TypeScript reports one that lets through more than the body is safe for. And a wrong one can hide a bug: with out T on the store, line 14 stopped being marked.
• "Variance is about classes and inheritance." No. TypeScript compares shapes. Any two types with matching shapes follow these rules, with or without extends.
• "readonly stops the array from changing." No. It stops your code from changing it through that name. The types are removed before the code runs, and another name for the same array can still push.

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 Product = { name: string; price: number };
type SaleProduct = { name: string; price: number; salePrice: number };
type Loader<T> = () => T;

const loadTea: Loader<Product> = () => ({ name: "Tea", price: 3 });
const loadCake: Loader<SaleProduct> = () => ({ name: "Cake", price: 4, salePrice: 3 });

const first: Loader<Product> = loadCake;
const second: Loader<SaleProduct> = loadTea;

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3type Loader<T> = () => T;4 5const loadTea: Loader<Product> = () => ({ name: "Tea", price: 3 });6const loadCake: Loader<SaleProduct> = () => ({ name: "Cake", price: 4, salePrice: 3 });7 8const first: Loader<Product> = loadCake; // fine: a sale product is a product9const second: Loader<SaleProduct> = loadTea; // line 9: tea has no salePrice

1const teaNames: string[] = ["green"];2const labels: (string | number)[] = teaNames;3labels.push(4);4console.log(teaNames.length, typeof teaNames[1]);

1const teaNames: string[] = ["green"];2const labels: readonly (string | number)[] = teaNames;3console.log(teaNames.length, labels.length);

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3type SelectHandler = (product: Product) => void;4 5function renderList(products: Product[], onSelect: SelectHandler) {6  onSelect(products[0]);7}8 9renderList([{ name: "Tea", price: 3 }], (item: SaleProduct) => console.log(item.salePrice));

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3type SelectHandler = (product: Product) => void;4 5function renderList(products: Product[], onSelect: SelectHandler) {6  onSelect(products[0]);7}8 9renderList([{ name: "Tea", price: 3 }], (item: Product) => console.log(item.price));

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3 4function addFreeGift(items: Product[]) {5  items.push({ name: "Gift card", price: 0 });6}7 8const saleItems: SaleProduct[] = [{ name: "Cake", price: 4, salePrice: 3 }];9addFreeGift(saleItems);10console.log(saleItems.length);

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3 4function withFreeGift(items: readonly Product[]): Product[] {5  return [...items, { name: "Gift card", price: 0 }];6}7 8const saleItems: SaleProduct[] = [{ name: "Cake", price: 4, salePrice: 3 }];9const cartItems = withFreeGift(saleItems);10console.log(saleItems.length, cartItems.length);

1interface Feed<T> { latest: () => T }2interface Sink<T> { send: (value: T) => void }3interface Cache<T> { read: () => T; write: (value: T) => void }

1interface Feed<out T> { latest: () => T }2interface Sink<in T> { send: (value: T) => void }3interface Cache<in out T> { read: () => T; write: (value: T) => void }

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3 4interface ProductListProps { onSelect(product: Product): void }5 6const props: ProductListProps = {7  onSelect: (item: SaleProduct) => console.log(item.salePrice),8};9props.onSelect({ name: "Tea", price: 3 });

1type Product = { name: string; price: number };2type SaleProduct = { name: string; price: number; salePrice: number };3 4interface ProductListProps { onSelect: (product: Product) => void }5 6const props: ProductListProps = {7  onSelect: (item: Product) => console.log(item.price),8};9props.onSelect({ name: "Tea", price: 3 });

Check your understanding

For each question, ask which way the value flows: out of a type, into it, or both. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A subtype has everything its supertype has, so it fits where the supertype goes: a SaleProduct where a Product goes.
• Types that only hand values out, like loaders, promises, and read-only arrays, are covariant: they keep the direction.
• Function parameters are contravariant: a handler for the wider type fits where a handler for the narrower type goes.
• strictFunctionTypes, part of strict, checks function-type parameters strictly. Methods are still checked both ways.
• Arrays and object properties are treated as covariant even though you can write to them. Use readonly when you only read.
• out, in, and in out write the variance down. TypeScript checks them, and you rarely need them.

Coming next: Decorators. They are functions that wrap a class's methods and fields, like a logger or an auto-bound click handler, and TypeScript checks where you put them.