Cursor rule

1---
2description: Use when encountering TypeScript any types, type errors, or lax type checking - eliminates type holes and enforces strict type safety through proper interfaces, type guards, and module augmentation
3tags: [typescript, type-safety, best-practices, code-quality]
4---
5 
6# TypeScript Type Safety
7 
8## Overview
9 
10**Zero tolerance for `any` types.** Every `any` is a runtime bug waiting to happen.
11 
12Replace `any` with proper types using interfaces, `unknown` with type guards, or generic constraints. Use `@ts-expect-error` with explanation only when absolutely necessary.
13 
14## When to Use
15 
16**Use when you see:**
17- `: any` in function parameters or return types
18- `as any` type assertions
19- TypeScript errors you're tempted to ignore
20- External libraries without proper types
21- Catch blocks with implicit `any`
22 
23**Don't use for:**
24- Already properly typed code
25- Third-party `.d.ts` files (contribute upstream instead)
26 
27## Type Safety Hierarchy
28 
29**Prefer in this order:**
301. Explicit interface/type definition
312. Generic type parameters with constraints
323. Union types
334. `unknown` (with type guards)
345. `never` (for impossible states)
35 
36**Never use:** `any`
37 
38## Quick Reference
39 
40| Pattern | Bad | Good |
41|---------|-----|------|
42| **Error handling** | `catch (error: any)` | `catch (error) { if (error instanceof Error) ... }` |
43| **Unknown data** | `JSON.parse(str) as any` | `const data = JSON.parse(str); if (isValid(data)) ...` |
44| **Type assertions** | `(request as any).user` | `(request as AuthRequest).user` |
45| **Double casting** | `return data as unknown as Type` | Align interfaces instead: make types compatible |
46| **External libs** | `const server = fastify() as any` | `declare module 'fastify' { ... }` |
47| **Generics** | `function process(data: any)` | `function process<T extends Record<string, unknown>>(data: T)` |
48 
49## Implementation
50 
51### Error Handling
52 
53```typescript
54// ❌ BAD
55try {
56  await operation();
57} catch (error: any) {
58  console.error(error.message);
59}
60 
61// ✅ GOOD - Use unknown and type guard
62try {
63  await operation();
64} catch (error) {
65  if (error instanceof Error) {
66    console.error(error.message);
67  } else {
68    console.error('Unknown error:', String(error));
69  }
70}
71 
72// ✅ BETTER - Helper function
73function toError(error: unknown): Error {
74  if (error instanceof Error) return error;
75  return new Error(String(error));
76}
77 
78try {
79  await operation();
80} catch (error) {
81  const err = toError(error);
82  console.error(err.message);
83}
84```
85 
86### Unknown Data Validation
87 
88```typescript
89// ❌ BAD
90const data = await response.json() as any;
91console.log(data.user.name);
92 
93// ✅ GOOD - Type guard
94interface UserResponse {
95  user: {
96    name: string;
97    email: string;
98  };
99}
100 
101function isUserResponse(data: unknown): data is UserResponse {
102  return (
103    typeof data === 'object' &&
104    data !== null &&
105    'user' in data &&
106    typeof data.user === 'object' &&
107    data.user !== null &&
108    'name' in data.user &&
109    typeof data.user.name === 'string'
110  );
111}
112 
113const data = await response.json();
114if (isUserResponse(data)) {
115  console.log(data.user.name); // Type-safe
116}
117```
118 
119### Module Augmentation
120 
121```typescript
122// ❌ BAD
123const user = (request as any).user;
124const db = (server as any).pg;
125 
126// ✅ GOOD - Augment third-party types
127import { FastifyRequest, FastifyInstance } from 'fastify';
128 
129interface AuthUser {
130  user_id: string;
131  username: string;
132  email: string;
133}
134 
135declare module 'fastify' {
136  interface FastifyRequest {
137    user?: AuthUser;
138  }
139 
140  interface FastifyInstance {
141    pg: PostgresPlugin;
142  }
143}
144 
145// Now type-safe everywhere
146const user = request.user; // AuthUser | undefined
147const db = server.pg;      // PostgresPlugin
148```
149 
150### Generic Constraints
151 
152```typescript
153// ❌ BAD
154function merge(a: any, b: any): any {
155  return { ...a, ...b };
156}
157 
158// ✅ GOOD - Constrained generic
159function merge<
160  T extends Record<string, unknown>,
161  U extends Record<string, unknown>
162>(a: T, b: U): T & U {
163  return { ...a, ...b };
164}
165```
166 
167### Type Alignment (Avoid Double Casts)
168 
169```typescript
170// ❌ BAD - Double cast indicates misaligned types
171interface SearchPackage {
172  id: string;
173  type: string;  // Too loose
174}
175 
176interface RegistryPackage {
177  id: string;
178  type: PackageType;  // Specific enum
179}
180 
181return data.packages as unknown as RegistryPackage[];  // Hiding incompatibility
182 
183// ✅ GOOD - Align types from the source
184interface SearchPackage {
185  id: string;
186  type: PackageType;  // Use same specific type
187}
188 
189interface RegistryPackage {
190  id: string;
191  type: PackageType;  // Now compatible
192}
193 
194return data.packages;  // No cast needed - types match
195```
196 
197**Rule:** If you need `as unknown as Type`, your interfaces are misaligned. Fix the root cause, don't hide it with double casts.
198 
199## Common Mistakes
200 
201| Mistake | Why It Fails | Fix |
202|---------|--------------|-----|
203| Using `any` for third-party libs | Loses all type safety | Use module augmentation or `@types/*` package |
204| `as any` for complex types | Hides real type errors | Create proper interface or use `unknown` |
205| `as unknown as Type` double casts | Misaligned interfaces | Align types at source - same enums/unions |
206| Skipping catch block types | Unsafe error access | Use `unknown` with type guards or toError helper |
207| Generic functions without constraints | Allows invalid operations | Add `extends` constraint |
208| Ignoring `ts-ignore` accumulation | Tech debt compounds | Fix root cause, use `@ts-expect-error` with comment |
209 
210## TSConfig Strict Settings
211 
212Enable all strict options for maximum type safety:
213 
214```json
215{
216  "compilerOptions": {
217    "strict": true,
218    "noImplicitAny": true,
219    "strictNullChecks": true,
220    "strictFunctionTypes": true,
221    "strictBindCallApply": true,
222    "strictPropertyInitialization": true,
223    "noImplicitThis": true,
224    "noUnusedLocals": true,
225    "noUnusedParameters": true,
226    "noImplicitReturns": true,
227    "noFallthroughCasesInSwitch": true
228  }
229}
230```
231 
232## Type Audit Workflow
233 
2341. **Find**: `grep -r ": any\|as any" --include="*.ts" src/`
2352. **Categorize**: Group by pattern (errors, requests, external libs)
2363. **Define**: Create interfaces/types for each category
2374. **Replace**: Systematic replacement with proper types
2385. **Validate**: `npm run build` must succeed
2396. **Test**: All tests must pass
240 
241## Real-World Impact
242 
243**Before type safety:**
244- Runtime errors from undefined properties
245- Silent failures from type mismatches
246- Hours debugging production issues
247- Difficult refactoring
248 
249**After type safety:**
250- Errors caught at compile time
251- IntelliSense shows all available properties
252- Confident refactoring with compiler help
253- Self-documenting code
254 
255---
256 
257**Remember:** Type safety isn't about making TypeScript happy - it's about preventing runtime bugs. Every `any` you eliminate is a production bug you prevent.
258