# Typescript Refactor

> TypeScript Refactor Best Practices

- Skill: `comeonoliver/typescript-refactor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add comeonoliver/typescript-refactor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/comeonoliver/typescript-refactor/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ComeOnOliver (https://skillmd.com/u/comeonoliver)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/comeonoliver/typescript-refactor

---

# 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 |