Generic classes

A stack that keeps its item type

A text editor's undo button needs to remember your changes, newest first. A stack does that: a list where you add and remove items at the same end, like a pile of plates. push puts an item on top, and pop takes the top one off. Here is a stack class written for text (the Classes in TypeScript lesson covers fields and methods):

1class TextStack {2  private items: string[] = [];3  push(item: string) {4    this.items.push(item);5  }6  pop(): string | undefined {7    return this.items.pop();8  }9}10 11const edits = new TextStack();12edits.push("Hello");13const zoom = new TextStack();14zoom.push(150);15console.log(edits.pop(), zoom.pop());

Line 2 keeps the items in a private string[]. Line 3's push takes a string, and line 6's pop gives back the top string, or undefined when the stack is empty. Lines 11 and 12 make a stack of edits and push "Hello". Line 13 makes a second stack for zoom levels, and line 14 pushes 150. TypeScript marks it, on purpose:

• Argument of type 'number' is not assignable to parameter of type 'string' means "you passed a number where this method wants text".

Run it anyway and line 15 prints Hello 150: the code works for any item, and only the types say text. You could copy the class as NumberStack, and again for every kind of item. A generic class writes it once:

1class Stack<T> {2  private items: T[] = [];3  push(item: T) {4    this.items.push(item);5  }6  pop(): T | undefined {7    return this.items.pop();8  }9}10 11const edits = new Stack<string>();12edits.push("Hello");13const zoom = new Stack<number>();14zoom.push(150);15const lastZoom = zoom.pop();16//    ^?17console.log(edits.pop(), lastZoom);

Line 1 has the new part: <T> after the class name. As in the Generic types lesson, T is a type parameter, a blank for a type. Line 2 keeps a T[], line 3 takes a T, and line 6 gives one back.

Line 11 writes new Stack<string>(): the type argument string fills in T for this stack. Line 13 makes a Stack<number>, so pushing 150 on line 14 is fine. The query on line 16 shows const lastZoom: number | undefined. There are no errors, and line 17 prints Hello 150.

Type parameters on a class

You can write the type argument after new, as in the overview. When the constructor takes a T, TypeScript can also fill in T from the value you pass. A drop-down list on a shop page is a good example: each choice has a label to show and a value to use.

1class Choice<T> {2  constructor(public label: string, public value: T) {}3}4 5const size = new Choice("Large", "L");6//    ^?7const quantity = new Choice("Two", 2);8//    ^?9console.log(size.value, quantity.value + 1);

Line 2 is a constructor with two parameter properties: public label: string and public value: T become fields straight from the constructor's arguments (see Classes in TypeScript). Line 5 passes "L" as the value, so TypeScript fills in T with string, and line 6 shows const size: Choice<string>. Line 7 passes 2, and line 8 shows Choice<number>. Line 9 prints L 3.

A type argument you write wins, and the constructor's arguments are checked against it:

1class Choice<T> {2  constructor(public label: string, public value: T) {}3}4 5const size = new Choice<string>("Large", "L");6const quantity = new Choice<number>("Two", "2");7console.log(size.value, quantity.value);

Line 5 writes <string>, the same type TypeScript would fill in. Line 6 writes <number> and passes the text "2", so TypeScript marks it: Argument of type 'string' is not assignable to parameter of type 'number'. Line 7 prints L 2 anyway.

Our Stack's constructor takes nothing, so only a type argument can fill in its T. Here an undo history pushes "Hello" and shows the last change with showMessage, which needs text. Press the buttons to make the history three ways on line 15:

1class Stack<T> {2  private items: T[] = [];3  push(item: T) {4    this.items.push(item);5  }6  pop(): T | undefined {7    return this.items.pop();8  }9}10 11function showMessage(text: string | undefined) {12  console.log(text ?? "Nothing to undo");13}14 15const history = new Stack<string>();16history.push("Hello");17const last = history.pop();18//    ^?19showMessage(last);

With <string>, everything fits. With No type argument, nothing tells TypeScript what T is, so it becomes unknown, a type that means "this could be anything". The stack takes any push, and what comes out can't be used as text. TypeScript doesn't look at the later push("Hello") to decide. With <number>, line 16's text doesn't fit.

A typed Stack and Cache

A cache keeps server replies so the page doesn't ask for them twice. Each reply is stored under a key, like the address it came from. A generic class can use other generic types inside it, like a Map:

1type Product = { name: string; price: number };2 3class Cache<T> {4  private entries = new Map<string, T>();5  set(key: string, value: T) {6    this.entries.set(key, value);7  }8  get(key: string): T | undefined {9    return this.entries.get(key);10  }11}12 13const productCache = new Cache<Product[]>();14productCache.set("/products", [{ name: "Tea", price: 3 }]);15const cached = productCache.get("/products");16//    ^?17console.log(cached?.length, productCache.get("/sale"));

Line 3 declares Cache<T>. Line 4 keeps the replies in a Map<string, T>: text keys, and values of whatever type T is (the Map and Set lesson covers Map). Line 5's set takes a T, and line 8's get gives back a T, or undefined for a key it doesn't have.

Line 13 makes a cache for lists of products, Cache<Product[]>. Line 14 stores one list, and the query on line 16 shows const cached: Product[] | undefined. Line 17 prints 1 undefined: one product, and nothing stored under "/sale". The ?. reads length only when cached isn't undefined.

Now change what the cache stores. Type a type argument for line 13, and watch line 14 and the answer on line 16:

1type Product = { name: string; price: number };2 3class Cache<T> {4  private entries = new Map<string, T>();5  set(key: string, value: T) {6    this.entries.set(key, value);7  }8  get(key: string): T | undefined {9    return this.entries.get(key);10  }11}12 13const productCache = new Cache<Product[]>();14productCache.set("/products", [{ name: "Tea", price: 3 }]);15const cached = productCache.get("/products");16//    ^?17console.log(cached?.length, productCache.get("/sale"));

Product without the brackets is one product, so a list doesn't fit. string doesn't fit either. Array<Product> is the same as Product[]. any accepts the list, but then TypeScript stops checking what comes out.

A generic class can also promise to match a generic interface. Write the interface's type argument after implements (the implements and abstract classes lesson covers implements):

1interface Store<T> {2  get(key: string): T | undefined;3  set(key: string, value: T): void;4}5 6class MemoryStore<T> implements Store<T> {7  private entries = new Map<string, T>();8  get(key: string) {9    return this.entries.get(key);10  }11  set(key: string, value: T) {12    this.entries.set(key, value);13  }14}15 16const preferences: Store<string> = new MemoryStore<string>();17preferences.set("theme", "dark");18console.log(preferences.get("theme"));

Lines 1 to 4 describe a Store<T>: anything with a get and a set for values of type T. Line 6 says MemoryStore<T> implements Store<T>, passing its own T on, so a MemoryStore<string> is a Store<string>. Line 16 makes a store for a page's preferences as text, line 17 stores the theme, and line 18 prints dark. Code that takes a Store<string> works with this class, or with any other class that stores text the same way.

Static members can't use T

A static member belongs to the class itself, not to each object (the Static members and class types lesson covers them). There is only one Stack class, however many kinds of stack you make:

1class Stack<T> {2  static created = 0;3  private items: T[] = [];4  constructor() {5    Stack.created += 1;6  }7}8 9new Stack<string>();10new Stack<number>();11console.log(Stack.created);

Line 2 makes a static created counter, and line 5 adds 1 each time a stack is made. Line 9 makes a Stack<string> and line 10 a Stack<number>. Line 11 prints 2: both stacks counted on the same static field. Stack<string> and Stack<number> are two types, but one class.

So a static member can't use T: it belongs to the class, and the class serves every T at once. A common case is a static factory, a method on the class that makes objects for you, like Stack.from(["S", "M"]). Press the buttons to write line 9 three ways:

1class Stack<T> {2  constructor(private items: T[] = []) {}3  push(item: T) {4    this.items.push(item);5  }6  pop(): T | undefined {7    return this.items.pop();8  }9  static from(items: T[]): Stack<T> {10    return new Stack(items);11  }12}13 14const sizes = Stack.from(["S", "M"]);15//    ^?16console.log(sizes.pop());

static, using T gets Static members cannot reference class type parameters twice, once for each T. static from<Item> fixes it: the method gets its own type parameter, filled in for each call. Not static makes from a method of each stack, so the class has no from at all.

The table below shows where a class's T can go. Read each row as: this part of the class, can it use T, and why.

Generic methods: a type parameter for one method

The class's T is filled in once, when the object is made. Sometimes a method needs a type that changes with each call. Then the method gets a type parameter of its own, written after its name, like the Generic functions lesson's functions:

1class Stack<T> {2  constructor(private items: T[] = []) {}3  peek(): T | undefined {4    return this.items.at(-1);5  }6  map<U>(change: (item: T) => U): Stack<U> {7    return new Stack(this.items.map(change));8  }9}10 11const prices = new Stack([3, 4]);12//    ^?13const labels = prices.map((price) => "$" + price);14//    ^?15console.log(labels.peek());

Line 2's constructor takes the starting items. Line 3's peek gives back the top item without removing it: at(-1) reads the last one. Line 6 declares map<U>. It takes a change function that turns a T into a U, and gives back a Stack<U>. Line 7 uses the array's own map (see map, filter, and reduce).

Line 11 passes [3, 4], so the query on line 12 shows const prices: Stack<number>. Line 13 calls map with a callback that gives back text, so this call's U is string, and line 14 shows const labels: Stack<string>. Line 15 prints $4, the top label.

A method uses the class's T without declaring it. Writing <T> on the method again makes a new T, unrelated to the class's:

1class Stack<T> {2  private items: T[] = [];3  push<T>(item: T) {4    this.items.push(item);5  }6}7 8const tags = new Stack<string>();9tags.push(3);

Line 3 writes push<T>, so inside push, T means the method's own type parameter. Line 4 marks it: Argument of type 'T' is not assignable to parameter of type 'T'. In plain words: these are two different blanks that happen to share a name, and the method's T might not be the stack's. Worse, line 9 pushes 3 into a Stack<string> with no error, because push no longer uses the stack's T. Remove <T> from line 3, and both problems are gone.

The table below compares the two kinds of type parameter. Read each row as a question, then each answer.

Undo for a settings panel

A settings panel lets the user change the theme and the font size, and undo their last change. The undo part doesn't care what the settings are, so one generic class can handle it, and the same class can undo text in a box:

1type Settings = { theme: "light" | "dark"; fontSize: number };2 3class History<T> {4  private past: T[] = [];5  constructor(private current: T) {}6  get value(): T {7    return this.current;8  }9  change(next: T) {10    this.past.push(this.current);11    this.current = next;12  }13  undo() {14    const previous = this.past.pop();15    if (previous !== undefined) this.current = previous;16  }17}18 19const settings = new History<Settings>({ theme: "light", fontSize: 16 });20settings.change({ theme: "dark", fontSize: 16 });21settings.change({ ...settings.value, fontSize: 18 });22settings.undo();23const now = settings.value;24//    ^?25console.log(now.theme, now.fontSize);26 27const draft = new History("Hi");28//    ^?29draft.change("Hi Asha");30draft.undo();31console.log(draft.value);

Line 1 describes the settings. Lines 3 to 17 are History<T>:

• Line 4 keeps the past values in a T[], used as a stack. Line 5 takes the starting value as a private current field.
• Line 6 is a getter (see Getters and setters): settings.value reads the current value.
• Lines 9 to 12 push the current value onto past, then switch to the new one.
• Lines 13 to 16 pop the last value off past and go back to it, if there is one.

Line 19 makes a History<Settings>. Line 20 switches to the dark theme. Line 21 copies the current settings with the spread ... (see Spread and rest) and changes the font size to 18. Line 22 undoes that, so the query on line 24 shows const now: Settings and line 25 prints dark 16.

Line 27 makes a history for a text box. The constructor's argument is text, so line 28 shows const draft: History<string>. Lines 29 and 30 change it and undo, and line 31 prints Hi.

For an object, the type argument matters. Without it, TypeScript fills in T from the starting value, and that can be too loose:

1type Settings = { theme: "light" | "dark"; fontSize: number };2 3class History<T> {4  constructor(private current: T) {}5  change(next: T) {6    this.current = next;7  }8}9 10const settings = new History<Settings>({ theme: "light", fontSize: 16 });11settings.change({ theme: "blue", fontSize: 16 });12const guessed = new History({ theme: "light", fontSize: 16 });13//    ^?14guessed.change({ theme: "blue", fontSize: 16 });

Line 10 writes <Settings>, so line 11's typo is caught: Type '"blue"' is not assignable to type '"light" | "dark"' means "the theme must be one of these two words". Line 12 leaves the type argument out. TypeScript fills in T from the object, and the query on line 13 shows theme: string: any text. So line 14's "blue" gets no error. When the starting value doesn't say everything, write the type argument.

Common mix-ups

Type parameters are removed before the code runs, like every type. So while the code runs, a stack doesn't know its T:

1class Stack<T> {2  constructor(public items: T[] = []) {}3}4 5const saved: unknown = new Stack([3, 4]);6if (saved instanceof Stack) {7  console.log(saved.items);8  //                ^?9}

Line 5 stores a stack of numbers as unknown, as if it came from somewhere TypeScript can't see. Line 6 checks it with instanceof (the in and instanceof lesson covers it). Inside, TypeScript knows it's a Stack, but not which kind: the query on line 8 shows (property) Stack<any>.items: any[]. Line 7 prints [ 3, 4 ]. Writing saved instanceof Stack<number> is an error, because there's no T to check while the code runs.

The table below shows what is left of a generic class when the code runs. Read each row as: what you write, what TypeScript checks, and what runs.

• "Stack<string> and Stack<number> are two classes." No. They're two types made from one class. A static field, like created, is shared by both.
• "TypeScript works out T from what I push later." No. T is filled in when the object is made. new Stack() with nothing to go on is a Stack<unknown>.
• "A static method can use the class's T." No. Static members belong to the one class, which serves every T. Give the static method its own type parameter, like from<Item>.
• "A method must declare <T> to use T." No. Every instance method can use the class's T. Declaring it again makes a new, unrelated T.
• "instanceof can check Stack<string>." No. It only checks the class. The type argument is gone when the code runs.
• "A class that holds any kind of item needs any inside." No. T lets it hold any kind of item and still check each object's own kind.

Practice exercises

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

1class Stack<T> {2  private items: T[] = [];3  push(item: T) {4    this.items.push(item);5  }6  pop(): T | undefined {7    return this.items.pop();8  }9}10 11const orders = new Stack<string>();12orders.push("Tea");13const next = orders.pop();

1class Stack<T> {2  private items: T[] = [];3  push(item: T) {4    this.items.push(item);5  }6  pop(): T | undefined {7    return this.items.pop();8  }9}10 11const orders = new Stack<string>();12orders.push("Tea");13const next = orders.pop();14//    ^?

class Stack<T> {
  private items: T[] = [];
  push(item: T) {
    this.items.push(item);
  }
}

const sizes = new Stack<string>();
sizes.push("S");
sizes.push("M");
sizes.push(42);

1class Stack<T> {2  private items: T[] = [];3  push(item: T) {4    this.items.push(item);5  }6}7 8const sizes = new Stack<string>();9sizes.push("S");10sizes.push("M");11sizes.push(42); // line 11: 42 is not text

1class RecentList {2  private items: string[] = [];3  add(item: string) {4    this.items = [item, ...this.items].slice(0, 3);5  }6  latest(): string | undefined {7    return this.items[0];8  }9}10 11const viewed = new RecentList();12viewed.add("Tea");13const prices = new RecentList();14prices.add(4);15console.log(viewed.latest(), prices.latest());

1class RecentList<T> {2  private items: T[] = [];3  add(item: T) {4    this.items = [item, ...this.items].slice(0, 3);5  }6  latest(): T | undefined {7    return this.items[0];8  }9}10 11const viewed = new RecentList<string>();12viewed.add("Tea");13const prices = new RecentList<number>();14prices.add(4);15console.log(viewed.latest(), prices.latest());

1class Cache<T> {2  private entries = new Map<string, T>();3  set(key: string, value: T) {4    this.entries.set(key, value);5  }6  get(key: string): T | undefined {7    return this.entries.get(key);8  }9}10 11function showPrice(price: number | undefined) {12  console.log(price === undefined ? "No price" : "$" + price);13}14 15const prices = new Cache();16prices.set("Tea", 3);17showPrice(prices.get("Tea"));

1class Cache<T> {2  private entries = new Map<string, T>();3  set(key: string, value: T) {4    this.entries.set(key, value);5  }6  get(key: string): T | undefined {7    return this.entries.get(key);8  }9}10 11function showPrice(price: number | undefined) {12  console.log(price === undefined ? "No price" : "$" + price);13}14 15const prices = new Cache<number>();16prices.set("Tea", 3);17showPrice(prices.get("Tea"));

1class Stack<T> {2  constructor(private items: T[] = []) {}3  pop(): T | undefined {4    return this.items.pop();5  }6  static of(...items: T[]): Stack<T> {7    return new Stack(items);8  }9}10 11const sizes = Stack.of("S", "M", "L");12console.log(sizes.pop());

1class Stack<T> {2  constructor(private items: T[] = []) {}3  pop(): T | undefined {4    return this.items.pop();5  }6  static of<Item>(...items: Item[]): Stack<Item> {7    return new Stack(items);8  }9}10 11const sizes = Stack.of("S", "M", "L");12//    ^?13console.log(sizes.pop());

1class Cache<T> {2  private entries = new Map<string, T>();3  set(key: string, value: T) {4    this.entries.set(key, value);5  }6  getOr(key: string, fallback) {7    const found = this.entries.get(key);8    return found === undefined ? fallback : found;9  }10}11 12const sizes = new Cache<string>();13sizes.set("shirt", "M");14const size = sizes.getOr("shoes", null);15console.log(size);

1class Cache<T> {2  private entries = new Map<string, T>();3  set(key: string, value: T) {4    this.entries.set(key, value);5  }6  getOr<F>(key: string, fallback: F): T | F {7    const found = this.entries.get(key);8    return found === undefined ? fallback : found;9  }10}11 12const sizes = new Cache<string>();13sizes.set("shirt", "M");14const size = sizes.getOr("shoes", null);15//    ^?16console.log(size);

Check your understanding

For each question, ask when each type parameter is filled in: the class's T when the object is made, or a method's own one at each call. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A generic class has a type parameter after its name, like class Stack<T>, used in its fields, constructor, and instance methods.
• Each object fills in T when it's made: from a type argument, new Stack<string>(), or from the constructor's arguments.
• With nothing to fill it in, T is unknown. Later calls don't change it.
• Static members belong to the one class, shared by every T, so they can't use T. Give a static method its own type parameter.
• A method can have its own type parameter, like map<U>, filled in at each call. Don't declare the class's T again on a method.
• While the code runs, there's no T: instanceof checks only the class.

Coming next: Generics in practice. It builds a typed fetch helper and a typed event emitter, and shows how to read the generic types in a library.