ts-pattern

ts-pattern brings exhaustive, type-safe pattern matching to TypeScript, a feature borrowed from languages like Rust, OCaml, and Haskell. Its match() API lets developers replace deeply nested if/else and switch statements with declarative pattern-matching expressions that TypeScript’s type checker can verify for exhaustiveness.

The library provides selectors like P.string, P.number, P.array(), P.union(), and P.when() for building complex match patterns, and narrows types automatically within each matched branch, catching unhandled cases at compile time via .exhaustive().

What You Get

• A match() function with a fluent .with()/.exhaustive()/.otherwise() API for building match expressions
• A rich pattern selector library (P.string, P.number, P.array, P.union, P.when, P.instanceOf, etc.)
• Compile-time exhaustiveness checking that fails to build if a case is unhandled
• Automatic type narrowing within each matched branch based on the pattern shape
• Support for matching discriminated unions, tuples, nested objects, and arrays

Common Use Cases

• Replacing deeply nested if/else or switch statements with declarative pattern matching
• Exhaustively handling all variants of a discriminated union (e.g. a state machine or Redux action type)
• Matching and destructuring complex nested API response shapes with type-safe narrowing
• Implementing type-safe reducers or event handlers where every case must be explicitly covered

Under The Hood

Architecture - The library’s core is the match() entry point (src/index.ts) combined with a pattern-building DSL exposed as P (patterns module), which constructs a pattern tree matched against the input value at runtime while TypeScript’s conditional types compute the narrowed branch type at compile time; the .exhaustive() terminal method triggers a compile-time check that all union variants were handled. Tech Stack - Pure TypeScript with zero runtime dependencies, built with a dual ESM/CJS output (dist/index.js and dist/index.cjs) and published to both npm and JSR; benchmarks live in a dedicated benchmarks/ directory to track match performance. Code Quality - The tests/ directory contains around 50 TypeScript test files covering exhaustiveness checking, deep pattern nesting, and type-inference edge cases, run via Jest; docs/ contains a documentation site source alongside examples/ demonstrating real-world matching scenarios. API Design - The fluent match(value).with(pattern, handler).exhaustive() chain reads close to native pattern-matching syntax in ML-family languages, and the type system does the heavy lifting so incorrect handlers are caught at compile time rather than requiring manual runtime checks — a deliberate design choice that trades a small amount of match() call overhead for strong compile-time guarantees.