Generic classes

A class parameterised by a type

Why put a type parameter on a class rather than on each method individually? Because you want every method on the instance to share the same resolved T — so a Box<number> can only ever map numbers, no matter which method you call. A generic class declares a type parameter that each instance fills in:

class Box<T> {
  constructor(public value: T) {}
  map<U>(fn: (v: T) => U): Box<U> {
    return new Box(fn(this.value));
  }
}

const b = new Box(42);
//    ^? const b: Box<number>   — T inferred from the constructor argument
const s = b.map((n) => n.toFixed(2));
//    ^? const s: Box<string>   — map's own U inferred from the callback

T is solved from the constructor argument, just like a generic function infers from its call arguments. The method map<U> introduces its own type parameter U, independent of the instance’s T.

The static-side restriction

Each instance binds T to a concrete type. But static members belong to the class object, which exists once, before and across all instances — there is no single T for them to refer to:

class Box<T> {
  constructor(public value: T) {}

  // Error: Static members cannot reference class type parameters.
  static empty(): Box<T> {
    return new Box(undefined as any);
  }
}

The fix is to make the static itself generic — its own type parameter, resolved at the static call:

class Box<T> {
  constructor(public value: T) {}
  static of<U>(value: U): Box<U> {
    return new Box(value);
  }
}

const b = Box.of("hi");
//    ^? const b: Box<string>

Box.of<U> has nothing to do with any instance’s T; it is solved at the static call site. This is why factory methods are written as standalone generics.

A real container: Result<T, E>

Two type parameters model success-or-failure without exceptions:

type Result<T, E> =
  | { ok: true; value: T }
  | { ok: false; error: E };

function ok<T>(value: T): Result<T, never> {
  return { ok: true, value };
}
function err<E>(error: E): Result<never, E> {
  return { ok: false, error };
}

function parsePort(s: string): Result<number, string> {
  const n = Number(s);
  return Number.isInteger(n) && n > 0 ? ok(n) : err(`bad port: ${s}`);
}

const r = parsePort("8080");
if (r.ok) {
  r.value;
//  ^? (property) value: number   — narrowed by the discriminant
} else {
  r.error;
//  ^? (property) error: string
}

ok returns Result<T, never> and err returns Result<never, E> so the unused side is never — assignable to any expected error or value type. The discriminant ok then narrows the union (that was the discriminated-unions lesson) to expose exactly one branch’s payload.

Generic interfaces for factories

Interfaces carry type parameters too, which is how you type a factory or a collection contract independent of any implementation:

interface Repository<T, Id = string> {
  find(id: Id): T | undefined;
  save(entity: T): void;
}

interface Comparator<T> {
  (a: T, b: T): number;
}

const byLength: Comparator<string> = (a, b) => a.length - b.length;
//    ^? const byLength: Comparator<string>

Repository<T, Id = string> shows defaults working on interfaces (most ids are strings); Comparator<T> is a generic call signature — a function type parameterised by T.

Structural compatibility foreshadows variance

Two generic instances are compatible when their contents are compatible — TypeScript is structural, so Box<T> is just “an object with a value: T”:

class Box<T> {
  constructor(public value: T) {}
}

let animals: Box<{ name: string }> = new Box({ name: "Rex", legs: 4 });
//                                            ^ extra prop ok via inference widening
let named: Box<{ name: string }> = new Box({ name: "Rex" });
animals = named; // ok — same T

let dogBox: Box<{ name: string; legs: number }> = new Box({ name: "Rex", legs: 4 });
named = dogBox;  // ok — Box<{name; legs}> assignable to Box<{name}>?  Yes here.
// dogBox = named; // Error: missing 'legs' — narrower target, wider source

Whether Box<Dog> is assignable to Box<Animal> depends on how T is used inside the class — read-only positions behave one way, write positions another. That direction-of-assignability question is variance, and it is the entire next lesson.

What generic containers cost the declaration files

Generics are erased from the emitted JS — class Box<T> compiles to a plain class Box with zero runtime trace of T. But they are very much present in the declaration output. A non-generic container emits a flat .d.ts entry; a deeply parameterised one — Result<T, E>, a Repository<T, Id>, a builder threading three type parameters through a dozen methods — emits every method signature with its full generic shape, and library authors regularly watch a public API’s .d.ts grow from a few kilobytes to tens of kilobytes once the container types get rich. That bundle ships to every consumer and every consumer’s tsc re-checks it, so over-parameterised public types are a tax paid by everyone downstream, not just the author.

There is an editor-latency angle too. Each new Box(...) and each .map(...) call re-runs inference for that instance’s T (and the method’s own U); a screen of chained container operations is a screen of independent inference problems the language server solves on every keystroke. One Result<T, E> is free; a hot path built from twenty stacked generic container calls is where hover and autocomplete start lagging, and the --extendedDiagnostics Check time for that file climbs out of proportion to its line count.