Generics
Generics allow a function, interface, or class to operate on a type that is determined at the call site rather than at definition time. A function that wraps a value in an array works correctly for any type without losing the type information that a non-generic version using any would discard.
The power of generics is type propagation: the relationship between input types and output types is preserved. A function that returns the first element of an array typed as T[] returns T, not unknown. The caller knows what they will receive without needing a type assertion.
Generics are commonly overused. A generic type parameter that appears only once — used in the input and nowhere else — adds complexity without benefit. Generic constraints are the mechanism for restricting what types a parameter can be: <T extends string> limits T to string subtypes; <T extends { id: number }> limits T to objects with an id field.
Design Thinking
Generics preserve type information across operations
A non-generic identity function that accepts any and returns any loses the type: the caller cannot know that the return value is the same type as the argument. A generic <T>(value: T): T preserves that relationship — the return type is the same type as the input type, which TypeScript infers at the call site without any assertion. The generic version gives callers accurate type information for everything they do with the return value.
Constraints express the minimum required shape
A generic function that accesses value.length can use <T extends { length: number }> rather than <T extends string | Array<any>>. This is narrower about intent — the function requires any value with a length property — and wider about capability: it accepts typed arrays, strings, and custom objects with a length field. Constraints should state the minimum structural requirement the function body actually needs, not an enumeration of all types the author expected callers to pass.
When not to use generics
A function that takes string | number and returns string | number does not benefit from being generic. A generic <T extends string | number>(value: T): T is harder to read and provides no additional safety. Use a union type when the relationship between input and output is symmetric; use a generic when the output type is derived from the specific input type. When in doubt, write the union type first — if callers need the output type to narrow to match the input type exactly, that is the signal to introduce a generic.
Best Practices
MUST constrain generic type parameters when the function body accesses a property or method of the parameter. Using <T extends { id: string }> instead of bare <T> when the function accesses value.id makes the requirement explicit, produces a better error message when the constraint is violated, and prevents callers from passing incompatible types that would fail at runtime.
MUST NOT define a generic type parameter that appears only in the return type or only once in the entire signature. A parameter that appears only once cannot be inferred from call-site arguments and requires explicit annotation at every call. If the caller must always write fn<string>(arg) rather than fn(arg), the generic is not providing inference — it is requiring annotation. A simpler overload or union type is clearer.
SHOULD name single-letter type parameters only when the parameter is truly interchangeable with any type. T is appropriate for a generic identity function. When a type parameter has semantic meaning — it represents a resource type, a key type, an entity — name it descriptively: ResourceType, KeyType, EntityShape. Meaningful names make complex generic signatures readable without requiring documentation.
SHOULD use infer in conditional types to extract component types from composite types rather than requiring callers to provide type arguments explicitly. ReturnType<typeof fn> uses infer to extract the return type from a function type without the caller needing to annotate it. Writing infer R in a conditional type is the right tool when a utility type needs to reach inside another type to extract a part.
Related FEEs
- FEE-1701 — Type System Fundamentals & Type Inference
- FEE-1703 — Utility Types & Type Manipulation
References
- TypeScript Handbook: Generics — https://www.typescriptlang.org/docs/handbook/2/generics.html
- TypeScript Handbook: Conditional Types — https://www.typescriptlang.org/docs/handbook/2/conditional-types.html