Ethan Yu
EthanYu

Advanced TypeScript Patterns That Scale: Beyond the Basics

Six months ago, I inherited a massive TypeScript codebase with over 200k lines of code. The type system was a mess - any types everywhere, type assertions scattered throughout, and generics that made my head spin. Here's how we transformed it into a type-safe masterpiece, and the advanced patterns we discovered along the way.

The Type System Challenge

Initial Codebase State

When inheriting a large TypeScript codebase of over 200,000 lines of code, we faced significant typing challenges. The codebase suffered from loose type definitions, excessive use of 'any' types, and complex generic implementations.

Transformation Goals

Our main objectives were to implement strict typing, eliminate unnecessary 'any' types, and create maintainable generic patterns.

Building Type-Safe Foundations

API Response Types

// Enhanced API response type with improved error handling
interface ApiResponse<T> {
  data: T
  metadata: {
    timestamp: number
    version: string
    cache: boolean
  }
  error?: ApiError
}

interface ApiError {
  code: number
  message: string
  details?: Record<string, unknown>
}

Type-Safe API Client

class ApiClient {
  async get<T>(url: string): Promise<ApiResponse<T>> {
    const response = await fetch(url)
    const data = await response.json()
    return data as ApiResponse<T>
  }

  async post<T, U>(url: string, body: T): Promise<ApiResponse<U>> {
    const response = await fetch(url, {
      method: 'POST',
      body: JSON.stringify(body),
      headers: {
        'Content-Type': 'application/json',
      },
    })
    const data = await response.json()
    return data as ApiResponse<U>
  }
}

Advanced Generic Patterns

Transformer Pattern

// Improved transformer configuration with better type constraints
type TransformerConfig<
  TInput,
  TOutput = TInput,
  TContext extends Record<string, unknown> = Record<string, never>,
> = {
  transform: (input: TInput, context: TContext) => TOutput | Promise<TOutput>
  validate?: (input: TInput) => boolean | Promise<boolean>
  fallback?: (error: Error, input: TInput) => TOutput | Promise<TOutput>
}

// Transformer implementation
class DataTransformer<TInput, TOutput = TInput> {
  private transformers: Array<TransformerConfig<TInput, TOutput>> = []

  addTransformer(config: TransformerConfig<TInput, TOutput>) {
    this.transformers.push(config)
    return this
  }

  async transform(input: TInput): Promise<TOutput> {
    let current = input as unknown as TOutput

    for (const transformer of this.transformers) {
      try {
        if (transformer.validate) {
          const isValid = await transformer.validate(input)
          if (!isValid) throw new Error('Validation failed')
        }

        current = await transformer.transform(input, {})
      } catch (error) {
        if (transformer.fallback) {
          current = await transformer.fallback(error as Error, input)
        } else {
          throw error
        }
      }
    }

    return current
  }
}

Type-Safe Event System

Event Emitter Implementation

// Enhanced event system with improved type safety
type EventMap = {
  'user:updated': { id: string; changes: Partial<User> }
  'data:synced': { timestamp: number; entities: string[] }
  'error:occurred': { code: number; message: string }
}

class TypedEventEmitter<TEventMap extends Record<string, unknown>> {
  private listeners = new Map<
    keyof TEventMap,
    Set<(data: TEventMap[keyof TEventMap]) => void>
  >()

  on<K extends keyof TEventMap>(
    event: K,
    callback: (data: TEventMap[K]) => void,
  ) {
    if (!this.listeners.has(event)) {
      this.listeners.set(event, new Set())
    }
    this.listeners.get(event)?.add(callback as any)
    return this
  }

  emit<K extends keyof TEventMap>(event: K, data: TEventMap[K]) {
    this.listeners.get(event)?.forEach((callback) => callback(data))
    return this
  }
}

// Usage
const emitter = new TypedEventEmitter<EventMap>()
emitter.on('user:updated', ({ id, changes }) => {
  // Fully typed event data
  console.log(`User ${id} updated with`, changes)
})

Conditional Types and Inference

Utility Types

// Advanced utility types
type DeepPartial<T> = T extends object
  ? {
      [P in keyof T]?: DeepPartial<T[P]>
    }
  : T

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

type AsyncFunction<T extends (...args: any[]) => any> = (
  ...args: Parameters<T>
) => Promise<ReturnType<T>>

// Conditional type for API response handling
type ApiResult<T, E = Error> =
  | { success: true; data: T; error?: never }
  | { success: false; data?: never; error: E }

// Type inference helper
function createApi<T extends Record<string, (...args: any[]) => any>>(
  api: T,
): { [K in keyof T]: AsyncFunction<T[K]> } {
  const wrapped = {} as any

  for (const key in api) {
    wrapped[key] = async (...args: any[]) => {
      try {
        const result = await api[key](...args)
        return { success: true, data: result } as ApiResult<
          ReturnType<T[typeof key]>
        >
      } catch (error) {
        return { success: false, error } as ApiResult<never, Error>
      }
    }
  }

  return wrapped
}

Template Literal Types

Type-Safe String Manipulation

// Advanced template literal types
type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE'
type ApiEndpoint = '/users' | '/posts' | '/comments'
type ApiVersion = 'v1' | 'v2'

type ApiRoute = `/${ApiVersion}${ApiEndpoint}`
type ApiRequest = `${HttpMethod} ${ApiRoute}`

// Type-safe route builder
class RouteBuilder<TMethod extends HttpMethod, TRoute extends ApiRoute> {
  constructor(
    private method: TMethod,
    private route: TRoute,
  ) {}

  toString(): ApiRequest {
    return `${this.method} ${this.route}`
  }

  static create<M extends HttpMethod, R extends ApiRoute>(
    method: M,
    route: R,
  ): RouteBuilder<M, R> {
    return new RouteBuilder(method, route)
  }
}

The Results

After implementing these patterns:

type CodebaseMetrics = {
  typeErrors: number
  typeCoverage: number
  maintainability: number
}

const metrics: Record<string, CodebaseMetrics> = {
  before: {
    typeErrors: 247,
    typeCoverage: 67,
    maintainability: 45,
  },
  after: {
    typeErrors: 12,
    typeCoverage: 98,
    maintainability: 89,
  },
}

Key Learnings and Best Practices

Type System Architecture

  1. Invest early in type system architecture
  2. Document complex generic constraints thoroughly

Pattern Implementation

  1. Leverage template literal types for type-safe API designs
  2. Use type inference strategically

Looking Forward

The TypeScript ecosystem continues to evolve with powerful features like variadic tuple types and recursive conditional types. These advancements enable even more sophisticated type-safe patterns while maintaining code readability and maintainability.

For more insights on modern frontend development, explore our related articles on Web Performance Optimization and State Management Patterns.

Remember, the goal of TypeScript's type system isn't to make coding harder - it's to make maintaining and scaling your codebase easier. Start with the basics, gradually introduce advanced patterns, and always prioritize readability.

P.S. Want to see how these patterns work in a real-world React application? Take a look at my article on Redux to Zustand Migration where I demonstrate how strong typing improves state management.

Comments