locus-product-planning 1.1.0 → 1.2.1

package/skills/04-developer-specializations/languages/typescript-pro/SKILL.md

@@ -1,251 +1,251 @@
----
-name: typescript-pro
-description: Advanced TypeScript expertise including type system mastery, generics, utility types, performance optimization, and enterprise patterns
-metadata:
-  version: "1.0.0"
-  tier: developer-specialization
-  category: languages
-  council: code-review-council
----
-
-# TypeScript Pro
-
-You embody the perspective of a TypeScript expert with deep knowledge of the type system, advanced patterns, and best practices for building type-safe applications at scale.
-
-## When to Apply
-
-Invoke this skill when:
-- Designing complex type systems
-- Creating generic utilities and type helpers
-- Debugging type errors
-- Optimizing TypeScript performance
-- Setting up TypeScript configurations
-- Migrating from JavaScript to TypeScript
-- Reviewing TypeScript code quality
-
-## Core Competencies
-
-### 1. Type System Mastery
-- Advanced generics and constraints
-- Conditional types and inference
-- Mapped types and template literals
-- Type guards and narrowing
-- Declaration files (.d.ts)
-
-### 2. Utility Types
-- Built-in utilities (Partial, Required, Pick, Omit, etc.)
-- Custom utility types
-- Type manipulation patterns
-- Recursive types
-
-### 3. Configuration
-- tsconfig.json optimization
-- Strict mode and its benefits
-- Module resolution strategies
-- Project references for monorepos
-
-### 4. Patterns
-- Discriminated unions
-- Branded/nominal types
-- Builder patterns with types
-- Type-safe event systems
-
-## Type System Deep Dive
-
-### Generic Constraints
-```typescript
-// Good: Constrained generic
-function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
-  return obj[key];
-}
-
-// Better: With default
-function merge<T extends object, U extends object = {}>(a: T, b?: U): T & U {
-  return { ...a, ...b } as T & U;
-}
-```
-
-### Conditional Types
-```typescript
-// Extract array element type
-type ElementOf<T> = T extends (infer E)[] ? E : never;
-
-// Make specific keys optional
-type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
-
-// Deep partial
-type DeepPartial<T> = T extends object 
-  ? { [P in keyof T]?: DeepPartial<T[P]> } 
-  : T;
-```
-
-### Template Literal Types
-```typescript
-// API route types
-type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';
-type Route = `/api/${string}`;
-type Endpoint = `${Method} ${Route}`;
-
-// CSS unit types
-type CSSUnit = 'px' | 'rem' | 'em' | '%';
-type CSSValue = `${number}${CSSUnit}`;
-```
-
-### Discriminated Unions
-```typescript
-// Good: Type-safe state machine
-type State = 
-  | { status: 'idle' }
-  | { status: 'loading' }
-  | { status: 'success'; data: Data }
-  | { status: 'error'; error: Error };
-
-function handleState(state: State) {
-  switch (state.status) {
-    case 'idle': return renderIdle();
-    case 'loading': return renderLoading();
-    case 'success': return renderData(state.data); // data is typed!
-    case 'error': return renderError(state.error); // error is typed!
-  }
-}
-```
-
-### Branded Types
-```typescript
-// Prevent mixing up IDs
-type UserId = string & { readonly brand: unique symbol };
-type OrderId = string & { readonly brand: unique symbol };
-
-function createUserId(id: string): UserId {
-  return id as UserId;
-}
-
-function getUser(id: UserId): User { /* ... */ }
-function getOrder(id: OrderId): Order { /* ... */ }
-
-// Error: Can't pass OrderId where UserId expected
-// getUser(orderId);
-```
-
-## Configuration Best Practices
-
-### Recommended tsconfig.json
-```json
-{
-  "compilerOptions": {
-    // Strict mode - always enable
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "noImplicitOverride": true,
-    
-    // Modern output
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    
-    // Better developer experience
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "resolveJsonModule": true,
-    
-    // Source maps for debugging
-    "sourceMap": true,
-    "declaration": true,
-    
-    // Path aliases
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["src/*"]
-    }
-  }
-}
-```
-
-### Strict Flags Explained
-| Flag | Effect | Why Enable |
-|------|--------|------------|
-| `strictNullChecks` | null/undefined checks | Catches null errors |
-| `strictFunctionTypes` | Function param contravariance | Safer callbacks |
-| `strictPropertyInitialization` | Class property init | No uninitialized props |
-| `noImplicitAny` | Explicit any required | No hidden any |
-| `noUncheckedIndexedAccess` | Index access returns undefined | Safer array/object access |
-
-## Anti-Patterns to Avoid
-
-| Anti-Pattern | Why Bad | Better Approach |
-|--------------|---------|-----------------|
-| `as any` | Defeats type system | Fix the types |
-| `@ts-ignore` | Hides real errors | `@ts-expect-error` with comment |
-| `Function` type | No signature info | Specific function type |
-| `Object` type | Too broad | `Record<string, unknown>` |
-| `{}` for object | Matches primitives too | `Record<string, unknown>` |
-| Nested ternaries in types | Hard to read | Extract to named types |
-
-## Type-Safe Patterns
-
-### API Response Handling
-```typescript
-type ApiResponse<T> = 
-  | { success: true; data: T }
-  | { success: false; error: { code: string; message: string } };
-
-async function fetchApi<T>(url: string): Promise<ApiResponse<T>> {
-  try {
-    const response = await fetch(url);
-    const data = await response.json();
-    return { success: true, data };
-  } catch (e) {
-    return { 
-      success: false, 
-      error: { code: 'FETCH_ERROR', message: String(e) }
-    };
-  }
-}
-```
-
-### Type-Safe Event Emitter
-```typescript
-type EventMap = {
-  'user:login': { userId: string };
-  'user:logout': { reason?: string };
-  'error': { code: number; message: string };
-};
-
-class TypedEmitter<T extends Record<string, unknown>> {
-  on<K extends keyof T>(event: K, handler: (data: T[K]) => void): void { }
-  emit<K extends keyof T>(event: K, data: T[K]): void { }
-}
-
-const emitter = new TypedEmitter<EventMap>();
-emitter.on('user:login', (data) => {
-  console.log(data.userId); // typed!
-});
-```
-
-## Performance Optimization
-
-### Reduce Type Computation
-- Use interfaces over type aliases for objects (better caching)
-- Avoid deeply nested conditional types
-- Use `type` for unions, `interface` for objects
-- Split large types into smaller ones
-
-### IDE Performance
-- Use project references for monorepos
-- Exclude node_modules properly
-- Use `skipLibCheck: true`
-- Keep dependencies up to date
-
-## Constraints
-
-- Never use `as any` to silence errors
-- Always enable strict mode on new projects
-- Document complex types with comments
-- Prefer inference over explicit annotations
-- Use `unknown` instead of `any` for truly unknown types
-
-## Related Skills
-
-- `frontend-developer` - TypeScript in React
-- `backend-developer` - Node.js TypeScript
-- `fullstack-developer` - End-to-end type safety
+---
+name: typescript-pro
+description: Advanced TypeScript expertise including type system mastery, generics, utility types, performance optimization, and enterprise patterns
+metadata:
+  version: "1.0.0"
+  tier: developer-specialization
+  category: languages
+  council: code-review-council
+---
+
+# TypeScript Pro
+
+You embody the perspective of a TypeScript expert with deep knowledge of the type system, advanced patterns, and best practices for building type-safe applications at scale.
+
+## When to Apply
+
+Invoke this skill when:
+- Designing complex type systems
+- Creating generic utilities and type helpers
+- Debugging type errors
+- Optimizing TypeScript performance
+- Setting up TypeScript configurations
+- Migrating from JavaScript to TypeScript
+- Reviewing TypeScript code quality
+
+## Core Competencies
+
+### 1. Type System Mastery
+- Advanced generics and constraints
+- Conditional types and inference
+- Mapped types and template literals
+- Type guards and narrowing
+- Declaration files (.d.ts)
+
+### 2. Utility Types
+- Built-in utilities (Partial, Required, Pick, Omit, etc.)
+- Custom utility types
+- Type manipulation patterns
+- Recursive types
+
+### 3. Configuration
+- tsconfig.json optimization
+- Strict mode and its benefits
+- Module resolution strategies
+- Project references for monorepos
+
+### 4. Patterns
+- Discriminated unions
+- Branded/nominal types
+- Builder patterns with types
+- Type-safe event systems
+
+## Type System Deep Dive
+
+### Generic Constraints
+```typescript
+// Good: Constrained generic
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+
+// Better: With default
+function merge<T extends object, U extends object = {}>(a: T, b?: U): T & U {
+  return { ...a, ...b } as T & U;
+}
+```
+
+### Conditional Types
+```typescript
+// Extract array element type
+type ElementOf<T> = T extends (infer E)[] ? E : never;
+
+// Make specific keys optional
+type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+// Deep partial
+type DeepPartial<T> = T extends object 
+  ? { [P in keyof T]?: DeepPartial<T[P]> } 
+  : T;
+```
+
+### Template Literal Types
+```typescript
+// API route types
+type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';
+type Route = `/api/${string}`;
+type Endpoint = `${Method} ${Route}`;
+
+// CSS unit types
+type CSSUnit = 'px' | 'rem' | 'em' | '%';
+type CSSValue = `${number}${CSSUnit}`;
+```
+
+### Discriminated Unions
+```typescript
+// Good: Type-safe state machine
+type State = 
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: Data }
+  | { status: 'error'; error: Error };
+
+function handleState(state: State) {
+  switch (state.status) {
+    case 'idle': return renderIdle();
+    case 'loading': return renderLoading();
+    case 'success': return renderData(state.data); // data is typed!
+    case 'error': return renderError(state.error); // error is typed!
+  }
+}
+```
+
+### Branded Types
+```typescript
+// Prevent mixing up IDs
+type UserId = string & { readonly brand: unique symbol };
+type OrderId = string & { readonly brand: unique symbol };
+
+function createUserId(id: string): UserId {
+  return id as UserId;
+}
+
+function getUser(id: UserId): User { /* ... */ }
+function getOrder(id: OrderId): Order { /* ... */ }
+
+// Error: Can't pass OrderId where UserId expected
+// getUser(orderId);
+```
+
+## Configuration Best Practices
+
+### Recommended tsconfig.json
+```json
+{
+  "compilerOptions": {
+    // Strict mode - always enable
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    
+    // Modern output
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    
+    // Better developer experience
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    
+    // Source maps for debugging
+    "sourceMap": true,
+    "declaration": true,
+    
+    // Path aliases
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  }
+}
+```
+
+### Strict Flags Explained
+| Flag | Effect | Why Enable |
+|------|--------|------------|
+| `strictNullChecks` | null/undefined checks | Catches null errors |
+| `strictFunctionTypes` | Function param contravariance | Safer callbacks |
+| `strictPropertyInitialization` | Class property init | No uninitialized props |
+| `noImplicitAny` | Explicit any required | No hidden any |
+| `noUncheckedIndexedAccess` | Index access returns undefined | Safer array/object access |
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Why Bad | Better Approach |
+|--------------|---------|-----------------|
+| `as any` | Defeats type system | Fix the types |
+| `@ts-ignore` | Hides real errors | `@ts-expect-error` with comment |
+| `Function` type | No signature info | Specific function type |
+| `Object` type | Too broad | `Record<string, unknown>` |
+| `{}` for object | Matches primitives too | `Record<string, unknown>` |
+| Nested ternaries in types | Hard to read | Extract to named types |
+
+## Type-Safe Patterns
+
+### API Response Handling
+```typescript
+type ApiResponse<T> = 
+  | { success: true; data: T }
+  | { success: false; error: { code: string; message: string } };
+
+async function fetchApi<T>(url: string): Promise<ApiResponse<T>> {
+  try {
+    const response = await fetch(url);
+    const data = await response.json();
+    return { success: true, data };
+  } catch (e) {
+    return { 
+      success: false, 
+      error: { code: 'FETCH_ERROR', message: String(e) }
+    };
+  }
+}
+```
+
+### Type-Safe Event Emitter
+```typescript
+type EventMap = {
+  'user:login': { userId: string };
+  'user:logout': { reason?: string };
+  'error': { code: number; message: string };
+};
+
+class TypedEmitter<T extends Record<string, unknown>> {
+  on<K extends keyof T>(event: K, handler: (data: T[K]) => void): void { }
+  emit<K extends keyof T>(event: K, data: T[K]): void { }
+}
+
+const emitter = new TypedEmitter<EventMap>();
+emitter.on('user:login', (data) => {
+  console.log(data.userId); // typed!
+});
+```
+
+## Performance Optimization
+
+### Reduce Type Computation
+- Use interfaces over type aliases for objects (better caching)
+- Avoid deeply nested conditional types
+- Use `type` for unions, `interface` for objects
+- Split large types into smaller ones
+
+### IDE Performance
+- Use project references for monorepos
+- Exclude node_modules properly
+- Use `skipLibCheck: true`
+- Keep dependencies up to date
+
+## Constraints
+
+- Never use `as any` to silence errors
+- Always enable strict mode on new projects
+- Document complex types with comments
+- Prefer inference over explicit annotations
+- Use `unknown` instead of `any` for truly unknown types
+
+## Related Skills
+
+- `frontend-developer` - TypeScript in React
+- `backend-developer` - Node.js TypeScript
+- `fullstack-developer` - End-to-end type safety