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#.