TypeScript Advanced Types: A Deep Dive

TypeScript's type system goes far beyond annotating variables with string or number. Its advanced type features let you express complex invariants, build type-safe APIs, and catch entire categories of bugs at compile time. This guide explores the type-level tools that separate TypeScript beginners from power users.

Generics with Constraints

Generics become powerful when you constrain them. The extends keyword limits what types a generic parameter can accept:

interface HasId {
  id: string;
}

function findById<T extends HasId>(items: T[], id: string): T | undefined {
  return items.find(item => item.id === id);
}

// Works: User has an id property
interface User extends HasId { name: string; email: string }
const user = findById<User>(users, "abc-123");

// Error: number[] doesn't have an id property
findById([1, 2, 3], "abc");

You can also constrain generics based on other generic parameters:

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

const user = { name: "Alice", age: 30, email: "alice@example.com" };
const name = getProperty(user, "name");  // type: string
const age = getProperty(user, "age");    // type: number
getProperty(user, "phone");              // Error: "phone" not in keyof User

Conditional Types and the infer Keyword

Conditional types select between two types based on a condition, using the familiar ternary syntax:

type IsString<T> = T extends string ? true : false;

type A = IsString<"hello">;  // true
type B = IsString<42>;       // false

The infer keyword extracts types from within conditional types. It lets you "pattern match" on type structures:

// Extract the return type of a function
type ReturnOf<T> = T extends (...args: any[]) => infer R ? R : never;

type A = ReturnOf<() => string>;           // string
type B = ReturnOf<(x: number) => boolean>; // boolean

// Extract the element type of an array
type ElementOf<T> = T extends (infer E)[] ? E : never;

type C = ElementOf<string[]>;  // string
type D = ElementOf<number[]>;  // number

// Extract Promise resolved type
type Awaited<T> = T extends Promise<infer U> ? Awaited<U> : T;

type E = Awaited<Promise<Promise<string>>>;  // string

A practical example: extracting route parameters from a URL pattern:

type ExtractParams<T extends string> =
  T extends `${string}:${infer Param}/${infer Rest}`
    ? { [K in Param | keyof ExtractParams<Rest>]: string }
    : T extends `${string}:${infer Param}`
    ? { [K in Param]: string }
    : {};

type Params = ExtractParams<"/users/:userId/posts/:postId">;
// { userId: string; postId: string }

Mapped Types

Mapped types transform every property of an existing type. TypeScript's built-in utility types (Partial, Required, Readonly, Pick) are all mapped types:

// Make all properties optional
type Partial<T> = { [K in keyof T]?: T[K] };

// Make all properties required
type Required<T> = { [K in keyof T]-?: T[K] };

// Create a read-only version
type Readonly<T> = { readonly [K in keyof T]: T[K] };

Build custom mapped types for your domain:

// Make all properties nullable
type Nullable<T> = { [K in keyof T]: T[K] | null };

// Create setter functions for each property
type Setters<T> = {
  [K in keyof T as `set${Capitalize<string & K>}`]: (value: T[K]) => void;
};

interface Config {
  host: string;
  port: number;
  debug: boolean;
}

type ConfigSetters = Setters<Config>;
// {
//   setHost: (value: string) => void;
//   setPort: (value: number) => void;
//   setDebug: (value: boolean) => void;
// }

Template Literal Types

Template literal types combine string literal types with interpolation, enabling type-safe string manipulation:

type EventName = "click" | "focus" | "blur";
type HandlerName = `on${Capitalize<EventName>}`;
// "onClick" | "onFocus" | "onBlur"

type CSSProperty = "margin" | "padding";
type CSSDirection = "top" | "right" | "bottom" | "left";
type CSSRule = `${CSSProperty}-${CSSDirection}`;
// "margin-top" | "margin-right" | ... | "padding-left"

Combined with mapped types, template literals enable expressive API types:

type EventMap = {
  click: { x: number; y: number };
  focus: { target: HTMLElement };
  keydown: { key: string; code: string };
};

type EventHandlers = {
  [K in keyof EventMap as `on${Capitalize<string & K>}`]: (event: EventMap[K]) => void;
};

// {
//   onClick: (event: { x: number; y: number }) => void;
//   onFocus: (event: { target: HTMLElement }) => void;
//   onKeydown: (event: { key: string; code: string }) => void;
// }

Discriminated Unions

Discriminated unions use a common literal property to distinguish between variants. TypeScript narrows the type automatically based on the discriminant:

type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E };

function processResult(result: Result<User>) {
  if (result.success) {
    // TypeScript knows result.data is User here
    console.log(result.data.name);
  } else {
    // TypeScript knows result.error is Error here
    console.error(result.error.message);
  }
}

Discriminated unions shine for modeling state machines:

type RequestState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error };

function renderRequest<T>(state: RequestState<T>) {
  switch (state.status) {
    case "idle":
      return <Placeholder />;
    case "loading":
      return <Spinner />;
    case "success":
      return <DataView data={state.data} />;
    case "error":
      return <ErrorMessage error={state.error} />;
  }
}

Use never to ensure exhaustive handling:

function assertNever(x: never): never {
  throw new Error(`Unexpected value: ${x}`);
}

function handleState(state: RequestState<User>) {
  switch (state.status) {
    case "idle": return;
    case "loading": return;
    case "success": return;
    case "error": return;
    default: assertNever(state);
    // If you add a new status but forget to handle it,
    // TypeScript will error here at compile time
  }
}

Branded Types

TypeScript's structural type system means two types with the same shape are interchangeable. Branded types add a phantom property to create nominally distinct types:

type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

function createUserId(id: string): UserId {
  return id as UserId;
}

function createOrderId(id: string): OrderId {
  return id as OrderId;
}

function getUser(id: UserId): Promise<User> { /* ... */ }
function getOrder(id: OrderId): Promise<Order> { /* ... */ }

const userId = createUserId("user-123");
const orderId = createOrderId("order-456");

getUser(userId);   // OK
getUser(orderId);  // Error: OrderId is not assignable to UserId

Branded types prevent mixing up values that have the same underlying type but different semantic meanings. Common uses include currency amounts (USD vs EUR), validated strings (Email vs PhoneNumber), and database IDs for different tables.

Type-Level Programming

Combining these features lets you build sophisticated type-level programs. Here is a type-safe builder pattern:

type BuilderState = {
  host: boolean;
  port: boolean;
  database: boolean;
};

type InitialState = { host: false; port: false; database: false };

class ConnectionBuilder<State extends BuilderState> {
  private config: Partial<ConnectionConfig> = {};

  host(h: string): ConnectionBuilder<State & { host: true }> {
    this.config.host = h;
    return this as any;
  }

  port(p: number): ConnectionBuilder<State & { port: true }> {
    this.config.port = p;
    return this as any;
  }

  database(d: string): ConnectionBuilder<State & { database: true }> {
    this.config.database = d;
    return this as any;
  }

  build(this: ConnectionBuilder<{ host: true; port: true; database: true }>): Connection {
    return new Connection(this.config as ConnectionConfig);
  }
}

new ConnectionBuilder<InitialState>()
  .host("localhost")
  .port(5432)
  .database("mydb")
  .build();  // OK: all required fields set

new ConnectionBuilder<InitialState>()
  .host("localhost")
  .build();  // Error: port and database not set

TypeScript's advanced types are tools for expressing domain constraints in the type system. The compiler then enforces those constraints automatically, catching bugs before code ever runs. Start with discriminated unions and branded types for the highest practical impact, then explore conditional types and mapped types as your needs grow.