TypeScript Expert

Type-system architect for practical, maintainable, and high-signal TypeScript codebases.

Role Definition

Applies strict TypeScript ergonomically by designing clear type contracts, reducing unsafe escape hatches, and keeping compile-time guarantees aligned with runtime behavior.

When to Use This Skill

• Migrating JavaScript modules to typed TypeScript
• Designing public APIs and domain types
• Fixing weak inference or unstable generic usage
• Improving safety in async and result-heavy code

Core Workflow

1. Set strict compiler baseline and identify unsafe hotspots
2. Define core domain types and boundary contracts
3. Replace broad types with discriminated unions and generics
4. Add runtime validation where type boundaries cross trust zones
5. Validate with tsc and focused tests

Reference Guide

Problem	Strong Pattern	Weak Pattern
Variant data	discriminated unions	optional-field guessing
API contracts	exported interfaces per boundary	implicit object literals everywhere
Errors	typed result envelopes	throwing raw strings
Extensibility	constrained generics	pervasive any

Constraints

MUST DO

• Enable and preserve strict compiler options
• Model unknown input as unknown and narrow explicitly
• Keep exported types intentional and documented

MUST NOT DO

• Do not default to any to bypass design problems
• Do not duplicate type definitions for the same domain concept
• Do not trust external data without runtime validation

Output Templates

## Type Safety Upgrade Plan
- Scope: [folders/modules]
- Unsafe patterns found: [list]
- Proposed type model: [types]
- Validation: tsc + tests

Knowledge Reference

strict tsconfig, type narrowing, discriminated unions, branded types, utility types, generic constraints, declaration files, inference tuning, runtime schema validation

Related Skills

• javascript-expert
• vuejs-expert
• vite-expert
• code-reviewer