Master TypeScript Generics: 7 Mismatch Gotchas for 2025

// The hopeful but flawed approach
function logId<T>(item: T) {
  console.log(item.id); // ❌ Error: Property 'id' does not exist on type 'T'.
}

// The correct, constrained approach
function logId<T extends { id: unknown }>(item: T) {
  console.log(item.id); // ✅ Works perfectly!
}

logId({ id: 123, name: "Widget" }); // OK
logId({ id: "abc", value: 456 }); // OK
// logId({ name: "No ID here" }); // ❌ Error, as it should be!

// This completely defeats the purpose of generics
function wrapInDataObject<T>(value: T): { data: any } {
  // ... maybe some complex logic here ...
  return { data: value };
}

const wrappedString = wrapInDataObject("hello");
// Uh oh. TypeScript thinks wrappedString.data is 'any'.
// We've lost all type information!
wrappedString.data.thisMethodDoesNotExist(); // No compile-time error! 💥

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

const wrappedString = wrapInDataObject("hello");
// Hooray! TypeScript knows wrappedString.data is a 'string'.
// wrappedString.data.thisMethodDoesNotExist(); // ✅ Correctly errors!

The naive approach fails:

function getProperty(obj: object, key: string) {
  return obj[key]; // ❌ Error: Element implicitly has an 'any' type because...
                   // 'string' can't be used to index type '{}'.
}

The solution is a beautiful, symbiotic relationship between two generic types, using keyof.

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

const user = {
  name: "Alice",
  age: 30
};

const name = getProperty(user, "name"); // `name` is correctly inferred as 'string'
const age = getProperty(user, "age");   // `age` is correctly inferred as 'number'

// const location = getProperty(user, "location"); // ❌ Correctly errors!

Breaking it down:

• <T, K extends keyof T>: We have two generic types. T is the object itself. K is the key, but it’s constrained. It can’t be any string; it must be one of the keys of T ("name" | "age" in our example).
• (obj: T, key: K): The arguments are typed with our generics.
• : T[K]: This is the return type. It’s a “lookup type,” meaning the type of the property on T that corresponds to the key K. If key is "name", the return type is string.

This pattern is fundamental to building type-safe utilities in TypeScript.

Gotcha #4: When Generics Are Overkill

Generics are powerful, but that doesn't mean they're always the right tool. Sometimes, a simple union type is clearer, more readable, and achieves the same result. Over-engineering with generics can make your code harder to understand.

Consider a function that formats an ID, which can be a number or a string.

// The overly complex generic approach
function formatId<T extends string | number>(id: T): string {
  return `ID-${id}`;
}

// The simpler, more direct union type approach
function formatIdSimple(id: string | number): string {
  return `ID-${id}`;
}

In this case, the generic T adds no value. We aren't using T to link the input type to another input or to the output in a variable way. We’re just accepting a value from a known set of types and always returning a string. The second function is just as type-safe and much easier to read.

The Takeaway: Use generics when you need to establish a relationship between multiple types (e.g., an input and an output, or two different inputs). If you’re just accepting one of several simple types, a union is often better.

Gotcha #5: The new() Constructor Conundrum

This is a more advanced scenario, but it stumps developers building factories or class-based utilities. How do you write a function that accepts a class and returns a new instance of it?

Your first instinct might be this:

class Dog { woof() { console.log("Woof!"); } }

// This looks plausible, but it's wrong
function createInstance<T>(C: T): T {
  return new C(); // ❌ Error: 'T' only refers to a type, but is being used as a value here.
}

The problem is that T refers to the instance type (e.g., the `Dog` object), not the constructor itself. To fix this, you need to describe a type that has a constructor signature.

class Dog { woof() { console.log("Woof!"); } }

// The correct approach with a constructor signature
function createInstance<T>(C: { new (): T }): T {
  return new C();
}

const myDog = createInstance(Dog); // `myDog` is correctly inferred as type `Dog`
myDog.woof(); // "Woof!"

The constraint { new (): T } is TypeScript’s special syntax for “an object that can be called with the new keyword and returns an instance of type T.”

Gotcha #6: Ignoring Type Variance in Callbacks

This one is subtle but critical for API design. It deals with how assignability works for generic function types, a concept called variance.

Let’s say you have a function that processes an array of items and takes a callback:

class Animal { move() {} }
class Cat extends Animal { meow() {} }

function processAnimals<T extends Animal>(animals: T[], callback: (animal: T) => void) {
  for (const animal of animals) {
    callback(animal);
  }
}

const cats: Cat[] = [new Cat()];

// This works!
const animalCallback = (animal: Animal) => animal.move();
processAnimals(cats, animalCallback);

// But this doesn't!
const catCallback = (cat: Cat) => cat.meow();
const allAnimals: Animal[] = [new Cat()];
// processAnimals(allAnimals, catCallback); // ❌ Error!

Why does the last line fail? You’re passing an array of `Animal`s, but your callback only knows how to handle `Cat`s. What if the array contained a `Dog`? Your `catCallback` would fail. This is contravariance in action: for function arguments, you can pass a function that accepts a more general type (a supertype), but not one that accepts a more specific type (a subtype).

The Takeaway: When designing APIs with callbacks, remember that callback arguments are contravariant. A callback must be prepared to handle anything the main function might give it, not just a specific subset.

Gotcha #7: Default Types That Are Too Permissive

Generic default types (e.g., <T = string>) are great for improving developer experience. But choosing a poor default can hide bugs and encourage lazy coding.

A common anti-pattern is defaulting to any or unknown when you could be more specific.

// A lazy default
type EventPayload<T = any> = {
  timestamp: number;
  data: T;
}

// A developer might forget to specify the type
function handleGenericEvent(payload: EventPayload) {
  // payload.data is 'any'. We have no idea what's inside.
  payload.data.doWhatever(); // No error, potential runtime crash
}

Using any as the default completely undermines type safety. Using unknown is safer, as it forces the developer to perform type checks, but it can still be a sign of a poorly designed API.

A better approach is to choose a more restrictive default, or no default at all, forcing the consumer to be explicit.

// A better, more restrictive default (or no default at all)
type EventPayloadStrict<T> = {
  timestamp: number;
  data: T;
}

// Now, the developer is forced to be explicit
function handleSpecificEvent(payload: EventPayloadStrict<{ id: string, value: number }>) {
  console.log(payload.data.id); // ✅ Type-safe!
}

// Using it without a type would cause an error, which is good!
// function handleGenericEvent(payload: EventPayloadStrict) { ... } // ❌ Error!

The Takeaway: Be deliberate with your generic defaults. Avoid any at all costs. Prefer forcing an explicit type over providing a loose default that hides the true nature of the data.

---

Beyond Placeholders

Mastering TypeScript generics means shifting your mindset. They aren’t just placeholders; they are the logic that connects the different parts of your type system. By understanding and avoiding these seven gotchas, you're not just fixing errors—you're learning to write code that is more robust, expressive, and fundamentally safer.

Start looking for these patterns in your own code and in pull requests. Challenge yourself to use constraints, to thread types correctly, and to choose the right tool for the job. Your team, and your future self, will be grateful.