TypeScript Generics Practical Guide 2026: Master Generic Types With Real Examples
Generics are TypeScript's most powerful—and most misunderstood—feature. They're the difference between writing type-safe, reusable code and drowning in any types across your entire codebase. If you've ever copy-pasted a function just to handle a different type, generics are the fix.
Generic Syntax Fundamentals & Type Inference Mechanics
Most tutorials show generic syntax and move on. The real confusion happens when inference breaks silently and you don't know why. This section covers both the syntax and the mechanics behind it.
Generic Function Declarations & Parameter Syntax
Here's the problem generics solve. Without them, you either lose type information or write duplicate functions:
// Wrong: loses all type information
function getFirstElement(arr: any[]): any {
return arr[0];
}
const val = getFirstElement([1, 2, 3]);
val.toUpperCase(); // No error at compile time — explodes at runtime
// Right: type parameter T captures and preserves the caller's type
function getFirstElement<T>(arr: T[]): T {
return arr[0];
}
const num = getFirstElement([1, 2, 3]); // T inferred as number
const str = getFirstElement(["a", "b", "c"]); // T inferred as string
num.toUpperCase(); // Compile error — exactly what we want
TypeScript infers T from the argument you pass. You can also force it explicitly: getFirstElement<string>(arr). Do this when inference produces a type that's too wide, or when you're passing an empty array and TypeScript has nothing to infer from.
Multiple type parameters work when your function bridges two independent types:
function pair<T, U>(first: T, second: U): [T, U] {
return [first, second];
}
const result = pair("hello", 42); // [string, number]
Use multiple parameters only when the types are genuinely independent. If they're always the same type, one parameter is enough.
Type Inference & Constraint-Based Resolution
TypeScript infers generic types left-to-right from function arguments. When multiple arguments are supposed to resolve the same type parameter, TypeScript tries to find a common supertype. This fails in surprising ways:
function merge<T>(obj1: T, obj2: T): T {
return { ...obj1, ...obj2 } as T;
}
// Inference problem: TypeScript widens T to the union of both shapes
const result = merge({ name: "Alice" }, { name: "Bob", age: 30 });
// T becomes { name: string } — age property is lost on result type
result.age; // Compile error, even though value exists at runtime
The fix is two separate type parameters with a constraint:
function merge<T extends object, U extends object>(obj1: T, obj2: U): T & U {
return { ...obj1, ...obj2 } as T & U;
}
const result = merge({ name: "Alice" }, { name: "Bob", age: 30 });
result.age; // Works — type is { name: string } & { name: string; age: number }
Another common trap: inference fails inside callbacks. TypeScript can't always infer generic types from callback parameters because the inference happens bidirectionally. When you hit this, add an explicit type annotation on the callback parameter instead of fighting inference.
Use as const to prevent over-widening when you need literal types:
const config = { method: "GET" } as const;
// Without as const, TypeScript infers { method: string }
// With as const: { readonly method: "GET" }
Generic Constraints with the extends Keyword
Constraints tell TypeScript what shape T must have. Without them, T could be anything, which blocks you from accessing properties on it.
// Wrong: TypeScript won't let you access obj[key] without constraints
function getProperty<T, K>(obj: T, key: K) {
return obj[key]; // Error: Type 'K' cannot be used to index type 'T'
}
// Right: constrain K to only valid keys of T
function getProperty<T extends object, K extends keyof T>(obj: T, key: K): T[K] {
return obj[key];
}
const user = { name: "Alice", age: 30 };
getProperty(user, "name"); // Returns string — ✓
getProperty(user, "email"); // Compile error: "email" not a key of user — ✓
The keyof T operator returns the union of all keys in T. Combining it with extends gives you a compile-time guarantee that only valid keys are accepted. This pattern appears constantly in utility libraries and ORM query builders.
Watch out for over-constraining. If you write <T extends string> when you just need T to be a primitive, you've blocked numbers and booleans unnecessarily. Start with the loosest constraint that makes your implementation work.
Generic Classes, Interfaces & Real-World Pattern Implementation
Generics become genuinely useful when you're designing reusable data structures and API wrappers. This is where the patterns you'll actually ship to production live.
Generic Classes & Constructor Type Parameters
Generic classes let you write one data structure that works across multiple entity types:
// Wrong: separate class for every entity type
class UserRepository {
private items: User[] = [];
findById(id: number): User | undefined {
return this.items.find(item => item.id === id);
}
}
class ProductRepository {
private items: Product[] = [];
findById(id: number): Product | undefined {
return this.items.find(item => item.id === id);
}
}
// Right: one generic repository for all entity types
class Repository<T extends { id: number }> {
private items: T[] = [];
add(item: T): void {
this.items.push(item);
}
findById(id: number): T | undefined {
return this.items.find(item => item.id === id);
}
getAll(): T[] {
return [...this.items];
}
}
interface User { id: number; name: string; }
interface Product { id: number; price: number; }
const userRepo = new Repository<User>();
userRepo.add({ id: 1, name: "Alice" });
userRepo.findById(1); // Returns User | undefined — fully typed
const productRepo = new Repository<Product>();
The constraint T extends { id: number } guarantees every entity has an id, which the findById method depends on. Without that constraint, accessing item.id inside the class would be a compile error.
One thing most tutorials skip: static methods on generic classes cannot use the class type parameter. Static methods belong to the class itself, not to instances, so they need their own type parameters:
class Repository<T extends { id: number }> {
// Static method needs its own <U> — can't use <T> here
static fromArray<U extends { id: number }>(items: U[]): Repository<U> {
const repo = new Repository<U>();
items.forEach(item => repo.add(item));
return repo;
}
}
Generic Interfaces & Structural Typing Interactions
Generic interfaces are the backbone of API client patterns. Here's a response wrapper that works for any endpoint:
interface ApiResponse<T, E = Error> {
success: boolean;
data?: T;
error?: E;
}
// Usage with a specific data type
type UserResponse = ApiResponse<User>;
type ProductListResponse = ApiResponse<Product[], { code: number; message: string }>;
async function fetchUser(id: number): Promise<ApiResponse<User>> {
try {
const data = await fetch(`/api/users/${id}`).then(r => r.json());
return { success: true, data };
} catch (error) {
return { success: false, error: error as Error };
}
}
The default type parameter E = Error means callers don't have to specify an error type unless they need custom error shapes. Default type parameters were added in TypeScript 2.3 and are still underused in most codebases.
TypeScript's structural typing means two generic interfaces are compatible if their shapes match — the names don't matter. This is worth remembering when you're working across library boundaries where you don't control both interface definitions.
Generic Utility Types & Mapped Type Patterns
TypeScript ships built-in generic utility types. Record<K, T>, Pick<T, K>, and Omit<T, K> are all implemented with the same mapped type syntax you can write yourself. See the official utility types documentation for the full list.
// Building a type-safe form field map using mapped types + generics
type FormField<T> = {
[K in keyof T]: {
value: T[K];
validate: (val: T[K]) => boolean;
error?: string;
};
};
interface User {
name: string;
age: number;
email: string;
}
type UserForm = FormField<User>;
// Resolves to:
// {
// name: { value: string; validate: (val: string) => boolean; error?: string }
// age: { value: number; validate: (val: number) => boolean; error?: string }
// email:{ value: string; validate: (val: string) => boolean; error?: string }
// }
The [K in keyof T] syntax iterates over every key in T and maps it to a new type. TypeScript uses T[K] to get the type of each property, so validate is always typed for the specific field — not a generic any.
Advanced Generic Patterns & Debugging
This is where most tutorials stop. These patterns show up constantly in mature TypeScript codebases and popular libraries.
Conditional Types with Generics
Conditional types let your generic return different shapes based on what the caller passes. The syntax is T extends U ? X : Y:
// Return type changes based on whether input is an array
type Unwrap<T> = T extends Array<infer Item> ? Item : T;
type A = Unwrap<string[]>; // string
type B = Unwrap<number>; // number
type C = Unwrap<User[]>; // User
The infer keyword extracts a type from within a conditional check. It's how TypeScript's built-in ReturnType<T> and Parameters<T> utility types work internally.
Conditional types also apply to functions, letting you vary the return type based on input:
function parseInput<T extends string | number>(
input: T
): T extends string ? string[] : number {
if (typeof input === "string") {
return input.split(",") as any;
}
return (input * 2) as any;
}
const words = parseInput("a,b,c"); // string[]
const doubled = parseInput(5); // number
The as any casts inside the implementation are an acknowledged limitation — TypeScript can't narrow conditional return types inside the function body. The external types remain accurate for callers.
Generic Best Practices & Common Mistakes
These are the patterns that separate clean generic code from the kind that causes three-hour debugging sessions.
Always use your type parameters. An unused type parameter creates phantom compatibility and confuses callers:
// Wrong: T is declared but never used — any T is accepted
function broken<T>(value: string): string {
return value;
}
// Right: T should influence the signature
function identity<T>(value: T): T {
return value;
}
Explicit return types on public APIs. Inference is convenient during development but makes library code harder to consume and document:
// Avoid in library code — callers have to hover to discover the return type
export function transform<T, U>(items: T[], fn: (item: T) => U) {
return items.map(fn);
}
// Better — contract is explicit and shows up in generated .d.ts files
export function transform<T, U>(items: T[], fn: (item: T) => U): U[] {
return items.map(fn);
}
For a deeper look at how generics fit into larger TypeScript architecture patterns, check out our TypeScript utility types guide. And if you're still getting comfortable with the basics, our interfaces vs. types breakdown is worth reading first.
| Pattern | Use Case | Key Syntax |
|---|---|---|
| Generic function | Reusable logic across types | function f<T>(x: T): T |
| Constrained generic | Require specific shape on T | <T extends { id: number }> |
| Generic class | Reusable data structures | class Repo<T> { } |
| Generic interface | API response wrappers | interface R<T, E = Error> |
| Mapped type | Transform all keys of a type | [K in keyof T]: ... |
| Conditional type | Type varies by input shape | T extends U ? X : Y |
Frequently Asked Questions
Q: When should I use a generic instead of a union type?
A: Use a generic when the caller's type needs to flow through — the input type and output type are linked. Use a union when a function genuinely accepts multiple types but doesn't need to track which one came in. function wrap<T>(val: T): { value: T } is a generic case; function log(val: string | number): void is a union case.
Q: Why does TypeScript sometimes infer `unknown` or `{}` for my generic type?
A: This happens when TypeScript has no argument to infer from — like an empty array call or a generic used only in a return position. The fix is to pass an explicit type argument: myFunction<User>(). Adding a constraint like <T extends object> also narrows the fallback type.
Q: Do generics have any runtime performance cost?
A: No. Generics are erased entirely during compilation — they exist only in the type system. The JavaScript output contains zero trace of type parameters. All the type checking happens at build time, so there's no runtime overhead whatsoever.
Wrap-up
Generics aren't a niche TypeScript feature — they're how modern libraries like Zod, tRPC, and React Query achieve type safety without manual casting. The core patterns are: generic functions for reusable logic, constrained generics to enforce shapes, generic classes for data structures, and mapped or conditional types when you need type transformations. Start with the repository pattern from this guide, implement it against a real data structure in your project, and the rest of the patterns will click into place.
References
- Typescript Generics | Beginners Tutorial with Examples
- What are Generics in TypeScript ? - GeeksforGeeks
- How TypeScript Generics Work – Explained with Examples
- TypeScript Generics: A Simple Guide with Practical Examples
- TypeScript Basic Generics
- You're Using TypeScript Wrong (7 Patterns to Avoid) - YouTube
Comments
Post a Comment