TypeScript Best Practices

Type Safety

• Enable strict: true in tsconfig.json — never disable strict checks in production code.
• Prefer unknown over any. If any is unavoidable, add a comment explaining why and narrow it immediately.
• Use satisfies to validate a value matches a type while preserving its narrowed literal type:

const config = {
    endpoint: "/api/users",
    timeout: 3000,
} satisfies Config;

• Prefer type narrowing (type guards, in operator, instanceof) over type assertions (as).

Type Inference

• Let TypeScript infer when the type is obvious — don't annotate what the compiler already knows:

// Redundant
const name: string = "Graham";

// Let it infer
const name = "Graham";

• Always annotate function return types for exported/public functions — it catches accidental return type changes and improves IDE performance:

export function getUser(id: string): User | undefined {
    return users.get(id);
}

• Annotate function parameters — they cannot be inferred from implementation.

Types vs Interfaces

• Use type for unions, intersections, mapped types, and utility types.
• Use interface for object shapes that may be extended or implemented.
• Be consistent within a codebase — pick one default and stick with it.

Enums and Constants

• Prefer as const objects over enum:

const Status = {
    Active: "active",
    Inactive: "inactive",
} as const;

type Status = (typeof Status)[keyof typeof Status];

• This gives you type safety, tree-shaking, and no runtime enum overhead.

Null Handling

• Prefer explicit | undefined in types over optional properties when the distinction matters.
• Use optional chaining (?.) and nullish coalescing (??) over manual null checks.
• Avoid non-null assertions (!) — narrow the type instead.

Generics

• Name generic parameters descriptively when there are multiple: TInput, TOutput instead of T, U.
• Constrain generics with extends to communicate intent:

function merge<T extends Record<string, unknown>>(a: T, b: Partial<T>): T {
    return { ...a, ...b };
}

• Avoid over-genericizing — if a function only ever handles one type, don't make it generic.

Utility Types

• Use built-in utility types (Partial, Required, Pick, Omit, Record, Readonly) instead of reimplementing them.
• Readonly<T> for data that should not be mutated.
• Pick and Omit to derive subsets from existing types rather than duplicating fields.

Error Handling

• Type errors explicitly — don't rely on catch (e) being any:

try {
    await fetchData();
} catch (error) {
    if (error instanceof ApiError) {
        handleApiError(error);
    }
    throw error;
}

• Create typed error classes for domain-specific errors.

Module Organization

• One type/interface per concern — avoid monolithic types.ts files.
• Co-locate types with the code that uses them.
• Export types from barrel files only when they form part of the public API.
• Use import type / export type for type-only imports to enable proper tree-shaking.

Naming Conventions

• PascalCase for types, interfaces, enums, and classes.
• camelCase for variables, functions, and methods.
• UPPER_SNAKE_CASE for true constants (compile-time values).
• Don't prefix interfaces with I or types with T — it's not C#.