mk:typescript

<!-- Improvements over source skills:

• Split from 361-line monolith to SKILL.md + references/ (Phase 1: CLASS A)
• Framework-agnostic (removed React-specific patterns from frontend-development)
• Integrated with security-rules.md (no any types already enforced)
• Added workflow phase anchoring (Phase 3 Build)

-->

TypeScript Expert

Strict TypeScript patterns for type safety, null handling, and modern best practices.

When to Use

Auto-activate on: .ts, .tsx, .js, .jsx files, type errors, ESLint issues, "fix types", "add types", "TypeScript help"

Explicit: /mk:typescript [concern]

Do NOT invoke for: Vue-specific patterns (use mk:vue), visual design (use mk:frontend-design)

Workflow Integration

Operates in Phase 3 (Build GREEN). Output supports the developer agent.

Process

1. Detect concern — type error? new code? refactor? ESLint config?
2. Load relevant reference — strict-null, type-safety, utility-types, or eslint
3. Apply patterns — implement using strict TS patterns from references
4. Verify — npx tsc --noEmit must pass with zero errors

Core Rules (always apply)

• NEVER use any — use unknown + type guards (security-rules.md)
• NEVER use type assertion — use unknown + type guards (security-rules.md)
• NEVER use implicit truthiness for null checks — use explicit === null || === undefined
• ALWAYS use strict TypeScript config: strict: true, noUncheckedIndexedAccess: true
• ALWAYS use type imports: import type { X } from 'y'
• PREFER named exports over default exports
• PREFER discriminated unions over type assertions

Anti-Patterns

| Don't | Do Instead | | ----------------------------- | -------------------------------------------- | | as any or as unknown as X | Proper type narrowing with guards | | if (value) for null check | if (value !== null && value !== undefined) | | export default | export const X / export function X | | Object type | Record<string, unknown> | | Implicit return types | Explicit return type annotations | | enum (runtime overhead) | as const satisfies or union types |

Output Format

## TypeScript: {concern}

**Files:** {list of .ts/.tsx files modified}
**Config:** {tsconfig changes if any}

### Changes Applied
{numbered list of type improvements}

### Verification
{tsc --noEmit output — must show 0 errors}

References

| Reference | When to load | Content | | --------------------------------------------------------- | ---------------- | --------------------------------------------------------------- | | [strict-patterns.md](./references/strict-patterns.md) | Type safety work | Null handling, discriminated unions, type guards, utility types | | [review-checklist.md](./references/review-checklist.md) | When reviewing TypeScript code | Prioritized checklist: CRITICAL (security), HIGH (type safety, async, errors), MEDIUM (React, perf) |

Failure Handling

| Failure | Recovery | | ---------------------------------- | ---------------------------------------------------------- | | tsc --noEmit fails after changes | Fix errors before proceeding — never ship with type errors | | No tsconfig.json found | Suggest creating one with strict config | | Third-party types missing | npm install @types/{package} |

Gotchas

• as cast silences narrowing errors and hides real bugs — value as User tells TS to trust you, not validate; a malformed API response passes the cast and crashes at runtime; use a type guard or Zod parse at the boundary instead.
• moduleResolution: "bundler" breaks import type in non-bundler contexts — tsconfig moduleResolution: bundler (Vite/esbuild default) allows extensionless imports that Node.js --esm rejects at runtime; flip to nodenext for backend code or keep dual configs per target.
• noUncheckedIndexedAccess: true makes every array index T | undefined — enabling this flag (required by strict config) means arr[0] is string | undefined not string; code that was type-correct before will error until every indexed access is null-guarded.
• Declaration merging in ambient .d.ts files silently adds properties to global types — a declare module 'express' block in any .d.ts in the project augments Express's types globally; two libraries doing this with conflicting shapes cause TS2300 duplicate identifier errors that appear far from the source.
• Template literal types create unique brands that break assignability — type UserId = \user_\${string}\` is not assignable from string; passing a plain string where UserId` is expected fails even though values look identical at runtime; always brand at the input boundary with a parse function.
• enum generates runtime JS objects, causing tree-shaking failures — enums are not erased; a const enum inside a library published as .js is inlined at compile time but not consumable by projects that don't re-compile the source; use as const satisfies patterns for exported enums.