Generics

The Cache That Almost Crashed Our Database

It was 2:15 PM on a Tuesday when our database server's CPU hit 98%. Queries that took 5ms were timing out. Our ops team was preparing to scale up the instance – a $3,000/month increase.

I checked our application code and found the culprit:

// cache.js - Our old JavaScript cache
class Cache {
  constructor() {
    this.data = new Map();
  }
  
  get(key) {
    return this.data.get(key);  // What type is this?
  }
  
  set(key, value) {
    this.data.set(key, value);  // What type is value?
  }
}

// Usage
const userCache = new Cache();
userCache.set('user-123', { id: '123', name: 'John' });

const user = userCache.get('user-123');
console.log(user.name);  // Works

// But then someone did this:
const productCache = new Cache();
productCache.set('prod-456', '{"id":"456","name":"Laptop"}');  // String instead of object!

const product = productCache.get('prod-456');
console.log(product.price);  // Undefined! Should have been parsed first

Without types, developers stored raw JSON strings instead of parsed objects. The app repeatedly parsed the same JSON and hit the database when it failed. Result: 15,000 unnecessary database queries per minute.

I rewrote it with TypeScript generics:

class Cache<T> {
  private data = new Map<string, T>();
  
  get(key: string): T | undefined {
    return this.data.get(key);
  }
  
  set(key: string, value: T): void {
    this.data.set(key, value);
  }
}

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

interface Product {
  id: string;
  name: string;
  price: number;
}

const userCache = new Cache<User>();
userCache.set('user-123', { id: '123', name: 'John', email: '[email protected]' });

const user = userCache.get('user-123');
if (user) {
  console.log(user.name);  // TypeScript knows user is User
}

const productCache = new Cache<Product>();
// productCache.set('prod-456', '{"id":"456"}');  // ✗ Error: string not assignable to Product
productCache.set('prod-456', { id: '456', name: 'Laptop', price: 999 });  // ✓

Result: Type errors caught at compile time. Database load dropped to normal. Saved $3,000/month.

This article covers generics – TypeScript's most powerful feature for building reusable, type-safe code.

---

Generic Functions

Functions that work with multiple types while preserving type information.

Basic Generic Function

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

const num = identity(42);           // Type: number
const str = identity('hello');      // Type: string
const bool = identity(true);        // Type: boolean

// Explicit type argument
const value = identity<string>('world');  // Type: string

Generic Array Functions

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

const numbers = [1, 2, 3];
const first = firstElement(numbers);  // Type: number | undefined

const strings = ['a', 'b', 'c'];
const firstStr = firstElement(strings);  // Type: string | undefined

// Empty array
const empty: number[] = [];
const result = firstElement(empty);  // Type: number | undefined

Multiple Type Parameters

function pair<T, U>(first: T, second: U): [T, U] {
  return [first, second];
}

const p1 = pair('name', 42);           // Type: [string, number]
const p2 = pair(true, 'yes');          // Type: [boolean, string]
const p3 = pair({ id: 1 }, [1, 2]);    // Type: [{ id: number }, number[]]

Real-World Example: API Wrapper

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
  timestamp: Date;
}

async function fetchData<T>(url: string): Promise<ApiResponse<T>> {
  try {
    const response = await fetch(url);
    const data = await response.json();
    
    return {
      success: true,
      data: data as T,
      timestamp: new Date()
    };
  } catch (error) {
    return {
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error',
      timestamp: new Date()
    };
  }
}

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

const userResponse = await fetchData<User>('/api/users/123');
if (userResponse.success && userResponse.data) {
  console.log(userResponse.data.name);  // TypeScript knows this is User
}

---

Generic Constraints

Restrict generic types to types with specific properties.

extends Constraint

interface HasLength {
  length: number;
}

function getLength<T extends HasLength>(item: T): number {
  return item.length;
}

getLength('hello');            // ✓ String has length
getLength([1, 2, 3]);          // ✓ Array has length
getLength({ length: 10 });     // ✓ Object has length
// getLength(42);              // ✗ Error: number doesn't have length

Constraining to Object Types

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

const user = {
  id: '123',
  name: 'John',
  age: 30
};

const name = getProperty(user, 'name');    // Type: string
const age = getProperty(user, 'age');      // Type: number
// const invalid = getProperty(user, 'email');  // ✗ Error: 'email' doesn't exist on user

Multiple Constraints

interface Printable {
  toString(): string;
}

interface Comparable {
  compareTo(other: any): number;
}

function compare<T extends Printable & Comparable>(a: T, b: T): number {
  console.log(`Comparing ${a.toString()} and ${b.toString()}`);
  return a.compareTo(b);
}

---

Generic Interfaces

Interfaces with type parameters.

Basic Generic Interface

interface Box<T> {
  value: T;
  getValue(): T;
  setValue(value: T): void;
}

const numberBox: Box<number> = {
  value: 42,
  getValue() {
    return this.value;
  },
  setValue(value: number) {
    this.value = value;
  }
};

const stringBox: Box<string> = {
  value: 'hello',
  getValue() {
    return this.value;
  },
  setValue(value: string) {
    this.value = value;
  }
};

Generic Interface with Multiple Parameters

interface Pair<K, V> {
  key: K;
  value: V;
}

const userIdToName: Pair<number, string> = {
  key: 123,
  value: 'John Doe'
};

const emailToUser: Pair<string, User> = {
  key: '[email protected]',
  value: {
    id: '123',
    name: 'John',
    email: '[email protected]'
  }
};

Real-World Example: Repository Pattern

interface Repository<T> {
  findById(id: string): Promise<T | null>;
  findAll(): Promise<T[]>;
  create(item: Omit<T, 'id'>): Promise<T>;
  update(id: string, item: Partial<T>): Promise<T>;
  delete(id: string): Promise<boolean>;
}

interface User {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
}

class UserRepository implements Repository<User> {
  async findById(id: string): Promise<User | null> {
    // Implementation
    return null;
  }
  
  async findAll(): Promise<User[]> {
    // Implementation
    return [];
  }
  
  async create(item: Omit<User, 'id'>): Promise<User> {
    const newUser: User = {
      id: generateId(),
      ...item,
      createdAt: new Date()
    };
    // Save to database
    return newUser;
  }
  
  async update(id: string, item: Partial<User>): Promise<User> {
    // Implementation
    throw new Error('Not implemented');
  }
  
  async delete(id: string): Promise<boolean> {
    // Implementation
    return true;
  }
}

---

Generic Classes

Classes with type parameters.

Basic Generic Class

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[this.items.length - 1];
  }
  
  isEmpty(): boolean {
    return this.items.length === 0;
  }
  
  size(): number {
    return this.items.length;
  }
}

const numberStack = new Stack<number>();
numberStack.push(1);
numberStack.push(2);
numberStack.push(3);
console.log(numberStack.pop());  // 3

const stringStack = new Stack<string>();
stringStack.push('a');
stringStack.push('b');
console.log(stringStack.pop());  // 'b'

Generic Class with Constraints

interface Comparable<T> {
  compareTo(other: T): number;
}

class SortedList<T extends Comparable<T>> {
  private items: T[] = [];
  
  add(item: T): void {
    this.items.push(item);
    this.items.sort((a, b) => a.compareTo(b));
  }
  
  get(index: number): T | undefined {
    return this.items[index];
  }
  
  toArray(): T[] {
    return [...this.items];
  }
}

class Person implements Comparable<Person> {
  constructor(public name: string, public age: number) {}
  
  compareTo(other: Person): number {
    return this.age - other.age;
  }
}

const people = new SortedList<Person>();
people.add(new Person('Alice', 30));
people.add(new Person('Bob', 25));
people.add(new Person('Charlie', 35));

console.log(people.toArray());  // Sorted by age: Bob(25), Alice(30), Charlie(35)

Real-World Example: Event Emitter

type Listener<T> = (data: T) => void;

class EventEmitter<T> {
  private listeners: Listener<T>[] = [];
  
  on(listener: Listener<T>): () => void {
    this.listeners.push(listener);
    
    // Return unsubscribe function
    return () => {
      const index = this.listeners.indexOf(listener);
      if (index > -1) {
        this.listeners.splice(index, 1);
      }
    };
  }
  
  emit(data: T): void {
    this.listeners.forEach(listener => listener(data));
  }
  
  removeAllListeners(): void {
    this.listeners = [];
  }
}

interface UserLoggedIn {
  userId: string;
  timestamp: Date;
}

const loginEmitter = new EventEmitter<UserLoggedIn>();

const unsubscribe = loginEmitter.on(event => {
  console.log(`User ${event.userId} logged in at ${event.timestamp}`);
});

loginEmitter.emit({
  userId: '123',
  timestamp: new Date()
});

// Later: unsubscribe()

---

Default Type Parameters

Provide default types for generics.

Basic Default Type

interface Request<T = any> {
  url: string;
  method: string;
  body?: T;
}

// Use default
const request1: Request = {
  url: '/api/users',
  method: 'GET'
};

// Override default
interface UserCreateData {
  email: string;
  name: string;
}

const request2: Request<UserCreateData> = {
  url: '/api/users',
  method: 'POST',
  body: {
    email: '[email protected]',
    name: 'John Doe'
  }
};

Default with Constraints

interface ApiResponse<T = unknown, E = Error> {
  success: boolean;
  data?: T;
  error?: E;
}

// Use defaults
const response1: ApiResponse = {
  success: false,
  error: new Error('Something went wrong')
};

// Override both
interface CustomError {
  code: string;
  message: string;
}

const response2: ApiResponse<User, CustomError> = {
  success: false,
  error: {
    code: 'USER_NOT_FOUND',
    message: 'User does not exist'
  }
};

---

Generic Utility Functions

Build reusable utility functions with generics.

Map Function

function map<T, U>(array: T[], fn: (item: T) => U): U[] {
  const result: U[] = [];
  for (const item of array) {
    result.push(fn(item));
  }
  return result;
}

const numbers = [1, 2, 3, 4, 5];
const doubled = map(numbers, n => n * 2);        // number[]
const strings = map(numbers, n => `#${n}`);      // string[]
const objects = map(numbers, n => ({ value: n }));  // { value: number }[]

Filter Function

function filter<T>(array: T[], predicate: (item: T) => boolean): T[] {
  const result: T[] = [];
  for (const item of array) {
    if (predicate(item)) {
      result.push(item);
    }
  }
  return result;
}

const numbers = [1, 2, 3, 4, 5, 6];
const evens = filter(numbers, n => n % 2 === 0);  // [2, 4, 6]

interface User {
  id: string;
  name: string;
  active: boolean;
}

const users: User[] = [
  { id: '1', name: 'Alice', active: true },
  { id: '2', name: 'Bob', active: false },
  { id: '3', name: 'Charlie', active: true }
];

const activeUsers = filter(users, u => u.active);

Reduce Function

function reduce<T, U>(
  array: T[],
  fn: (accumulator: U, item: T) => U,
  initial: U
): U {
  let result = initial;
  for (const item of array) {
    result = fn(result, item);
  }
  return result;
}

const numbers = [1, 2, 3, 4, 5];
const sum = reduce(numbers, (acc, n) => acc + n, 0);  // 15
const product = reduce(numbers, (acc, n) => acc * n, 1);  // 120

interface Product {
  name: string;
  price: number;
}

const products: Product[] = [
  { name: 'Laptop', price: 999 },
  { name: 'Mouse', price: 25 },
  { name: 'Keyboard', price: 75 }
];

const totalPrice = reduce(products, (acc, p) => acc + p.price, 0);  // 1099

---

Advanced Generic Patterns

Generic Factory Function

type Constructor<T> = new (...args: any[]) => T;

function createInstance<T>(ctor: Constructor<T>, ...args: any[]): T {
  return new ctor(...args);
}

class User {
  constructor(public name: string, public email: string) {}
}

const user = createInstance(User, 'John', '[email protected]');
// Type: User

Generic Mixin Pattern

type Constructor<T = {}> = new (...args: any[]) => T;

function Timestamped<T extends Constructor>(Base: T) {
  return class extends Base {
    timestamp = new Date();
  };
}

function Identifiable<T extends Constructor>(Base: T) {
  return class extends Base {
    id = Math.random().toString(36);
  };
}

class User {
  constructor(public name: string) {}
}

const TimestampedUser = Timestamped(User);
const IdentifiableUser = Identifiable(User);
const FullUser = Timestamped(Identifiable(User));

const user = new FullUser('John');
console.log(user.name);       // 'John'
console.log(user.id);         // Random ID
console.log(user.timestamp);  // Current date

Conditional Types with Generics

type Unwrap<T> = T extends Promise<infer U> ? U : T;

type A = Unwrap<Promise<string>>;  // string
type B = Unwrap<string>;            // string

async function getValue(): Promise<number> {
  return 42;
}

type ReturnType1 = Unwrap<ReturnType<typeof getValue>>;  // number

---

Real-World Example: Type-Safe State Management

interface State {
  user: User | null;
  cart: CartItem[];
  theme: 'light' | 'dark';
}

type Action<T extends keyof State, P = State[T]> = {
  type: T;
  payload: P;
};

type StateAction = 
  | Action<'user', User | null>
  | Action<'cart', CartItem[]>
  | Action<'theme', 'light' | 'dark'>;

class Store<T> {
  private state: T;
  private listeners: Array<(state: T) => void> = [];
  
  constructor(initialState: T) {
    this.state = initialState;
  }
  
  getState(): T {
    return this.state;
  }
  
  setState<K extends keyof T>(key: K, value: T[K]): void {
    this.state = {
      ...this.state,
      [key]: value
    };
    this.notify();
  }
  
  subscribe(listener: (state: T) => void): () => void {
    this.listeners.push(listener);
    
    return () => {
      const index = this.listeners.indexOf(listener);
      if (index > -1) {
        this.listeners.splice(index, 1);
      }
    };
  }
  
  private notify(): void {
    this.listeners.forEach(listener => listener(this.state));
  }
}

const store = new Store<State>({
  user: null,
  cart: [],
  theme: 'light'
});

store.setState('user', {
  id: '123',
  name: 'John',
  email: '[email protected]'
});

store.setState('theme', 'dark');

// store.setState('theme', 'blue');  // ✗ Error: 'blue' not assignable
// store.setState('invalid', 123);   // ✗ Error: 'invalid' not a key

---

Common Mistakes I Made

1. Not Using Generic Constraints

Bad:

function getProperty<T>(obj: T, key: string): any {
  return obj[key];  // Any type, no safety!
}

Good:

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

2. Over-Complicating with Generics

Bad:

function add<T extends number, U extends number>(a: T, b: U): number {
  return a + b;  // Unnecessarily generic
}

Good:

function add(a: number, b: number): number {
  return a + b;  // Simple is better
}

3. Forgetting Generic Constraints

Bad:

function sortBy<T>(array: T[], key: string): T[] {
  return array.sort((a, b) => a[key] - b[key]);  // What if key doesn't exist?
}

Good:

function sortBy<T, K extends keyof T>(array: T[], key: K): T[] {
  return array.sort((a, b) => {
    const aVal = a[key];
    const bVal = b[key];
    
    if (typeof aVal === 'number' && typeof bVal === 'number') {
      return aVal - bVal;
    }
    return 0;
  });
}

---

Your Challenge

Build a type-safe query builder:

// TODO: Define these types

interface User {
  id: string;
  email: string;
  name: string;
  age: number;
  createdAt: Date;
}

// TODO: Build a generic QueryBuilder

class QueryBuilder<T> {
  // where(key: keyof T, value: T[keyof T]): QueryBuilder<T>
  // select<K extends keyof T>(...keys: K[]): QueryBuilder<Pick<T, K>>
  // orderBy(key: keyof T, direction: 'asc' | 'desc'): QueryBuilder<T>
  // limit(count: number): QueryBuilder<T>
  // execute(): Promise<T[]>
}

// Usage should work like this:
const query = new QueryBuilder<User>()
  .where('age', 30)
  .select('id', 'name', 'email')
  .orderBy('createdAt', 'desc')
  .limit(10)
  .execute();

// Type of query should be Promise<Pick<User, 'id' | 'name' | 'email'>[]>

// Requirements:
// 1. Type-safe property access (only valid keys)
// 2. Type-safe select (return type matches selected fields)
// 3. Generic constraints where needed
// 4. Fluent/chainable API
// 5. No any types

---

Key Takeaways

1. Generics preserve type information - work with any type safely

2. Generic constraints - restrict types with extends

3. Generic interfaces - reusable type-safe contracts

4. Generic classes - type-safe data structures

5. Default type parameters - provide sensible defaults

6. keyof constraint - type-safe property access

7. Don't over-use - generics add complexity, use when needed

---

What I Learned

The database overload incident taught me: generics are about type preservation, not type flexibility.

Without generics:

class Cache {
  get(key) { return this.data.get(key); }  // Returns any
  set(key, value) { this.data.set(key, value); }  // Accepts any
}

We stored strings when we meant to store objects. The cache became unreliable. Type information was lost. Result: 15,000 unnecessary database queries per minute.

With generics:

class Cache<T> {
  get(key: string): T | undefined { /* ... */ }
  set(key: string, value: T): void { /* ... */ }
}

const userCache = new Cache<User>();  // Only accepts/returns User
const productCache = new Cache<Product>();  // Only accepts/returns Product

Type information flows through. The compiler catches mistakes. The cache does what it promises.

The $3,000/month savings came from type safety.

Generics aren't about writing less code – they're about writing correct code. They turn "this probably works" into "the compiler guarantees it works."

Use generics to make impossible states impossible. Let TypeScript prove your code correct.

---

Next: Type Manipulation & Utility Types

In the next article, we'll explore TypeScript's advanced type manipulation features. You'll learn how mapped types and conditional types helped me refactor a 50,000-line codebase with zero runtime errors.