typescript-type-safety

ffMathy's avatarfrom ffMathy

TypeScript type safety guidelines. Use this when writing TypeScript code, especially when handling errors or unknown data types.

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026

When & Why to Use This Skill

This Claude skill provides comprehensive TypeScript type safety guidelines designed to eliminate runtime errors and improve code maintainability. It enforces strict typing standards by offering practical rules for avoiding the 'any' type, implementing robust type guards, and handling unknown data structures safely, ensuring your codebase remains scalable and bug-free.

Use Cases

  • Refactoring legacy codebases: Systematically replacing 'any' types with 'unknown' and proper type assertions to enhance IDE autocomplete and catch bugs at compile-time.
  • Robust Error Handling: Implementing type-safe error catch blocks that narrow 'unknown' errors into specific types using custom type guards.
  • Team Standardization: Serving as a technical style guide for development teams to ensure consistent type safety practices across large-scale TypeScript projects.
  • API Integration: Safely processing unpredictable data from external APIs by validating shapes before usage, preventing runtime crashes.
nametypescript-type-safety
descriptionTypeScript type safety guidelines. Use this when writing TypeScript code, especially when handling errors or unknown data types.

TypeScript Type Safety

CRITICAL: Never use any type - it defeats TypeScript's purpose.

Rules

  1. Use proper types for all data structures
  2. Use unknown for truly unknown data, then narrow with type guards
  3. Use type assertions sparingly and only when verified
  4. Enable strict mode in tsconfig.json

Error Handling

❌ BAD - Using any:

server.on('error', (error: any) => {
  console.error('Server error:', error.message);
  if (error.details) {
    console.error('Details:', error.details.message);
  }
});

✅ GOOD - Proper Type Assertion:

server.on('error', (error) => {
  const typedError = error as Error & {
    details?: { message?: string };
  };
  console.error('Server error:', typedError.message);
  if (typedError.details?.message) {
    console.error('Details:', typedError.details.message);
  }
});

✅ EVEN BETTER - Type Guard:

function isErrorWithDetails(error: unknown): error is Error & { details: { message: string } } {
  return error instanceof Error &&
    typeof (error as any).details === 'object' &&
    typeof (error as any).details.message === 'string';
}

server.on('error', (error) => {
  console.error('Server error:', error instanceof Error ? error.message : String(error));
  if (isErrorWithDetails(error)) {
    console.error('Details:', error.details.message);
  }
});

Why any is Problematic

  • Disables all TypeScript checking
  • No autocomplete in IDE
  • Typos caught only at runtime
  • Makes refactoring dangerous
  • Defeats the purpose of TypeScript

When to Use Type Assertions

  • Only after verifying the shape/type at runtime
  • When TypeScript can't infer but you know the type
  • Use as assertions, not angle brackets
  • Document why the assertion is safe