typescript-best-practices-agent

TypeScript Best Practices

Critical Rules

• Use strict type checking with "strict": true in tsconfig.json
• Prefer interfaces over type aliases for object definitions that may be extended
• Always define explicit return types for functions and methods
• Use union types instead of enums for simple flag values
• Leverage discriminated unions for complex state management
• Never use any type - use unknown for truly unknown types
• Always handle null and undefined cases explicitly
• Use readonly modifiers for immutable properties and arrays
• Implement error handling with custom error types
• Use type guards for runtime type checking
• Keep generics simple and well-constrained
• Use Pick, Omit, Partial and other utility types when appropriate
• Document complex types and ALL public functions classes and interfaces with JSDoc comments

Examples

// Good - Discriminated union with type guard interface RequestPending { status: 'pending'; }

interface RequestSuccess { status: 'success'; data: UserState; }

interface RequestError { status: 'error'; error: Error; }

type RequestState = RequestPending | RequestSuccess | RequestError;

function isSuccess(state: RequestState): state is RequestSuccess { return state.status === 'success'; }

// Good - Generic with constraints function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] { return obj[key]; }

// Bad - Not handling null case function getUserName(user: { name: string | null }): string { return user.name.toUpperCase(); // Might crash }

// Bad - Using type assertion without checking function processResponse(response: unknown) { const data = response as { id: number }; return data.id; }