TypeScript Generics: Generic Functions, Types and Classes

Generics are type parameters. A generic function declares a placeholder type, usually called T, and each call fills it in, so the types that go in decide the types that come out. One function then works for numbers, strings and your own objects, and every call is still fully typed.

function first<T>(items: T[]): T | undefined {
  return items[0];
}

const n = first([10, 20, 30]);        // T = number, n: number | undefined
const s = first(["ada", "grace"]);    // T = string, s: string | undefined
const u = first([{ id: 1 }]);         // T = { id: number }

console.log(n?.toFixed(1));           // 10.0
console.log(s?.toUpperCase());        // ADA
console.log(u?.id);                   // 1

<T> after the function name declares the type parameter. items: T[] uses it for the input and T | undefined for the output, which ties the two together. You never wrote number or string: TypeScript inferred T from the argument.

Why Not any or unknown?

Without generics you would type the parameter as any or unknown. Both accept every array, and both lose the connection between input and output:

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

function firstUnknown(items: unknown[]): unknown {
  return items[0];
}

function firstGeneric<T>(items: T[]): T | undefined {
  return items[0];
}

const a = firstAny(["x"]);
console.log(typeof a.toFixed);         // undefined: a.toFixed(2) would compile, then throw

const b = firstUnknown(["x"]);
// b.toUpperCase();                    // error TS18046: 'b' is of type 'unknown'.
console.log(typeof b === "string" ? b.toUpperCase() : "?"); // X (after narrowing)

const c = firstGeneric(["x"]);
console.log(c?.toUpperCase());         // X, with no narrowing needed

Type Argument Inference

Usually TypeScript infers the type arguments from the values you pass. You can also write them explicitly in angle brackets at the call, which is needed when nothing in the arguments mentions T, or when inference picks something you did not want.

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

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

const p1 = pair(1, 2);                      // T inferred as number
const p2 = pair<string | number>(1, "one"); // explicit: mixing allowed
const names = emptyList<string>();          // nothing to infer from, so pass it
names.push("Ada");

console.log(p1, p2, names); // [ 1, 2 ] [ 1, 'one' ] [ 'Ada' ]

Two inference results are worth knowing. pair(1, "one") without the explicit argument is an error: TypeScript infers T = number from the first argument and then reports Argument of type 'string' is not assignable to parameter of type 'number'. (TS2345). And emptyList() with no argument at all gets T = unknown, giving unknown[], which is rarely what you want.

Several Type Parameters

A function can declare as many type parameters as it needs, separated by commas. Each one is inferred independently.

function zip<A, B>(left: A[], right: B[]): [A, B][] {
  const length = Math.min(left.length, right.length);
  const out: [A, B][] = [];
  for (let i = 0; i < length; i++) out.push([left[i], right[i]]);
  return out;
}

function mapValues<K extends string, V, R>(obj: Record<K, V>, fn: (value: V) => R): Record<K, R> {
  const out = {} as Record<K, R>;
  for (const key of Object.keys(obj) as K[]) out[key] = fn(obj[key]);
  return out;
}

console.log(zip(["a", "b", "c"], [1, 2]));        // [ [ 'a', 1 ], [ 'b', 2 ] ]
const prices = mapValues({ tea: 2.5, cake: 4 }, (v) => `$${v.toFixed(2)}`);
console.log(prices);                               // { tea: '$2.50', cake: '$4.00' }

mapValues infers three things at once: K is "tea" | "cake", V is number, and R is string from the callback's return. K extends string is a constraint, covered on the next page.

Generic Interfaces and Type Aliases

Types can take parameters too. You then write the argument when you use the type: Box<number>, ApiResponse<User>. Most built-in collection types work this way: Array<T>, Map<K, V>, Promise<T>, Record<K, V>.

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

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

interface User {
  id: number;
  name: string;
}

function parseAge(text: string): Result<number> {
  const n = Number(text);
  return Number.isInteger(n) && n >= 0 ? { ok: true, value: n } : { ok: false, error: `bad age: ${text}` };
}

const res: ApiResponse<User[]> = { status: 200, data: [{ id: 1, name: "Ada" }] };
console.log(res.data[0].name);   // Ada

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? r.value + 1 : r.error); // 37, then bad age: abc
}

Result<T, E = string> also shows a default type parameter: Result<number> means Result<number, string>. Like optional function parameters, parameters with defaults must come after the required ones.

Generic Classes

A class takes type parameters after its name, and every instance fixes them. Fields, methods and constructor parameters can all use them.

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

  push(item: T): void {
    this.items.push(item);
  }

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

  peek(): T | undefined {
    return this.items.at(-1);
  }

  get size(): number {
    return this.items.length;
  }
}

const visited = new Stack<string>();
visited.push("/home");
visited.push("/docs");
console.log(visited.pop(), visited.size); // /docs 1

const numbers = new Stack<number>();
numbers.push(42);
// numbers.push("42"); // error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
console.log(numbers.peek()); // 42

If the constructor takes a T, you can drop the explicit argument: new Box(5) infers Box<number>. Static members belong to the class itself, not to an instance, so they cannot use the class's type parameter (Static members cannot reference class type parameters., TS2302).

Generic Arrow Functions and Function Types

The type parameter list goes before the parameter list. The same syntax describes a generic function type.

const last = <T>(items: T[]): T | undefined => items[items.length - 1];

type Mapper = <T, R>(items: T[], fn: (item: T) => R) => R[];
const mapAll: Mapper = (items, fn) => items.map(fn);

// In a .tsx file, <T> looks like a JSX tag. Add a trailing comma:
const lastTsx = <T,>(items: T[]) => items[items.length - 1];

Inferring Literal Types With const Type Parameters

By default a generic infers widened types: pair("a", "b") gives [string, string]. When the exact values matter (route names, event names, column lists), mark the parameter const (TypeScript 5.0 and later) and it infers as if the argument were written as const:

function defineColumns<const T extends readonly string[]>(columns: T): T {
  return columns;
}

const loose = ["id", "name"];                  // string[]
const columns = defineColumns(["id", "name"]); // readonly ["id", "name"]

type Column = (typeof columns)[number];        // "id" | "name"
const sortBy: Column = "name";
console.log(columns, sortBy, loose.length);    // [ 'id', 'name' ] name 2

The caller writes an ordinary array, and the function keeps the literal types.

When Not to Use Generics

A type parameter earns its place when it connects two things: a parameter and the return type, two parameters, or a parameter and a callback. If T appears only once, it adds nothing and a plain type is clearer.

// Pointless: T is used once, so it is just a longer way to write unknown
function logValue<T>(value: T): void {
  console.log(value);
}

// Clearer
function logValueSimple(value: unknown): void {
  console.log(value);
}

// Also pointless: returns T but nothing connects T to an argument,
// so the caller is really just asserting a type
function parseJson<T>(text: string): T {
  return JSON.parse(text);
}

The last one is common and misleading: parseJson<User>(text) looks type-safe but checks nothing, exactly like JSON.parse(text) as User. Return unknown and validate instead. Other signs of overuse: a type parameter that is always given the same argument, or one that could be replaced by a union of two known types.

For generics that need to know something about T (that it has a length, or that K is a key of T), constraints with extends are the next step.