typescript-type-safety

TypeScript Type Safety

Overview

Zero tolerance for any types. Every any is a runtime bug waiting to happen.

Replace any with proper types using interfaces, unknown with type guards, or generic constraints. Use @ts-expect-error with explanation only when absolutely necessary.

When to Use

Use when you see:

• : any in function parameters or return types
• as any type assertions
• TypeScript errors you're tempted to ignore
• External libraries without proper types
• Catch blocks with implicit any

Don't use for:

• Already properly typed code
• Third-party .d.ts files (contribute upstream instead)

Type Safety Hierarchy

Prefer in this order:

1. Explicit interface/type definition
2. Generic type parameters with constraints
3. Union types
4. unknown (with type guards)
5. never (for impossible states)

Never use: any

Quick Reference

Pattern	Bad	Good
Error handling	catch (error: any)	catch (error) { if (error instanceof Error) ... }
Unknown data	JSON.parse(str) as any	const data = JSON.parse(str); if (isValid(data)) ...
Type assertions	(request as any).user	(request as AuthRequest).user
Double casting	return data as unknown as Type	Align interfaces instead: make types compatible
External libs	const server = fastify() as any	declare module 'fastify' { ... }
Generics	function process(data: any)	function process<T extends Record<string, unknown>>(data: T)

Implementation

Error Handling

// ❌ BAD
try {
  await operation();
} catch (error: any) {
  console.error(error.message);
}

// ✅ GOOD - Use unknown and type guard
try {
  await operation();
} catch (error) {
  if (error instanceof Error) {
    console.error(error.message);
  } else {
    console.error('Unknown error:', String(error));
  }
}

// ✅ BETTER - Helper function
function toError(error: unknown): Error {
  if (error instanceof Error) return error;
  return new Error(String(error));
}

try {
  await operation();
} catch (error) {
  const err = toError(error);
  console.error(err.message);
}