Typescript

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

   // 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

   {
     "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

   // 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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.