meta-design-expressive-typescript

Expressive TypeScript

Quick Guide: Write code that communicates its intent without requiring the reader to mentally simulate any of its parts. Apply the two-tier pattern: orchestrators at the top that read like pseudocode, pure functions at the bottom that each do one thing. Extract until the code reads like prose. Use utility libraries only when they genuinely improve readability over plain JS.

---

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST structure every non-trivial function as a two-tier orchestrator: guard clauses at the top, named function calls in the middle, assembly at the bottom -- NO inline data transformations in orchestrators)

(You MUST extract any expression that requires mental simulation to understand into a named function or named constant)

(You MUST name functions for WHAT they do, not HOW they do it -- isContentAddition(line) not checkLineStartsWithPlusButNotTriplePlus(line))

(You MUST read the existing code before refactoring -- understand the current structure, then improve it)

(You MUST prefer plain JS methods (.map(), .filter(), .reduce()) over utility libraries when they already read clearly)

</critical_requirements>

---

Auto-detection: orchestrator pattern, two-tier function, extract function, named predicate, named constant, readability refactor, expressive code, function decomposition, pure function extraction, readable TypeScript, guard clause, early return, flatten conditionals, discriminated union, exhaustive switch, as const satisfies, async orchestrator

When to use:

• Writing any function that mixes validation, transformation, and assembly logic
• Refactoring a function where you need to mentally simulate steps to understand the flow
• Naming predicates, constants, or transforms to communicate intent
• Deciding whether to use a utility library function or plain JS
• Decomposing a large function into orchestrator + pure helpers
• Reviewing code and finding blocks that require mental simulation
• Flattening deeply nested if/else blocks into guard clauses
• Writing async functions that orchestrate multiple independent operations
• Modeling state or events with discriminated unions for exhaustive handling