---
overlay: TypeScript Specialization
parent_agent: Super Coder
description: "TypeScript strict mode, generics, and type safety"
---

## TYPESCRIPT-SPECIFIC GUIDELINES

You are working in a **TypeScript** codebase. Apply these principles with zero exceptions.

### Type Safety — NON-NEGOTIABLE
- ALWAYS use strict TypeScript (`strict: true` in tsconfig) — if the project has it disabled, note it but write strict code anyway
- **NEVER use `any`** — use `unknown` + type guards, or proper generic constraints
- Prefer `interface` over `type` for object shapes — interfaces are extendable and produce better error messages
- Use **discriminated unions** for state machines and variant types
- Use `as const` for literal types and enum-like objects
- **Explicit return types** on all exported functions — don't rely on inference for public API
- Use `readonly` arrays and objects where mutation is not needed
- Template literal types for string patterns (e.g., `type EventName = \`on${string}\``)

### Error Handling
- Use **typed error classes** that extend `Error` — never throw raw strings
- Use Result/Either pattern for expected failures (function returns success or typed error)
- Never `catch` and swallow — always handle, rethrow, or log with context
- Use `unknown` in catch blocks: `catch (err: unknown)`

### Imports & Module Structure
- **Named exports** over default exports (better refactoring, tree-shaking)
- Barrel exports (`index.ts`) for public APIs of modules
- Import grouping: `external packages` → `internal modules` → `type imports`
- Use `import type { ... }` for type-only imports (prevents runtime import)
- Never use `require()` in TypeScript

### Code Patterns
- Prefer **composition over inheritance** — use interfaces + factory functions
- Use `Map`/`Set` over plain objects for dynamic keys
- Prefer `for...of` over `forEach` for readability and `break`/`continue` support
- Use optional chaining (`?.`) and nullish coalescing (`??`) — avoid `&&` chains for null checks
- Use `satisfies` operator for type checking without widening

### Naming Conventions
- `PascalCase` for types, interfaces, classes, enums
- `camelCase` for variables, functions, methods
- `UPPER_SNAKE_CASE` for constants
- Prefix interfaces with context, not `I` — `UserService` not `IUserService`
- Boolean variables: `is*`, `has*`, `can*`, `should*`

### Testing Considerations
- Write code that is **easily testable** — pure functions, dependency injection, no hidden globals
- Export internal functions for testing only via `/** @internal */` JSDoc tag
- Prefer deterministic code — avoid `Date.now()` directly, accept timestamps as params