playbooks

home / skills / pproenca / dot-skills / typescript-refactor

typescript-refactor skill

/skills/.experimental/typescript-refactor

This skill guides TypeScript refactoring and modernization to improve type safety, performance, and idiomatic patterns across codebases.

npx playbooks add skill pproenca/dot-skills --skill typescript-refactor

Review the files below or copy the command above to add this skill to your agents.

Files (47)
SKILL.md
7.9 KB
---
name: typescript-refactor
description: TypeScript refactoring and modernization guidelines from a principal specialist perspective. This skill should be used when refactoring, reviewing, or modernizing TypeScript code to ensure type safety, compiler performance, and idiomatic patterns. Triggers on tasks involving TypeScript type architecture, narrowing, generics, error handling, or migration to modern TypeScript features.
---

# TypeScript Refactor Best Practices

Comprehensive TypeScript refactoring and modernization guide designed for AI agents and LLMs. Contains 43 rules across 8 categories, prioritized by impact to guide automated refactoring, code review, and code generation.

## When to Apply

Reference these guidelines when:
- Refactoring TypeScript code for type safety and maintainability
- Designing type architectures (discriminated unions, branded types, generics)
- Narrowing types to eliminate unsafe `as` casts
- Adopting modern TypeScript 4.x-5.x features (`satisfies`, `using`, const type parameters)
- Optimizing compiler performance in large codebases
- Implementing type-safe error handling patterns
- Reviewing code for TypeScript quirks and pitfalls

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Type Architecture | CRITICAL | `arch-` |
| 2 | Type Narrowing & Guards | CRITICAL | `narrow-` |
| 3 | Modern TypeScript | HIGH | `modern-` |
| 4 | Generic Patterns | HIGH | `generic-` |
| 5 | Compiler Performance | MEDIUM-HIGH | `compile-` |
| 6 | Error Safety | MEDIUM | `error-` |
| 7 | Runtime Patterns | MEDIUM | `perf-` |
| 8 | Quirks & Pitfalls | LOW-MEDIUM | `quirk-` |

## Quick Reference

### 1. Type Architecture (CRITICAL)

- [`arch-discriminated-unions`](references/arch-discriminated-unions.md) — Use discriminated unions over string enums for exhaustive pattern matching
- [`arch-branded-types`](references/arch-branded-types.md) — Use branded types for domain identifiers to prevent value mix-ups
- [`arch-satisfies-over-annotation`](references/arch-satisfies-over-annotation.md) — Use `satisfies` for config objects to preserve literal types
- [`arch-interfaces-over-intersections`](references/arch-interfaces-over-intersections.md) — Extend interfaces instead of intersecting types for better error messages
- [`arch-const-assertion`](references/arch-const-assertion.md) — Use `as const` for immutable literal inference
- [`arch-readonly-by-default`](references/arch-readonly-by-default.md) — Default to readonly types for function parameters and return values
- [`arch-avoid-partial-abuse`](references/arch-avoid-partial-abuse.md) — Avoid `Partial<T>` abuse for builder patterns

### 2. Type Narrowing & Guards (CRITICAL)

- [`narrow-custom-type-guards`](references/narrow-custom-type-guards.md) — Write custom type guards instead of type assertions
- [`narrow-assertion-functions`](references/narrow-assertion-functions.md) — Use assertion functions for precondition checks
- [`narrow-exhaustive-switch`](references/narrow-exhaustive-switch.md) — Enforce exhaustive switch with `never`
- [`narrow-in-operator`](references/narrow-in-operator.md) — Narrow with the `in` operator for interface unions
- [`narrow-eliminate-as-casts`](references/narrow-eliminate-as-casts.md) — Eliminate `as` casts with proper narrowing chains
- [`narrow-typeof-chains`](references/narrow-typeof-chains.md) — Use `typeof` narrowing before property access

### 3. Modern TypeScript (HIGH)

- [`modern-using-keyword`](references/modern-using-keyword.md) — Use the `using` keyword for resource cleanup
- [`modern-const-type-parameters`](references/modern-const-type-parameters.md) — Use const type parameters for literal inference
- [`modern-template-literal-types`](references/modern-template-literal-types.md) — Use template literal types for string patterns
- [`modern-noinfer-utility`](references/modern-noinfer-utility.md) — Use `NoInfer` to control type parameter inference
- [`modern-accessor-keyword`](references/modern-accessor-keyword.md) — Use `accessor` for auto-generated getters and setters
- [`modern-verbatim-module-syntax`](references/modern-verbatim-module-syntax.md) — Enable `verbatimModuleSyntax` for explicit import types

### 4. Generic Patterns (HIGH)

- [`generic-infer-over-annotate`](references/generic-infer-over-annotate.md) — Let TypeScript infer instead of explicit annotation
- [`generic-constrain-dont-overconstrain`](references/generic-constrain-dont-overconstrain.md) — Constrain generics minimally
- [`generic-avoid-distributive-surprises`](references/generic-avoid-distributive-surprises.md) — Control distributive conditional types
- [`generic-mapped-type-utilities`](references/generic-mapped-type-utilities.md) — Build custom mapped types for repeated transformations
- [`generic-return-type-inference`](references/generic-return-type-inference.md) — Preserve return type inference in generic functions

### 5. Compiler Performance (MEDIUM-HIGH)

- [`compile-explicit-return-types`](references/compile-explicit-return-types.md) — Add explicit return types to exported functions
- [`compile-avoid-deep-recursion`](references/compile-avoid-deep-recursion.md) — Avoid deeply recursive type definitions
- [`compile-project-references`](references/compile-project-references.md) — Use project references for monorepo builds
- [`compile-base-types-over-unions`](references/compile-base-types-over-unions.md) — Use base types instead of large union types

### 6. Error Safety (MEDIUM)

- [`error-result-type`](references/error-result-type.md) — Use Result types instead of thrown exceptions
- [`error-exhaustive-error-handling`](references/error-exhaustive-error-handling.md) — Use exhaustive checks for typed error variants
- [`error-typed-catch`](references/error-typed-catch.md) — Type catch clause variables as `unknown`
- [`error-never-for-unreachable`](references/error-never-for-unreachable.md) — Use `never` to mark unreachable code paths
- [`error-discriminated-error-unions`](references/error-discriminated-error-unions.md) — Model domain errors as discriminated unions

### 7. Runtime Patterns (MEDIUM)

- [`perf-union-literals-over-enums`](references/perf-union-literals-over-enums.md) — Use union literals instead of enums
- [`perf-avoid-delete-operator`](references/perf-avoid-delete-operator.md) — Avoid the `delete` operator on objects
- [`perf-object-freeze-const`](references/perf-object-freeze-const.md) — Use `Object.freeze` with `as const` for true immutability
- [`perf-object-keys-narrowing`](references/perf-object-keys-narrowing.md) — Avoid `Object.keys` type widening
- [`perf-map-set-over-object`](references/perf-map-set-over-object.md) — Use `Map` and `Set` over plain objects for dynamic collections

### 8. Quirks & Pitfalls (LOW-MEDIUM)

- [`quirk-excess-property-checks`](references/quirk-excess-property-checks.md) — Understand excess property checks on object literals
- [`quirk-empty-object-type`](references/quirk-empty-object-type.md) — Avoid the `{}` type — it means non-nullish
- [`quirk-type-widening-let`](references/quirk-type-widening-let.md) — Prevent type widening with `let` declarations
- [`quirk-variance-annotations`](references/quirk-variance-annotations.md) — Use variance annotations for generic interfaces
- [`quirk-structural-typing-escapes`](references/quirk-structural-typing-escapes.md) — Guard against structural typing escape hatches

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) — Category structure and impact levels
- [Rule template](assets/templates/_template.md) — Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

Overview

This skill provides principal-level TypeScript refactoring and modernization guidance focused on type safety, compiler performance, and idiomatic patterns. It codifies high-impact rules for architecture, narrowing, generics, modern language features, and runtime patterns to guide automated refactors, human reviews, and migrations. Use it as a checklist and decision aid when changing TypeScript code in production systems.

How this skill works

The skill inspects TypeScript tasks and triggers on items related to type architecture, narrowing, generics, error handling, and migrations to modern TypeScript features. It recommends prioritized rules—critical to low-impact—so an agent can apply targeted transformations (e.g., discriminated unions, assertion functions, const type parameters) and avoid common pitfalls. It also suggests compiler-performance optimizations and runtime pattern changes that reduce type-check time and runtime surprises.

When to use it

  • Refactoring modules to improve type safety and maintainability
  • Designing or revising type architectures (unions, branded ids, interfaces)
  • Replacing unsafe casts with narrowing, guards, or assertion functions
  • Migrating code to modern TypeScript features (satisfies, const type params, using)
  • Optimizing compiler performance in large projects or monorepos
  • Implementing typed error handling and exhaustive error variants

Best practices

  • Prefer discriminated unions and interfaces over broad unions or intersections for clearer errors and exhaustive checks
  • Eliminate 'as' casts by adding narrowing steps, custom guards, or assertion functions
  • Use 'satisfies' and 'as const' to preserve literal types without over-annotating
  • Let TypeScript infer generics when safe; constrain generics minimally to avoid overconstraints
  • Add explicit return types for exported functions and use project references to speed large builds
  • Model errors as typed discriminated unions and treat catch values as unknown

Example use cases

  • Convert a set of ad-hoc string enums to discriminated union types for exhaustive switch handling
  • Replace runtime 'instanceof' plus casts with small custom type guards and assertion helpers
  • Migrate configuration objects to use 'satisfies' so caller literals remain narrow
  • Rewrite deep recursive conditional types into simpler base types to reduce type-check time
  • Introduce Result/Ok/Err patterns and typed catch handling to stop untyped error propagation

FAQ

Will these recommendations change runtime behavior?

Most recommendations are type-level-only—they improve compile-time safety and developer ergonomics without altering runtime semantics. A few runtime pattern suggestions (e.g., replacing enums with union literals) may affect emitted code size or initialization behavior and should be validated in CI.

How do I prioritize rules in a large codebase?

Start with CRITICAL categories: Type Architecture and Narrowing. Next apply Modern and Generic patterns that reduce unsafe casts. Then address compiler performance and error safety items. Triage rules by measured build time and the frequency of type-related bugs.