TypeScript - Type-Safe JavaScript

Static typing for JavaScript - works across frontend, backend, and full-stack applications

When to Use This Skill

Use this skill when:

• Writing any JavaScript code that would benefit from type safety

• Building Node.js backend applications

• Developing React, Vue, or other frontend frameworks

• Creating libraries or shared code packages

• Working with APIs and need to define request/response types

• Refactoring existing JavaScript to add type safety

Don't use this skill when:

• Writing simple scripts where type safety adds no value (config files, build scripts)

• Working with languages other than JavaScript/TypeScript (use their respective skills)

• Types become more complex than the value they provide (prefer simplicity)

Critical Patterns

Pattern 1: Type Inference vs Explicit Types

When: Writing functions and variables

Good:

// ✅ Let TypeScript infer simple types const name = 'John' // inferred as string const age = 30 // inferred as number const items = [1, 2, 3] // inferred as number[]

// ✅ Explicit types for function signatures (better docs) function processUser(id: string, options?: { admin: boolean }): User { return { id, name: 'John', isAdmin: options?.admin ?? false } }

// ✅ Infer return type for simple functions const double = (n: number) => n * 2 // return type inferred as number

// ✅ Explicit return type for complex functions async function fetchUser(id: string): Promise<User | null> { const response = await fetch(/api/users/${id}) if (!response.ok) return null return response.json() }

Bad:

// ❌ Over-annotating obvious types const name: string = 'John' // unnecessary const age: number = 30 // unnecessary

// ❌ Missing function parameter types function processUser(id, options) { // any, any - loses type safety return { id, name: 'John' } }

// ❌ Missing return types on exported functions export function fetchUser(id: string) { // return type unclear return fetch(/api/users/${id}).then(r => r.json()) }

Why: Let TypeScript infer simple types to reduce noise. Add explicit types for function signatures to improve documentation and catch errors.

Pattern 2: Discriminated Unions for Type Safety

When: Handling multiple possible states or types

Good:

// ✅ Discriminated union with type field type Result<T> = | { status: 'success'; data: T } | { status: 'error'; error: string } | { status: 'loading' }

function handleResult<T>(result: Result<T>) { if (result.status === 'success') { console.log(result.data) // ✅ TypeScript knows data exists } else if (result.status === 'error') { console.log(result.error) // ✅ TypeScript knows error exists } else { console.log('Loading...') // ✅ TypeScript knows no extra fields } }

// ✅ Discriminated union for different shapes type Shape = | { kind: 'circle'; radius: number } | { kind: 'rectangle'; width: number; height: number } | { kind: 'square'; size: number }

function calculateArea(shape: Shape): number { switch (shape.kind) { case 'circle': return Math.PI * shape.radius ** 2 case 'rectangle': return shape.width * shape.height case 'square': return shape.size ** 2 } }

Bad:

// ❌ Union without discriminator type Result<T> = { data?: T error?: string loading?: boolean }

function handleResult<T>(result: Result<T>) { if (result.data) { console.log(result.data) // ❌ Could still have error or loading } }

Why: Discriminated unions provide exhaustive type checking and make illegal states unrepresentable.

Pattern 3: Generic Constraints for Reusable Code

When: Writing reusable functions that work with multiple types

Good:

// ✅ Generic with constraints interface HasId { id: string }

function findById<T extends HasId>(items: T[], id: string): T | undefined { return items.find(item => item.id === id) // ✅ TypeScript knows T has id }

// ✅ keyof constraint function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] { return obj[key] // ✅ Type-safe property access }

const user = { name: 'John', age: 30 } const name = getProperty(user, 'name') // string const age = getProperty(user, 'age') // number

Bad:

// ❌ Generic without constraints function findById<T>(items: T[], id: string): T | undefined { return items.find(item => item.id === id) // ❌ Error: 'id' doesn't exist on T }

// ❌ Using any loses type safety function getProperty(obj: any, key: string): any { return obj[key] // ❌ No type safety }

Why: Generic constraints ensure type safety while maintaining flexibility.

Pattern 4: Utility Types for Type Transformations

When: Deriving new types from existing ones

Good:

interface User { id: string name: string email: string password: string role: 'admin' | 'user' createdAt: Date }

// ✅ Pick for selecting specific properties type UserPreview = Pick<User, 'id' | 'name'>

// ✅ Omit for excluding sensitive data type PublicUser = Omit<User, 'password'>

// ✅ Partial for optional updates function updateUser(id: string, updates: Partial<User>) { // ✅ Can update any subset of user fields }

// ✅ Record for maps/dictionaries type UserMap = Record<string, User> const users: UserMap = { 'user1': { id: '1', name: 'John', /* ... */ }, }

// ✅ ReturnType to extract function return type function getUser() { return { id: '1', name: 'John', email: 'john@example.com' } }

type UserType = ReturnType<typeof getUser>

Bad:

// ❌ Manually duplicating types type UserPreview = { id: string // ❌ Duplicated from User name: string // ❌ Duplicated from User }

Why: Utility types keep types DRY and automatically sync with source types.

For more examples and patterns, see references/examples.md and references/patterns.md.

Anti-Patterns

❌ Anti-Pattern 1: Overusing any

Don't do this:

// ❌ Using any defeats the purpose of TypeScript function processData(data: any): any { return data.map((item: any) => item.value) }

Why it's bad: Disables TypeScript's type checking, loses IntelliSense.

Do this instead:

// ✅ Use specific types or generics function processData<T extends { value: any }>(data: T[]): any[] { return data.map(item => item.value) }

// ✅ Or use unknown for truly unknown data function processUnknown(data: unknown) { if (typeof data === 'string') { return data.toUpperCase() // ✅ Type narrowed to string } throw new Error('Invalid data') }

❌ Anti-Pattern 2: Type Assertions Instead of Type Guards

Don't do this:

// ❌ Unsafe type assertion function processUser(data: any) { const user = data as User // ❌ No runtime check console.log(user.name.toUpperCase()) // ❌ Runtime error if not a User }

Why it's bad: Type assertions bypass type checking and can cause runtime errors.

Do this instead:

// ✅ Type guards for runtime validation function isUser(data: unknown): data is User { return ( typeof data === 'object' && data !== null && 'id' in data && 'name' in data ) }

function processUser(data: unknown) { if (isUser(data)) { console.log(data.name.toUpperCase()) // ✅ Type-safe } }

❌ Anti-Pattern 3: Ignoring Strict Mode

Don't do this:

// tsconfig.json { "compilerOptions": { "strict": false // ❌ Disables all strict checks } }

Why it's bad: Disables TypeScript's most valuable features.

Do this instead:

// tsconfig.json { "compilerOptions": { "strict": true, // ✅ Enable all strict checks "noUncheckedIndexedAccess": true, "noImplicitOverride": true } }

For more anti-patterns and solutions, see references/best-practices.md.

Quick Reference

// Type annotations let name: string = 'John' let numbers: number[] = [1, 2, 3]

// Interfaces interface User { id: string name: string email?: string // Optional }

// Type aliases type ID = string | number type Status = 'idle' | 'loading' | 'success'

// Functions function add(a: number, b: number): number { return a + b }

// Generics function identity<T>(value: T): T { return value }

// Utility types Partial<T> // All properties optional Required<T> // All properties required Readonly<T> // All properties readonly Pick<T, K> // Select properties Omit<T, K> // Exclude properties Record<K, T> // Object with keys K and values T

Learn More

• Examples: references/examples.md - Complete code examples for basic and advanced usage

• Advanced Patterns: references/patterns.md - Mapped types, conditional types, advanced generics

• Configuration: references/configuration.md - tsconfig.json, compiler options

• Advanced Types: references/advanced-types.md - Template literals, branded types

• Best Practices: references/best-practices.md - Code organization, naming conventions

• Node.js Patterns: references/nodejs.md - Express, Prisma, tRPC integration

External References

• TypeScript Documentation

• TypeScript Handbook

Maintained by dsmj-ai-toolkit