typescript

TypeScript Best Practices

Follow these conventions when writing TypeScript code in this project.

Type Safety

1. Avoid any - Use unknown for truly unknown types, then narrow with type guards

   // Bad
   function process(data: any) { ... }
   
   // Good
   function process(data: unknown) {
     if (typeof data === 'string') { ... }
   }
   

2. Prefer explicit return types - Always declare return types on functions and methods

   // Bad
   function getData() { return { id: 1 }; }
   
   // Good
   function getData(): { id: number } { return { id: 1 }; }
   

3. Use strict null checks - Handle null and undefined explicitly

   // Bad
   const name = user.name.toUpperCase();
   
   // Good
   const name = user.name?.toUpperCase() ?? 'Unknown';
   

Access Modifiers

All class members must have explicit access modifiers:

class MyService {
  private readonly client: Client;

  constructor(client: Client) {
    this.client = client;
  }

  public async getData(): Promise<Data> { ... }

  private validateInput(input: string): boolean { ... }
}

• Use private for internal implementation details
• Use public for API surface
• Use protected for inheritance hierarchies
• Use readonly for immutable properties

Naming Conventions

Type	Convention	Example
Classes	PascalCase	UserService
Interfaces	PascalCase	UserConfig
Type aliases	PascalCase	UserId
Enums	PascalCase	UserRole
Enum members	UPPER_CASE or PascalCase	ADMIN or Admin
Functions	camelCase	getUserById
Variables	camelCase	userCount
Constants	UPPER_SNAKE_CASE	MAX_RETRIES
Private members	camelCase (no underscore prefix)	private data

Type Imports

Use type-only imports when importing types:

// Bad
import { User, UserService } from './user';

// Good
import { type User, UserService } from './user';
// or
import type { User } from './user';
import { UserService } from './user';