typescript-migration

What this skill does

# TypeScript Migration Guide

Incremental strategy for migrating JavaScript codebases to TypeScript. Designed for legacy projects that need progressive, non-disruptive migration.

## When to Use This Skill

Activate when the user:
- Wants to convert a JS project (or parts of it) to TypeScript
- Needs to add TypeScript to an existing JavaScript project
- Asks about typing legacy code or reducing `any` usage
- Wants to improve type safety incrementally
- Is setting up tsconfig for a mixed JS/TS codebase

## Core Principle: Incremental Migration

**Never rewrite everything at once.** Migrate file by file, starting from the leaves of the dependency tree. Every intermediate state must be a working codebase.

```
Phase 1: Setup          → tsconfig + tooling, zero code changes
Phase 2: Rename         → .js → .ts for leaf files, fix type errors
Phase 3: Type boundaries → Add types to public APIs and shared interfaces
Phase 4: Deepen         → Enable stricter checks, eliminate `any`
Phase 5: Strict mode    → Full strict TypeScript
```

## Phase 1: Project Setup

### 1.1 Install TypeScript

```bash
npm install --save-dev typescript @types/node
```

For framework-specific types:

```bash
# React
npm install --save-dev @types/react @types/react-dom

# Express
npm install --save-dev @types/express

# Vue (types included in vue package)
# No extra install needed
```

### 1.2 Create tsconfig.json

Start permissive, tighten later:

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,

    "allowJs": true,
    "checkJs": false,

    "strict": false,
    "noImplicitAny": false,
    "strictNullChecks": false,

    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "isolatedModules": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.*"]
}
```

**Key settings for migration:**
- `allowJs: true` — allows mixed JS/TS
- `checkJs: false` — don't type-check JS files yet
- `strict: false` — start permissive
- `noImplicitAny: false` — allow implicit `any` initially

### 1.3 Update Build Tools

Most modern tools support TS out of the box:

```bash
# Vite — zero config needed
# Next.js — zero config, just rename files
# Webpack — add ts-loader or use babel
npm install --save-dev ts-loader
```

## Phase 2: Rename and Fix (Leaf-First)

### 2.1 Identify Migration Order

Start from files with NO internal imports (leaf nodes), then work up:

```
Level 0 (first):  utils/formatDate.js     → no imports from src/
Level 0 (first):  constants/index.js       → no imports from src/
Level 1:          services/dateService.js   → imports from utils/
Level 2:          api/patientApi.js         → imports from services/
Level 3 (last):   pages/PatientList.jsx     → imports from everything
```

### 2.2 Rename One File at a Time

```bash
# Rename
mv src/utils/formatDate.js src/utils/formatDate.ts

# Fix type errors
# Run build/IDE to see errors
npx tsc --noEmit
```

### 2.3 Typing Strategy Per File

For each renamed file:

1. **Add explicit return types** to exported functions
2. **Add parameter types** to exported functions
3. **Add interface/type for complex objects**
4. **Use `unknown` instead of `any`** where possible
5. **Keep internal functions loosely typed** initially — tighten later

```typescript
// BEFORE (JavaScript)
export function formatPatientName(patient) {
  return `${patient.lastName} ${patient.firstName}`
}

// AFTER (TypeScript — Phase 2)
interface Patient {
  lastName: string
  firstName: string
}

export function formatPatientName(patient: Patient): string {
  return `${patient.lastName} ${patient.firstName}`
}
```

## Phase 3: Type Boundaries

Focus on typing the **public API surface** — exports, function signatures, shared types.

### 3.1 Create Shared Type Files

```typescript
// src/types/patient.ts
export interface Patient {
  id: string
  lastName: string
  firstName: string
  birthDate: string  // ISO 8601
  sex: 'M' | 'F' | 'U'
  ipp?: string       // Internal Patient ID (optional)
}

export interface PatientSearchParams {
  query?: string
  unit?: string
  page?: number
  limit?: number
}

export type PatientCreateInput = Omit<Patient, 'id'>
```

### 3.2 Type API Responses

```typescript
// src/types/api.ts
export interface ApiResponse<T> {
  success: boolean
  data: T
  error?: ApiError
}

export interface ApiError {
  code: string
  message: string
  details?: Record<string, string[]>
}

export interface PaginatedResponse<T> extends ApiResponse<T[]> {
  pagination: {
    page: number
    limit: number
    total: number
    totalPages: number
  }
}
```

### 3.3 Type Event/Message Payloads

Especially important for healthcare message processing:

```typescript
// src/types/hpk.ts
export type HPKMessageType = 'ID' | 'MV' | 'CV' | 'PR' | 'FO'
export type HPKMode = 'C' | 'M' | 'D'

export interface HPKMessage {
  type: HPKMessageType
  code: string
  mode: HPKMode
  sender: string
  timestamp: string
  userId: string
  fields: string[]
}

// Discriminated union for type-safe message handling
export type HPKIdentityMessage = HPKMessage & {
  type: 'ID'
  patient: {
    id: string
    lastName: string
    firstName: string
    birthDate: string
    sex: 'M' | 'F'
  }
}

export type HPKMovementMessage = HPKMessage & {
  type: 'MV'
  visit: {
    id: string
    unit: string
    bed?: string
  }
}

export type TypedHPKMessage = HPKIdentityMessage | HPKMovementMessage
```

## Phase 4: Tighten the Compiler

Enable stricter checks one at a time. After each change, fix all errors before enabling the next.

### Recommended Order

```json
// Step 1 — catch null/undefined bugs (highest value)
"strictNullChecks": true

// Step 2 — catch missing types
"noImplicitAny": true

// Step 3 — catch forgotten returns
"noImplicitReturns": true

// Step 4 — catch switch fallthrough
"noFallthroughCasesInSwitch": true

// Step 5 — full strict mode (enables all strict options)
"strict": true
```

### Dealing with `strictNullChecks` Errors

Most common patterns:

```typescript
// Problem: Object is possibly 'undefined'
const patient = patients.find(p => p.id === id)
patient.name  // Error!

// Fix 1: Guard clause (preferred)
if (!patient) {
  throw new Error(`Patient ${id} not found`)
}
patient.name  // OK — TypeScript narrows the type

// Fix 2: Optional chaining (when absence is expected)
const name = patient?.name ?? 'Unknown'

// Fix 3: Non-null assertion (LAST RESORT — avoid if possible)
patient!.name  // Suppresses error, but defeats the purpose
```

### Eliminating `any`

```typescript
// STEP 1: Replace `any` with `unknown`
function parseMessage(raw: unknown): HPKMessage {
  if (typeof raw !== 'string') {
    throw new Error('Expected string input')
  }
  // Now TypeScript knows raw is a string
  const parts = raw.split('|')
  // ...
}

// STEP 2: Use type guards for runtime checking
function isPatient(data: unknown): data is Patient {
  return (
    typeof data === 'object' &&
    data !== null &&
    'id' in data &&
    'lastName' in data
  )
}

// STEP 3: Use Zod for validated parsing (recommended)
import { z } from 'zod'

const PatientSchema = z.object({
  id: z.string(),
  lastName: z.string(),
  firstName: z.string(),
  birthDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
  sex: z.enum(['M', 'F', 'U']),
})

type Patient = z.infer<typeof PatientSchema>

function parsePatient(data: unknown): Patient {
  return PatientSchema.parse(data)  // Throws ZodError if invalid
}
```

## Phase 5: Strict Mode

When all files are `.ts` and all strict checks pass individually:

```json
{
  "compilerOptions": {
    "strict": true,
    "allowJs": false,
    "checkJs": false
  }
}
```

Remove `allowJs` since all files are now TypeScript.

## Common Patterns for