generics-as-functions

Generic types are the type-level equivalent of functions in value space. Just as a function takes parameters and returns a value, a generic type takes type parameters and produces a concrete type. This mental model helps you write better generic types by applying the same principles you use for writing functions: constraining inputs, choosing good names, and documenting behavior.

Understanding generics as functions between types clarifies when to use constraints, how to name type parameters, and why some generic patterns work while others don't. This perspective is essential for effective type-level programming in TypeScript.

• Defining generic types that transform other types
• Writing generic functions with type parameters
• Constraining what types can be passed to generics
• Documenting generic types with TSDoc
• Creating reusable type utilities

Think of generic types as functions between types: use extends to constrain inputs like type annotations, choose descriptive names, and document with @template TSDoc.

Watch for these patterns:

```typescript

// RED FLAGS - Poor generic design

type MyPick = { [P in K]: T[P] }; // No constraints, errors in implementation

type BadGeneric = ...; // Single-letter names without context

function parse(input: string): T; // Return-only generic, no better than any

```

A generic type takes type parameters and produces a concrete type:

```typescript

// Generic type "function"

type MyPartial = { [K in keyof T]?: T[K] };

// "Calling" the function with Person

type PartPerson = MyPartial;

// Equivalent to: { name?: string; age?: number; }

```

Just like functions, generic types can have multiple parameters:

```typescript

// Two type parameters

type MyPick = { [P in K]: T[P] };

// Usage

type NameOnly = MyPick;

// Equivalent to: { name: string }

```

Use extends to constrain type parameters, just as you'd use type annotations for function parameters:

```typescript

// GOOD: Constrained type parameters

type MyPick = {

[P in K]: T[P]

};

// Without constraints - allows invalid instantiations

type BadPick = { [P in K]: T[P] }; // Errors in implementation

// Invalid uses caught by constraints:

type Bad1 = MyPick; // Error: 'firstName' not in Person

type Bad2 = MyPick<'age', Person>; // Error: string doesn't satisfy object

```

Choose descriptive names, especially for complex generics:

```typescript

// Short names OK for simple, local generics

type Partial = { [K in keyof T]?: T[K] };

// Longer names for complex or exported generics

type MapValues<

ObjectType extends object,

ValueTransformer extends (value: any) => any

> = {

[Key in keyof ObjectType]: ValueTransformer

};

```

Use @template TSDoc tag to document type parameters:

```typescript

/**

* Construct a new object type using a subset of properties from another.

* @template T - The original object type

* @template K - The keys to pick, typically a union of string literal types

*/

type MyPick = {

[P in K]: T[P]

};

```

Generic functions define associated generic types and enable type inference:

```typescript

function pick(

obj: T,

...keys: K[]

): Pick {

const result: Partial> = {};

for (const k of keys) {

result[k] = obj[k];

}

return result as Pick;

}

// TypeScript infers types from arguments

const person = { name: 'Alice', age: 30 };

const nameOnly = pick(person, 'name');

// Type: Pick<{ name: string; age: number }, 'name'>

```

Generic classes capture types that don't need to be passed to methods:

```typescript

class Box {

value: T;

constructor(value: T) {

this.value = value;

}

getValue(): T {

return this.value;

}

}

// Type inferred from constructor

const dateBox = new Box(new Date());

// Type: Box

```

When pressured to use unconstrained generics:

1. Add constraints: Use extends to limit valid type arguments
2. Consider defaults: Provide sensible defaults for type parameters
3. Document requirements: Use TSDoc to explain constraints
4. Test edge cases: Verify generics work with unions and edge cases

| Anti-Pattern | Why It's Bad |

|--------------|--------------|

| Unconstrained type parameters | Allows invalid instantiations, implementation errors |

| Single-letter names in complex generics | Reduces readability |

| Return-only generics | Equivalent to type assertions, no type safety |

| Missing TSDoc on public generics | Poor developer experience |

"Constraints limit flexibility"

Reality: Constraints catch errors at the type level rather than producing confusing type errors or wrong types. They document valid usage.

"T, K, V are standard names"

Reality: They are conventional for simple cases, but descriptive names improve readability in complex generics. Match name length to scope.

"Users can figure out the types"

Reality: Documentation helps users understand generics without reading implementation. @template tags appear in IDE tooltips.

| Concept | Value-Level | Type-Level |

|---------|-------------|------------|

| Definition | function | type |

| Parameters | (x: T) | |

| Return | : ReturnType | = ResultType |

| Documentation | @param | @template |

| Constraints | Type annotations | extends keyword |

Generic types are functions between types. Apply the same principles you use for writing functions: constrain inputs, choose meaningful names, and document thoroughly. This mental model makes complex type-level code more approachable and maintainable.

• Effective TypeScript, 2nd Edition by Dan Vanderkam
• Item 50: Think of Generics as Functions Between Types