Generics

1The Problem Generics Solve

Without generics, writing a reusable function forces an unpleasant choice: either lock it to one specific type (not reusable), or use any (reusable, but loses all type safety).

function firstAny(arr: any[]): any {
  return arr[0];
}

const num = firstAny([1, 2, 3]);      // typed `any` — no safety, could be anything
const str = firstAny(["a", "b"]);      // also `any` — TypeScript forgot it was a string array

2Generic Functions — Type Parameters

A type parameter (conventionally T) lets a function stay fully reusable while preserving the exact type relationship between its inputs and output.

function first<T>(arr: T[]): T {
  return arr[0];
}

const num = first([1, 2, 3]);     // T inferred as number → num: number
const str = first(["a", "b"]);     // T inferred as string → str: string

T is a placeholder decided per call site — first([1,2,3]) and first(["a","b"]) each independently substitute their own concrete type for T, without you writing it explicitly (thanks to inference, previewed in the Type Inference topic and covered in depth in Part 2 of this topic).

3Multiple Type Parameters

function pair<A, B>(first: A, second: B): [A, B] {
  return [first, second];
}

const p = pair("age", 30); // [string, number], both inferred independently

4Generic Interfaces and Type Aliases

interface Box<T> {
  value: T;
}

const numberBox: Box<number> = { value: 42 };

type Pair<A, B> = { first: A; second: B };
const p: Pair<string, number> = { first: "age", second: 30 };

5Generic Classes

class Stack<T> {
  private items: T[] = [];

  push(item: T): void {
    this.items.push(item);
  }
  pop(): T | undefined {
    return this.items.pop();
  }
}

const numberStack = new Stack<number>();
numberStack.push(1);
// numberStack.push("a"); // ❌ error — this Stack instance is locked to T = number

Once instantiated with a concrete type (Stack<number>), every method on that instance is checked against that specific substitution — push only accepts number for that particular stack.

6Explicit Type Arguments

function wrapInArray<T>(value: T): T[] {
  return [value];
}

const explicit = wrapInArray<string>("hello"); // explicitly specify T, instead of relying on inference
const inferred = wrapInArray("hello");           // same result — T inferred as string automatically

Explicit type arguments are needed when there's nothing for the checker to infer from (an empty array literal with no other context, for example) or when you deliberately want a wider type than inference alone would choose.

7Default Type Parameters

interface ApiResponse<T = unknown> {
  data: T;
  status: number;
}

const response: ApiResponse = { data: "anything", status: 200 }; // T defaults to unknown
const typedResponse: ApiResponse<string> = { data: "hello", status: 200 }; // T explicitly string

A default type parameter behaves like a default function parameter — used only when no type argument is supplied and nothing can be inferred.

1How Generic Type Inference Actually Works

When you call first([1, 2, 3]), TypeScript doesn't guess T — it solves for it by comparing the shape of the argument against the shape of the parameter type, position by position, and reading off whatever concrete type lines up with T.

function first<T>(arr: T[]): T { return arr[0]; }

first([1, 2, 3]);
// parameter shape:  T[]
// argument shape:    number[]
// aligning them:      T = number

This process is called unification — finding a substitution for the type variable(s) that makes the parameter type and argument type match. It's the same general idea as inference algorithms in other statically-typed languages with generics (Java, C#, Rust), adapted to TypeScript's structural type system.

2Inference from Multiple Arguments — Combining Evidence

function combine<T>(a: T, b: T): T[] {
  return [a, b];
}

combine(1, 2);          // T = number
combine(1, "two");       // T = number | string — the checker computes the BEST COMMON TYPE across both

When multiple arguments all constrain the same type parameter, TypeScript doesn't just use the first one — it collects evidence from every position and computes the best common type across all of them (same mechanism as the Type Inference topic's array best-common-type rule, applied here to a type parameter instead of an array's element type).

3When Inference Fails: Needing Explicit Type Arguments

function createEmpty<T>(): T[] {
  return [];
}

const arr = createEmpty(); // T has NOTHING to infer from — no argument mentions T at all
// arr's type ends up as `unknown[]` in strict settings, not a useful specific type

const arr2 = createEmpty<string>(); // must supply T explicitly here

Inference can only work when T appears somewhere in the function's actual parameters — a type parameter that only appears in the return type has no argument to unify against, forcing an explicit type argument.

4Generic Constraints (Preview)

function getLength<T extends { length: number }>(item: T): number {
  return item.length;
}

extends here restricts which types are valid for T — full depth is the Generic Constraints topic; the short version is that unconstrained T can be anything, which means the function body can only do things valid for literally every possible type (nothing, essentially) until a constraint narrows what's guaranteed to exist.

5Generics Are Erased Too — No Runtime Type Parameters

function identity<T>(value: T): T {
  return value;
}

compiles to:

function identity(value) {
  return value;
}

T never exists at runtime in any form — there's no way to inspect "what was T instantiated as" inside the function body at runtime, unlike languages with runtime generic reflection (C#'s typeof(T)). If you need runtime knowledge of the type, it must be passed as an ordinary runtime value (e.g. a constructor function or a string tag), not derived from the erased type parameter.

TypeScript:  identity<T>(value: T): T   → ONE generic definition, checked structurally
Compiled JS:  function identity(value) { return value; }   → ONE function, used for every T

function unwrap<T>(box: { value: T }): T { return box.value; }

unwrap({ value: 42 });
// parameter shape:  { value: T }
// argument shape:    { value: 42 }  →  { value: number }
// walking into the matching property: T = number

⚠️ Common Pitfalls

1. Expecting a type parameter to give runtime type information — T is fully erased; nothing about it exists once compiled, per section 5.
2. Writing an unconstrained T and then trying to use T-specific operations — with no constraint, T could be anything, so the function body can't assume it has any properties or methods at all (see the Generic Constraints topic).
3. Assuming generics generate separate compiled code per type, the way C++ templates do — TypeScript compiles to exactly one function; all the "specialization" is purely a compile-time checking activity.
4. Forgetting inference needs T in the parameters — a type parameter that only appears in the return type can't be inferred from arguments; it needs either an explicit type argument or a contextual type at the call site.

📋 Quick Reference

function f<T>(x: T): T {}          → T inferred by unifying parameter shape against argument shape
f<string>(x)                          → explicit type argument, when inference has nothing to work from
generics erased entirely at compile     → no runtime reflection of T, ever
one compiled function, not one per T     → checking is per-call-site, code is not duplicated

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

Source: ts_generics_theory_1.md, ts_generics_theory_2.md · generated by tools/build_lessons.py