Typescript

# TypeScript

This curated skill mirrors `SKILL.md`. When maintaining it, keep the guidance focused on TypeScript performance, compiler errors, async patterns, type definitions, and module organization.


---
title: Rule Title Here
impact: MEDIUM
impactDescription: Quantified impact (e.g., "2-10× improvement", "200ms savings")
tags: prefix, technique, related-concepts
---

## Rule Title Here

Brief explanation of the rule and why it matters (1-3 sentences). Focus on performance implications.

**Incorrect (description of what's wrong):**

```typescript
// Bad code example here
const badExample = inefficientOperation()
```

**Correct (description of what's right):**

```typescript
// Good code example here
const goodExample = efficientOperation()
```

Reference: [Link to documentation](https://example.com)


{
  "version": "1.1.9",
  "organization": "TypeScript Best Practices",
  "technology": "TypeScript",
  "date": "February 2026",
  "abstract": "Comprehensive performance optimization guide for TypeScript applications, designed for AI agents and LLMs. Contains 45 rules across 8 categories, prioritized by impact from critical (type system performance, compiler configuration) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation. Updated for TypeScript 5.5+ (isolatedDeclarations) and 5.8+ (erasableSyntaxOnly).",
  "references": [
    "https://github.com/microsoft/TypeScript/wiki/Performance",
    "https://www.typescriptlang.org/docs/handbook/",
    "https://v8.dev/blog",
    "https://nodejs.org/en/learn/diagnostics/memory"
  ],
  "category": "Lang"
}


# Sections

This file defines all sections, their ordering, impact levels, and descriptions.
The section ID (in parentheses) is the filename prefix used to group rules.

---

## 1. Type System Performance (type)

**Impact:** CRITICAL
**Description:** Complex types, deep generics, and large unions cause quadratic compilation time. Simplifying type definitions yields the largest compile-time gains.

## 2. Compiler Configuration (tscfg)

**Impact:** CRITICAL
**Description:** Misconfigured tsconfig causes full rebuilds and unnecessary file scanning. Proper configuration reduces compile time by 50-80%.

## 3. Async Patterns (async)

**Impact:** HIGH
**Description:** Sequential awaits create runtime waterfalls. Parallelizing async operations yields 2-10× improvement in I/O-bound code.

## 4. Module Organization (module)

**Impact:** HIGH
**Description:** Barrel files and circular dependencies force excessive module loading. Direct imports reduce bundle size and improve tree-shaking.

## 5. Type Safety Patterns (safety)

**Impact:** MEDIUM-HIGH
**Description:** Type guards, narrowing, and strict mode prevent runtime errors. Proper patterns eliminate defensive runtime checks.

## 6. Memory Management (mem)

**Impact:** MEDIUM
**Description:** Object pooling, WeakMap usage, and closure hygiene reduce GC pressure and memory leaks in long-running applications.

## 7. Runtime Optimization (runtime)

**Impact:** LOW-MEDIUM
**Description:** Loop optimization, property caching, and collection choice improve hot-path performance.

## 8. Advanced Patterns (advanced)

**Impact:** LOW
**Description:** Branded types, variance annotations, and declaration merging for specialized use cases.


---
title: Use Branded Types for Type-Safe IDs
impact: LOW
impactDescription: prevents mixing incompatible ID types
tags: advanced, branded-types, nominal-types, type-safety, ids
---

## Use Branded Types for Type-Safe IDs

TypeScript uses structural typing, so `string` types are interchangeable even when they represent different concepts. Branded types add a unique marker to prevent mixing incompatible values.

**Incorrect (structural typing allows mixing):**

```typescript
type UserId = string
type OrderId = string
type ProductId = string

fun