Typescript Best Practices

1---2name: typescript-best-practices3description: Use when reading or writing TypeScript or JavaScript files (.ts, .tsx, .js, tsconfig.json).4---5 6# TypeScript Best Practices7 8Follows type-first, functional, and error handling patterns from CLAUDE.md. This skill covers language-specific idioms only.9 10## Pair with React Best Practices11 12When working with React components (`.tsx`, `.jsx` files or `@react` imports), always load `react-best-practices` alongside this skill. This skill covers TypeScript fundamentals; React-specific patterns (effects, hooks, refs, component design) are in the dedicated React skill.13 14## Make Illegal States Unrepresentable15 16Use the type system to prevent invalid states at compile time.17 18**Discriminated unions for mutually exclusive states:**19```ts20// Good: only valid combinations possible21type RequestState<T> =22  | { status: 'idle' }23  | { status: 'loading' }24  | { status: 'success'; data: T }25  | { status: 'error'; error: Error };26 27// Bad: allows invalid combinations like { loading: true, error: Error }28type RequestState<T> = {29  loading: boolean;30  data?: T;31  error?: Error;32};33```34 35**Branded types for domain primitives:**36```ts37type UserId = string & { readonly __brand: 'UserId' };38type OrderId = string & { readonly __brand: 'OrderId' };39 40// Compiler prevents passing OrderId where UserId expected41function getUser(id: UserId): Promise<User> { /* ... */ }42```43 44**Const assertions for literal unions:**45```ts46const ROLES = ['admin', 'user', 'guest'] as const;47type Role = typeof ROLES[number]; // 'admin' | 'user' | 'guest'48 49// Array and type stay in sync automatically50function isValidRole(role: string): role is Role {51  return ROLES.includes(role as Role);52}53```54 55**Exhaustive switch with never check:**56```ts57type Status = "active" | "inactive";58 59function processStatus(status: Status): string {60  switch (status) {61    case "active":62      return "processing";63    case "inactive":64      return "skipped";65    default: {66      const _exhaustive: never = status;67      throw new Error(`unhandled status: ${_exhaustive}`);68    }69  }70}71```72 73## Runtime Validation with Zod74 75- Define schemas as single source of truth; infer TypeScript types with `z.infer<>`. Avoid duplicating types and schemas.76- Use `safeParse` for user input where failure is expected; use `parse` at trust boundaries where invalid data is a bug.77- Compose schemas with `.extend()`, `.pick()`, `.omit()`, `.merge()` for DRY definitions.78- Add `.transform()` for data normalization at parse time (trim strings, parse dates).79 80```ts81import { z } from "zod";82 83const UserSchema = z.object({84  id: z.string().uuid(),85  email: z.string().email(),86  name: z.string().min(1),87  createdAt: z.string().transform((s) => new Date(s)),88});89 90type User = z.infer<typeof UserSchema>;91 92// Strict parsing at trust boundaries — throws if API contract violated93export async function fetchUser(id: string): Promise<User> {94  const response = await fetch(`/api/users/${id}`);95  if (!response.ok) {96    throw new Error(`fetch user ${id} failed: ${response.status}`);97  }98  return UserSchema.parse(await response.json());99}100 101// Caller handles both success and error from user input102const result = UserSchema.safeParse(formData);103if (!result.success) {104  setErrors(result.error.flatten().fieldErrors);105  return;106}107```108 109## Optional: type-fest110 111For advanced type utilities beyond TypeScript builtins, consider [type-fest](https://github.com/sindresorhus/type-fest):112 113- `Opaque<T, Token>` - cleaner branded types than manual `& { __brand }` pattern114- `PartialDeep<T>` - recursive partial for nested objects115- `ReadonlyDeep<T>` - recursive readonly for immutable data116- `SetRequired<T, K>` / `SetOptional<T, K>` - targeted field modifications117- `Simplify<T>` - flatten complex intersection types in IDE tooltips118 119```ts120import type { Opaque, PartialDeep } from 'type-fest';121 122type UserId = Opaque<string, 'UserId'>;123type UserPatch = PartialDeep<User>;124```