TypeScript Skill

Overview

TypeScript's value comes from catching errors at compile time, not runtime. This skill guides systematic use of TypeScript's type system for safer, more maintainable code.

Core principle: If TypeScript can't verify it, neither can you. Use the type system to make invalid states unrepresentable.

The Type-Safe Development Process

Phase 1: Design Types First

Before writing implementation:

1. •

   Define Data Shapes

   • •What data flows through this code?
   • •What are the possible states?
   • •What states are INVALID and shouldn't exist?
2. •

   Use Discriminated Unions for States

   typescript

   // Make invalid states unrepresentable
   type RequestState =
     | { status: 'idle' }
     | { status: 'loading' }
     | { status: 'success'; data: User }
     | { status: 'error'; error: Error };
   

3. •

   Define Function Signatures

   • •What goes in? What comes out?
   • •What errors can occur?
   • •See references/advanced-types.md for patterns

Phase 2: Implement with Strict Mode

Let the compiler guide you:

1. •

   Enable All Strict Flags

   json

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

2. •

   Fix Errors, Don't Silence Them

   • •Type error = bug waiting to happen
   • •// @ts-ignore is almost never the answer
   • •any defeats the purpose of TypeScript
3. •

   Use Type Narrowing

   typescript

   // Let TypeScript narrow types for you
   if (result.status === 'success') {
     console.log(result.data);  // TypeScript knows data exists
   }
   

Phase 3: Review for Type Safety

Before approving:

1. •

   Check for Type Escapes

   • •Any use of any?
   • •Any type assertions (as Type)?
   • •Any // @ts-ignore or // @ts-expect-error?
2. •

   Verify Null Handling

   • •Are null/undefined cases handled?
   • •Does strictNullChecks catch issues?
3. •

   Test Type Inference

   • •Hover over variables - are types what you expect?
   • •Are generics inferring correctly?

Red Flags - STOP and Fix

Type Safety Red Flags

- any type (find the real type)
- Type assertions: value as Type (use type guards)
- // @ts-ignore (fix the underlying issue)
- ! non-null assertion (handle the null case)
- Object or {} as type (be specific)
- Function type without parameters (define signature)

Code Quality Red Flags

- Deeply nested generics (simplify with type aliases)
- Types duplicated across files (centralize in types/)
- Runtime type checking (let TypeScript do it)
- Optional chaining everywhere (fix the types)
- Type definitions longer than implementation (too complex)

Configuration Red Flags

- strict: false (enable it)
- skipLibCheck: true without good reason
- any in function returns
- Missing return types on public functions
- No ESLint TypeScript rules

Common Rationalizations - Don't Accept These

Type Safety Checklist

Before approving TypeScript code:

• • No any: All types are specific
• • No assertions: Using type guards instead of as
• • Null handled: Optional values properly checked
• • Strict mode: All strict flags enabled
• • No ignores: No @ts-ignore or @ts-expect-error
• • Interfaces defined: Data shapes are explicit
• • Errors typed: Error handling is type-safe

Quick Type Patterns

Prefer unknown over any

// ❌ any bypasses all checking
function parse(json: string): any { ... }

// ✅ unknown requires narrowing
function parse(json: string): unknown { ... }
const data = parse(input);
if (isUser(data)) {
  console.log(data.name);  // Safe
}

Use Type Guards

// ❌ Type assertion (unsafe)
const user = response.data as User;

// ✅ Type guard (safe)
function isUser(data: unknown): data is User {
  return typeof data === 'object' && data !== null && 'id' in data;
}
if (isUser(response.data)) {
  const user = response.data;  // Typed correctly
}

Use Discriminated Unions

// ❌ Optional fields (any combination valid)
interface Result {
  data?: User;
  error?: Error;
  loading?: boolean;
}

// ✅ Discriminated union (only valid states)
type Result =
  | { status: 'loading' }
  | { status: 'success'; data: User }
  | { status: 'error'; error: Error };

Quick Commands

# Type check without emitting
npx tsc --noEmit

# Type check with strict
npx tsc --noEmit --strict

# Find any types
grep -r ": any" src/

# ESLint with TypeScript
npx eslint . --ext .ts,.tsx

References

Detailed patterns and examples in references/:

• •advanced-types.md - Generics, conditional types, mapped types
• •typescript-config.md - tsconfig.json best practices
• •migration-guide.md - JavaScript to TypeScript migration