TypeScript

TypeScript

Overview

Strict TypeScript engineering standard. Enforces noImplicitAny, discriminated unions, branded types, immutability, exhaustive switch checks, and zero unsafe any or as unknown as T casts.

When to Use

Activate on all TypeScript and JavaScript codebases to ensure compile-time type safety, robust domain modeling, and foolproof function contracts.

Negative Constraints (What NOT to Do)

1. NEVER use any: Use unknown with type guards, discriminated unions, or Zod schemas.
2. NEVER use type assertions (as Type or as unknown as Type) to bypass safety: Fix the underlying type signature or use runtime narrowing (instanceof, typeof, in).
3. NEVER use non-null assertions (foo!.bar): Handle null and undefined with optional chaining (?.) or explicit error guards.
4. NEVER export mutable global arrays or object constants: Always mark constant objects and arrays with as const and readonly.
5. NEVER omit explicit return types on exported functions: Exported public APIs must declare explicit return types to protect consumers.

Rules & Patterns

Strict Mode

Always use strict TypeScript configuration:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  }
}

Types

• Prefer interface for object shapes, type for unions/intersections
• No any — use unknown if type is truly unknown, then narrow
• Explicit return types for exported functions
• Const assertions — as const for literal types

// Good
interface User {
  id: string;
  name: string;
  role: 'admin' | 'user';
}

// Unions
type Result<T> = { ok: true; data: T } | { ok: false; error: string };

Utility Types

• Partial<T> — all properties optional
• Required<T> — all properties required
• Pick<T, K> — select specific properties
• Omit<T, K> — remove specific properties
• Record<K, V> — key-value map

Type Guards

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

Generic Patterns

// Repository pattern
interface Repository<T extends { id: string }> {
  findById(id: string): Promise<T | null>;
  create(data: Omit<T, 'id'>): Promise<T>;
  update(id: string, data: Partial<T>): Promise<T>;
  delete(id: string): Promise<void>;
}

Anti-Patterns

• [FAIL] any — use unknown + type guards
• [FAIL] Type assertions (as) — prefer type guards
• [FAIL] Non-null assertions (!) — handle null explicitly
• [FAIL] Enums — prefer union types or as const objects
• [FAIL] Complex generics without JSDoc — document intent

Code Examples

See EXAMPLES.md for detailed code examples.

Validation Checklist

What to verify during the review phase before completing the task.

Common Mistakes

Anti-patterns and things to explicitly avoid. See TROUBLESHOOTING.md.

Integration Notes

How this skill interacts with other skills.