ts-pattern
Exhaustive pattern matching for TypeScript. ts-pattern provides a match() function that handles all cases of discriminated unions, union types, and complex data structures with compile-time exhaustiveness checking. The TypeScript compiler guarantees all cases are handled — missing a case is a type error. Replaces verbose switch statements with readable, type-safe pattern matching like Rust's match or Haskell's case expressions.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Local library — no network access. Zero dependencies — minimal supply chain risk. MIT licensed.
⚡ Reliability
Best When
You have discriminated union types in TypeScript and want compile-time guarantees that all cases are handled — especially for complex state management, command handling, or API response processing.
Avoid When
Simple boolean conditions, non-TypeScript code, or use cases where basic switch handles the complexity adequately.
Use Cases
- • Handle all cases of discriminated union types (Redux actions, API response states, event types) with TypeScript compile-time completeness guarantees
- • Replace verbose switch/if-else chains for tagged union handling with readable match() patterns that TypeScript verifies are exhaustive
- • Handle agent tool responses typed as discriminated unions ensuring all success, error, and pending states are explicitly addressed
- • Pattern match on complex nested data structures using ts-pattern's structural matching patterns without custom type guards
- • Implement state machine transitions using match() to exhaustively handle all current states and produce correct next states
Not For
- • Simple single-condition checks — ts-pattern is overkill for basic if/else
- • Teams not using TypeScript — ts-pattern's value is 100% in TypeScript's type system
- • Performance-critical hot paths — match() adds minor function call overhead compared to switch
Interface
Authentication
Local library — no authentication.
Pricing
ts-pattern is MIT open source. Free for personal and commercial use.
Agent Metadata
Known Gotchas
- ⚠ Exhaustive checking requires calling .exhaustive() — using .otherwise(defaultFn) disables exhaustiveness checking and allows unhandled cases
- ⚠ ts-pattern 5.x changed the API from 4.x — P.select(), P.when(), P.array() patterns have different syntax in v5; check migration guide when upgrading
- ⚠ Pattern matching on class instances requires P.instanceOf(ClassName) — structural matching doesn't work for class instances with the same shape
- ⚠ Deep patterns are validated at compile time but matched at runtime — a very deep pattern on a large object has minimal runtime cost but may require careful TypeScript inference for complex union types
- ⚠ TypeScript inference for very complex discriminated unions (10+ members) can slow TypeScript compilation when used with ts-pattern — if tsc becomes slow, simplify union types
- ⚠ P.select() for extracting matched values requires TypeScript 4.1+ for named selections to work with typed extraction — verify TypeScript version compatibility
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for ts-pattern.
Scores are editorial opinions as of 2026-03-06.