Typescript

Comprehensive guidelines for writing production-quality TypeScript based on Google's TypeScript Style Guide. Naming Conventions Type Convention Example Classes, Interfaces, Types, Enums UpperCamelCase UserService, HttpClient Variables, Parameters, Functions lowerCamelCase userName, processData Global Constants, Enum Values CONSTANT_CASE MAX_RETRIES, Status.ACTIVE Type Parameters Single letter or UpperCamelCase T, ResponseType Naming Principles

Descriptive names, avoid ambiguous abbreviations
Treat acronyms as words: loadHttpUrl not loadHTTPURL
No prefixes like opt_ for optional parameters
No trailing underscores for private properties
Single-letter variables only when scope is <10 lines

Variable Declarations

// Always use const by default const users = getUsers();

// Use let only when reassignment is needed let count = 0; count++;

// Never use var // var x = 1; // WRONG

// One variable per declaration const a = 1; const b = 2; // const a = 1, b = 2; // WRONG

Types and Interfaces Prefer Type Aliases Over Interfaces

// Good: type alias for object shapes type User = { id: string; name: string; email?: string; };

// Avoid: interface for object shapes // interface User { // id: string; // name: string; // }

// Type aliases work for everything: objects, unions, intersections, mapped types type Status = 'active' | 'inactive'; type Combined = TypeA & TypeB; type Handler = (event: Event) => void;

// Benefits of types over interfaces: // 1. Consistent syntax for all type definitions // 2. Cannot be merged/extended unexpectedly (no declaration merging) // 3. Better for union types and computed properties // 4. Works with utility types more naturally

Type Inference

Leverage inference for trivially inferred types:

// Good: inference is clear const name = 'Alice'; const items = [1, 2, 3];

// Good: explicit for complex expressions const result: ProcessedData = complexTransformation(input);

Array Types

// Simple types: use T[] const numbers: number[]; const names: readonly string[];

// Multi-dimensional: use T[][] const matrix: number[][];

// Complex types: use Array<T> const handlers: Array<(event: Event) => void>;

Null and Undefined

// Prefer optional fields over union with undefined interface Config { timeout?: number; // Good // timeout: number | undefined; // Avoid }

// Type aliases must NOT include |null or |undefined type UserId = string; // Good // type UserId = string | null; // WRONG

// May use == for null comparison (catches both null and undefined) if (value == null) { // handles both null and undefined }

Types to Avoid

// Avoid any - use unknown instead function parse(input: unknown): Data { }

// Avoid {} - use unknown, Record<string, T>, or object function process(obj: Record<string, unknown>): void { }

// Use lowercase primitives let name: string; // Good // let name: String; // WRONG

// Never use wrapper objects // new String('hello') // WRONG

Classes Structure

class UserService { // Fields first, initialized where declared private readonly cache = new Map<string, User>(); private lastAccess: Date | null = null;

// Constructor with parameter properties constructor( private readonly api: ApiClient, private readonly logger: Logger, ) {}

// Methods separated by blank lines async getUser(id: string): Promise<User> { // ... }

private validateId(id: string): boolean { // ... } }

Visibility

class Example { // private by default, only use public when needed externally private internalState = 0;

// readonly for properties never reassigned after construction readonly id: string;

// Never use #private syntax - use TypeScript visibility // #field = 1; // WRONG private field = 1; // Good }

Avoid Arrow Functions as Properties

class Handler { // Avoid: arrow function as property // handleClick = () => { ... };

// Good: instance method handleClick(): void { // ... } }

// Bind at call site if needed element.addEventListener('click', () => handler.handleClick());

Static Methods

Never use this in static methods
Call on defining class, not subclasses

Functions Prefer Function Declarations

// Good: function declaration for named functions function processData(input: Data): Result { return transform(input); }

// Arrow functions when type annotation needed const handler: EventHandler = (event) => { // ... };

Arrow Function Bodies

// Concise body only when return value is used const double = (x: number) => x * 2;

// Block body when return should be void const log = (msg: string) => { console.log(msg); };

Parameters

// Use rest parameters, not arguments function sum(...numbers: number[]): number { return numbers.reduce((a, b) => a + b, 0); }

// Destructuring for multiple optional params interface Options { timeout?: number; retries?: number; } function fetch(url: string, { timeout = 5000, retries = 3 }: Options = {}) { // ... }