typescript-patterns

name	typescript-patterns
description	Modern TypeScript patterns for type-safe, maintainable code. Use when designing interfaces, working with generics, or implementing type utilities. Triggers on TypeScript, type, interface, generic, discriminated union, type guard, infer, utility type.

TypeScript Best Practices

Modern TypeScript patterns for type-safe, maintainable code with maximum developer experience.

When to Use This Skill

• Designing interfaces and types
• Working with generics
• Creating type-safe APIs
• Implementing type guards
• Building utility types

Core Principles

Use TypeScript Strict Mode

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  }
}

Prefer interface for Objects

// ✅ GOOD: Interface for object shapes
interface Task {
  id: string;
  title: string;
  status: TaskStatus;
}

// ✅ GOOD: Type for unions, primitives, utilities
type TaskStatus = 'pending' | 'active' | 'completed';
type TaskId = string;
type TaskRecord = Record<string, Task>;

// Interface can be extended
interface TimestampedTask extends Task {
  createdAt: Date;
  updatedAt: Date;
}

Make Invalid States Unrepresentable

// ❌ BAD: Allows invalid states
interface Session {
  status: 'idle' | 'running' | 'completed' | 'error';
  startedAt?: Date;
  completedAt?: Date;
  error?: Error;
  result?: SessionResult;
}
// Can have error with status 'completed', result with status 'idle', etc.

// ✅ GOOD: Discriminated union - each state is explicit
type Session = 
  | { status: 'idle' }
  | { status: 'running'; startedAt: Date }
  | { status: 'completed'; startedAt: Date; completedAt: Date; result: SessionResult }
  | { status: 'error'; startedAt: Date; error: Error };

// TypeScript enforces correct fields for each state
function handleSession(session: Session) {
  switch (session.status) {
    case 'idle':
      // Only idle-specific fields available
      return 'Ready to start';
      
    case 'running':
      // startedAt is guaranteed to exist
      return `Running since ${session.startedAt.toISOString()}`;
      
    case 'completed':
      // result is guaranteed to exist
      return `Completed: ${session.result.summary}`;
      
    case 'error':
      // error is guaranteed to exist
      return `Error: ${session.error.message}`;
  }
}

Type Guards

Custom Type Guards

// Type guard with `is` keyword
function isTask(value: unknown): value is Task {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    'title' in value &&
    'status' in value &&
    typeof (value as Task).id === 'string' &&
    typeof (value as Task).title === 'string'
  );
}

// Usage
function processItem(item: unknown) {
  if (isTask(item)) {
    // TypeScript knows item is Task here
    console.log(item.title);
  }
}

Assertion Functions

// Assertion function - throws if invalid
function assertTask(value: unknown): asserts value is Task {
  if (!isTask(value)) {
    throw new Error('Invalid task data');
  }
}

// Usage
function processResponse(data: unknown) {
  assertTask(data);
  // TypeScript knows data is Task after this point
  return data.title;
}

Discriminated Union Type Guards

type AgentStep = 
  | { type: 'text'; content: string }
  | { type: 'tool_call'; toolName: string; args: Record<string, unknown> }
  | { type: 'tool_result'; toolName: string; result: unknown };

// Type guard for specific variant
function isToolCall(step: AgentStep): step is Extract<AgentStep, { type: 'tool_call' }> {
  return step.type === 'tool_call';
}

// Usage
function handleStep(step: AgentStep) {
  if (isToolCall(step)) {
    // TypeScript knows toolName and args exist
    executeToolCall(step.toolName, step.args);
  }
}

Generics

Basic Generic Functions

// Generic function for type-safe operations
function first<T>(items: T[]): T | undefined {
  return items[0];
}

// Type is inferred
const task = first(tasks);  // task: Task | undefined
const num = first([1, 2, 3]);  // num: number | undefined

Constrained Generics

// Constrain to objects with id
interface HasId {
  id: string;
}

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

// Works with any type that has id
const task = findById(tasks, 'task-1');  // task: Task | undefined
const user = findById(users, 'user-1');  // user: User | undefined

Generic Interfaces

// Generic result type
interface Result<T, E = Error> {
  success: boolean;
  data?: T;
  error?: E;
}

// Type-safe success/error functions
function success<T>(data: T): Result<T> {
  return { success: true, data };
}

function failure<E = Error>(error: E): Result<never, E> {
  return { success: false, error };
}

// Usage
async function fetchTask(id: string): Promise<Result<Task>> {
  try {
    const task = await taskService.get(id);
    return success(task);
  } catch (e) {
    return failure(e as Error);
  }
}

Utility Types

Built-in Utility Types

interface Task {
  id: string;
  title: string;
  description: string;
  status: TaskStatus;
  priority: number;
  createdAt: Date;
}

// Partial - all properties optional
type TaskUpdate = Partial<Task>;

// Pick - select specific properties
type TaskSummary = Pick<Task, 'id' | 'title' | 'status'>;

// Omit - exclude specific properties
type CreateTaskInput = Omit<Task, 'id' | 'createdAt'>;

// Required - make all required
type RequiredTask = Required<Task>;

// Record - create object type
type TasksByStatus = Record<TaskStatus, Task[]>;

// Readonly - make immutable
type ImmutableTask = Readonly<Task>;

Custom Utility Types

// Make specific properties required
type RequireKeys<T, K extends keyof T> = T & Required<Pick<T, K>>;
type TaskWithTitle = RequireKeys<Partial<Task>, 'title'>;

// Make specific properties optional
type OptionalKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
type TaskOptionalDescription = OptionalKeys<Task, 'description'>;

// Extract non-nullable
type NonNullableFields<T> = {
  [K in keyof T]: NonNullable<T[K]>;
};

// Deep partial
type DeepPartial<T> = {
  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
};

Template Literal Types

// Event name generation
type EventName<T extends string> = `on${Capitalize<T>}`;
type TaskEventName = EventName<'create' | 'update' | 'delete'>;
// 'onCreate' | 'onUpdate' | 'onDelete'

// API route types
type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';
type Route<M extends Method, P extends string> = `${M} ${P}`;

type TaskRoutes = 
  | Route<'GET', '/tasks'>
  | Route<'GET', '/tasks/:id'>
  | Route<'POST', '/tasks'>
  | Route<'PUT', '/tasks/:id'>
  | Route<'DELETE', '/tasks/:id'>;

Const Assertions

// Without as const - types are widened
const config = {
  apiUrl: 'https://api.example.com',  // string
  timeout: 5000,  // number
  retries: 3,  // number
};

// With as const - literal types preserved
const config = {
  apiUrl: 'https://api.example.com',
  timeout: 5000,
  retries: 3,
} as const;
// { readonly apiUrl: 'https://api.example.com'; readonly timeout: 5000; readonly retries: 3 }

// Useful for enums
const TaskStatus = {
  PENDING: 'pending',
  ACTIVE: 'active',
  COMPLETED: 'completed',
} as const;

type TaskStatus = typeof TaskStatus[keyof typeof TaskStatus];
// 'pending' | 'active' | 'completed'

Function Overloads

// Multiple signatures for different use cases
function createTask(title: string): Task;
function createTask(input: CreateTaskInput): Task;
function createTask(titleOrInput: string | CreateTaskInput): Task {
  if (typeof titleOrInput === 'string') {
    return {
      id: generateId(),
      title: titleOrInput,
      status: 'pending',
      priority: 3,
      createdAt: new Date(),
    };
  }
  return {
    id: generateId(),
    ...titleOrInput,
    createdAt: new Date(),
  };
}

// Usage - TypeScript picks correct overload
const task1 = createTask('Quick task');
const task2 = createTask({ title: 'Detailed task', priority: 1 });

Branded Types

// Prevent mixing semantically different types
declare const brand: unique symbol;

type Brand<T, B> = T & { [brand]: B };

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

function getTask(id: TaskId): Task { /* ... */ }
function getUser(id: UserId): User { /* ... */ }

// Create branded values
function taskId(id: string): TaskId {
  return id as TaskId;
}

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

// TypeScript prevents mixing
const tId = taskId('task-1');
const uId = userId('user-1');

getTask(tId);  // ✅ OK
getTask(uId);  // ❌ Error: UserId not assignable to TaskId

Inference with infer

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

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

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

// Extract function parameters
type FirstParam<T> = T extends (first: infer F, ...rest: any[]) => any ? F : never;

// Usage
type TaskServiceReturn = ReturnTypeOf<typeof taskService.getAll>;
// Task[]

type FetchedTask = Awaited<ReturnType<typeof fetchTask>>;
// Task

type SingleTask = ElementOf<Task[]>;
// Task

Best Practices Summary

Do	Don't
Use interface for objects	Use type for everything
Use discriminated unions	Use optional properties for state
Enable strict mode	Disable for convenience
Use type guards	Use type assertions (as)
Make invalid states unrepresentable	Allow ambiguous states
Use generics for reusable code	Duplicate type definitions
Prefer unknown over any	Use any to bypass checks
Use const assertions for literals	Let types widen unnecessarily