typescript-rules

TypeScript Development Rules

Prerequisite Detection

Inspect tsconfig, runtime/framework configuration, lint/format configuration, path aliases, package scripts, and representative modules before applying project conventions. Treat a rule as project-specific only when configuration or an established pattern supports it. Label limited-pattern conclusions as inferred. When competing conventions change a public contract, runtime behavior, or error boundary, stop and name the source or user decision required.

Type Safety in Backend Implementation

Type Safety in Data Flow Input Layer (unknown) -> Type Guard -> Business Layer (Type Guaranteed) -> Output Layer (Serialization)

Backend-Specific Type Scenarios:

• API Communication: Receive responses as unknown and validate them with type guards
• Form Input: External input as unknown, type determined after validation
• Legacy Integration: Receive the legacy boundary as unknown; isolate any evidence-backed assertion in the adapter that owns the boundary
• Test Code: Define mock input/output types with the configured test harness; use Partial<T> for intentionally partial fixtures and typed vi.fn<[Args], Return>() only when Vitest is configured

Coding Conventions

Class Usage Criteria

• Recommended: Implementation with Functions and Interfaces
  • Rationale: Improves testability and flexibility of function composition
• Classes Allowed:
  • Framework requirements (NestJS Controller/Service, TypeORM Entity, etc.)
  • Custom error class definitions
  • When state and business logic are tightly coupled (e.g., ShoppingCart, Session, StateMachine)
• Decision Criterion: If "Does this data have behavior?" is Yes, consider using a class

  // Functions and interfaces
  interface UserService { create(data: UserData): User }
  const userService: UserService = { create: (data) => {...} }
  

Function Design

• 0-2 parameters maximum: Use object for 3+ parameters

  // Object parameter
  function createUser({ name, email, role }: CreateUserParams) {}