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) {}

Dependency Injection

• Inject external dependencies as parameters: Ensure testability and modularity

  // Receive dependency as parameter
  function createService(repository: Repository) { return {...} }

Asynchronous Processing

• Promise Handling: Follow the established repository style; use async/await when it makes sequencing and error propagation explicit
• Error Handling: Add try-catch when the current layer can convert, enrich, recover, or record the failure. Otherwise allow the promise rejection to propagate to the owning boundary
• Type Definition: Explicitly define return value types (e.g., Promise<Result>)

Format Rules

• Follow the repository's configured formatter, including its semicolon policy
• Types in PascalCase, variables/functions in camelCase
• Use absolute imports only through aliases declared in tsconfig or the configured build tool; otherwise use relative imports

Clean Code Principles

• Remove unused code within the current change
• Delete debug console.log()
• Keep executable source free of commented-out code; version control retains removed implementations
• Comments explain "why" (not "what")