Typescript Refactor

# TypeScript 6.0 / TSX (React 19)

**Version 1.2.0**  
TypeScript Principal Specialist  
May 2026

---

## Abstract

Comprehensive TypeScript and TSX refactoring and modernization guide designed for AI agents and LLMs. Contains 47 rules across 9 categories, prioritized by impact from critical (type architecture, narrowing) to incremental (quirks and pitfalls). Each rule includes a detailed explanation, a production-realistic example, and an authoritative reference. Current to TypeScript 6.0 and React 19: covers modern TypeScript features (satisfies, using, const type parameters, inferred type predicates, isolatedDeclarations, erasable syntax, with import attributes), React/TSX component and hook typing (ref-as-prop, ComponentProps, discriminated props, synthetic events), compiler performance, and type-safe error handling.

---

## Table of Contents

1. [Type Architecture](references/_sections.md#1-type-architecture) — **CRITICAL**
   - 1.1 [Avoid Partial Type Abuse for Builder Patterns](references/arch-avoid-partial-abuse.md) — HIGH (prevents accessing properties that were never set)
   - 1.2 [Default to Readonly Types](references/arch-readonly-by-default.md) — HIGH (prevents accidental mutation, catches side-effect bugs at compile time)
   - 1.3 [Extend Interfaces Instead of Intersecting Types](references/arch-interfaces-over-intersections.md) — CRITICAL (2-3× faster type-checking, detects property conflicts)
   - 1.4 [Use as const for Immutable Literal Inference](references/arch-const-assertion.md) — HIGH (prevents type widening, enables literal-based narrowing)
   - 1.5 [Use Branded Types for Domain Identifiers](references/arch-branded-types.md) — CRITICAL (prevents cross-domain ID mix-ups at compile time)
   - 1.6 [Use Discriminated Unions Over String Enums](references/arch-discriminated-unions.md) — CRITICAL (eliminates entire classes of invalid state bugs)
   - 1.7 [Use satisfies for Config Objects Instead of Type Annotations](references/arch-satisfies-over-annotation.md) — CRITICAL (preserves literal types while validating structure)
2. [Type Narrowing & Guards](references/_sections.md#2-type-narrowing-&-guards) — **CRITICAL**
   - 2.1 [Eliminate as Casts with Proper Narrowing Chains](references/narrow-eliminate-as-casts.md) — HIGH (removes 80-90% of type assertions through control flow)
   - 2.2 [Enforce Exhaustive Switch with never](references/narrow-exhaustive-switch.md) — CRITICAL (prevents silent fallthrough when union members expand)
   - 2.3 [Narrow with the in Operator for Interface Unions](references/narrow-in-operator.md) — HIGH (eliminates as casts with 1-line property checks)
   - 2.4 [Use Assertion Functions for Precondition Checks](references/narrow-assertion-functions.md) — CRITICAL (narrows types while validating invariants in a single call)
   - 2.5 [Write Custom Type Guards Instead of Type Assertions](references/narrow-custom-type-guards.md) — CRITICAL (eliminates unsafe as casts with runtime-verified narrowing)
3. [Modern TypeScript](references/_sections.md#3-modern-typescript) — **HIGH**
   - 3.1 [Enable verbatimModuleSyntax for Explicit Import Types](references/modern-verbatim-module-syntax.md) — MEDIUM (prevents runtime import of type-only modules)
   - 3.2 [Prefer Erasable Syntax Over Enums and Namespaces](references/modern-erasable-syntax.md) — HIGH (keeps code runnable under Node.js type-stripping)
   - 3.3 [Use Const Type Parameters for Literal Inference](references/modern-const-type-parameters.md) — HIGH (eliminates as const at call sites)
   - 3.4 [Use NoInfer to Control Type Parameter Inference](references/modern-noinfer-utility.md) — MEDIUM-HIGH (prevents incorrect inference from secondary parameters)
   - 3.5 [Use Template Literal Types for String Patterns](references/modern-template-literal-types.md) — MEDIUM-HIGH (eliminates invalid string formats at compile time)
   - 3.6 [Use the using Keyword for Resource Cleanup](references/modern-using-keyword.md) — HIGH (prevents resource leaks by