typescript-coding-standards

TypeScript Coding Standards

Quick Navigation: Level 1: Quick Start (5 min) → Level 2: Implementation (30 min) → Level 3: Mastery (Extended)

Level 1: Quick Start (<2,000 tokens, 5 minutes)

Core Principles

1. Strict Type Safety: Enable strict mode and leverage TypeScript's type system fully
2. Type Inference: Use type inference when obvious, explicit types when clarity matters
3. No Any: Avoid any type; use unknown for truly dynamic data
4. Immutability: Prefer readonly properties and immutable data structures
5. Modern Tooling: Use tsconfig strict mode, ESLint, and Prettier

Essential Checklist

• Strict Mode: Enable all strict compiler options in tsconfig.json
• No Implicit Any: All variables have explicit or inferred types
• Proper Generics: Use generics for reusable type-safe functions and classes
• Testing: Jest with TypeScript support, type testing with tsd
• Documentation: TSDoc comments for public APIs
• Module System: ES6 modules with proper imports/exports
• Linting: ESLint with TypeScript plugin configured
• Build: Proper tsconfig with source maps and declaration files

Quick Example

/**
 * Authentication service with type-safe error handling.
 */
import { hash, compare } from 'bcrypt';
import jwt from 'jsonwebtoken';

// Type definitions
interface User {
  readonly id: string;
  readonly username: string;
  readonly email: string;
  readonly passwordHash: string;
}

interface AuthResult<T> {
  readonly success: boolean;
  readonly data?: T;
  readonly error?: Error;
}

// Custom errors
class AuthError extends Error {
  constructor(message: string, public readonly code: string) {
    super(message);
    this.name = 'AuthError';
  }
}

// Service implementation
class AuthService {
  constructor(
    private readonly repository: UserRepository,
    private readonly jwtSecret: string
  ) {}

  async authenticate(username: string, password: string): Promise<AuthResult<{ token: string }>> {
    if (!username || !password) {
      return { success: false, error: new AuthError('Credentials required', 'VALIDATION') };
    }

    const user = await this.repository.findByUsername(username);
    if (!user || !await compare(password, user.passwordHash)) {
      return { success: false, error: new AuthError('Invalid credentials', 'AUTH_FAILED') };
    }

    const token = jwt.sign({ userId: user.id, username: user.username }, this.jwtSecret, {
      expiresIn: '1h',
    });

    return { success: true, data: { token } };
  }

  async hashPassword(password: string): Promise<string> {
    return hash(password, 10);
  }
}