# Type Safety Quick Reference

**30-SECOND CHECKLIST - USE BEFORE EVERY EDIT**

---

## ✅ Golden Rules

| Rule | Example |
|------|---------|
| **Use `plan.name`** | ✅ `plan.name` ❌ `plan.title` |
| **Use `stage.name`** | ✅ `stage.name` ❌ `stage.title` |
| **Use `stage.notes`** | ✅ `stage.notes` ❌ `stage.description` |
| **Package name** | ✅ `@my-roadtrip/types` ❌ `@my-road-trip/types` |
| **No duplicates** | ✅ Import from `packages/types/` ❌ Local definition |

---

## 🔍 Pre-Edit Commands

```bash
# 1. Check if type exists (5 sec)
grep -r "export interface TypeName" packages/types/src/

# 2. Find property names (5 sec)
grep -A 10 "export interface Plan" packages/types/src/planner.types.ts

# 3. Verify imports (5 sec)
grep -r "import.*TypeName" apps/
```

---

## 📋 Common Types & Properties

### Plan
```typescript
interface Plan {
  id: string
  userId: string
  name: string          // ← Use 'name' not 'title'
  description?: string
  stages: Stage[]
}
```

### Stage
```typescript
interface Stage {
  id: string
  planId: string        // ← Required
  name: string          // ← Use 'name' not 'title'
  notes?: string        // ← Use 'notes' not 'description'
  location: Location
  order: number         // ← Required
}
```

### UserProfile
```typescript
interface UserProfile {
  id: string
  email: string
  displayName: string   // ← Use 'displayName' not 'name'
  gamification?: {      // ← Nested object (optional)
    points: number
    level: number
    badges: Badge[]
    stats: UserStats
  }
}
```

### Accessing Gamification Data
```typescript
// ✅ CORRECT - Via nested object
const points = profile.gamification?.points ?? 0
const level = profile.gamification?.level ?? 1
const badges = profile.gamification?.badges ?? []

// ❌ WRONG - Direct access
const points = profile.points      // Property doesn't exist
const level = profile.level        // Property doesn't exist
```

---

## 🚫 Never Do This

```typescript
// ❌ WRONG - Duplicate type
export interface Plan { ... }

// ❌ WRONG - Wrong property
const title = plan.title

// ❌ WRONG - Package typo
import { Plan } from '@my-road-trip/types'

// ❌ WRONG - Local override
interface Plan { customField: string }
```

---

## ✅ Always Do This

```typescript
// ✅ CORRECT - Import existing type
import type { Plan } from '@my-roadtrip/types'

// ✅ CORRECT - Use correct property
const name = plan.name

// ✅ CORRECT - Extend if needed
interface ExtendedPlan extends Plan {
  customField: string
}
```

---

## 🆘 Emergency Commands

```bash
# Find duplicates
grep -r "export interface Plan" packages/ apps/

# Find wrong properties
grep -r "plan\.title" apps/web/src/modules/planner/

# Find typos
grep -r "@my-road-trip/types" apps/

# Validate all
./scripts/validate-types.sh
```

---

**Full documentation:** `.github/instructions/TYPE_SAFETY_PROTOCOL.md`
