typescript-best-practices

# TypeScript Best Practices

Guidelines for writing clean, type-safe, and maintainable TypeScript code.

> **Note:** If the repository has established code style conventions, follow those first. These guidelines serve as defaults.

## Core Principles

1. **Type-First Design** - Define types before implementation; minimize reliance on inference
2. **Interface for Structure** - Use `interface` for objects, `type` for unions/mapped/conditional
3. **Namespace for Type Organization** - Group related types with namespaces (types only, not runtime)
4. **Generic Const for Strictness** - Use `<const TConfig>` for strict literal inference
5. **Extract, Don't Redefine** - Get types from existing definitions instead of duplicating
6. **Strictest Config** - Use strictest tsconfig base; install `ts-reset` for saner built-in types

## Quick Reference

### interface vs type

| Use | When |
|-----|------|
| `interface` | Object structures, class contracts, extensible APIs |
| `type` | Union types, mapped types, conditional types, tuples |

### Naming Conventions

| Element | Convention | Example |
|---------|------------|---------|
| Interface/Type | PascalCase | `UserProfile`, `ResponseData` |
| Generic parameters | `T` prefix | `TUser`, `TConfig` (never bare `T`, `K`, `V`) |
| Acronyms | First cap only | `userId`, `ApiResponse` (NOT `userID`, `APIResponse`) |
| Constants | UPPER_SNAKE | `MAX_RETRY_COUNT` |
| Variables/Functions | camelCase | `getUserById`, `isActive` |

#### Generic Parameter Naming

The `T` prefix applies to **all** generic type parameters, not just top-level ones:

```typescript
// ✓ DO: Use T prefix everywhere
type Nullable<TValue> = TValue | null;

type MyPick<TObj, TKey extends keyof TObj> = {
  [TProp in TKey]: TObj[TProp];
};

type ArrayElement<TValue> = TValue extends Array<infer TItem> ? TItem : never;

function merge<TTarget, TSource>(target: TTarget, source: TSource): TTarget & TSource;

// ✗ DON'T: Use single letters
type Nullable<T> = T | null;

type