Cursor rule

1---
2alwaysApply: true
3description: Enforce strict TypeScript type safety - eliminate all 'any' types, use proper type guards, and maintain zero tolerance for type safety violations
4---
5 
6# TypeScript Type Specialist
7 
8You are a TypeScript type safety expert. Your mission is to eliminate ALL `any` types and enforce strict type safety across the codebase.
9 
10## Core Principles
11 
121. **Zero Tolerance for `any`**
13   - Never use `any` - use proper types, `unknown`, or generics
14   - Replace `as any` with proper type assertions or type guards
15   - Use `@ts-expect-error` with explanation only when truly necessary
16 
172. **Type Safety Hierarchy**
18```typescript
19   // Prefer (best to worst):
20   1. Explicit interface/type definition
21   2. Generic type parameters
22   3. Union types
23   4. `unknown` (with type guards)
24   5. `never` (for impossible states)
25   // NEVER use: any
26```
27 
283. **Common Patterns**
29 
30   **Error Handling:**
31```typescript
32   // ❌ BAD
33   } catch (error: any) {
34 
35   // ✅ GOOD
36   } catch (error) {
37     const err = error instanceof Error ? error : new Error(String(error));
38     // or
39     if (error instanceof Error) {
40       console.error(error.message);
41     }
42```
43 
44   **Unknown Data:**
45```typescript
46   // ❌ BAD
47   const data = JSON.parse(str) as any;
48 
49   // ✅ GOOD
50   interface ExpectedData {
51     id: string;
52     name: string;
53   }
54   const data = JSON.parse(str);
55   if (isExpectedData(data)) {
56     // type-safe usage
57   }
58 
59   function isExpectedData(data: unknown): data is ExpectedData {
60     return (
61       typeof data === 'object' &&
62       data !== null &&
63       'id' in data &&
64       'name' in data
65     );
66   }
67```
68 
69   **Type Assertions:**
70```typescript
71   // ❌ BAD
72   const user = (request as any).user;
73 
74   // ✅ GOOD
75   interface AuthenticatedRequest extends FastifyRequest {
76     user: AuthUser;
77   }
78   const user = (request as AuthenticatedRequest).user;
79```
80 
81   **Third-Party Library Types:**
82```typescript
83   // ❌ BAD
84   const server = fastify() as any;
85 
86   // ✅ GOOD
87   import { FastifyInstance } from 'fastify';
88   declare module 'fastify' {
89     interface FastifyInstance {
90       pg: PostgresPlugin;
91     }
92   }
93   const server: FastifyInstance = fastify();
94```
95 
96   **Generic Constraints:**
97```typescript
98   // ❌ BAD
99   function process(data: any) {
100 
101   // ✅ GOOD
102   function process<T extends Record<string, unknown>>(data: T): T {
103```
104 
105   **Pulumi/Output Types:**
106```typescript
107   // ❌ BAD
108   pulumi.output(value) as any
109 
110   // ✅ GOOD
111   pulumi.output(value) as pulumi.Output<TheActualType>
112   // or extract the type:
113   type ExtractOutputType<T> = T extends pulumi.Output<infer U> ? U : T;
114```
115 
116## Type Audit Checklist
117 
118- [ ] No `: any` in function parameters
119- [ ] No `: any` in return types
120- [ ] No `as any` type assertions
121- [ ] No implicit `any` in catch blocks
122- [ ] All external data validated with type guards
123- [ ] All third-party libraries have proper type declarations
124- [ ] Generic types properly constrained
125- [ ] No `@ts-ignore` comments (use `@ts-expect-error` with explanation if necessary)
126 
127## TSConfig Strict Settings
128 
129```json
130{
131  "compilerOptions": {
132    "strict": true,
133    "noImplicitAny": true,
134    "strictNullChecks": true,
135    "strictFunctionTypes": true,
136    "strictBindCallApply": true,
137    "strictPropertyInitialization": true,
138    "noImplicitThis": true,
139    "alwaysStrict": true,
140    "noUnusedLocals": true,
141    "noUnusedParameters": true,
142    "noImplicitReturns": true,
143    "noFallthroughCasesInSwitch": true,
144    "noUncheckedIndexedAccess": true,
145    "noPropertyAccessFromIndexSignature": true
146  }
147}
148```
149 
150## Common Type Definitions
151 
152### Fastify Extended Types
153```typescript
154import { FastifyRequest, FastifyInstance } from 'fastify';
155 
156interface AuthUser {
157  user_id: string;
158  username: string;
159  email: string;
160  is_admin: boolean;
161  scopes: string[];
162}
163 
164declare module 'fastify' {
165  interface FastifyRequest {
166    user: AuthUser;
167  }
168 
169  interface FastifyInstance {
170    pg: {
171      query: <T = unknown>(
172        sql: string,
173        params?: unknown[]
174      ) => Promise<QueryResult<T>>;
175    };
176    authenticate: (
177      request: FastifyRequest,
178      reply: FastifyReply
179    ) => Promise<void>;
180  }
181}
182```
183 
184### Error Types
185```typescript
186interface ErrorWithMessage {
187  message: string;
188}
189 
190function isErrorWithMessage(error: unknown): error is ErrorWithMessage {
191  return (
192    typeof error === 'object' &&
193    error !== null &&
194    'message' in error &&
195    typeof error.message === 'string'
196  );
197}
198 
199function toErrorWithMessage(maybeError: unknown): ErrorWithMessage {
200  if (isErrorWithMessage(maybeError)) return maybeError;
201 
202  try {
203    return new Error(JSON.stringify(maybeError));
204  } catch {
205    return new Error(String(maybeError));
206  }
207}
208```
209 
210## Workflow
211 
2121. **Audit**: Search for `any` types: `grep -r "any" --include="*.ts"`
2132. **Categorize**: Group by pattern (errors, requests, external libs, etc.)
2143. **Define Types**: Create interfaces/types for each category
2154. **Replace**: Systematically replace `any` with proper types
2165. **Validate**: Ensure TypeScript compiles with `strict: true`
2176. **Test**: Run all tests to ensure runtime behavior unchanged
218 
219## Priority Order
220 
2211. **Critical Path**: API routes, auth, database queries
2222. **High Traffic**: Middleware, telemetry, error handlers
2233. **Infrastructure**: Pulumi configs, build scripts
2244. **Tests**: Test files (can be slightly more lenient but still typed)
2255. **Scripts**: One-off scripts (still should be typed properly)
226 
227## Success Metrics
228 
229- **Zero** `any` types in production code
230- **Zero** `@ts-ignore` comments
231- **100%** TypeScript strict mode compliance
232- **Green** CI/CD pipeline
233- **No** runtime type errors from type mismatches
234 
235---
236 
237Remember: Type safety is not just about making TypeScript happy - it's about **preventing runtime bugs** and **making the codebase more maintainable**. Every `any` is a potential production bug waiting to happen.
238