## Introduction: Why Generics Exist TypeScript's type system is powerful, but without generics you hit a wall almost immediately. Consider this function: ```ts function firstElement(arr: any[]): any { return arr[0]; } const num = firstElement([1, 2, 3]); // type: any const str = firstElement(['a', 'b']); // type: any ``` It works, but the return type is `any`. You put in a `number[]` and got back `any`. The type information is gone. You've traded the whole point of TypeScript — type safety — for flexibility. The alternative without generics is duplication: ```ts function firstNumber(arr: number[]): number { return arr[0]; } function firstString(arr: string[]): string { return arr[0]; } function firstUser(arr: User[]): User { return arr[0]; } ``` Same logic, copy-pasted for every type. That doesn't scale. Generics solve both problems. They let you write a single function that works with **any** type while **preserving** what that type actually is: ```ts function firstElement(arr: T[]): T { return arr[0]; } const num = firstElement([1, 2, 3]); // type: number const str = firstElement(['a', 'b']); // type: string ``` The `` is a **type parameter** — a placeholder that gets filled in when the function is called. You put in `number[]`, TypeScript infers `T = number`, and the return type is `number`. Type safety preserved. Zero duplication. > Think of generics like a shipping container. The container doesn't care whether it holds electronics, food, or furniture — it works with any cargo. But it guarantees that whatever you put in is what you get out. The container is generic; the cargo is the type parameter. By the end of this guide you will: - Understand why generics exist and the problems they solve - Write generic functions, interfaces, classes, and type aliases with confidence - Use constraints to narrow what types are allowed - Know how every built-in utility type works under the hood - Build custom mapped types and conditional types - Master the `infer` keyword for type-level extraction - Use template literal types for string-level type safety - Understand variance (covariance and contravariance) and why it matters - Apply generics to real-world patterns: API clients, React components, builders, and state machines - Avoid the common pitfalls that trip up even experienced developers Let's start with the fundamentals. --- ## Your First Generic ### The Identity Function The simplest possible generic is the **identity function** — it takes a value and returns it unchanged: ```ts function identity(value: T): T { return value; } ``` Breaking this down: - `` declares a **type parameter** named `T`. It's a variable, but for types instead of values. - `(value: T)` says the parameter's type is whatever `T` is. - `: T` says the return type is the same `T`. When you call it, TypeScript **infers** `T` from the argument: ```ts const a = identity(42); // T inferred as number → type: number const b = identity('hello'); // T inferred as string → type: string const c = identity(true); // T inferred as boolean → type: boolean const d = identity([1, 2, 3]); // T inferred as number[] → type: number[] ``` You can also specify `T` explicitly: ```ts const e = identity('hello'); // explicit: T = string const f = identity(42); // explicit: T = number ``` Explicit type arguments are useful when inference fails or when you want to be precise. ### Without Generics vs With Generics ```ts // WITHOUT generics — type information lost function wrapInArray(value: any): any[] { return [value]; } const nums = wrapInArray(42); // any[] — useless nums[0].toUpperCase(); // no error at compile time, crash at runtime! // WITH generics — type information preserved function wrapInArray(value: T): T[] { return [value]; } const nums = wrapInArray(42); // number[] nums[0].toUpperCase(); // ERROR: Property 'toUpperCase' does not exist on type 'number' ``` The generic version catches the bug at compile time. That's the entire value proposition. --- ## Generic Functions ### Multiple Type Parameters Sometimes you need more than one type variable: ```ts function pair(first: T, second: U): [T, U] { return [first, second]; } const p1 = pair('hello', 42); // [string, number] const p2 = pair(true, [1, 2]); // [boolean, number[]] ``` Each type parameter is independent. `T` and `U` can be the same type or different types — it depends entirely on what you pass in. ### Default Type Parameters Just like function parameters can have defaults, type parameters can too: ```ts function createArray(length: number, value: T): T[] { return Array(length).fill(value); } const strings = createArray(3, 'hi'); // string[] (inferred from value) const numbers = createArray(3, 42); // number[] (inferred from value) const explicit = createArray(3, true); // boolean[] ``` Defaults kick in when TypeScript can't infer the type and you don't specify it explicitly. They're most useful in generic interfaces and classes. ### Generic Arrow Functions Arrow functions work the same way, with one caveat in `.tsx` files: ```ts // Regular .ts file — fine const identity = (value: T): T => value; // In .tsx files, looks like a JSX tag. Add a trailing comma: const identity = (value: T): T => value; // Or use extends to disambiguate: const identity = (value: T): T => value; ``` The trailing comma (``) tells the parser "this is a type parameter, not a JSX element." It's ugly but it's the standard workaround. ### Generic Rest Parameters You can make rest parameters generic: ```ts function logAll(...args: T): T { console.log(...args); return args; } const result = logAll(1, 'two', true); // type: [number, string, boolean] ``` TypeScript infers a **tuple type** for the rest parameter, preserving the exact types and order. --- ## Generic Constraints Unconstrained generics accept **any** type. Sometimes that's too broad: ```ts function getLength(value: T): number { return value.length; // ERROR: Property 'length' does not exist on type 'T' } ``` TypeScript can't assume `T` has a `length` property — it could be `number`, which doesn't. You need a **constraint**. ### The `extends` Keyword Constraints use `extends` to limit what types are allowed: ```ts function getLength(value: T): number { return value.length; // OK — T is guaranteed to have 'length' } getLength('hello'); // OK: string has length getLength([1, 2, 3]); // OK: array has length getLength({ length: 5, name: 'test' }); // OK: has length property getLength(42); // ERROR: number doesn't have 'length' ``` `T extends { length: number }` means "T must be assignable to `{ length: number }`." Any type with a `length` property that's a number will work. ### Constraining to Keys with `keyof` One of the most useful constraints: ensuring a key exists on an object. ```ts function getProperty(obj: T, key: K): T[K] { return obj[key]; } const user = { name: 'Ray', age: 30, email: 'ray@example.com' }; const name = getProperty(user, 'name'); // type: string const age = getProperty(user, 'age'); // type: number const bad = getProperty(user, 'address'); // ERROR: '"address"' is not assignable to keyof user ``` `K extends keyof T` constrains `K` to only be one of the keys of `T`. The return type `T[K]` is an **indexed access type** — it gives you the type of that specific property. So `getProperty(user, 'name')` returns `string`, not `string | number | string`. ### Multiple Constraints with Intersection When you need multiple constraints, use intersection (`&`): ```ts interface HasId { id: string; } interface HasTimestamps { createdAt: Date; updatedAt: Date; } function updateEntity(entity: T, updates: Partial): T { return { ...entity, ...updates, updatedAt: new Date() }; } ``` `T` must satisfy **both** `HasId` and `HasTimestamps`. ### Constraining to Constructor Types You can constrain to types that are constructable: ```ts function createInstance(ctor: new () => T): T { return new ctor(); } class UserService { greet() { return 'hello'; } } const service = createInstance(UserService); // type: UserService service.greet(); // OK ``` The `new () => T` type represents a constructor that takes no arguments and returns `T`. --- ## Generic Interfaces and Type Aliases ### Generic API Response A classic pattern: typing API responses generically. ```ts interface ApiResponse { data: T; status: number; message: string; timestamp: Date; } interface User { id: string; name: string; email: string; } interface Product { id: string; title: string; price: number; } type UserResponse = ApiResponse; type ProductListResponse = ApiResponse; async function fetchUser(id: string): Promise> { const res = await fetch(`/api/users/${id}`); return res.json(); } const response = await fetchUser('123'); response.data.name; // type: string — fully typed! response.data.email; // type: string ``` One interface, any data shape. The generic parameter flows through to give you exact types for `data`. ### The Result Type (Success or Error) A generic type that eliminates `try/catch` in favor of explicit success/failure: ```ts type Result = | { success: true; data: T } | { success: false; error: E }; function divide(a: number, b: number): Result { if (b === 0) { return { success: false, error: 'Division by zero' }; } return { success: true, data: a / b }; } const result = divide(10, 2); if (result.success) { console.log(result.data); // type: number } else { console.log(result.error); // type: string } ``` The discriminated union (`success: true | false`) narrows the type in each branch. This is a powerful alternative to throwing exceptions. ### Generic Event Emitter Interface ```ts interface EventMap { login: { userId: string; timestamp: Date }; logout: { userId: string }; purchase: { productId: string; amount: number }; } interface TypedEmitter> { on(event: K, handler: (payload: TEvents[K]) => void): void; emit(event: K, payload: TEvents[K]): void; } declare const emitter: TypedEmitter; emitter.on('login', (payload) => { console.log(payload.userId); // type: string console.log(payload.timestamp); // type: Date }); emitter.emit('purchase', { productId: 'abc', amount: 29.99 }); // OK emitter.emit('purchase', { productId: 'abc' }); // ERROR: missing 'amount' emitter.emit('unknown', {}); // ERROR: '"unknown"' is not a key of EventMap ``` The event name constrains the payload type. Misspell an event or forget a field and TypeScript catches it at compile time. --- ## Generic Classes ### Generic Stack ```ts class Stack { 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]; } get size(): number { return this.items.length; } isEmpty(): boolean { return this.items.length === 0; } } const numberStack = new Stack(); numberStack.push(1); numberStack.push(2); const top = numberStack.pop(); // type: number | undefined const stringStack = new Stack(); stringStack.push('hello'); stringStack.push(42); // ERROR: Argument of type 'number' is not assignable to parameter of type 'string' ``` ### Generic Repository Pattern A common pattern in applications with data access layers: ```ts interface Entity { id: string; } class Repository { private items = new Map(); create(item: T): T { this.items.set(item.id, item); return item; } findById(id: string): T | undefined { return this.items.get(id); } findAll(): T[] { return Array.from(this.items.values()); } update(id: string, updates: Partial>): T | undefined { const existing = this.items.get(id); if (!existing) return undefined; const updated = { ...existing, ...updates }; this.items.set(id, updated); return updated; } delete(id: string): boolean { return this.items.delete(id); } } interface User extends Entity { name: string; email: string; } interface Product extends Entity { title: string; price: number; } const userRepo = new Repository(); userRepo.create({ id: '1', name: 'Ray', email: 'ray@test.com' }); const user = userRepo.findById('1'); // type: User | undefined const productRepo = new Repository(); productRepo.create({ id: '1', title: 'Widget', price: 9.99 }); productRepo.update('1', { price: 12.99 }); // OK productRepo.update('1', { id: 'new' }); // ERROR: 'id' is excluded from updates ``` The constraint `T extends Entity` ensures every item has an `id`. The `Partial>` for updates prevents changing the ID — a nice type-level business rule. ### When to Use Generic Classes vs Functions | Scenario | Use | |----------|-----| | Stateless transformation | Generic function | | Stateful container (stack, queue, cache) | Generic class | | Configuration that's set once and used many times | Generic class | | One-off utility | Generic function | | Shared across a codebase with consistent typing | Either (class for DI, function for simplicity) | --- ## Built-in Utility Types: How They Work Under the Hood TypeScript ships with utility types that are themselves built with generics. Understanding their implementation demystifies them and teaches you the patterns to build your own. ### `Partial` — Make All Properties Optional ```ts // Implementation type Partial = { [K in keyof T]?: T[K]; }; // Usage interface User { name: string; email: string; age: number; } type PartialUser = Partial; // { name?: string; email?: string; age?: number } function updateUser(user: User, updates: Partial): User { return { ...user, ...updates }; } ``` The `[K in keyof T]` iterates over every key in `T`. The `?` makes each property optional. `T[K]` preserves the original value type. ### `Required` — Make All Properties Required ```ts // Implementation type Required = { [K in keyof T]-?: T[K]; }; ``` The `-?` **removes** the optional modifier. The minus sign is the "remove modifier" syntax. ### `Readonly` — Make All Properties Readonly ```ts // Implementation type Readonly = { readonly [K in keyof T]: T[K]; }; const user: Readonly = { name: 'Ray', email: 'ray@test.com', age: 30 }; user.name = 'Other'; // ERROR: Cannot assign to 'name' because it is a read-only property ``` ### `Pick` — Select Specific Properties ```ts // Implementation type Pick = { [P in K]: T[P]; }; type UserPreview = Pick; // { name: string; email: string } ``` `K extends keyof T` ensures you can only pick keys that actually exist on `T`. ### `Omit` — Remove Specific Properties ```ts // Implementation type Omit = Pick>; type UserWithoutEmail = Omit; // { name: string; age: number } ``` `Omit` is built on top of `Pick` and `Exclude`. It picks all keys except the ones you want to remove. ### `Record` — Create an Object Type with Specific Keys ```ts // Implementation type Record = { [P in K]: T; }; type Roles = 'admin' | 'user' | 'guest'; const permissions: Record = { admin: ['read', 'write', 'delete'], user: ['read', 'write'], guest: ['read'], }; ``` ### `ReturnType` — Extract a Function's Return Type ```ts // Implementation type ReturnType any> = T extends (...args: any) => infer R ? R : any; function getUser() { return { id: '1', name: 'Ray', isAdmin: true }; } type UserType = ReturnType; // { id: string; name: string; isAdmin: boolean } ``` This uses **conditional types** and **`infer`** — two features we'll deep-dive into shortly. ### `Parameters` — Extract a Function's Parameter Types ```ts // Implementation type Parameters any> = T extends (...args: infer P) => any ? P : never; function createUser(name: string, age: number, email: string): void { /* ... */ } type CreateUserParams = Parameters; // [name: string, age: number, email: string] ``` ### `Exclude` and `Extract` ```ts // Exclude: remove members from a union type Exclude = T extends U ? never : T; type Status = 'active' | 'inactive' | 'pending' | 'deleted'; type ActiveStatuses = Exclude; // 'active' | 'pending' // Extract: keep only members assignable to U type Extract = T extends U ? T : never; type StringOrNumber = Extract; // string | number ``` These work because conditional types **distribute** over unions. Each member of the union is evaluated independently. ### `NonNullable` ```ts // Implementation type NonNullable = T extends null | undefined ? never : T; type MaybeString = string | null | undefined; type DefinitelyString = NonNullable; // string ``` ### `Awaited` — Unwrap Promises ```ts // Simplified implementation type Awaited = T extends Promise ? Awaited : T; type A = Awaited>; // string type B = Awaited>>; // number (recursively unwraps) type C = Awaited; // string (non-promise passes through) ``` --- ## Mapped Types Mapped types let you create new types by transforming each property of an existing type. They're the `Array.map()` of the type system. ### Basic Syntax ```ts type Mapped = { [K in keyof T]: SomeTransformation; }; ``` `[K in keyof T]` iterates over every key `K` in `T`. For each key, you define what the new value type should be. ### Making Properties Nullable ```ts type Nullable = { [K in keyof T]: T[K] | null; }; interface Form { name: string; email: string; age: number; } type NullableForm = Nullable

; // { name: string | null; email: string | null; age: number | null } ``` ### Wrapping Properties in Getters ```ts type Getters = { [K in keyof T as `get${Capitalize}`]: () => T[K]; }; interface Person { name: string; age: number; } type PersonGetters = Getters; // { getName: () => string; getAge: () => number } ``` The `as` clause **remaps** the key. `Capitalize` is a built-in utility that uppercases the first letter. `string & K` ensures `K` is a string (since `keyof` can include `number | symbol`). ### Key Remapping with `as` You can filter, rename, or transform keys: ```ts // Remove specific keys type RemoveKind = { [K in keyof T as Exclude]: T[K]; }; // Only keep string-valued properties type StringProps = { [K in keyof T as T[K] extends string ? K : never]: T[K]; }; interface Config { name: string; version: string; port: number; debug: boolean; } type StringConfig = StringProps; // { name: string; version: string } ``` Mapping a key to `never` removes it from the output type. ### Form Validation Type A practical example — generating a validation schema type from a form type: ```ts type ValidationRule = { required?: boolean; min?: T extends number ? number : never; max?: T extends number ? number : never; minLength?: T extends string ? number : never; maxLength?: T extends string ? number : never; pattern?: T extends string ? RegExp : never; custom?: (value: T) => string | null; }; type FormValidation = { [K in keyof T]: ValidationRule; }; interface SignupForm { username: string; email: string; age: number; password: string; } type SignupValidation = FormValidation; const validation: SignupValidation = { username: { required: true, minLength: 3, maxLength: 20 }, email: { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ }, age: { required: true, min: 13, max: 120 }, password: { required: true, minLength: 8, custom: (val) => val.includes(' ') ? 'No spaces allowed' : null }, }; ``` The validation rules adapt to the field type — `min`/`max` only appear for numbers, `minLength`/`maxLength` only for strings. Type safety all the way down. --- ## Conditional Types Conditional types let you express type-level if/else logic: ```ts type Condition = T extends U ? TrueType : FalseType; ``` If `T` is assignable to `U`, the result is `TrueType`. Otherwise, `FalseType`. ### Basic Examples ```ts type IsString = T extends string ? true : false; type A = IsString; // true type B = IsString; // false type C = IsString<'hello'>; // true (literal string extends string) ``` ### Distributive Conditional Types When `T` is a **union**, conditional types distribute — each member is evaluated independently: ```ts type ToArray = T extends unknown ? T[] : never; type Result = ToArray; // string[] | number[] (NOT (string | number)[]) ``` TypeScript evaluates `string extends unknown ? string[] : never` and `number extends unknown ? number[] : never` separately, then unions the results. To prevent distribution, wrap in a tuple: ```ts type ToArrayNonDist = [T] extends [unknown] ? T[] : never; type Result = ToArrayNonDist; // (string | number)[] ``` ### Practical Conditional Types ```ts // Flatten a type: if it's an array, get the element type type Flatten = T extends Array ? Item : T; type A = Flatten; // string type B = Flatten; // number // Make a type promise-like or not type MaybePromise = T | Promise; // Extract non-function properties type DataProperties = { [K in keyof T as T[K] extends Function ? never : K]: T[K]; }; interface UserService { name: string; age: number; greet: () => string; save: (data: unknown) => Promise; } type UserData = DataProperties; // { name: string; age: number } ``` --- ## The `infer` Keyword Deep Dive `infer` is the most powerful feature in TypeScript's type system. It lets you **extract** types from other types — like destructuring, but at the type level. `infer` can only be used inside the `extends` clause of a conditional type. It declares a type variable that TypeScript fills in for you. ### Extracting Function Return Types ```ts type MyReturnType = T extends (...args: any[]) => infer R ? R : never; type A = MyReturnType<() => string>; // string type B = MyReturnType<(x: number) => boolean>; // boolean type C = MyReturnType; // never (not a function) ``` `infer R` says "figure out what the return type is and call it `R`." ### Extracting Function Parameters ```ts type FirstParam = T extends (first: infer F, ...rest: any[]) => any ? F : never; type A = FirstParam<(name: string, age: number) => void>; // string type B = FirstParam<() => void>; // never ``` ### Unwrapping Promises ```ts type UnwrapPromise = T extends Promise ? UnwrapPromise : T; type A = UnwrapPromise>; // string type B = UnwrapPromise>>>; // number type C = UnwrapPromise; // boolean ``` The recursion (`UnwrapPromise`) handles nested promises. ### Array and Tuple Manipulation ```ts // Get element type of an array type ElementOf = T extends (infer E)[] ? E : never; type A = ElementOf; // string type B = ElementOf<(number | boolean)[]>; // number | boolean // Get first element of a tuple type Head = T extends [infer H, ...unknown[]] ? H : never; type C = Head<[string, number, boolean]>; // string // Get everything except the first element type Tail = T extends [unknown, ...infer R] ? R : never; type D = Tail<[string, number, boolean]>; // [number, boolean] // Get the last element type Last = T extends [...unknown[], infer L] ? L : never; type E = Last<[string, number, boolean]>; // boolean ``` ### Extracting Generic Type Arguments ```ts // Extract the type inside a Set type SetElement = T extends Set ? E : never; type A = SetElement>; // string // Extract key and value from a Map type MapTypes = T extends Map ? { key: K; value: V } : never; type B = MapTypes>; // { key: string; value: number } ``` ### Building a Type-Safe `get` for Nested Properties ```ts type Get = Path extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? Get : never : Path extends keyof T ? T[Path] : never; interface Config { db: { host: string; port: number; credentials: { user: string; password: string; }; }; app: { name: string; }; } type A = Get; // string type B = Get; // string type C = Get; // string type D = Get; // never ``` This recursively splits a dot-notation path and traverses the type. It's the same pattern libraries like Lodash use at runtime, but enforced at the type level. --- ## Template Literal Types with Generics TypeScript can manipulate **string types** using template literal syntax. Combined with generics, this enables string-level type safety. ### Basic Template Literals ```ts type Greeting = `Hello, ${string}`; const a: Greeting = 'Hello, Ray'; // OK const b: Greeting = 'Goodbye, Ray'; // ERROR type EventName = `on${Capitalize}`; const c: EventName = 'onClick'; // OK const d: EventName = 'onclick'; // ERROR: must start with capital after 'on' ``` ### Type-Safe Event Names ```ts type DomEvents = 'click' | 'focus' | 'blur' | 'change'; type EventHandler = `on${Capitalize}`; // 'onClick' | 'onFocus' | 'onBlur' | 'onChange' type EventHandlerMap = { [K in DomEvents as `on${Capitalize}`]: (event: Event) => void; }; // { onClick: (event: Event) => void; onFocus: ...; onBlur: ...; onChange: ... } ``` ### Route Parameter Extraction ```ts type ExtractParams = T extends `${string}:${infer Param}/${infer Rest}` ? Param | ExtractParams<`/${Rest}`> : T extends `${string}:${infer Param}` ? Param : never; type Params = ExtractParams<'/users/:userId/posts/:postId'>; // 'userId' | 'postId' type RouteParams = { [K in ExtractParams]: string; }; type UserPostRoute = RouteParams<'/users/:userId/posts/:postId'>; // { userId: string; postId: string } ``` This parses a route string at the type level and extracts the parameter names. A framework like Express or Hono uses similar techniques for type-safe routing. ### String Manipulation Utilities TypeScript has built-in string manipulation types: ```ts type A = Uppercase<'hello'>; // 'HELLO' type B = Lowercase<'HELLO'>; // 'hello' type C = Capitalize<'hello'>; // 'Hello' type D = Uncapitalize<'Hello'>; // 'hello' ``` You can build custom ones: ```ts // CamelCase to kebab-case type CamelToKebab = S extends `${infer Head}${infer Tail}` ? Tail extends Uncapitalize ? `${Lowercase}${CamelToKebab}` : `${Lowercase}-${CamelToKebab}` : S; type A = CamelToKebab<'backgroundColor'>; // 'background-color' type B = CamelToKebab<'fontSize'>; // 'font-size' type C = CamelToKebab<'color'>; // 'color' ``` --- ## Variance: Covariance and Contravariance Variance describes how subtyping between generic types relates to subtyping between their type parameters. It sounds academic, but it has practical consequences. ### The Core Idea Given `Dog extends Animal`, is `Container` assignable to `Container`? - **Covariant** (preserves direction): `Container` IS assignable to `Container`. The `out` position. - **Contravariant** (reverses direction): `Container` IS assignable to `Container`. The `in` position. - **Invariant** (neither): No assignability in either direction. ### Return Types Are Covariant Functions that return a subtype are assignable to functions that return a supertype: ```ts type Animal = { name: string }; type Dog = { name: string; breed: string }; type GetAnimal = () => Animal; type GetDog = () => Dog; const getDog: GetDog = () => ({ name: 'Rex', breed: 'Labrador' }); const getAnimal: GetAnimal = getDog; // OK — Dog extends Animal, so () => Dog extends () => Animal ``` This makes sense: if you expect something that returns an `Animal`, a function that returns a `Dog` (which is an Animal) works fine. ### Parameter Types Are Contravariant Functions that accept a supertype are assignable to functions that accept a subtype: ```ts type HandleAnimal = (animal: Animal) => void; type HandleDog = (dog: Dog) => void; const handleAnimal: HandleAnimal = (a) => console.log(a.name); const handleDog: HandleDog = handleAnimal; // OK — HandleAnimal can handle any Animal, including Dogs ``` This also makes sense: if you need something that handles `Dog`s, a function that handles all `Animal`s can certainly handle `Dog`s. ### The `in` and `out` Keywords (TypeScript 4.7+) You can explicitly annotate variance: ```ts interface Producer { produce(): T; } interface Consumer { consume(value: T): void; } interface ReadWrite { get(): T; set(value: T): void; } ``` - `out T` — T appears only in output (return) positions. Covariant. - `in T` — T appears only in input (parameter) positions. Contravariant. - `in out T` — T appears in both. Invariant. These annotations are optional — TypeScript infers variance automatically. But they improve compile-time performance for complex types and serve as documentation. ### Why This Matters in Practice The most common place you encounter variance issues is with callbacks: ```ts interface EventMap { click: MouseEvent; keydown: KeyboardEvent; } type Handler = (event: T) => void; const mouseHandler: Handler = (e) => console.log(e.clientX); const eventHandler: Handler = (e) => console.log(e.type); // Can I use eventHandler where mouseHandler is expected? const handlers: Handler = eventHandler; // In strict mode with strictFunctionTypes: OK (contravariant) // eventHandler can handle any Event, including MouseEvent ``` Understanding variance prevents subtle type errors when working with callbacks, event systems, and generic containers. --- ## Real-World Patterns ### Type-Safe API Client ```ts interface ApiEndpoints { '/users': { response: User[]; params: { page?: number } }; '/users/:id': { response: User; params: { id: string } }; '/posts': { response: Post[]; params: { page?: number; tag?: string } }; '/posts/:id': { response: Post; params: { id: string } }; } async function apiGet( endpoint: T, params?: ApiEndpoints[T]['params'] ): Promise { const url = new URL(endpoint, 'https://api.example.com'); if (params) { Object.entries(params).forEach(([key, value]) => { if (value !== undefined) url.searchParams.set(key, String(value)); }); } const res = await fetch(url.toString()); return res.json(); } const users = await apiGet('/users', { page: 1 }); // type: User[] const post = await apiGet('/posts/:id', { id: '42' }); // type: Post const bad = await apiGet('/users', { tag: 'admin' }); // ERROR: 'tag' doesn't exist on User params ``` The endpoint string constrains which parameters are valid and what the response type is. Impossible to call with wrong params or misinterpret the response. ### Builder Pattern with Generics A type-safe query builder that tracks which methods have been called: ```ts interface QueryConfig { table: string; conditions: string[]; orderBy: string | null; limit: number | null; selected: string[]; } class QueryBuilder = {}> { private config: QueryConfig = { table: '', conditions: [], orderBy: null, limit: null, selected: [], }; from(table: T): QueryBuilder { this.config.table = table; return this as any; } where(condition: string): QueryBuilder { this.config.conditions.push(condition); return this as any; } select(...fields: string[]): QueryBuilder { this.config.selected = fields; return this as any; } orderBy(field: string): this { this.config.orderBy = field; return this; } limit(n: number): this { this.config.limit = n; return this; } build(this: QueryBuilder<{ table: string }>): string { const fields = this.config.selected.length > 0 ? this.config.selected.join(', ') : '*'; let query = `SELECT ${fields} FROM ${this.config.table}`; if (this.config.conditions.length > 0) { query += ` WHERE ${this.config.conditions.join(' AND ')}`; } if (this.config.orderBy) query += ` ORDER BY ${this.config.orderBy}`; if (this.config.limit) query += ` LIMIT ${this.config.limit}`; return query; } } new QueryBuilder() .from('users') .where('age > 18') .select('name', 'email') .orderBy('name') .limit(10) .build(); // OK new QueryBuilder() .where('age > 18') .build(); // ERROR: 'table' is required (from() not called) ``` The `build` method's `this` parameter requires that `table` has been set. If you forget `.from()`, you get a compile error. ### Generic State Machine ```ts type StateConfig = { [S in TStates]: { on: Partial>; }; }; class StateMachine { private current: TStates; private config: StateConfig; constructor(initial: TStates, config: StateConfig) { this.current = initial; this.config = config; } getState(): TStates { return this.current; } send(event: TEvents): TStates { const transitions = this.config[this.current]; const next = transitions.on[event]; if (next) { this.current = next; } return this.current; } } type LightState = 'green' | 'yellow' | 'red'; type LightEvent = 'TIMER' | 'EMERGENCY'; const trafficLight = new StateMachine('green', { green: { on: { TIMER: 'yellow', EMERGENCY: 'red' } }, yellow: { on: { TIMER: 'red' } }, red: { on: { TIMER: 'green' } }, }); trafficLight.send('TIMER'); // OK trafficLight.send('EMERGENCY'); // OK trafficLight.send('INVALID'); // ERROR: '"INVALID"' is not assignable to LightEvent ``` ### Polymorphic `as` Prop (React) A pattern used by component libraries like Chakra UI and Radix: ```ts import { ComponentPropsWithoutRef, ElementType, ReactNode } from 'react'; type PolymorphicProps = TProps & { as?: T; children?: ReactNode; } & Omit, keyof TProps | 'as' | 'children'>; function Box({ as, children, ...props }: PolymorphicProps) { const Component = as || 'div'; return {children}; } // Usage Default div This is a link {}}>This is a button {}}>Still valid — anchor has onClick ERROR: href must be string ``` When `as="a"`, the component accepts all anchor props (`href`, `target`, etc.). When `as="button"`, it accepts button props (`type`, `disabled`, etc.). The types change based on the element. --- ## Generic Patterns in React ### `useState` You use generics with `useState` all the time, often without realizing it: ```tsx const [count, setCount] = useState(0); // inferred: number const [name, setName] = useState(''); // inferred: string const [user, setUser] = useState(null); // explicit: initial null const [items, setItems] = useState([]); // explicit: empty array ``` Explicit type params are needed when the initial value doesn't represent the full range of possible types (e.g., `null` initial but will hold a `User`). ### Generic List Component ```tsx interface ListProps { items: T[]; renderItem: (item: T, index: number) => ReactNode; keyExtractor: (item: T) => string; emptyMessage?: string; } function List({ items, renderItem, keyExtractor, emptyMessage }: ListProps) { if (items.length === 0) { return
{emptyMessage ?? 'No items'}
; } return (
{items.map((item, index) => (
{renderItem(item, index)}
))}
); } // Usage — T is inferred from items user.id} renderItem={(user) => {user.name}} /> ``` The `renderItem` callback gets fully typed `user` parameter — no `any`, no casting. ### Generic Table Component ```tsx interface Column { key: keyof T & string; header: string; render?: (value: T[keyof T], item: T) => ReactNode; } interface TableProps { data: T[]; columns: Column[]; keyExtractor: (item: T) => string; } function Table({ data, columns, keyExtractor }: TableProps) { return ( {columns.map((col) => ( ))} {data.map((item) => ( {columns.map((col) => ( ))} ))}

{col.header}

{col.render ? col.render(item[col.key], item) : String(item[col.key])}

); } // Usage u.id} columns={[ { key: 'name', header: 'Name' }, { key: 'email', header: 'Email' }, { key: 'age', header: 'Age', render: (val) => {String(val)} }, ]} /> ``` `key: keyof T & string` ensures you can only reference columns that exist on the data type. --- ### Factory Pattern with Generics A factory that creates instances based on a type map: ```ts interface WidgetMap { button: { label: string; onClick: () => void }; input: { placeholder: string; value: string }; toggle: { checked: boolean; onChange: (checked: boolean) => void }; } function createWidget( kind: K, config: WidgetMap[K] ): { kind: K; config: WidgetMap[K]; id: string } { return { kind, config, id: Math.random().toString(36).slice(2), }; } const btn = createWidget('button', { label: 'Submit', onClick: () => {} }); // type: { kind: 'button'; config: { label: string; onClick: () => void }; id: string } const input = createWidget('input', { placeholder: 'Enter name', value: '' }); // type: { kind: 'input'; config: { placeholder: string; value: string }; id: string } const bad = createWidget('button', { placeholder: 'oops' }); // ERROR: 'placeholder' does not exist on button config ``` The factory guarantees that the config matches the widget kind. You can't pass input config to a button widget. ### Type-Safe Event Emitter (Full Implementation) ```ts type EventMap = Record; type EventHandler = (payload: T) => void; class TypedEventEmitter { private handlers = new Map>>(); on(event: K, handler: EventHandler): () => void { if (!this.handlers.has(event)) { this.handlers.set(event, new Set()); } this.handlers.get(event)!.add(handler); return () => { this.handlers.get(event)?.delete(handler); }; } emit(event: K, payload: TEvents[K]): void { this.handlers.get(event)?.forEach((handler) => handler(payload)); } off(event: K, handler: EventHandler): void { this.handlers.get(event)?.delete(handler); } } interface AppEvents { 'user:login': { userId: string; email: string }; 'user:logout': { userId: string }; 'cart:add': { productId: string; quantity: number }; 'cart:clear': undefined; } const emitter = new TypedEventEmitter(); const unsubscribe = emitter.on('user:login', (payload) => { console.log(`${payload.email} logged in`); // payload fully typed }); emitter.emit('user:login', { userId: '1', email: 'ray@test.com' }); // OK emitter.emit('user:login', { userId: '1' }); // ERROR: missing 'email' emitter.emit('cart:add', { productId: 'abc', quantity: 2 }); // OK unsubscribe(); // Clean up ``` The `on` method returns an unsubscribe function. Every event name is constrained to `AppEvents`, and the payload type is inferred from the event name. This pattern is used in real-world libraries and apps. ### Generic Pipe / Compose A type-safe pipe function that chains transformations: ```ts function pipe(fn1: (a: A) => B): (a: A) => B; function pipe(fn1: (a: A) => B, fn2: (b: B) => C): (a: A) => C; function pipe(fn1: (a: A) => B, fn2: (b: B) => C, fn3: (c: C) => D): (a: A) => D; function pipe(...fns: Array<(arg: any) => any>) { return (input: any) => fns.reduce((acc, fn) => fn(acc), input); } const processUser = pipe( (name: string) => ({ name, createdAt: new Date() }), (user) => ({ ...user, id: Math.random().toString(36) }), (user) => `User ${user.name} created with id ${user.id}` ); const result = processUser('Ray'); // type: string ``` Each function's output type flows into the next function's input type. The overloads provide type safety for up to 3 functions (you can extend for more). --- ## Common Pitfalls ### Pitfall 1: Over-Engineering with Generics ```ts // BAD — generic used once, adds complexity for no benefit function greet(name: T): string { return `Hello, ${name}!`; } // GOOD — just use the type directly function greet(name: string): string { return `Hello, ${name}!`; } ``` > Rule of thumb: if a type parameter is only used once in the function signature, you probably don't need it. Generics are for **relating** types — connecting input to output, or one parameter to another. ### Pitfall 2: Unnecessary Type Parameters ```ts // BAD — T is used but doesn't add value function getLength(arr: T): number { return arr.length; } // GOOD — unless you need T in the return type function getLength(arr: { length: number }): number { return arr.length; } // OK — T is used in the return type, so it adds value function firstElement(arr: T[]): T | undefined { return arr[0]; } ``` ### Pitfall 3: Forgetting Constraints ```ts // BAD — T is unconstrained, can't access properties function getName(obj: T): string { return obj.name; // ERROR: Property 'name' does not exist on type 'T' } // GOOD — constrain T to types that have 'name' function getName(obj: T): string { return obj.name; } ``` ### Pitfall 4: `any` Leaking Through ```ts // BAD — using 'any' defeats the purpose function wrap(value: T): { value: any } { return { value }; } const result = wrap(42); result.value; // type: any — the generic is pointless // GOOD function wrap(value: T): { value: T } { return { value }; } const result = wrap(42); result.value; // type: number ``` ### Pitfall 5: The `` JSX Workaround In `.tsx` files, `` is ambiguous — it could be a JSX tag. The fix: ```tsx // ERROR in .tsx files const identity = (value: T): T => value; // FIX: trailing comma const identity = (value: T): T => value; // FIX: extend something const identity = (value: T): T => value; ``` ### Pitfall 6: Recursive Type Depth Limits TypeScript has a recursion depth limit (~50 levels). Deeply recursive types can hit it: ```ts // This works for reasonable depths type DeepReadonly = { readonly [K in keyof T]: T[K] extends object ? DeepReadonly : T[K]; }; // But extreme nesting might hit: "Type instantiation is excessively deep and possibly infinite" ``` If you hit this, simplify your types or add a base case that stops recursion earlier. --- ## Performance and Best Practices ### Naming Conventions For simple generics, single letters are fine: ```ts function map(arr: T[], fn: (item: T) => U): U[] ``` For complex generics with multiple parameters, use descriptive names: ```ts interface Repository { findById(id: TId): Promise; } ``` Common conventions: - `T` — the primary type - `U`, `V` — secondary types - `K` — key type - `E` — element or error type - `R` — return type - `TItem`, `TResult`, `TConfig` — descriptive names with `T` prefix ### When to Use Generics vs Overloads vs Unions | Approach | Use When | |----------|----------| | **Generics** | Input and output types are **related** — return type depends on input type | | **Overloads** | A few specific combinations of input/output with **different behavior** per overload | | **Unions** | The function accepts multiple types but the **return type doesn't change** based on input | ```ts // GENERIC — return type tracks input type function clone(value: T): T { /* ... */ } // OVERLOAD — different behavior per signature function parse(input: string): number; function parse(input: string[]): number[]; function parse(input: string | string[]): number | number[] { if (Array.isArray(input)) return input.map(Number); return Number(input); } // UNION — return type is always the same function stringify(value: string | number | boolean): string { return String(value); } ``` ### Decision Framework ``` Do I need type safety between input and output? ├── YES → Is the relationship simple (one type flows through)? │ ├── YES → Generic │ └── NO → Are there 2-3 specific combinations? │ ├── YES → Overloads │ └── NO → Generic with constraints └── NO → Do I accept multiple types? ├── YES → Union └── NO → Plain type ``` --- ## Cheat Sheet ### Syntax Quick Reference | Syntax | Description | |--------|-------------| | `` | Declare a type parameter | | `` | Multiple type parameters | | `` | Default type parameter | | `` | Constrained type parameter | | `` | Multiple constraints (intersection) | | `` | JSX-safe type parameter in `.tsx` | | `keyof T` | Union of all keys of `T` | | `T[K]` | Indexed access — type of property `K` on `T` | | `T extends U ? X : Y` | Conditional type | | `infer R` | Type inference in conditional type | | `[K in keyof T]` | Mapped type — iterate over keys | | `[K in keyof T as ...]` | Key remapping in mapped type | | `-?` | Remove optional modifier | | `-readonly` | Remove readonly modifier | | `in T` | Contravariant type parameter | | `out T` | Covariant type parameter | ### Common Patterns ```ts // Preserve type through transformation function transform(value: T): Wrapped // Constrain to objects with specific shape function process(item: T): T // Key-value relationship function get(obj: T, key: K): T[K] // Factory that returns instances function create(ctor: new (...args: any[]) => T): T // Discriminated union result type Result = { ok: true; value: T } | { ok: false; error: E } // Generic React component function List(props: { items: T[]; render: (item: T) => ReactNode }): JSX.Element ``` ### Utility Type Implementations ```ts type Partial = { [K in keyof T]?: T[K] } type Required = { [K in keyof T]-?: T[K] } type Readonly = { readonly [K in keyof T]: T[K] } type Pick = { [P in K]: T[P] } type Record = { [P in K]: T } type Exclude = T extends U ? never : T type Extract = T extends U ? T : never type NonNullable = T extends null | undefined ? never : T type ReturnType any> = T extends (...args: any) => infer R ? R : any type Parameters any> = T extends (...args: infer P) => any ? P : never ``` --- ## What's Next Generics are the backbone of TypeScript's type system. Once you internalize them, everything else — utility types, library typings, complex inference — becomes readable and buildable. If you want to go deeper: - **TypeScript 101** covers the foundational type system that generics build on. - **React Context: The Complete Deep Dive** shows generics in action with `createContext`, typed providers, and generic factory functions. - **useMemo vs useCallback** demonstrates how React's hooks use generics under the hood. The best way to get comfortable with generics is to use them. Start simple — generic functions that preserve types. Then try building a utility type. Then a conditional type with `infer`. Each step builds on the last, and before long you'll be reading library `.d.ts` files like they're plain English.

TypeScript Generics: The Complete Deep Dive