Clean TypeScript

We use TypeScript as a correctness and clarity tool, not as ceremony. Types should reduce bugs and cognitive load.

Type Philosophy

• PREFER explicit, readable types over clever or overly generic ones
• AVOID

  any

  and unsafe type assertions
• Use

  unknown

  instead of

  any

  when necessary
• Let TypeScript infer types when inference is clear and stable

Types & Interfaces

• PREFER

  type

  aliases for most use cases
• Use

  interface

  primarily for public, extendable object shapes
• Keep types small, composable, and well-named

Functions & APIs

• PREFER explicit return types for public functions
• Avoid function overloads unless they meaningfully improve the API
• Keep function signatures simple and predictable

Nullability & Safety

• Handle

  null

  and

  undefined

  explicitly
• DO NOT rely on non-null assertions (

  !

  ) except as a last resort
• Prefer narrowing via control flow and guards

Enums & Constants

• AVOID

  enum

• PREFER union types or

  as const

  objects
• Keep runtime output predictable and minimal

Error Handling

• Type errors and error states explicitly
• Prefer result objects or typed errors over throwing where appropriate
• Do not hide failure modes behind broad types

General Principles

• Types should explain intent
• If a type is hard to understand, it’s probably wrong
• Favor maintainability over theoretical completeness