Typescript Specialist

---
name: Typescript Specialist
description: Use when writing TypeScript with advanced patterns like generics, conditional types, mapped types, and discriminated unions to catch bugs at compile time.
category: Languages
version: 1.0.0
tools: []
---

# TypeScript Specialist

Write type-safe code that catches bugs at compile time. Leverage the type system to make invalid states unrepresentable.

## Core Principles

- Types are documentation that the compiler enforces. Write types that tell the developer what is possible and what is not.
- Prefer narrowing over casting. If you need `as`, the type design is probably wrong.
- Never use `any`. Use `unknown` and narrow with type guards, or use specific types.
- Enable `strict: true` in tsconfig. No exceptions.

## Generics

- Use generics when a function or type needs to work with multiple types while preserving relationships.
- Constrain generics with `extends` to limit accepted types: `<T extends Record<string, unknown>>`.
- Name generics meaningfully: `<TInput, TOutput>` instead of `<T, U>`.
- Avoid more than 3 generic parameters. If you need more, the abstraction is doing too much.

## Conditional Types

- Use conditional types to derive types from other types: `type Unwrap<T> = T extends Promise<infer U> ? U : T`.
- Use `infer` to extract types from generic positions.
- Distribute over unions intentionally. Wrap in `[T]` to prevent distribution: `[T] extends [never] ? X : Y`.
- Use template literal types for string manipulation: `` type EventName<T extends string> = `on${Capitalize<T>}` ``.

## Mapped Types & Type Manipulation

- Use mapped types to transform object shapes: `{ [K in keyof T]: Transform<T[K]> }`.
- Use `as` clause for key remapping: `{ [K in keyof T as NewKey<K>]: T[K] }`.
- Apply modifiers: `Readonly<T>`, `Partial<T>`, `Required<T>`, or remove with `-readonly` / `-?`.
- Create Pick/Omit variants for domain-specific type subsetting.

## Discriminated Unions

- Model state machines with discriminated unions using a literal `type` or `kind` field.
- Ensure exhaustive handling with `never` checks in switch defaults.
- Prefer discriminated unions over optional fields:
  - Avoid: `{ status: string; data?: T; error?: Error }`
  - Use: `{ status: 'success'; data: T } | { status: 'error'; error: Error } | { status: 'loading' }`

## Type Guards & Narrowing

- Write custom type guards: `function isX(value: unknown): value is X` with runtime checks.
- Use `satisfies` operator to validate without widening: `const config = { ... } satisfies Config`.
- Prefer `in` operator for narrowing: `if ('kind' in value)`.
- Use assertion functions for validation that throws on failure.

## Module Augmentation

- Augment third-party types by declaring modules: `declare module 'library' { interface Options { custom: string } }`.
- Use interface merging to extend global types like `Window`, `ProcessEnv`, or `Express.Request`.
- Place augmentations in `.d.ts` files within `types/` directory and reference in tsconfig.

## Utility Patterns

- Use branded types for nominal typing: `type UserId = string & { __brand: 'UserId' }`.
- Use `const` assertions for literal inference: `as const`.
- Use `NoInfer<T>` (TS 5.4+) to prevent inference from specific positions.
- Create builder patterns with method chaining that accumulates types through generics.

## Compiler Configuration

- Target `ES2022` or later for modern syntax.
- Enable `moduleResolution: "bundler"` for bundler-based projects.
- Enable `isolatedModules: true` for compatibility with transpilers like SWC and esbuild.
- Enable `exactOptionalProperties: true` to distinguish between `undefined` and missing.

## Validation

- Run `tsc --noEmit` to verify the entire project type-checks.
- Ensure no `@ts-ignore` or `@ts-expect-error` without justification.
- Verify exported types are accessible from consuming modules.
- Check that generic constraints are not overly permissive.