type-safety-standards

What this skill does

# Frontend Type Safety Standards

**Pattern**: Strict TypeScript + Runtime Validation + Type Guards

Comprehensive type safety across frontend code using **TypeScript strict mode**, **runtime validation at boundaries**, and **type guards** for complex types.

> **Scope**: This skill covers type safety *patterns and techniques*. For general TypeScript/React rules (component design, state management, error handling), see `typescript-rules`.

## Runtime Validation with Zod

Validate at trust boundaries: API responses, user input, URL parameters, localStorage, and any external data source.

### Schema Definition and Type Derivation

Always derive TypeScript types from Zod schemas to prevent schema-type drift:

```typescript
import { z } from 'zod';

export const UserProfileSchema = z.object({
  id: z.string().uuid(),
  displayName: z.string().min(1),
  email: z.string().email(),
  preferences: z.object({
    theme: z.enum(['light', 'dark', 'system']),
    locale: z.string(),
  }),
  createdAt: z.string().datetime(),
  updatedAt: z.string().datetime(),
});

// Derive type from schema - single source of truth
export type UserProfile = z.infer<typeof UserProfileSchema>;
```

### API Response Validation

```typescript
async function fetchUserProfile(userId: string): Promise<UserProfile> {
  const response = await fetch(`/api/users/${userId}`);
  const data: unknown = await response.json();

  const result = UserProfileSchema.safeParse(data);
  if (!result.success) {
    throw new Error(`Invalid user profile data: ${result.error.message}`);
  }

  return result.data;
}
```

### Form Input Validation

```typescript
const ContactFormSchema = z.object({
  name: z.string().min(1, 'Name is required').max(100, 'Name too long'),
  email: z.string().email('Invalid email address'),
  message: z.string().min(10, 'Message must be at least 10 characters').max(2000),
});

function handleSubmit(formData: unknown) {
  const result = ContactFormSchema.safeParse(formData);

  if (!result.success) {
    const errors = result.error.flatten().fieldErrors;
    setFieldErrors(errors);
    return;
  }

  submitForm(result.data); // Type-safe after validation
}
```

## Discriminated Unions and Type Guards

### Defining Discriminated Unions

Use a shared literal field (`type`, `kind`, `status`) as the discriminant:

```typescript
export type MediaElement =
  | { type: 'image'; id: string; src: string; alt?: string }
  | { type: 'video'; id: string; src: string; poster?: string }
  | { type: 'text'; id: string; content: string; fontSize: number };
```

### Type Guards for Discriminated Unions

```typescript
export function isImageElement(
  element: MediaElement
): element is Extract<MediaElement, { type: 'image' }> {
  return element.type === 'image';
}

export function isVideoElement(
  element: MediaElement
): element is Extract<MediaElement, { type: 'video' }> {
  return element.type === 'video';
}
```

### Exhaustiveness Checking

Ensure all union variants are handled at compile time:

```typescript
function renderElement(element: MediaElement): JSX.Element {
  switch (element.type) {
    case 'image':
      return <img src={element.src} alt={element.alt} />;
    case 'video':
      return <video src={element.src} poster={element.poster} />;
    case 'text':
      return <p style={{ fontSize: element.fontSize }}>{element.content}</p>;
    default: {
      const _exhaustive: never = element;
      return _exhaustive;
    }
  }
}
```

## Branded Types

Prevent accidental interchange of structurally identical types:

```typescript
type UserId = string & { readonly __brand: 'UserId' };
type WorkspaceId = string & { readonly __brand: 'WorkspaceId' };
type OrderId = string & { readonly __brand: 'OrderId' };

// Constructor functions for branded types
function toUserId(id: string): UserId {
  return id as UserId;
}

function toWorkspaceId(id: string): WorkspaceId {
  return id as WorkspaceId;
}

// Compile-time safety: cannot mix ID types
function getUser(userId: UserId): Promise<User> { /* ... */ }
function getWorkspace(workspaceId: WorkspaceId): Promise<Workspace> { /* ... */ }

const userId = toUserId('user-123');
const workspaceId = toWorkspaceId('ws-456');

getUser(userId);        // OK
getUser(workspaceId);   // Compile error - type mismatch
```

## Type Assertion Avoidance

### DON'T: Assert Without Validation

```typescript
// UNSAFE: No runtime guarantee that data matches type
const data = await fetch('/api/data').then(res => res.json());
const user = data as User;
```

### DO: Validate Then Use

```typescript
const data: unknown = await fetch('/api/data').then(res => res.json());
const result = UserSchema.safeParse(data);
if (!result.success) {
  throw new Error('Invalid user data');
}
const user = result.data; // Type-safe without assertion
```

### DO: Assertion Functions for Reusable Validation

```typescript
function assertIsUser(value: unknown): asserts value is User {
  const result = UserSchema.safeParse(value);
  if (!result.success) {
    throw new Error(`Not a valid user: ${result.error.message}`);
  }
}

const data: unknown = loadFromStorage();
assertIsUser(data);
// TypeScript knows data is User from here
```

## Generic Component Typing

### Typed List Components

```typescript
interface ListProps<T> {
  items: T[];
  renderItem: (item: T, index: number) => React.ReactNode;
  keyExtractor: (item: T) => string;
  emptyMessage?: string;
}

function TypedList<T>({
  items,
  renderItem,
  keyExtractor,
  emptyMessage = 'No items',
}: ListProps<T>) {
  if (items.length === 0) return <p>{emptyMessage}</p>;

  return (
    <ul>
      {items.map((item, index) => (
        <li key={keyExtractor(item)}>{renderItem(item, index)}</li>
      ))}
    </ul>
  );
}

// Usage preserves type inference
<TypedList
  items={users}
  renderItem={(user) => <span>{user.name}</span>}
  keyExtractor={(user) => user.id}
/>
```

### Typed Select/Dropdown

```typescript
interface SelectProps<T extends string> {
  value: T;
  options: readonly { value: T; label: string }[];
  onChange: (value: T) => void;
}

function TypedSelect<T extends string>({
  value,
  options,
  onChange,
}: SelectProps<T>) {
  return (
    <select
      value={value}
      onChange={(e) => onChange(e.target.value as T)}
    >
      {options.map((opt) => (
        <option key={opt.value} value={opt.value}>
          {opt.label}
        </option>
      ))}
    </select>
  );
}
```

## State Type Safety

### Typed Reducer with Discriminated Actions

```typescript
type CounterState = { count: number; lastAction: string };

type CounterAction =
  | { type: 'increment'; payload: number }
  | { type: 'decrement'; payload: number }
  | { type: 'reset' };

function counterReducer(state: CounterState, action: CounterAction): CounterState {
  switch (action.type) {
    case 'increment':
      return { count: state.count + action.payload, lastAction: 'increment' };
    case 'decrement':
      return { count: state.count - action.payload, lastAction: 'decrement' };
    case 'reset':
      return { count: 0, lastAction: 'reset' };
    default: {
      const _exhaustive: never = action;
      return _exhaustive;
    }
  }
}
```

### Typed Context with Null Safety

```typescript
interface AuthContext {
  user: User | null;
  login: (credentials: Credentials) => Promise<void>;
  logout: () => void;
}

const AuthContext = createContext<AuthContext | undefined>(undefined);

function useAuth(): AuthContext {
  const context = useContext(AuthContext);
  if (context === undefined) {
    throw new Error('useAuth must be used within an AuthProvider');
  }
  return context;
}
```

## Result Type Pattern for Typed Error Handling

```typescript
type ResultSuccess<T> = { success: true; data: T };
type ResultError<E = string> = { success: false; error: E };
type Result<T, E = string> = ResultSuccess<T> | ResultError<E>;

// Usage in API layer
async function fetchUsers(): Promise<Result<User[], ApiError>> {
  try {
    const response = await f