agentop: Skill for Claude Code

TypeScript Best Practices

Modern TypeScript patterns for type-safe, maintainable code with maximum developer experience.

When to Use This Skill

• Designing interfaces and types
• Working with generics
• Creating type-safe APIs
• Implementing type guards
• Building utility types

Core Principles

Use TypeScript Strict Mode

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  }
}

Prefer interface for Objects

// ✅ GOOD: Interface for object shapes
interface Task {
  id: string;
  title: string;
  status: TaskStatus;
}

// ✅ GOOD: Type for unions, primitives, utilities
type TaskStatus = 'pending' | 'active' | 'completed';
type TaskId = string;
type TaskRecord = Record<string, Task>;

// Interface can be extended
interface TimestampedTask extends Task {
  createdAt: Date;
  updatedAt: Date;
}

Make Invalid States Unrepresentable

// ❌ BAD: Allows invalid states
interface Session {
  status: 'idle' | 'running' | 'completed' | 'error';
  startedAt?: Date;
  completedAt?: Date;
  error?: Error;
  result?: SessionResult;
}
// Can have error with status 'completed', result with status 'idle', etc.

// ✅ GOOD: Discriminated union - each state is explicit
type Session = 
  | { status: 'idle' }
  | { status: 'running'; startedAt: Date }
  | { status: 'completed'; startedAt: Date; completedAt: Date; result: SessionResult }
  | { status: 'error'; startedAt: Date; error: Error };

// TypeScript enforces correct fields for each state
function handleSession(session: Session) {
  switch (session.status) {
    case 'idle':
      // Only idle-specific fields available
      return 'Ready to start';
      
    case 'running':
      // startedAt is guaranteed to exist
      return `Running since ${session.startedAt.toISOString()}`;
      
    case 'completed':
      // result is guaranteed to exist
      return `Completed: ${session.result.summary}`;
      
    case 'error':
      // error is guaranteed to exist
      return `Error: ${session.error.message}`;
  }
}