TS-Pattern

The exhaustive Pattern Matching library for TypeScript with smart type inference.

import { match, P } from 'ts-pattern';

type Data =
  | { type: 'text'; content: string }
  | { type: 'img'; src: string };

type Result =
  | { type: 'ok'; data: Data }
  | { type: 'error'; error: Error };

const result: Result = ...;

const html = match(result)
  .with({ type: 'error' }, () =&gt; <p>Oups! An error occured</p>)
  .with({ type: 'ok', data: { type: 'text' } }, (res) =&gt; <p>{res.data.content}</p>)
  .with({ type: 'ok', data: { type: 'img', src: P.select() } }, (src) =&gt; <img src="{src}">)
  .exhaustive();

About

Write better and safer conditions. Pattern matching lets you express complex conditions in a single, compact expression. Your code becomes shorter and more readable. Exhaustiveness checking ensures you haven’t forgotten any possible case.

Animation by @nicoespeon

Features

• Pattern-match on any data structure: nested Objects, Arrays, Tuples, Sets, Maps and all primitive types.
• Typesafe, with helpful type inference.
• Exhaustiveness checking support, enforcing that you are matching every possible case with .exhaustive().
• Use patterns to validate the shape of your data with isMatching.
• Expressive API, with catch-all and type specific wildcards: P._, P.string, P.number, etc.
• Supports predicates, unions, intersections and exclusion patterns for non-trivial cases.
• Supports properties selection, via the P.select(name?) function.
• Tiny bundle footprint (only ~2kB).

What is Pattern Matching?

Pattern Matching is a code-branching technique coming from functional programming languages that's more powerful and often less verbose than imperative alternatives (if/else/switch statements), especially for complex conditions.

Pattern Matching is implemented in Haskell, Rust, Swift, Elixir, and many other languages. There is a tc39 proposal to add Pattern Matching to EcmaScript, but it is still in stage 1 and isn't likely to land before several years. Luckily, pattern matching can be implemented in userland. ts-pattern Provides a typesafe pattern matching implementation that you can start using today.

Read the introduction blog post: Bringing Pattern Matching to TypeScript 🎨 Introducing TS-Pattern

Installation

Via npm

npm install ts-pattern

Via yarn

yarn add ts-pattern

Via pnpm

pnpm add ts-pattern

Via Bun

bun add ts-pattern

Compatibility with different TypeScript versions

TS-Pattern assumes that Strict Mode is enabled in your tsconfig.json file.

• ✅ Full support
• ❌ Not supported

Want to get better at TypeScript?

Check out 👉 Type-Level TypeScript, my online course teaching how to take full advantage of the most advanced features of TypeScript. You will learn everything there is to know to build awesome libraries with great developer experiences and become a real TypeScript expert in the process!

Documentation

• Sandbox examples
• Getting Started
• API Reference
  • match
  • .with
  • .when
  • .returnType
  • .exhaustive
  • .otherwise
  • isMatching
  • Patterns
    • Literals
    • Wildcards
    • Objects
    • Tuples (arrays)
    • Sets
    • Maps
    • P.array patterns
    • P.when patterns
    • P.not patterns
    • P.select patterns
    • P.optional patterns
    • P.instanceOf patterns
    • P.union patterns
    • P.intersection patterns
    • P.string predicates
    • P.number and P.bigint predicates
  • Types
    • P.infer
    • P.Pattern
    • Type inference
• Inspirations

Sandbox examples

• Basic Demo
• React gif fetcher app Demo
• React.useReducer Demo
• Handling untyped API response Demo
• P.when Guard Demo
• P.not Pattern Demo
• P.select Pattern Demo
• P.union Pattern Demo

Getting Started

As an example, let's create a state reducer for a frontend application that fetches some data.

Example: a state reducer with ts-pattern

Our application can be in four different states: idle, loading, success and error. Depending on which state we are in, some events can occur. Here are all the possible types of event our application can respond to: fetch, success, error and cancel.

I use the word event but you can replace it with action if you are used to Redux's terminology.

type State =
  | { status: 'idle' }
  | { status: 'loading'; startTime: number }
  | { status: 'success'; data: string }
  | { status: 'error'; error: Error };

type Event =
  | { type: 'fetch' }
  | { type: 'success'; data: string }
  | { type: 'error'; error: Error }
  | { type: 'cancel' };

Even though our application can handle 4 events, only a subset of these events make sense for each given state. For instance we can only cancel a request if we are currently in the loading state. To avoid unwanted state changes that could lead to bugs, we want our state reducer function to branch on both the state and the event, and return a new state.

This is a case where match really shines. Instead of writing nested switch statements, we can use pattern matching to simultaneously check the state and the event object:

import { match, P } from 'ts-pattern';

const reducer = (state: State, event: Event) =>
  match([state, event])
    .returnType()
    .with(
      [{ status: 'loading' }, { type: 'success' }],
      ([_, event]) => ({ status: 'success', data: event.data })
    )
    .with(
      [{ status: 'loading' }, { type: 'error', error: P.select() }],
      (error) => ({ status: 'error', error })
    )
    .with(
      [{ status: P.not('loading') }, { type: 'fetch' }],
      () => ({ status: 'loading', startTime: Date.now() })
    )
    .with(
      [
        {
          status: 'loading',
          startTime: P.when((t) => t + 2000 < Date.now()),
        },
        { type: 'cancel' },
      ],
      () => ({ status: 'idle' })
    )
    .with(P._, () => state)
    .exhaustive();

There's a lot going on, so let's go through this code bit by bit:

match(value)

match takes a value and returns a builder on which you can add your pattern matching cases.

match([state, event])

It's also possible to specify the input and output type explicitly with match(...), but this is usually unnecessary, as TS-Pattern is able to infer them.

.returnType()

.returnType is an optional method that you can call if you want to force all following code-branches to return a value of a specific type. It takes a single type parameter, provided between ``.

  .returnType()

Here, we use this method to make sure all branches return a valid State object.

.with(pattern, handler)

Then we add a first with clause:

  .with(
    [{ status: 'loading' }, { type: 'success' }],
    ([state, event]) => ({
      // `state` is inferred as { status: 'loading' }
      // `event` is inferred as { type: 'success', data: string }
      status: 'success',
      data: event.data,
    })
  )

The first argument is the pattern: the shape of value you expect for this branch.

The second argument is the handler function: the code branch that will be called if the input value matches the pattern.

The handler function takes the input value as first parameter with its type narrowed down to what the pattern matches.

P.select(name?)

In the second with clause, we use the P.select function:

  .with(
    [
      { status: 'loading' },
      { type: 'error', error: P.select() }
    ],
    (error) => ({ status: 'error', error })
  )

P.select() lets you extract a piece of your input value and inject it into your handler. It is pretty useful when pattern matching on deep data structures because it avoids the hassle of destructuring your input in your handler.

Since we didn't pass any name to P.select(), It will inject the event.error property as first argument to the handler function. Note that you can still access the full input value with its type narrowed by your pattern as second argument of the handler function:

  .with(
    [
      { status: 'loading' },
      { type: 'error', error: P.select() }
    ],
    (error, stateAndEvent) => {
      // error: Error
      // stateAndEvent: [{ status: 'loading' }, { type: 'error', error: Error }]
    }
  )

In a pattern, we can only have a single anonymous selection. If you need to select more properties on your input data structure, you will need to give them names:

.with(
    [
      { status: 'success', data: P.select('prevData') },
      { type: 'error', error: P.select('err') }
    ],
    ({ prevData, err }) => {
      // Do something with (prevData: string) and (err: Error).
    }
  )

Each named selection will be injected inside a selections object, passed as first argument to the handler function. Names can be any strings.

P.not(pattern)

If you need to match on everything but a specific value, you can use a `P.not(