TypeScript Coding Conventions

General Principles

• Use TypeScript strict mode ("strict": true in tsconfig.json).
• Prefer const over let; never use var.
• Use explicit return types on exported functions.
• Prefer interfaces over type aliases for object shapes.
• Use unknown instead of any where possible.

Naming Conventions

• Variables & functions: camelCase
• Classes & interfaces: PascalCase
• Constants: UPPER_SNAKE_CASE for true constants, camelCase for derived values
• Files: kebab-case.ts
• Type parameters: Single uppercase letter (T, K, V) or descriptive (TResult)

File Structure

src/
  index.ts          # Entry point, exports
  types.ts          # Shared type definitions
  utils/            # Utility functions
  services/         # Business logic
  middleware/       # Express/framework middleware

Error Handling

• Use typed errors (extend Error class).
• Always handle promise rejections.
• Prefer try/catch with specific error types over generic catches.

class AppError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly statusCode: number = 500
  ) {
    super(message);
    this.name = 'AppError';
  }
}

Async Patterns

• Use async/await over raw promises.
• Use Promise.all() for concurrent independent operations.
• Avoid mixing callbacks and promises.

Imports

• Use named imports: import { thing } from './module'
• Group imports: external packages first, then internal modules.
• Use .js extensions in import paths for ESM compatibility.

Code Style

• Maximum line length: 100 characters.
• Use template literals for string interpolation.
• Prefer Array.map/filter/reduce over for loops for transformations.
• Use optional chaining (?.) and nullish coalescing (??).
• Destructure objects and arrays when accessing multiple properties.

Testing

• Co-locate test files: thing.ts → thing.test.ts
• Use descriptive test names: it('should return empty array when no items match')
• Test edge cases: empty inputs, null values, error conditions.