Master TypeScript for Robust Code

Provides deep, practical TypeScript expertise with disciplined invocation and validation workflows. On invocation it first checks whether the problem needs a more specialized subagent - deep bundler internals (typescript-build-expert), complex ESM/CJS migration or circular-dependency analysis (typescript-module-expert), or type-performance profiling and compiler internals (typescript-type-expert) - and stops with a recommendation rather than proceeding itself. Otherwise it analyzes the project (preferring Read/Grep/Glob over shell, falling back to npx tsc --version, package.json tooling detection, and monorepo detection via pnpm-workspace.yaml/lerna.json/nx.json/turbo.json), matches the existing import style and baseUrl/paths configuration, then validates changes with one-shot commands - typecheck, then tests, then build only if config or outputs are affected - explicitly avoiding watch/serve processes.

Type-level programming guidance covers branded/nominal types (type Brand<K, T> = K & { __brand: T }) to prevent primitive obsession at domain and API boundaries; recursive conditional types (DeepReadonly<T>) and template-literal-type event systems, watching for type-instantiation-depth errors past roughly 10 recursion levels; and inference techniques - satisfies (TS 5.0+) to validate constraints while preserving literal types, and as const assertions for maximum literal inference. Performance guidance diagnoses slow type-checking with tsc --extendedDiagnostics --incremental false, fixes "Type instantiation is excessively deep" by replacing intersections with interfaces, splitting unions over 100 members, and breaking recursion with type aliases, and speeds builds with skipLibCheck, incremental plus a .tsbuildinfo cache, precise include/exclude, and composite project references in monorepos.

Real-world error patterns each carry a fix priority: "The inferred type of X cannot be named" (export the type, use ReturnType<typeof fn>, or break circular deps with type-only imports); missing type declarations (ambient .d.ts module declarations); "Excessive stack depth comparing types" (limit recursion, prefer interface extends over intersection, simplify generic constraints); "Cannot find module" despite the file existing (check moduleResolution against the bundler, verify baseUrl/paths, check workspace protocol in monorepos, clear cache); and TypeScript path mappings not resolving at runtime (ts-node -r tsconfig-paths/register, an ESM loader, or pre-compiled paths in production).

Migration guidance gives an incremental JS-to-TS path (enable allowJs/checkJs, rename files gradually, type file by file, enable strict-mode features one at a time, optionally ts-migrate and typesync) and a tool-migration table (ESLint+Prettier to Biome for speed, low effort; TSC-for-linting to type-check-only for 100+ files, medium effort; Lerna to Nx/Turborepo for caching, high effort; CJS to ESM on Node 18+, high/variable effort). Monorepo guidance picks Turborepo for simple setups under 20 packages needing speed, Nx for complex dependencies, visualization needs, or over 50 packages. Modern-tooling guidance picks Biome over ESLint when speed and a single lint-plus-format tool matter and type-aware linting isn't yet needed, and Vitest's expectTypeOf for type testing when publishing libraries or working with complex generics. Debugging guidance covers CLI tools - tsx or ts-node with --inspect/--inspect-brk for stepping through TypeScript files directly, tsc --traceResolution for module-resolution issues, tsc --generateTrace for type-checking performance traces, and node --max-old-space-size for out-of-memory type-checking - plus a custom error-class pattern that extends Error, carries a code and statusCode, and calls Error.captureStackTrace to preserve the stack.

Use it for type-level programming, performance diagnosis, real-world TypeScript error resolution, JS-to-TS migration, monorepo tooling decisions, or code review against its six-category checklist (type safety, TypeScript best practices, performance, module system, error handling, and code organization).

Do NOT use it for deep bundler-internals questions, complex ESM/CJS or circular-dependency migration, or compiler-internals performance profiling - it explicitly redirects those to the specialized build/module/type subagents.

Validation always runs one-shot: typecheck, then tests, then build only if config- or output-affecting; watch/serve processes are avoided. A strict-by-default compilerOptions block:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "exactOptionalPropertyTypes": true,
    "noPropertyAccessFromIndexSignature": true
  }
}

An ESM-first setup sets "type": "module", uses .mts where needed, and moduleResolution: "bundler".

Hands off to typescript-build-expert, typescript-module-expert, and typescript-type-expert for out-of-scope specialization; references TypeScript Wiki Performance docs, Type Challenges, Biome, TypeStat, ts-migrate, and Vitest/tsd type-testing documentation.

Developers needing expert-level TypeScript help - type-level programming, compiler performance, real-world error resolution, JS-to-TS migration, or monorepo and tooling decisions - with a built-in checklist for reviewing type safety, module hygiene, and error handling.