typescript-advanced

name	typescript-advanced
description	Advanced TypeScript type system patterns including generics, conditional types, mapped types, template literals, branded types, and utility types. Use when implementing complex type systems, creating reusable type utilities, building type-safe APIs, or ensuring compile-time type safety.

TypeScript Advanced Types

Comprehensive guidance for TypeScript's advanced type system.

When to Use This Skill

• Building type-safe libraries or APIs
• Creating reusable generic components
• Implementing complex type inference logic
• Designing type-safe state management
• Migrating JavaScript to TypeScript
• Working with complex domain models
• Creating compile-time validation

Core Patterns

1. Generics

Basic Generic Function:

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

const num = identity(42);        // Type: number (inferred)
const str = identity("hello");   // Type: string (inferred)

Generic Constraints:

interface HasLength {
  length: number;
}

function logLength<T extends HasLength>(item: T): T {
  console.log(item.length);
  return item;
}

logLength("hello");           // OK: string has length
logLength([1, 2, 3]);         // OK: array has length
// logLength(42);             // Error: number has no length

Multiple Type Parameters:

function merge<T extends object, U extends object>(obj1: T, obj2: U): T & U {
  return { ...obj1, ...obj2 };
}

const merged = merge({ name: "John" }, { age: 30 });
// Type: { name: string } & { age: number }

2. Conditional Types

Basic Conditional Type:

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

type A = IsString<string>;    // true
type B = IsString<number>;    // false

Extracting Types with infer:

// Extract return type
type ReturnType<T> = T extends (...args: any[]) => infer R ? R : never;

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

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

function getUser() {
  return { id: 1, name: "John" };
}

type User = ReturnType<typeof getUser>;
// Type: { id: number; name: string }

Distributive Conditional Types:

type ToArray<T> = T extends any ? T[] : never;

type StrOrNumArray = ToArray<string | number>;
// Type: string[] | number[] (distributed)

3. Mapped Types

Basic Mapped Types:

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

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

// Make all properties readonly
type Readonly<T> = {
  readonly [P in keyof T]: T[P];
};

Key Remapping (TypeScript 4.1+):

type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};

interface Person {
  name: string;
  age: number;
}

type PersonGetters = Getters<Person>;
// Type: { getName: () => string; getAge: () => number }

Filtering Properties:

type PickByType<T, U> = {
  [K in keyof T as T[K] extends U ? K : never]: T[K];
};

interface Mixed {
  id: number;
  name: string;
  age: number;
  active: boolean;
}

type OnlyNumbers = PickByType<Mixed, number>;
// Type: { id: number; age: number }

4. Template Literal Types

Basic Template Literals:

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

type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
type Route = `/api/${'users' | 'posts'}`;
type Endpoint = `${HTTPMethod} ${Route}`;
// Type: "GET /api/users" | "POST /api/users" | ...

Nested Path Types:

type PathKeys<T> = T extends object
  ? {
      [K in keyof T & string]: K | `${K}.${PathKeys<T[K]>}`;
    }[keyof T & string]
  : never;

interface Config {
  server: {
    host: string;
    port: number;
  };
  database: {
    url: string;
  };
}

type ConfigPath = PathKeys<Config>;
// Type: "server" | "server.host" | "server.port" | "database" | "database.url"

5. Branded Types

Prevent mixing similar primitives:

type Brand<K, T> = K & { __brand: T };

type UserId = Brand<string, 'UserId'>;
type ProductId = Brand<string, 'ProductId'>;

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

function getUser(id: UserId) { /* ... */ }

const userId = createUserId('user_123');
const productId = 'prod_456' as ProductId;

getUser(userId);      // OK
// getUser(productId);   // Error: ProductId not assignable to UserId

Branded types for validation:

type ValidEmail = string & { readonly __brand: 'ValidEmail' };

function validateEmail(email: string): ValidEmail | null {
  const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return regex.test(email) ? (email as ValidEmail) : null;
}

function sendEmail(to: ValidEmail, subject: string) {
  // Guaranteed to have valid email
}

6. Discriminated Unions

Type-safe state machines:

type LoadingState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: string[] }
  | { status: 'error'; error: Error };

function renderState(state: LoadingState): string {
  switch (state.status) {
    case 'idle':
      return 'Not started';
    case 'loading':
      return 'Loading...';
    case 'success':
      return `Loaded ${state.data.length} items`;  // data is typed
    case 'error':
      return `Error: ${state.error.message}`;      // error is typed
  }
}

Redux-style actions:

type Action =
  | { type: 'FETCH_USER'; payload: { userId: string } }
  | { type: 'UPDATE_USER'; payload: { userId: string; data: Partial<User> } }
  | { type: 'DELETE_USER'; payload: { userId: string } }
  | { type: 'CLEAR_USERS' };

function reducer(state: State, action: Action): State {
  switch (action.type) {
    case 'FETCH_USER':
      return { ...state, loading: true };  // payload.userId available
    case 'UPDATE_USER':
      return updateUser(state, action.payload);  // payload.data available
    case 'DELETE_USER':
      return deleteUser(state, action.payload.userId);
    case 'CLEAR_USERS':
      return { ...state, users: [] };  // no payload
  }
}

7. Type Guards

Basic type guards:

function isString(value: unknown): value is string {
  return typeof value === 'string';
}

function isArrayOf<T>(
  value: unknown,
  guard: (item: unknown) => item is T
): value is T[] {
  return Array.isArray(value) && value.every(guard);
}

const data: unknown = ['a', 'b', 'c'];

if (isArrayOf(data, isString)) {
  data.forEach(s => s.toUpperCase());  // Type: string[]
}

Assertion functions:

function assertIsString(value: unknown): asserts value is string {
  if (typeof value !== 'string') {
    throw new Error('Not a string');
  }
}

function processValue(value: unknown) {
  assertIsString(value);
  // value is now typed as string
  console.log(value.toUpperCase());
}

Advanced Patterns

Deep Utility Types

type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object
    ? T[P] extends Function
      ? T[P]
      : DeepPartial<T[P]>
    : T[P];
};

type DeepReadonly<T> = {
  readonly [P in keyof T]: T[P] extends object
    ? T[P] extends Function
      ? T[P]
      : DeepReadonly<T[P]>
    : T[P];
};

type DeepRequired<T> = {
  [P in keyof T]-?: T[P] extends object
    ? DeepRequired<T[P]>
    : T[P];
};

Type-Safe Event Emitter

type EventMap = {
  'user:created': { id: string; name: string };
  'user:deleted': { id: string };
};

class TypedEventEmitter<T extends Record<string, any>> {
  private listeners: {
    [K in keyof T]?: Array<(data: T[K]) => void>;
  } = {};

  on<K extends keyof T>(event: K, callback: (data: T[K]) => void): void {
    if (!this.listeners[event]) {
      this.listeners[event] = [];
    }
    this.listeners[event]!.push(callback);
  }

  emit<K extends keyof T>(event: K, data: T[K]): void {
    this.listeners[event]?.forEach(cb => cb(data));
  }
}

const emitter = new TypedEventEmitter<EventMap>();

emitter.on('user:created', (data) => {
  console.log(data.id, data.name);  // Type-safe!
});

emitter.emit('user:created', { id: '1', name: 'John' });
// emitter.emit('user:created', { wrong: 'data' });  // Error

Builder Pattern with Type State

class QueryBuilder<T, HasSelect extends boolean = false> {
  private selectFields?: string[];
  private whereClause?: string;

  select<K extends keyof T>(...fields: K[]): QueryBuilder<Pick<T, K>, true> {
    this.selectFields = fields as string[];
    return this as any;
  }

  where(clause: string): this {
    this.whereClause = clause;
    return this;
  }

  // execute() only available after select() is called
  execute(this: QueryBuilder<T, true>): Promise<T[]> {
    return Promise.resolve([]);
  }
}

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

const query = new QueryBuilder<User>();
// query.execute();  // Error - must call select() first
query.select('id', 'name').execute();  // OK

Function Type Utilities

// Extract parameters
type Parameters<T extends (...args: any) => any> = 
  T extends (...args: infer P) => any ? P : never;

// Curry type
type Curry<T extends any[], R> = T extends [infer First, ...infer Rest]
  ? (arg: First) => Curry<Rest, R>
  : R;

type Add = Curry<[number, number], number>;
// (arg: number) => (arg: number) => number

Best Practices

1. Use unknown over any - Enforce type checking
2. Prefer interface for objects - Better error messages, extensible
3. Use type for unions/intersections - More flexible for complex types
4. Leverage inference - Don't over-annotate; let TypeScript infer
5. Use const assertions - as const preserves literal types
6. Avoid type assertions - Use type guards instead of as
7. Document complex types - Add JSDoc comments
8. Test your types - Use type-level tests

Common Pitfalls

1. Over-using any - Defeats TypeScript's purpose
2. Ignoring strict null checks - Can lead to runtime errors
3. Too complex types - Can slow compilation
4. Not using discriminated unions - Misses type narrowing opportunities
5. Circular type references - Can cause compiler errors
6. Forgetting readonly - Allows unintended mutations

Type Testing

// Type assertion tests
type AssertEqual<T, U> =
  [T] extends [U]
    ? [U] extends [T]
      ? true
      : false
    : false;

type Test1 = AssertEqual<string, string>;        // true
type Test2 = AssertEqual<string, number>;        // false

// Expect helper
type Expect<T extends true> = T;

// Usage
type TestGetters = Expect<AssertEqual<
  Getters<{ name: string }>,
  { getName: () => string }
>>;

Resources

• TypeScript Handbook: https://www.typescriptlang.org/docs/handbook/
• Type Challenges: https://github.com/type-challenges/type-challenges
• TypeScript Deep Dive: https://basarat.gitbook.io/typescript/