typescript

Sub-Skill: TypeScript Best Practices

Purpose: Prevents the TypeScript-specific mistakes LLMs make repeatedly — weak types, unsafe assertions, and patterns that compile but fail at runtime.

Rule classification

• MUST — load-bearing. Violating leaks runtime errors past the type checker. Never break.
• SHOULD — default behavior. Deviation needs a documented reason in the code or PR.
• AVOID — usually wrong; documented exception inline where needed.

Where these rules don't strictly apply: test fixtures, generated types (e.g. from GraphQL codegen, OpenAPI generators, Prisma), declaration files (*.d.ts) for untyped third-party libraries, and migration scripts may legitimately differ. The rules below apply to production application code.

---

Type Safety

1. MUST: Never use any. Use unknown and narrow it. any disables the type checker entirely. unknown forces you to prove the type before use. Exception: third-party libraries without types and explicit dynamic-data boundaries (e.g. JSON parse at the API edge), with a comment explaining why.

   // Wrong
   function parse(data: any) { return data.name; }
   
   // Correct
   function parse(data: unknown): string {
     if (typeof data === 'object' && data !== null && 'name' in data) {
       return String((data as { name: unknown }).name);
     }
     throw new Error('Invalid data shape');
   }
   

2. AVOID: Object or {} as a type. Both accept nearly everything. Use Record<string, unknown> for arbitrary objects or define an explicit interface.

   // Wrong
   function merge(a: {}, b: Object): {} { ... }
   
   // Correct
   function merge<T extends Record<string, unknown>>(a: T, b: Partial<T>): T { ... }
   

3. SHOULD: Use as only when you know more than the compiler — and document why. Prefer type guards or satisfies instead.

   // Wrong — silences the error, hides the bug
   const user = response.data as User;
   
   // Correct — validate first
   function isUser(v: unknown): v is User {
     return typeof v === 'object' && v !== null && 'id' in v && 'email' in v;
   }
   const user = isUser(response.data) ? response.data : null;