TS Best Practices

ts-best-practices

Write, review, and refactor TypeScript code to follow battle-tested conventions: object-arg parameters, JSDoc on exports, discriminated unions for variants, branded types for IDs, ts-pattern for multi-branch logic, and exports-first file structure.

Core conventions

Naming

Object properties: prefer nested when properties form a logical group; flat for standalone values.

File structure

Top-to-bottom order in every .ts file:

1. Imports (grouped: node built-ins, external, internal @pkg/*, relative — blank line between groups)
2. Types (interfaces, type aliases)
3. Constants
4. Exported functions (the public API — first, so readers see it without scrolling)
5. Private functions (function declarations are hoisted, so position doesn't matter)

No banner comments (// === HELPERS ===). The structure speaks for itself.

Function parameters

Use an object parameter when a function has 2+ related parameters. Define an interface with Params / Options / Args suffix, destructure in the signature.

export function createUser({ name, email, roleId }: CreateUserParams): User { // ... }

JSDoc

Every exported function needs JSDoc with @param, @returns, and @example (when useful). Document the why, not the what. Skip only in test files.

/**
 * Parses raw webhook headers into a typed structure.
 *
 * @param params - The raw headers and provider identifier
 * @returns Parsed webhook headers or a parse error
 *
 * @example
 * ```ts
 * const result = parseWebhookHeaders({ headers, provider: 'github' })
 * ```
 */
export function parseWebhookHeaders(params: ParseHeadersParams) {
  // ...
}

Private (non-exported) functions get JSDoc too, with @private:

/**
 * Extracts the display name from a user record.
 *
 * @private
 */
function getDisplayName(user: User): string {
  return user.displayName ?? user.email
}

Types

Discriminated unions for variants:

type AuthStrategy =
  | { strategy: 'connection'; connectionId: string }
  | { strategy: 'integration'; integrationId: string }
  | { strategy: 'user'; userId: string; token: string }

Branded types for IDs (prevents accidentally swapping userId and orgId):

type Brand<T, B> = T & { __brand: B }
type UserId = Brand<string, 'UserId'>
type OrgId = Brand<string, 'OrgId'>

function userId(id: string): UserId {
  return id as UserId
}

as const for literal types:

const STATUSES = ['pending', 'active', 'completed'] as const
type Status = (typeof STATUSES)[number] // "pending" | "active" | "completed"

type-fest for utility types not in stdlib: SetRequired, SetOptional, PartialDeep, ReadonlyDeep, Except, Simplify.

Never use any — use unknown and narrow with type guards.

Conditionals

const message = match(status) .with('pending', () => 'Waiting...') .with('success', () => 'Done!') .with('error', () => 'Failed') .exhaustive() // compile error if a case is missing

Anti-patterns

Examples

import type { User } from './types'

interface FetchUserParams {
  userId: UserId
}

interface FetchUserOptions {
  cache?: boolean
  includeDeleted?: boolean
}

/**
 * Fetches a user by ID, optionally with caching.
 *
 * @param params - Required: the user ID to fetch
 * @param options - Optional: cache + soft-delete flags
 * @returns The user record, or null if not found
 *
 * @example
 * ```ts
 * const user = await fetchUser({ userId }, { cache: true })
 * ```
 */
export async function fetchUser(
  { userId }: FetchUserParams,
  options?: FetchUserOptions
): Promise<User | null> {
  if (options?.cache) {
    const cached = await readCache(userId)
    if (cached) return cached
  }

  return loadUser(userId, options?.includeDeleted ?? false)
}

/**
 * @private
 */
function readCache(userId: UserId): Promise<User | null> {
  // ...
}

The agent applied: *Params + *Options split, branded UserId, JSDoc with @example, exports-first ordering, no banner comments, early-return-style cache check, private helper at the bottom.

Before:

function renderStatus(deployment: Deployment) {
  if (deployment.status === 'building') {
    return 'Building...'
  } else if (deployment.status === 'ready') {
    if (deployment.error) {
      return `Failed: ${deployment.error}`
    } else {
      return `Ready at ${deployment.url}`
    }
  } else {
    return 'Unknown'
  }
}

After:

import { match, P } from 'ts-pattern'

function renderStatus(deployment: Deployment): string {
  return match(deployment)
    .with({ status: 'building' }, () => 'Building...')
    .with({ status: 'ready', error: P.nullish }, (d) => `Ready at ${d.url}`)
    .with({ status: 'ready' }, (d) => `Failed: ${d.error}`)
    .exhaustive()
}

Compile-time exhaustiveness, type-narrowed callbacks, no nested ifs.

Rationalization table

Captured from RED-baseline transcripts where agents without this skill skipped rules under pressure. Future agents: recognize your own pattern before reaching for the excuse.

References

• type-fest — utility types library
• ts-pattern — exhaustive matching
• TypeScript handbook utility types