TypeScript Coder

Expert 10x engineer with extensive knowledge of TypeScript fundamentals, migration strategies, and best practices. Use when asked to "add TypeScript", "migrate to TypeScript", "add type checking", "create TypeScript config", "fix TypeScript errors", or work with .ts/.tsx files. Supports JavaScript to TypeScript migration, JSDoc type annotations, tsconfig.json configuration, and type-safe code patterns.

# TypeScript Coder Skill

Master TypeScript development with expert-level knowledge of type systems, migration strategies, and modern JavaScript/TypeScript patterns. This skill transforms you into a 10x engineer capable of writing type-safe, maintainable code and migrating existing JavaScript projects to TypeScript with confidence.

## When to Use This Skill

- User asks to "add TypeScript", "migrate to TypeScript", or "convert to TypeScript"
- Need to "add type checking" or "fix TypeScript errors" in a project
- Creating or configuring `tsconfig.json` for a project
- Working with `.ts`, `.tsx`, `.mts`, or `.d.ts` files
- Adding JSDoc type annotations to JavaScript files
- Debugging type errors or improving type safety
- Setting up TypeScript in a Node.js or JavaScript project
- Creating type definitions or ambient declarations
- Implementing advanced TypeScript patterns (generics, conditional types, mapped types)

## Prerequisites

- Basic understanding of JavaScript (ES6+)
- Node.js and npm/yarn installed (for TypeScript compilation)
- Familiarity with the project structure and build tools
- Access to the `typescript` package (can be installed if needed)

## Shorthand Keywords

Keywords to trigger this skill as if using a command-line tool:

```javascript
openPrompt = ["typescript-coder", "ts-coder"]
```

Use these shorthand commands to quickly invoke TypeScript expertise without lengthy explanations. For example: 

- `typescript-coder --check "this code"`
- `typescript-coder check this type guard`
- `ts-coder migrate this file`
- `ts-coder --migrate project-to-typescript`

## Role and Expertise

As a TypeScript expert, you operate with:

- **Deep Type System Knowledge**: Understanding of TypeScript's structural type system, generics, and advanced types
- **Migration Expertise**: Proven strategies for incremental JavaScript to TypeScript migration
- **Best Practices**: Knowledge of TypeScript patterns, conventions, and anti-patterns
- **Tooling Mastery**: Configuration of TypeScript compiler, build tools, and IDE integration
- **Problem Solving**: Ability to resolve complex type errors and design type-safe architectures

## Core TypeScript Concepts

### The TypeScript Type System

TypeScript uses **structural typing** (duck typing) rather than nominal typing:

```typescript
interface Point {
  x: number;
  y: number;
}

// This works because the object has the right structure
const point: Point = { x: 10, y: 20 };

// This also works - structural compatibility
const point3D = { x: 1, y: 2, z: 3 };
const point2D: Point = point3D;  // OK - has x and y
```

### Type Inference

TypeScript infers types when possible, reducing boilerplate:

```typescript
// Type inferred as string
const message = "Hello, TypeScript!";

// Type inferred as number
const count = 42;

// Type inferred as string[]
const names = ["Alice", "Bob", "Charlie"];

// Return type inferred as number
function add(a: number, b: number) {
  return a + b;  // Returns number
}
```

### Key TypeScript Features

| Feature | Purpose | When to Use |
|---------|---------|-------------|
| **Interfaces** | Define object shapes | Defining data structures, API contracts |
| **Type Aliases** | Create custom types | Union types, complex types, type utilities |
| **Generics** | Type-safe reusable components | Functions/classes that work with multiple types |
| **Enums** | Named constants | Fixed set of related values |
| **Type Guards** | Runtime type checking | Narrowing union types safely |
| **Utility Types** | Transform types | `Partial<T>`, `Pick<T, K>`, `Omit<T, K>`, etc. |

## Step-by-Step Workflows

### Task 1: Install and Configure TypeScript

For a new or existing JavaScript project:

1. **Install TypeScript as a dev dependency**:
   ```bash
   npm install --save-dev typescript
   ```

2. **Install type definitions for Node.js** (if using Node.js):
   ```bash
   npm install --save-dev @types/node
   ```

3. **Initialize TypeScript configuration**:
   ```bash
   npx tsc --init
   ```

4. **Configure `tsconfig.json`** for your project:
   ```json
   {
     "compilerOptions": {
       "target": "ES2020",
       "module": "commonjs",
       "lib": ["ES2020"],
       "outDir": "./dist",
       "rootDir": "./src",
       "strict": true,
       "esModuleInterop": true,
       "skipLibCheck": true,
       "forceConsistentCasingInFileNames": true,
       "resolveJsonModule": true,
       "declaration": true,
       "declarationMap": true,
       "sourceMap": true
     },
     "include": ["src/**/*"],
     "exclude": ["node_modules", "dist"]
   }
   ```

5. **Add build script to `package.json`**:
   ```json
   {
     "scripts": {
       "build": "tsc",
       "dev": "tsc --watch",
       "check": "tsc --noEmit"
     }
   }
   ```

### Task 2: Migrate JavaScript to TypeScript (Incremental Approach)

Safe, incremental migration strategy:

1. **Enable TypeScript to process JavaScript files**:
   ```json
   {
     "compilerOptions": {
       "allowJs": true,
       "checkJs": false,
       "noEmit": true
     }
   }
   ```

2. **Add JSDoc type annotations to JavaScript files** (optional intermediate step):
   ```javascript
   // @ts-check

   /**
    * Calculates the sum of two numbers
    * @param {number} a - First number
    * @param {number} b - Second number
    * @returns {number} The sum
    */
   function add(a, b) {
     return a + b;
   }

   /** @type {string[]} */
   const names = ["Alice", "Bob"];

   /** @typedef {{ id: number, name: string, email?: string }} User */

   /** @type {User} */
   const user = {
     id: 1,
     name: "Alice"
   };
   ```

3. **Rename files incrementally** from `.js` to `.ts`:
   ```bash
   # Start with utility files and leaf modules
   mv src/utils/helpers.js src/utils/helpers.ts
   ```

4. **Fix TypeScript errors in converted files**:
   - Add explicit type annotations where inference fails
   - Define interfaces for complex objects
   - Handle `any` types appropriately
   - Add type guards for runtime checks

5. **Gradually convert remaining files**:
   - Start with utilities and shared modules
   - Move to leaf components (no dependencies)
   - Finally convert orchestration/entry files

6. **Enable strict mode progressively**:
   ```json
   {
     "compilerOptions": {
       "strict": false,
       "noImplicitAny": true,
       "strictNullChecks": true
       // Enable other strict flags one at a time
     }
   }
   ```

### Task 3: Define Types and Interfaces

Creating robust type definitions:

1. **Define interfaces for data structures**:
   ```typescript
   // User data model
   interface User {
     id: number;
     name: string;
     email: string;
     age?: number;  // Optional property
     readonly createdAt: Date;  // Read-only property
   }

   // API response structure
   interface ApiResponse<T> {
     success: boolean;
     data?: T;
     error?: {
       code: string;
       message: string;
     };
   }
   ```

2. **Use type aliases for complex types**:
   ```typescript
   // Union type
   type Status = 'pending' | 'active' | 'completed' | 'failed';

   // Intersection type
   type Employee = User & {
     employeeId: string;
     department: string;
     salary: number;
   };

   // Function type
   type TransformFn<T, U> = (input: T) => U;

   // Conditional type
   type NonNullable<T> = T extends null | undefined ? never : T;
   ```

3. **Create type definitions in `.d.ts` files** for external modules:
   ```typescript
   // types/custom-module.d.ts
   declare module 'custom-module' {
     export interface Config {
       apiKey: string;
       timeout?: number;
     }

     export function initialize(config: Config): Promise<void>;
     export function fetchData<T>(endpoint: string): Promise<T>;
   }
   ```

### Task 4: Work with Generics

Type-safe reusable components:

1. **Generic functions**:
   ```typescript
   // Basic generic function
   function identity<T>(value: T): T {
     return value;
   }

   const num = identity(42);