Sub-Skill: TypeScript Best Practices

<!-- target: ~2500 tokens (real tiktoken count) | 17 rules with severity classification -->

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');
   }

1. 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 { ... }

1. 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;

1. SHOULD: Mark immutable data `readonly`. Prevents accidental mutation and communicates intent.

   // Avoid
   function process(ids: string[]) { ids.push('extra'); }

   // Prefer
   function process(ids: readonly string[]) { /* ids.push() is a compile error */ }

1. MUST: Enable `strictNullChecks` and handle every `T | undefined`. Optional chaining ?. returns undefined — always handle that branch.

   // Wrong
   const name = user?.profile.name.toUpperCase(); // crashes if name is undefined

   // Correct
   const name = user?.profile.name?.toUpperCase() ?? 'Anonymous';

1. SHOULD: Use branded types for IDs. Prevents passing a UserId where an OrderId is expected — both are string at runtime.

   type UserId = string & { readonly _brand: 'UserId' };
   type OrderId = string & { readonly _brand: 'OrderId' };

   function createUserId(raw: string): UserId { return raw as UserId; }

   function getUser(id: UserId): User { ... }
   // getUser(orderId) → compile error

Patterns

1. SHOULD: Use discriminated unions for state, not optional fields. Optional fields force you to reason about all combinations. A discriminated union makes illegal states unrepresentable.

   // Avoid — 8 possible combinations, most invalid
   type Request = { loading?: boolean; data?: User; error?: Error };

   // Prefer — exactly 3 valid states
   type Request =
     | { status: 'idle' }
     | { status: 'loading' }
     | { status: 'success'; data: User }
     | { status: 'error'; error: Error };

1. SHOULD: Use `satisfies` to validate shape without widening the type. as const preserves literals; satisfies validates against an interface without losing them.

   const config = {
     host: 'localhost',
     port: 5432,
   } satisfies DatabaseConfig;
   // config.port is still typed as 5432, not number

1. SHOULD: Use `const` objects instead of `enum`. Enums emit runtime code, have surprising reverse-mapping behavior, and are not idiomatic TypeScript.

   // Avoid
   enum Direction { Up, Down, Left, Right }

   // Prefer
   const Direction = { Up: 'Up', Down: 'Down', Left: 'Left', Right: 'Right' } as const;
   type Direction = typeof Direction[keyof typeof Direction];

1. AVOID: Barrel `index.ts` re-exports in large modules. They cause circular dependency chains that are hard to debug. Export directly from source files or use explicit named re-exports only.

    // Wrong — index.ts re-exports everything, A imports B through index, B imports A through index
    export * from './userService';
    export * from './orderService';

    // Correct — import directly
    import { getUser } from './services/userService';

Error Handling

1. MUST: Type your thrown errors explicitly. catch (e) gives you unknown in strict mode. Narrow before accessing properties.

    try {
      await fetchUser(id);
    } catch (e) {
      // Wrong: e.message — e is unknown
      // Correct:
      const message = e instanceof Error ? e.message : String(e);
      logger.error('fetchUser failed', { message, id });
    }

1. SHOULD: Use `Result` types for expected failures instead of throwing. Throwing for control flow forces callers to know which functions throw and what.

    type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };

    function parseConfig(raw: string): Result<Config> {
      try {
        return { ok: true, value: JSON.parse(raw) };
      } catch (e) {
        return { ok: false, error: e instanceof Error ? e : new Error(String(e)) };
      }
    }

Performance

1. MUST: Use `Promise.all` for independent async operations, not sequential `await`. Sequential awaits multiply latency.

    // Wrong — 300ms total if each takes 100ms
    const user = await getUser(id);
    const orders = await getOrders(id);
    const prefs = await getPrefs(id);

    // Correct — 100ms total
    const [user, orders, prefs] = await Promise.all([
      getUser(id),
      getOrders(id),
      getPrefs(id),
    ]);

1. SHOULD: Use `Promise.allSettled` when partial failure is acceptable. Promise.all rejects on the first failure. allSettled collects all results.

    const results = await Promise.allSettled(ids.map(fetchItem));
    const succeeded = results
      .filter((r): r is PromiseFulfilledResult<Item> => r.status === 'fulfilled')
      .map(r => r.value);

Testing

1. MUST: Type test helpers and mocks — never use `as any` to silence mock errors. Untyped mocks let type errors hide until runtime. Exception: prototyping spikes that are explicitly thrown away before merge.

    // Wrong
    const mockUser = { id: '1' } as any;

    // Correct
    const mockUser: User = { id: createUserId('1'), email: '[email protected]', name: 'Alice' };

1. SHOULD: Test the discriminated union branches explicitly. Each status variant is a separate code path. One test per branch minimum.

    it('renders error state', () => {
      const state: Request = { status: 'error', error: new Error('timeout') };
      render(<RequestView state={state} />);
      expect(screen.getByRole('alert')).toHaveTextContent('timeout');
    });

1. SHOULD: Use `expectTypeOf` or `assertType` for type-level tests. Runtime tests cannot catch type regressions.

    import { expectTypeOf } from 'vitest';
    expectTypeOf(createUserId('x')).toEqualTypeOf<UserId>();

Why This Sub-Skill Earns Stars

These rules target the gap between "TypeScript that compiles" and "TypeScript that is safe". LLMs default to any, skip discriminated unions, and reach for as assertions because they are the path of least resistance. Each rule here closes a specific escape hatch that lets type errors reach production. The MUST/SHOULD/AVOID classification means safety-critical rules are strict and stylistic rules respect context.