typescript

TypeScript Guidelines

Standards and best practices for TypeScript development with modern tooling. Follow these guidelines when writing or modifying TypeScript code.

Design Principles

Apply DRY, KISS, and SOLID consistently. Prefer functional approaches where relevant; use classes for stateful behavior. Use composition over inheritance. Each module should have a single responsibility. Use dependency injection for class dependencies.

Code Style

• Naming: Descriptive yet concise names for variables, functions, and classes
• Documentation: JSDoc comments for public APIs, complex logic, and non-obvious design decisions
• Type annotations: Be explicit with typing to reduce inference time; avoid any unless necessary
• Imports: Avoid barrel exports to prevent circular dependencies; prefer direct imports

Type Safety

• Strict TypeScript: Use strict mode with proper type definitions. Use type-safe patterns like Zod schemas for validation and type-safe DOM helpers where applicable.
• Avoid any: Use unknown instead of any when the type is truly unknown. Narrow types appropriately.
• Type inference: Be explicit with typing to reduce inference time and improve clarity

Type Patterns

• Union types: Use union types for values that can be one of several types
• Discriminated unions: Use discriminated unions for type-safe state machines
• Generic constraints: Use generic constraints to ensure type safety
• Utility types: Leverage TypeScript utility types (Pick, Omit, Partial, etc.)

Architecture

Module Organization

• Each module focuses on one concern with clear boundaries
• Extract reusable functions to avoid duplication
• Design for reusability across contexts
• Co-locate types with their usage or in dedicated type files
• Keep types at appropriate module boundaries

Dependency Management

• Use dependency injection for testability
• Prefer composition over inheritance
• Keep dependencies minimal and focused