Typescript

Critical Patterns

Const Types Pattern (REQUIRED)

// ✅ ALWAYS: Create const object first, then extract type
const STATUS = {
  ACTIVE: 'active',
  INACTIVE: 'inactive',
  PENDING: 'pending',
} as const;

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

// ❌ NEVER: Direct union types
type Status = 'active' | 'inactive' | 'pending';

Flat Interfaces (REQUIRED)

// ✅ ALWAYS: One level depth, nested objects → dedicated interface
interface UserAddress {
  street: string;
  city: string;
}

interface User {
  id: string;
  name: string;
  address: UserAddress; // Reference, not inline
}

// ❌ NEVER: Inline nested objects
interface User {
  address: { street: string; city: string }; // NO!
}

Never Use any (REQUIRED)

// ✅ Use unknown for truly unknown types
function parse(input: unknown): User {
  if (isUser(input)) return input;
  throw new Error('Invalid input');
}

// ✅ Use generics for flexible types
function first<T>(arr: T[]): T | undefined {
  return arr[0];
}

// ❌ NEVER
function parse(input: any): any {}

Decision Tree

Need a set of constants?    → Use const object + typeof
Need optional fields?       → Use Partial<T>
Need to pick fields?        → Use Pick<T, K>
Need to exclude fields?     → Use Omit<T, K>
Need runtime type check?    → Create type guard function
Need to extract type?       → Use ReturnType<typeof fn>

Code Examples

Type Guards

function isUser(value: unknown): value is User {
  return typeof value === 'object' && value !== null && 'id' in value && 'name' in value;
}

Utility Types

Pick<User, 'id' | 'name'>; // Select fields
Omit<User, 'id'>; // Exclude fields
Partial<User>; // All optional
Required<User>; // All required
Record<string, User>; // Object type
NonNullable<T | null>; // Remove null/undefined
ReturnType<typeof fn>; // Function return type

Import Types

import type { User } from './types';
import { createUser, type Config } from './utils';

Commands

npx tsc --noEmit              # Type check without emit
npx tsc --init                # Initialize tsconfig.json
npx tsc -w                    # Watch mode

Resources

Specialized TypeScript documentation:

• Best Practices: best-practices.md
• Type Safety: type-safety.md
• NestJS Integration: nestjs.md
• Node.js Patterns: node.md