This guide covers TypeScript generics from first principles to the advanced patterns you'll actually use in production. It starts with the mental model that makes generics click, walks through constraints, `keyof`, conditional types, `infer`, and mapped types, then ends with four real-world patterns from API wrappers to React hooks. Key takeaways: - **Generics are functions for types.** A generic takes a type as input and produces a type as output. Once that clicks, everything else follows naturally. - `extends` constrains what `T` can be. `keyof` gives you the keys of a type as a union. `infer` extracts a type from inside another type. - Conditional types (`T extends X ? Y : Z`) let you write types that branch — the foundation of `NonNullable`, `ReturnType`, and more. - Mapped types transform every property in a type. `Partial`, `Required`, `Readonly` are all just mapped types under the hood. - When in doubt: would a concrete type work here? If yes, skip the generic. The best generic is the simplest one that preserves the information you need.

## The Mental Model That Makes Generics Click **The mental model that makes everything else click: a generic is a type parameter — a placeholder for a type that gets filled in later.** Just like a function parameter is a placeholder for a value. Generics are the single most powerful feature in TypeScript's type system — and the most misunderstood. Here's the thing: generics aren't complicated. They're just functions for types. Once that clicks, everything else falls into place. ([source](https://dev.to/pockit_tools/typescript-generics-demystified-from-confusion-to-mastery-with-real-world-patterns-3p1e)) A regular function takes a value and returns a value. A generic takes a type and produces a type. The syntax is different, but the concept is identical. ```ts // Regular function — takes a value function double(x: number): number { return x * 2; } // Generic — takes a type type Nullable = T | null; // ^ input type ^ output type ``` `Nullable` produces `string | null`. `Nullable` produces `number | null`. One definition, works for any type. That's all generics are.

## Part 1: The Basics ### Generic Functions **The problem generics solve:** a function that needs to work with multiple types. Without generics, you have two bad options — lose type safety with `any`, or write a separate function for every type: ```ts // Bad — loses all type information function firstItem(arr: any[]): any { return arr[0]; } const first = firstItem(["a", "b", "c"]); // first is 'any' — TypeScript can't help you after this ``` With a generic, TypeScript infers `T` from what you pass and carries that information through: ```ts // Good — T flows from input to output function firstItem(arr: T[]): T | undefined { return arr[0]; } const first = firstItem(["a", "b", "c"]); // string | undefined const count = firstItem([1, 2, 3]); // number | undefined ``` TypeScript infers `T` from the argument you pass. You don't need to write `firstItem(["a"])` — the compiler figures it out. You only need to specify `T` explicitly when inference fails, typically when the generic appears only in the return type and not in the parameters. ### Multiple Type Parameters A generic can take more than one type parameter. A simple example: a function that wraps two values into a pair: ```ts // K is the first type, V is the second function pair(first: K, second: V): [K, V] { return [first, second]; } const result = pair("name", 42); // TypeScript infers [string, number] — no annotation needed ``` A more practical example — converting an array of values into key-value pairs: ```ts // T: the input type, K: which key to use as the ID function indexBy(items: T[], key: K): Map { return new Map(items.map(item => [item[key], item])); } const users = [ { id: 1, name: "Pablo" }, { id: 2, name: "Maria" }, ]; const byId = indexBy(users, "id"); // Map // TypeScript knows the key is a number because users[].id is a number ``` `T` is the object type. `K extends keyof T` ensures you can only pass a real key of that object. `T[K]` gives you the type of that property — which becomes the Map key type. ### Generic Interfaces and Types Generics work on interfaces and type aliases too: ```ts // Generic interface — used everywhere in React interface ApiResponse { data: T; status: number; message: string; } // T is filled in at the call site type UserResponse = ApiResponse; // { data: User; status: number; message: string } type PostListResponse = ApiResponse; // { data: Post[]; status: number; message: string } ``` This pattern — wrapping a concrete type in a generic envelope — is one of the most common uses of generics in API code.

## Part 2: Constraints with `extends` **An unconstrained `T` accepts literally anything** — numbers, booleans, objects. That's a problem when you need to access a property on it: ```ts function getLength(value: T): number { return value.length; // ❌ Error: Property 'length' does not exist on type 'T' } ``` TypeScript doesn't know `T` has a `length` property. It could be a number, a boolean, anything. The `extends` keyword constrains what `T` can be: ```ts function getLength(value: T): number { return value.length; // ✅ T is guaranteed to have 'length' } getLength("hello"); // ✅ string has length getLength([1, 2, 3]); // ✅ array has length getLength(42); // ❌ number doesn't have length ``` `T extends { length: number }` means "T must be any type that has a `length` property of type number." TypeScript enforces this at every call site. ### The `keyof` Constraint `keyof T` produces a union of all the keys of type `T`. Combined with `extends`, it's the foundation of type-safe property access: ```ts // Without keyof — unsafe function getProperty(obj: object, key: string) { return (obj as any)[key]; // any — TypeScript can't help } // With keyof — type-safe function getProperty(obj: T, key: K): T[K] { return obj[key]; } const user = { name: "Pablo", age: 22, role: "admin" }; const name = getProperty(user, "name"); // string ✅ const age = getProperty(user, "age"); // number ✅ const role = getProperty(user, "role"); // string ✅ getProperty(user, "email"); // ❌ TypeScript error — 'email' is not a key ``` `T[K]` is an indexed access type — it says "whatever type the property `K` has in `T`." This is how TypeScript knows that `getProperty(user, "age")` returns a `number`. ### Constraining to Literal Types with `as const` Without `as const`, TypeScript widens array values to `string`. With it, TypeScript keeps the exact literal types: ```ts // Without as const — TypeScript widens to string[] const colors = ["red", "green", "blue"]; type Color = typeof colors[number]; // string — not useful // With as const — TypeScript keeps literal types const COLORS = ["red", "green", "blue"] as const; type Color = typeof COLORS[number]; // "red" | "green" | "blue" ``` Now you can constrain a generic to only those literal values: ```ts function setColor(color: T): void { document.body.style.backgroundColor = color; } setColor("red"); // ✅ setColor("purple"); // ❌ TypeScript error — not in the list ``` This pattern replaces enums in most modern TypeScript code. Zero runtime overhead, full type safety. ### Default Type Parameters Type parameters can have defaults, reducing verbosity at call sites: ```ts interface PaginatedResponse> { data: T[]; total: number; page: number; meta: Meta; } // Without meta — default applies type UserList = PaginatedResponse; // meta is Record // With custom meta type PostList = PaginatedResponse; // meta is { tags: string[] } ```

## Part 3: Conditional Types **Conditional types let you write types that branch based on other types** — the same way a ternary operator branches based on a value. > **Arrow function + JSX gotcha:** When writing a generic arrow function in a `.tsx` file, TypeScript and JSX both use angle brackets. `` looks like a JSX tag. Add a trailing comma: `` to tell the parser you're writing a generic, not JSX. Or use `function` syntax instead. ```ts type IsArray = T extends any[] ? true : false; type A = IsArray; // true type B = IsArray; // false ``` `T extends any[] ? true : false` reads exactly like it looks: "if T is an array, produce `true`. Otherwise, produce `false`." ### A Practical Conditional Type Here's a conditional type you'd actually use: check whether a type is a string: ```ts type IsString = T extends string ? "yes" : "no"; type A = IsString; // "yes" type B = IsString; // "no" type C = IsString<"hello">; // "yes" — string literal extends string ``` A more useful one: strip `null` and `undefined` from a type: ```ts // This is exactly how TypeScript's built-in NonNullable works type NonNullable = T extends null | undefined ? never : T; type A = NonNullable; // string type B = NonNullable; // number type C = NonNullable; // never ``` When you apply a conditional type to a union (`string | null`), TypeScript applies it to each member separately and combines the results. `null` becomes `never` (which disappears from unions), so `string | null` becomes just `string`. ### Extracting Inner Types Conditional types become most powerful when you combine them with `infer` — but let's cover that in the next section. For now, here's the pattern without `infer`: ```ts // Is this type an array? type IsArray = T extends any[] ? true : false; type A = IsArray; // true type B = IsArray; // false type C = IsArray; // true ```

## Part 4: `infer` — Extracting Types from Other Types **`infer` captures a type from inside a pattern.** You use it inside a conditional type to say "when this matches, grab that inner type and give it a name." The easiest way to understand it: think of `infer U` as a variable declaration inside a type. If the pattern matches, `U` gets the captured type. If it doesn't match, the `never` branch fires. ```ts // Without infer — we know string[] matches T[], but we can't get the element type type IsArray = T extends any[] ? true : false; // With infer — we capture the element type as U type ElementType = T extends (infer U)[] ? U : never; // ^^^^^^ // "capture what's inside the array as U" type A = ElementType; // string ← U was string type B = ElementType; // number ← U was number type C = ElementType; // never ← didn't match the array pattern ``` The same pattern works for Promises: ```ts type UnwrapPromise = T extends Promise ? U : T; // ^^^^^^ // "capture what the Promise resolves to" type A = UnwrapPromise>; // string type B = UnwrapPromise>; // User type C = UnwrapPromise; // string (not a Promise, passes through) ``` This is so useful that TypeScript ships it as `Awaited` since version 4.5. ### Reading Built-in Utility Types Once you understand `infer`, the built-in utility types are readable: ```ts // How ReturnType works internally type ReturnType any> = T extends (...args: any) => infer R ? R // ← R is the return type : never; function getUser() { return { id: "1", name: "Pablo" }; } type User = ReturnType; // { id: string; name: string } // TypeScript figured out R by looking at what getUser returns ``` You never specify `R` manually. The compiler figures out what it is by matching the pattern against the actual type.

## Part 5: Mapped Types **Mapped types iterate over every key of a type and transform it.** The syntax looks like a for-loop for types. Start with the simplest possible mapped type — one that copies a type exactly: ```ts // Copy every property unchanged type Copy = { [K in keyof T]: T[K]; // "for each key K in T, the value type is T[K]" }; interface User { name: string; age: number; } type CopiedUser = Copy; // { name: string; age: number } — identical to User ``` Not useful on its own. But now add `?` to make every property optional: ```ts // This is exactly how Partial works type Partial = { [K in keyof T]?: T[K]; // ← ? makes each property optional }; type PartialUser = Partial; // { name?: string; age?: number } ``` Add `readonly` to make every property immutable: ```ts // This is exactly how Readonly works type Readonly = { readonly [K in keyof T]: T[K]; }; ``` Remove optionality with `-?`: ```ts // This is exactly how Required works type Required = { [K in keyof T]-?: T[K]; // ← -? removes the ? modifier }; ``` The pattern is always the same: `[K in keyof T]` iterates the keys, `T[K]` gives you the value type, and you add or remove modifiers around them. ### Building Your Own Mapped Types The power is in transforming property types: ```ts // Make every property nullable type Nullable = { [K in keyof T]: T[K] | null; }; // Make every property a function that returns the type type Getters = { [K in keyof T as `get${Capitalize}`]: () => T[K]; }; interface User { name: string; age: number; } type UserGetters = Getters; // { // getName: () => string; // getAge: () => number; // } ``` The `as` clause in the key position (TypeScript 4.1+) lets you remap key names — `name` becomes `getName`, `age` becomes `getAge`.

## Part 6: Real-World Patterns ### Type-Safe API Response Wrapper The most common pattern in any Next.js or Express codebase: ```ts type ApiResult = | { success: true; data: T } | { success: false; error: E }; async function fetchUser(id: string): Promise> { try { const res = await fetch(`/api/users/${id}`); if (!res.ok) return { success: false, error: new Error("Not found") }; const data = await res.json(); return { success: true, data }; } catch (err) { return { success: false, error: err as Error }; } } const result = await fetchUser("123"); if (result.success) { console.log(result.data.name); // TypeScript knows data is User } else { console.log(result.error.message); // TypeScript knows error is Error } ``` The generic `E = Error` default means you only specify the error type when you need something other than a plain `Error`. ### Type-Safe Event Emitter ```ts type EventMap = Record; class TypedEventEmitter { private handlers: Partial<{ [K in keyof Events]: Array<(data: Events[K]) => void>; }> = {}; on( event: K, handler: (data: Events[K]) => void ): this { (this.handlers[event] ??= []).push(handler); return this; } emit(event: K, data: Events[K]): void { this.handlers[event]?.forEach(h => h(data)); } } // Define your events interface AppEvents { "user:created": { id: string; name: string }; "user:deleted": { id: string }; "payment:succeeded": { amount: number; currency: string }; } const emitter = new TypedEventEmitter(); emitter.on("user:created", ({ id, name }) => { // TypeScript knows id and name are strings ✅ }); emitter.emit("user:created", { id: "1", name: "Pablo" }); // ✅ emitter.emit("user:created", { id: "1" }); // ❌ missing name emitter.emit("unknown:event", {}); // ❌ not in AppEvents ``` ### Type-Safe `pluck` Utility Extract an array of values for a specific key from an array of objects: ```ts function pluck(items: T[], key: K): T[K][] { return items.map(item => item[key]); } const users = [ { id: 1, name: "Pablo", role: "admin" }, { id: 2, name: "Maria", role: "member" }, ]; const names = pluck(users, "name"); // string[] ✅ const ids = pluck(users, "id"); // number[] ✅ pluck(users, "email"); // ❌ TypeScript error — not a key ``` ### Generic React Hook Custom hooks that work with any data type: ```ts import { useState, useCallback } from "react"; function useLocalStorage(key: string, defaultValue: T) { const [value, setValue] = useState(() => { try { const stored = localStorage.getItem(key); return stored ? (JSON.parse(stored) as T) : defaultValue; } catch { return defaultValue; } }); const setStoredValue = useCallback( (newValue: T | ((prev: T) => T)) => { setValue(prev => { const resolved = typeof newValue === "function" ? (newValue as (prev: T) => T)(prev) : newValue; localStorage.setItem(key, JSON.stringify(resolved)); return resolved; }); }, [key] ); return [value, setStoredValue] as const; } // TypeScript infers everything from the default value const [theme, setTheme] = useLocalStorage("theme", "light"); // theme: string, setTheme: (value: string | (prev: string) => string) => void const [count, setCount] = useLocalStorage("count", 0); // count: number ```

## When NOT to Use Generics The best type-level code is the simplest code that preserves the information you need. Ask yourself: "Would a concrete type work here?" If yes, skip the generic. ([source](https://dev.to/pockit_tools/typescript-generics-demystified-from-confusion-to-mastery-with-real-world-patterns-3p1e)) Generics add cognitive overhead for every developer who reads the code. That overhead is only worth it when a concrete type genuinely can't express what you need. Three signals that you've gone too far: **You're not using `T` in the return type.** If `T` appears only in the parameters and never in the return value, the generic probably isn't doing anything useful. ```ts // Useless generic — T appears in input but not output function logValue(value: T): void { console.log(value); } // This is simpler and equivalent function logValue(value: unknown): void { console.log(value); } ``` **The type signature is harder to read than the function body.** Generics are a communication tool. If your team members can't read the type signature in a code review, simplify it. **A union type or overload would be clearer.** For functions with a small, known set of input types, a union is often more explicit: ```ts // Overly generic function format(value: T): string { return String(value); } // Clearer with a union function format(value: string | number): string { return String(value); } ```

## Wrap Up TypeScript generics are functions for types. Every `Array`, every `Promise`, every built-in utility type is a generic. The entire type system is built on this one idea. The natural progression: start with generic functions where TypeScript infers `T`. Add `extends` when you need property access. Reach for `keyof` when you need type-safe key access. Use conditional types and `infer` when you need to extract or transform types. Use mapped types when you need to transform every property in a type. And at every step — ask whether a concrete type would do. The simplest code that preserves the information you need is always the right answer. If you're building a TypeScript product and want your project management, deployment tracking, and analytics in one workspace, check out [AdeptDev](https://adeptdev.io). Free for 7 days.

## What are TypeScript generics and why do I need them? TypeScript generics are type parameters that let you write functions, interfaces, and types that work with any data type while preserving full type safety. Without generics, you choose between losing type information (using `any`) or duplicating code (separate functions for each type). With generics, TypeScript infers the type from what you pass and carries that information through the return type. The mental model: generics are functions for types — they take a type as input and produce a type as output. ## What is `T extends` in TypeScript generics? `T extends SomeType` is a constraint that limits what types `T` can be. Without it, TypeScript doesn't know anything about `T` — it could be a number, boolean, anything — so you can't access properties on it. `T extends { length: number }` means "T must be any type that has a length property of type number." TypeScript enforces this at every call site, so you can safely access `value.length` inside the function. The `extends` keyword in generics is about constraint, not inheritance. ## What does `keyof` do in TypeScript? `keyof T` produces a union type of all the property names of type `T`. For `interface User { name: string; age: number }`, `keyof User` is `"name" | "age"`. Combined with generics, it enables type-safe property access: `function getProperty(obj: T, key: K): T[K]` ensures you can only pass valid property names and gives you back the exact type of that property. This is the foundation of utility types like `Pick` and `Omit`. ## What are conditional types in TypeScript? Conditional types use the syntax `T extends X ? Y : Z` — if T matches type X, produce type Y, otherwise produce type Z. They let you write types that branch based on other types. When applied to a union, TypeScript distributes the conditional over each member. This is how built-in utility types like `NonNullable` work — `T extends null | undefined ? never : T` — and how you build types that unwrap Promises, extract array element types, or transform types based on their shape. ## What is `infer` in TypeScript generics? `infer` lets you extract a type from inside another type within a conditional type. `T extends Promise ? U : T` says "if T is a Promise, extract the type it resolves to as U." The `infer` keyword tells TypeScript to bind the matched type to the variable name you provide. This is how TypeScript's built-in `ReturnType` works (`T extends (...args: any) => infer R ? R : never`) and how you extract parameter types, element types, or any nested type from a complex wrapper type. ## What are mapped types in TypeScript? Mapped types iterate over every property in a type and transform it. The syntax `{ [K in keyof T]: T[K] }` creates a new type with the same keys as T but potentially different values. Adding `?` makes properties optional, `readonly` makes them readonly, and `-?` removes optionality. This is how `Partial`, `Required`, and `Readonly` are implemented in TypeScript's standard library — they're all just mapped types. The `as` clause (TypeScript 4.1+) lets you also remap key names in the process. ## When should I not use TypeScript generics? Skip generics when a concrete type or union would work just as well. Three signals to simplify: the type parameter appears only in function parameters and never in the return type (the generic isn't preserving any information), the type signature is harder to read than the function body (readability matters), or a simple union type would be more explicit. The best generic is the simplest one that preserves the type information you need — not the most abstract one possible.