ts-pattern — Exhaustive Pattern Matching for TypeScript

Introduction

ts-pattern brings pattern matching to TypeScript, letting developers replace nested if-else chains and switch statements with declarative match expressions. The library checks at compile time that every possible case is handled, catching missing branches before runtime. It supports matching on objects, arrays, tuples, literals, and custom predicates.

What ts-pattern Does

• Matches values against structural patterns with nested object and array support
• Enforces exhaustiveness checking at the type level to prevent missed cases
• Provides wildcard patterns, guard clauses, and union matching via P helpers
• Narrows TypeScript types automatically inside each branch handler
• Supports chaining with .when(), .with(), .otherwise(), and .exhaustive()

Architecture Overview

ts-pattern uses TypeScript's type inference to track which patterns have been handled. Each .with() call narrows the remaining type, and .exhaustive() ensures the residual type is never. The runtime matching engine walks the pattern tree, comparing shape and value at each level. Pattern helpers like P.string, P.number, and P.array create reusable matchers.

Self-Hosting & Configuration

• Install via npm, yarn, or pnpm with no additional dependencies
• Requires TypeScript 4.5 or later for full type inference
• Works with any bundler; ships ESM and CommonJS formats
• No runtime configuration needed beyond importing match and P
• Integrates with existing TypeScript projects without build changes

Key Features

• Compile-time exhaustiveness guarantees that eliminate runtime surprises
• Deep nested pattern matching on objects, arrays, and tuples
• Built-in pattern helpers for primitives, unions, and optional values
• Automatic type narrowing inside each matched branch
• Zero dependencies and small bundle footprint

Comparison with Similar Tools

• switch/case — no exhaustiveness checking, verbose, and limited to primitives
• fp-ts match — part of a larger FP ecosystem, more ceremony for simple cases
• effect/Match — similar API within the Effect ecosystem, tighter coupling
• purify-ts — ADT matching with Maybe/Either types, narrower focus

FAQ

Q: Does ts-pattern add runtime overhead? A: Minimal. The matching engine is lightweight and patterns compile to simple property checks.

Q: Can I use ts-pattern with JavaScript instead of TypeScript? A: The library works in JavaScript but you lose exhaustiveness checking and type narrowing, which are the main benefits.

Q: How does exhaustiveness checking work? A: After each .with() call, TypeScript narrows the input type. Calling .exhaustive() errors at compile time if the remaining type is not never.

Q: Does it support async handlers? A: Yes. Handler functions can return promises, and the overall match expression will resolve to the awaited type.

Sources

• https://github.com/gvergnaud/ts-pattern
• https://github.com/gvergnaud/ts-pattern#documentation