typescript-patterns

This skill provides TypeScript-specific implementation patterns for type-safe, maintainable code.

## When to Invoke This Skill

Automatically activate for:
- TypeScript/JavaScript project implementation
- Type system design and refinement
- Generic patterns and utility types
- Error handling with type safety
- API type definitions

## Strict Typing Patterns

### Branded Types for Domain Safety

```typescript
// Prevent mixing IDs of different entities
type UserId = string & { readonly brand: unique symbol };
type OrderId = string & { readonly brand: unique symbol };

// Type-safe ID creation
function createUserId(id: string): UserId {
  return id as UserId;
}

// Compiler prevents: processOrder(userId) ✗
function processOrder(orderId: OrderId): void { /* ... */ }
```

### Discriminated Unions for State

```typescript
// Result type for error handling
type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E };

// Usage with exhaustive checking
function handleResult<T>(result: Result<T>): T {
  if (result.success) {
    return result.data;
  }
  throw result.error;
}

// State machines
type RequestState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error };
```

### Type Guards

```typescript
// Runtime type validation
function isUser(value: unknown): value is User {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    'email' in value &&
    typeof (value as User).id === 'string' &&
    typeof (value as User).email === 'string'
  );
}

// Array type guard
function isArrayOf<T>(
  arr: unknown,
  guard: (item: unknown) => item is T
): arr is T[] {
  return Array.isArray(arr) && arr.every(guard);
}

// Assertion function
function assertNonNull<T>(
  value: T | null | undefined,
  message?: string
): asserts value is T {
  if (value === null || value === undefined) {
    throw new Error(message ?? 'Value is null or undefined')