Technical Documentation: gvergnaud/ts-pattern

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

TS-Pattern

tsx

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' }, () => <p>Oups! An error occured</p>)
  .with({ type: 'ok', data: { type: 'text' } }, (res) => <p>{res.data.content}</p>)
  .with({ type: 'ok', data: { type: 'img', src: P.select() } }, (src) => <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.

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 Python, Rust, Swift, Elixir, Haskell 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

You can also use your favorite package manager:

pnpm add ts-pattern
# OR
yarn add ts-pattern
# OR
bun add ts-pattern
# OR
npx jsr add @gabriel/ts-pattern

Want to become a TypeScript Expert?

Check out 👉 Type-Level TypeScript, an online course teaching you how to unleash the full potential of TypeScript's Turing-complete type system. You already know how to code, and types are simply another programming language to master. This course bridges the gap, helping you apply your existing programming knowledge to TypeScript's type system, so you never again struggle with type errors or feel unable to type complex generic code correctly!

Sandbox examples

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<State>()
    .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 <AngleBrackets>.

.returnType<State>()

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() pattern. it's a function taking a pattern and returning its opposite:

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

`P.when()` and guard functions

Sometimes, we need to make sure our input value respects a condition that can't be expressed by a pattern. For example, imagine you need to check that a number is positive. In these cases, we can use guard functions: functions taking a value and returning a boolean.

With TS-Pattern, there are two ways to use a guard function:

use P.when(<guard function>) inside one of your patterns
pass it as second parameter to .with(...)

using P.when(predicate)

.with(
    [
      {
        status: 'loading',
        startTime: P.when((t) => t + 2000 < Date.now()),
      },
      { type: 'cancel' },
    ],
    () => ({ status: 'idle' })
  )

Passing a guard function to `.with(...)`

.with optionally accepts a guard function as second parameter, between
the pattern and the handler callback:

.with(
    [{ status: 'loading' }, { type: 'cancel' }],
    ([state, event]) => state.startTime + 2000 < Date.now(),
    () => ({ status: 'idle' })
  )

This pattern will only match if the guard function returns true.

the `P._` wildcard

P._ will match any value. You can use it either at the top level, or within another pattern.

.with(P._, () => state)

  // You could also use it inside another pattern:
  .with([P._, P._], () => state)

  // at any level:
  .with([P._, { type: P._ }], () => state)

.exhaustive(), .otherwise() and .run()

.exhaustive();

.exhaustive() executes the pattern matching expression, and returns the result. It also enables exhaustiveness checking, making sure we don't forget any possible case in our input value. This extra type safety is very nice because forgetting a case is an easy mistake to make, especially in an evolving code-base.

Note that exhaustive pattern matching is optional. It comes with the trade-off of having slightly longer compilation times because the type checker has more work to do.

Alternatively, you can use .otherwise(), which takes an handler function returning a default value. .otherwise(handler) is equivalent to .with(P._, handler).exhaustive().

.otherwise(() => state);

Matching several patterns

As you may know, switch statements allow handling several cases with
the same code block:

switch (type) {
  case 'text':
  case 'span':
  case 'p':
    return 'text';

  case 'btn':
  case 'button':
    return 'button';
}

Similarly, ts-pattern lets you pass several patterns to .with() and if
one of these patterns matches your input, the handler function will be called:

const sanitize = (name: string) =>
  match(name)
    .with('text', 'span', 'p', () => 'text')
    .with('btn', 'button', () => 'button')
    .otherwise(() => name);

sanitize('span'); // 'text'
sanitize('p'); // 'text'
sanitize('button'); // 'button'

As you might expect, this also works with more complex patterns than strings and exhaustiveness checking works as well.

API Reference

`match`

match(value);

Create a Match object on which you can later call .with, .when, .otherwise and .run.

Signature

function match<TInput, TOutput>(input: TInput): Match<TInput, TOutput>;

Arguments

input
- Required
- the input value your patterns will be tested against.

`.with`

match(...)
  .with(pattern, [...patterns], handler)

Signature

function with(
  pattern: Pattern<TInput>,
  handler: (selections: Selections<TInput>, value: TInput) => TOutput
): Match<TInput, TOutput>;

// Overload for multiple patterns
function with(
  pattern1: Pattern<TInput>,
  ...patterns: Pattern<TInput>[],
  // no selection object is provided when using multiple patterns
  handler: (value: TInput) => TOutput
): Match<TInput, TOutput>;

// Overload for guard functions
function with(
  pattern: Pattern<TInput>,
  when: (value: TInput) => unknown,
  handler: (
    selection: Selection<TInput>,
    value: TInput
  ) => TOutput
): Match<TInput, TOutput>;

Arguments

pattern: Pattern<TInput>
- Required
- The pattern your input must match for the handler to be called.
- See all valid patterns below
- If you provide several patterns before providing the handler, the with clause will match if one of the patterns matches.
when: (value: TInput) => unknown
- Optional
- Additional condition the input must satisfy for the handler to be called.
- The input will match if your guard function returns a truthy value.
- TInput might be narrowed to a more precise type using the pattern.
handler: (selections: Selections<TInput>, value: TInput) => TOutput
- Required
- Function called when the match conditions are satisfied.
- All handlers on a single match case must return values of the same type, TOutput.
- selections is an object of properties selected from the input with the select function.
- TInput might be narrowed to a more precise type using the pattern.

`.when`

match(...)
  .when(predicate, handler)

Signature

function when(
  predicate: (value: TInput) => unknown,
  handler: (value: TInput) => TOutput
): Match<TInput, TOutput>;

Arguments

predicate: (value: TInput) => unknown
- Required
- Condition the input must satisfy for the handler to be called.
handler: (value: TInput) => TOutput
- Required
- Function called when the predicate condition is satisfied.
- All handlers on a single match case must return values of the same type, TOutput.

`.returnType`

match(...)
  .returnType<string>()
  .with(..., () => "has to be a string")
  .with(..., () => "Oops".length)
  //               ~~~~~~~~~~~~~ ❌ `number` isn't a string!

The .returnType<SomeType>() method allows you to control the return type of all of your branches of code. It accepts a single type parameter that will be used as the return type of your match expression. All code branches must return values assignable to this type.

Signature

function returnType<TOutputOverride>(): Match<TInput, TOutputOverride>;

Type arguments

TOutputOverride
- The type that your match expression will return. All branches must return values assignable to it.

`.exhaustive`

match(...)
  .with(...)
  .exhaustive()

Runs the pattern-matching expression and returns its result. It also enables exhaustiveness checking, making sure that we have handled all possible cases at compile time.

By default, .exhaustive() will throw an error if the input value wasn't handled by any .with(...) clause. This should only happen if your types are incorrect.

It is possible to pass your own handler function as a parameter to decide what should happen if an unexpected value has been received. You can for example throw your own custom error:

match(...)
  .with(...)
  .exhaustive((unexpected: unknown) => {
    throw MyCustomError(unexpected);
  })

Or log an error and return a default value:

match<string, number>(...)
  .with(P.string, (str) => str.length)
  .exhaustive((notAString: unknown) => {
    console.log(`received an unexpected value: ${notAString}`);
    return 0;
  })

Signature

function exhaustive(): TOutput;
function exhaustive(handler: (unexpectedValue: unknown) => TOutput): TOutput;

Example

type Permission = 'editor' | 'viewer';
type Plan = 'basic' | 'pro';

const fn = (org: Plan, user: Permission) =>
  match([org, user])
    .with(['basic', 'viewer'], () => {})
    .with(['basic', 'editor'], () => {})
    .with(['pro', 'viewer'], () => {})
    // Fails with `NonExhaustiveError<['pro', 'editor']>`
    // because the `['pro', 'editor']` case isn't handled.
    .exhaustive();

const fn2 = (org: Plan, user: Permission) =>
  match([org, user])
    .with(['basic', 'viewer'], () => {})
    .with(['basic', 'editor'], () => {})
    .with(['pro', 'viewer'], () => {})
    .with(['pro', 'editor'], () => {})
    .exhaustive(); // Works!

`.otherwise`

match(...)
  .with(...)
  .otherwise(defaultHandler)

Runs the pattern-matching expression with a default handler which will be called if no previous .with() clause match the input value, and returns the result.

Signature

function otherwise(defaultHandler: (value: TInput) => TOutput): TOutput;

Arguments

defaultHandler: (value: TInput) => TOutput
- Required
- Function called if no pattern matched the input value.
- Think of it as the default: case of switch statements.
- All handlers on a single match case must return values of the same type, TOutput.

`.run`

match(...)
  .with(...)
  .run()

returns the result of the pattern-matching expression, or throws if no pattern matched the input. .run() is similar to .exhaustive(), but is unsafe because exhaustiveness is not checked at compile time, so you have no guarantees that all cases are indeed covered. Use at your own risks.

Signature

function run(): TOutput;

`.narrow`

match(...)
  .with(...)
  .narrow()
  .with(...)

The .narrow() method deeply narrows the input type to exclude all values that have previously been handled. This is useful when you want to exclude cases from union types or nullable properties that are deeply nested.

Note that handled case of top-level union types are excluded by default, without calling .narrow().

Signature

function narrow(): Match<Narrowed<TInput>, TOutput>;

Example

type Input = { color: 'red' | 'blue'; size: 'small' | 'large' };

declare const input: Input;

const result = match(input)
  .with({ color: 'red', size: 'small' }, (red) => `Red: ${red.size}`)
  .with({ color: 'blue', size: 'large' }, (red) => `Red: ${red.size}`)
  .narrow() // 👈
  .otherwise((narrowedInput) => {
    // narrowedInput:
    // | { color: 'red'; size: 'large' }
    // | { color: 'blue'; size: 'small' }
  });

`isMatching`

if (isMatching(pattern, value))  {
  ...
}

isMatching is a type guard function which checks if a pattern matches a given value. It is curried, which means it can be used in two ways.

With a single argument:

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

const isBlogPost = isMatching({
  type: 'blogpost',
  title: P.string,
  description: P.string,
});

if (isBlogPost(value)) {
  // value: { type: 'blogpost', title: string, description: string }
}

With two arguments:

const blogPostPattern = {
  type: 'blogpost',
  title: P.string,
  description: P.string,
} as const;

if (isMatching(blogPostPattern, value)) {
  // value: { type: 'blogpost', title: string, description: string }
}

Signature

export function isMatching<p extends Pattern<any>>(
  pattern: p
): (value: any) => value is InvertPattern<p>;
export function isMatching<p extends Pattern<any>>(
  pattern: p,
  value: any
): value is InvertPattern<p>;

Arguments

pattern: Pattern<any>
- Required
- The pattern a value should match.
value?: any
- Optional
- if a value is given as second argument, isMatching will return a boolean telling us whether the pattern matches the value or not.
- if we only give the pattern to the function, isMatching will return another type guard function taking a value and returning a boolean which tells us whether the pattern matches the value or not.

Patterns

A pattern is a description of the expected shape of your input value.

Patterns can be regular JavaScript values ("some string", 10, true, ...), data structures (objects, arrays, ...), wildcards (P._, P.string, P.number, ...), or special matcher functions (P.not,
P.when, P.select, ...).

All wildcards and matcher functions can be imported either as Pattern or as P from the ts-pattern module.

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

const toString = (value: unknown): string =>
  match(value)
    .with(Pattern.string, (str) => str)
    .with(Pattern.number, (num) => num.toFixed(2))
    .with(Pattern.boolean, (bool) => `${bool}`)
    .otherwise(() => 'Unknown');

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

const toString = (value: unknown): string =>
  match(value)
    .with(P.string, (str) => str)
    .with(P.number, (num) => num.toFixed(2))
    .with(P.boolean, (bool) => `${bool}`)
    .otherwise(() => 'Unknown');

If your input isn't typed, (if it's a any or a unknown), you are free to use any possible pattern. Your handler will infer the input type from the shape of your pattern.

Literals

Literals are primitive JavaScript values, like numbers, strings, booleans, bigints, symbols, null, undefined, or NaN.

import { match } from 'ts-pattern';

const input: unknown = 2;

const output = match(input)
  .with(2, () => 'number: two')
  .with(true, () => 'boolean: true')
  .with('hello', () => 'string: hello')
  .with(undefined, () => 'undefined')
  .with(null, () => 'null')
  .with(NaN, () => 'number: NaN')
  .with(20n, () => 'bigint: 20n')
  .otherwise(() => 'something else');

console.log(output);
// => 'number: two'

Objects

Patterns can be objects containing sub-patterns. An object pattern will match
If and only if the input value is an object, contains all properties the pattern defines
and each property matches the corresponding sub-pattern.

import { match } from 'ts-pattern';

type Input =
  | { type: 'user'; name: string }
  | { type: 'image'; src: string }
  | { type: 'video'; seconds: number };

let input: Input = { type: 'user', name: 'Gabriel' };

const output = match(input)
  .with({ type: 'image' }, () => 'image')
  .with({ type: 'video', seconds: 10 }, () => 'video of 10 seconds.')
  .with({ type: 'user' }, ({ name }) => `user of name: ${name}`)
  .otherwise(() => 'something else');

console.log(output);
// => 'user of name: Gabriel'

Tuples (arrays)

In TypeScript, Tuples are arrays with a fixed
number of elements that can be of different types. You can pattern-match on tuples
using a tuple pattern. A tuple pattern will match if the input value is an array of the same length,
and each item matches the corresponding sub-pattern.

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

type Input =
  | [number, '+', number]
  | [number, '-', number]
  | [number, '*', number]
  | ['-', number];

const input = [3, '*', 4] as Input;

const output = match(input)
  .with([P._, '+', P._], ([x, , y]) => x + y)
  .with([P._, '-', P._], ([x, , y]) => x - y)
  .with([P._, '*', P._], ([x, , y]) => x * y)
  .with(['-', P._], ([, x]) => -x)
  .exhaustive();

console.log(output);
// => 12

Wildcards

`P._` wildcard

The P._ pattern will match any value. You can also use P.any, which is an alias to P._.

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

const input = 'hello';

const output = match(input)
  .with(P._, () => 'It will always match')
  // OR
  .with(P.any, () => 'It will always match')
  .otherwise(() => 'This string will never be used');

console.log(output);
// => 'It will always match'

`P.string` wildcard

The P.string pattern will match any value of type string.

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

const input = 'hello';

const output = match(input)
  .with('bonjour', () => 'Won‘t match')
  .with(P.string, () => 'it is a string!')
  .exhaustive();

console.log(output);
// => 'it is a string!'

`P.number` wildcard

The P.number pattern will match any value of type number.

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

const input = 2;

const output = match<number | string>(input)
  .with(P.string, () => 'it is a string!')
  .with(P.number, () => 'it is a number!')
  .exhaustive();

console.log(output);
// => 'it is a number!'

`P.boolean` wildcard

The P.boolean pattern will match any value of type boolean.

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

const input = true;

const output = match<number | string | boolean>(input)
  .with(P.string, () => 'it is a string!')
  .with(P.number, () => 'it is a number!')
  .with(P.boolean, () => 'it is a boolean!')
  .exhaustive();

console.log(output);
// => 'it is a boolean!'

`P.nullish` wildcard

The P.nullish pattern will match any value of type null or undefined.

Even though null and undefined can be used as literal patterns, sometimes they appear in a union together
(e.g. null | undefined | string) and you may want to treat them as equivalent using P.nullish.

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

const input = null;

const output = match<number | null | undefined>(input)
  .with(P.number, () => 'it is a number!')
  .with(P.nullish, () => 'it is either null or undefined!')
  .exhaustive();

console.log(output);
// => 'it is either null or undefined!'

`P.nonNullable` wildcard

The P.nonNullable pattern will match any value except null or undefined.

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

const input = null;

const output = match<number | null | undefined>(input)
  .with(P.nonNullable, () => 'it is a number!')
  .otherwise(() => 'it is either null or undefined!');

console.log(output);
// => 'it is either null or undefined!'

`P.bigint` wildcard

The P.bigint pattern will match any value of type bigint.

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

const input = 20000000n;

const output = match<bigint | null>(input)
  .with(P.bigint, () => 'it is a bigint!')
  .otherwise(() => '?');

console.log(output);
// => 'it is a bigint!'

`P.symbol` wildcard

The P.symbol pattern will match any value of type symbol.

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

const input = Symbol('some symbol');

const output = match<symbol | null>(input)
  .with(P.symbol, () => 'it is a symbol!')
  .otherwise(() => '?');

console.log(output);
// => 'it is a symbol!'

`P.array` patterns

To match on arrays of unknown size, you can use P.array(subpattern).
It takes a sub-pattern, and will match if all elements in the input
array match this sub-pattern.

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

type Input = { title: string; content: string }[];

let input: Input = [
  { title: 'Hello world!', content: 'This is a very interesting content' },
  { title: 'Bonjour!', content: 'This is a very interesting content too' },
];

const output = match(input)
  .with(
    P.array({ title: P.string, content: P.string }),
    (posts) => 'a list of posts!'
  )
  .otherwise(() => 'something else');

console.log(output);
// => 'a list of posts!'

Matching variadic tuples with `P.array`

In TypeScript, Variadic Tuple Types are array types created with the ... spread operator, like [string, ...string[]], [number, ...boolean[], string] etc. You can match against variadic tuple types using array literals containing ...P.array(subpattern):

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

type Input = (number | string)[];

declare const input: Input;

const output = match(input)
  // P.array's parameter is optional
  .with([P.string, ...P.array()], (input) => input) // input: [string, ...(number | string)[]]
  .with(['print', ...P.array(P.string)], (input) => input) // input: ['print', ...string[]]
  // you can put patterns on either side of `...P.array()`:
  .with([...P.array(P.string), 'end'], (input) => input) // input: [...string[], 'end']
  .with(['start', ...P.array(P.string), 'end'], (input) => input) // input: ['start', ...string[], 'end']
  .otherwise((input) => input);

`P.record` patterns

To match a Record<Key, Value> (an object with consistent key and value types), you can use P.record(keyPattern, valuePattern).
It takes a sub-pattern to match against the key, a sub-pattern to match against the value, and will match if all entries in the object
match these two sub-patterns.

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

type Input = Record<string, number>;

const input: Input = {
  alice: 100,
  bob: 85,
  charlie: 92,
};

const output = match(input)
  .with(P.record(P.string, P.number), (scores) => `All user scores`)
  .with(P.record(P.string, P.string), (names) => `All user names`)
  .otherwise(() => '');

console.log(output);
// => "All user scores"

You can also use P.record with a single argument P.record(valuePattern), which assumes string keys:

const userProfiles = {
  alice: { name: 'Alice', age: 25 },
  bob: { name: 'Bob', age: 30 },
};

const output = match(userProfiles)
  .with(
    P.record({ name: P.string, age: P.number }),
    (profiles) => `User profiles with name and age`
  )
  .otherwise(() => 'Different format');

console.log(output);
// => "User profiles with name and age"

When using P.select in record patterns, you can extract all keys or all values as arrays:

const data = { a: 1, b: 2, c: 3 };

const keys = match(data)
  .with(P.record(P.string.select(), P.number), (keys) => keys)
  .otherwise(() => []);

const values = match(data)
  .with(P.record(P.string, P.number.select()), (values) => values)
  .otherwise(() => []);

console.log(keys); // => ['a', 'b', 'c']
console.log(values); // => [1, 2, 3]

`P.set` patterns

To match a Set, you can use P.set(subpattern).
It takes a sub-pattern, and will match if all elements inside the set
match this sub-pattern.

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

type Input = Set<string | number>;

const input: Input = new Set([1, 2, 3]);

const output = match(input)
  .with(P.set(1), (set) => `Set contains only 1`)
  .with(P.set(P.string), (set) => `Set contains only strings`)
  .with(P.set(P.number), (set) => `Set contains only numbers`)
  .otherwise(() => '');

console.log(output);
// => "Set contains only numbers"

`P.map` patterns

To match a Map, you can use P.map(keyPattern, valuePattern).
It takes a subpattern to match against the key, a subpattern to match agains the value, and will match if all elements inside this map
match these two sub-patterns.

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

type Input = Map<string, string | number>;

const input: Input = new Map([
  ['a', 1],
  ['b', 2],
  ['c', 3],
]);

const output = match(input)
  .with(P.map(P.string, P.number), (map) => `map's type is Map<string, number>`)
  .with(P.map(P.string, P.string), (map) => `map's type is Map<string, string>`)
  .with(
    P.map(P.union('a', 'c'), P.number),
    (map) => `map's type is Map<'a' | 'c', number>`
  )
  .otherwise(() => '');

console.log(output);
// => "map's type is Map<string, number>"

`P.when` patterns

P.when lets you define your own logic to check if the pattern should match or not.
If the predicate function given to when returns a truthy value, then the pattern
will match for this input.

Note that you can narrow down the type of your input by providing a
Type Guard function to P.when.

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

type Input = { score: number };

const output = match<Input>({ score: 10 })
  .with(
    {
      score: P.when((score): score is 5 => score === 5),
    },
    (input) => '😐' // input is inferred as { score: 5 }
  )
  .with({ score: P.when((score) => score < 5) }, () => '😞')
  .otherwise(() => '🙂');

console.log(output);
// => '🙂'

`P.not` patterns

P.not lets you match on everything but a specific value.
it's a function taking a pattern and returning the opposite pattern.

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

type Input = boolean | number;

const toNumber = (input: Input) =>
  match(input)
    .with(P.not(P.boolean), (n) => n) // n: number
    .with(true, () => 1)
    .with(false, () => 0)
    .exhaustive();

console.log(toNumber(2));
// => 2
console.log(toNumber(true));
// => 1

`P.select` patterns

P.select lets you pick a piece of your input data-structure
and injects it in your handler function.

It's especially useful when pattern matching on deep data structure to
avoid the hassle of destructuring it in the handler function.

Selections can be either named (with P.select('someName')) or anonymous (with P.select()).

You can have only one anonymous selection by pattern, and the selected value will be directly inject in your handler as first argument:

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

type Input =
  | { type: 'post'; user: { name: string } }
  | { ... };

const input: Input = { type: 'post', user: { name: 'Gabriel' } }

const output = match(input)
    .with(
      { type: 'post', user: { name: P.select() } },
      username => username // username: string
    )
    .otherwise(() => 'anonymous');

console.log(output);
// => 'Gabriel'

If you need to select several things inside your input data structure, you can name your selections by giving a string to P.select(<name>). Each selection will be passed as first argument to your handler in an object.

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

type Input =
  | { type: 'post'; user: { name: string }, content: string }
  | { ... };

const input: Input = { type: 'post', user: { name: 'Gabriel' }, content: 'Hello!' }

const output = match(input)
    .with(
      { type: 'post', user: { name: P.select('name') }, content: P.select('body') },
      ({ name, body }) => `${name} wrote "${body}"`
    )
    .otherwise(() => '');

console.log(output);
// => 'Gabriel wrote "Hello!"'

You can also pass a sub-pattern to P.select if you want it to only
select values which match this sub-pattern:

type User = { age: number; name: string };
type Post = { body: string };
type Input = { author: User; content: Post };

declare const input: Input;

const output = match(input)
  .with(
    {
      author: P.select({ age: P.number.gt(18) }),
    },
    (author) => author // author: User
  )
  .with(
    {
      author: P.select('author', { age: P.number.gt(18) }),
      content: P.select(),
    },
    ({ author, content }) => author // author: User, content: Post
  )
  .otherwise(() => 'anonymous');

`P.optional` patterns

P.optional(subpattern) lets you annotate a key in an object pattern as being optional,
but if it is defined it should match a given sub-pattern.

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

type Input = { key?: string | number };

const output = match(input)
  .with({ key: P.optional(P.string) }, (a) => {
    return a.key; // string | undefined
  })
  .with({ key: P.optional(P.number) }, (a) => {
    return a.key; // number | undefined
  })
  .exhaustive();

`P.instanceOf` patterns

The P.instanceOf function lets you build a pattern to check if
a value is an instance of a class:

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

class A {
  a = 'a';
}
class B {
  b = 'b';
}

type Input = { value: A | B };

const input: Input = { value: new A() };

const output = match(input)
  .with({ value: P.instanceOf(A) }, (a) => {
    return 'instance of A!';
  })
  .with({ value: P.instanceOf(B) }, (b) => {
    return 'instance of B!';
  })
  .exhaustive();

console.log(output);
// => 'instance of A!'

`P.union` patterns

P.union(...subpatterns) lets you test several patterns and will match if
one of these patterns do. It's particularly handy when you want to handle
some cases of a union type in the same code branch:

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

type Input =
  | { type: 'user'; name: string }
  | { type: 'org'; name: string }
  | { type: 'text'; content: string }
  | { type: 'img'; src: string };

declare const input: Input;

const output = match(input)
  .with({ type: P.union('user', 'org') }, (userOrOrg) => {
    // userOrOrg: User | Org
    return userOrOrg.name;
  })
  .otherwise(() => '');

`P.intersection` patterns

P.intersection(...subpatterns) lets you ensure that the input matches
all sub-patterns passed as parameters.

class A {
  constructor(public foo: 'bar' | 'baz') {}
}

class B {
  constructor(public str: string) {}
}

type Input = { prop: A | B };

declare const input: Input;

const output = match(input)
  .with(
    { prop: P.intersection(P.instanceOf(A), { foo: 'bar' }) },
    ({ prop }) => prop.foo // prop: A & { foo: 'bar' }
  )
  .with(
    { prop: P.intersection(P.instanceOf(A), { foo: 'baz' }) },
    ({ prop }) => prop.foo // prop: A & { foo: 'baz' }
  )
  .otherwise(() => '');

`P.string` predicates

P.string has a number of methods to help you match on specific strings.

`P.string.startsWith`

P.string.startsWith(str) matches strings that start with the provided string.

const fn = (input: string) =>
  match(input)
    .with(P.string.startsWith('TS'), () => '🎉')
    .otherwise(() => '❌');

console.log(fn('TS-Pattern')); // logs '🎉'

`P.string.endsWith`

P.string.endsWith(str) matches strings that end with the provided string.

const fn = (input: string) =>
  match(input)
    .with(P.string.endsWith('!'), () => '🎉')
    .otherwise(() => '❌');

console.log(fn('Hola!')); // logs '🎉'

`P.string.minLength`

P.string.minLength(min) matches strings with at least min characters.

const fn = (input: string) =>
  match(input)
    .with(P.string.minLength(2), () => '🎉')
    .otherwise(() => '❌');

console.log(fn('two')); // logs '🎉'

`P.string.length`

P.string.length(len) matches strings with exactly len characters.

const fn = (input: string) =>
  match(input)
    .with(P.string.length(2), () => '🎉')
    .otherwise(() => '❌');

console.log(fn('ok')); // logs '🎉'

`P.string.maxLength`

P.string.maxLength(max) matches strings with at most max characters.

const fn = (input: string) =>
  match(input)
    .with(P.string.maxLength(5), () => '🎉')
    .otherwise(() => 'too long');

console.log(fn('is this too long?')); // logs 'too long'

`P.string.includes`

P.string.includes(str) matches strings that contain the provided substring.

const fn = (input: string) =>
  match(input)
    .with(P.string.includes('!'), () => '✅')
    .otherwise(() => '❌');

console.log(fn('Good job! 🎉')); // logs '✅'

`P.string.regex`

P.string.regex(RegExp) matches strings if they match the provided regular expression.

const fn = (input: string) =>
  match(input)
    .with(P.string.regex(/^[a-z]+$/), () => 'single word')
    .otherwise(() => 'other strings');

console.log(fn('gabriel')); // logs 'single word'

`P.number` and `P.bigint` predicates

P.number and P.bigint have several of methods to help you match on specific numbers and bigints.

`P.number.between`

P.number.between(min, max) matches numbers between min and max.

const fn = (input: number) =>
  match(input)
    .with(P.number.between(1, 5), () => '✅')
    .otherwise(() => '❌');

console.log(fn(3), fn(1), fn(5), fn(7)); // logs '✅ ✅ ✅ ❌'

`P.number.lt`

P.number.lt(max) matches numbers smaller than max.

const fn = (input: number) =>
  match(input)
    .with(P.number.lt(7), () => '✅')
    .otherwise(() => '❌');

console.log(fn(2), fn(7)); // logs '✅ ❌'

`P.number.gt`

P.number.gt(min) matches numbers greater than min.

const fn = (input: number) =>
  match(input)
    .with(P.number.gt(7), () => '✅')
    .otherwise(() => '❌');

console.log(fn(12), fn(7)); // logs '✅ ❌'

`P.number.lte`

P.number.lte(max) matches numbers smaller than or equal to max.

const fn = (input: number) =>
  match(input)
    .with(P.number.lte(7), () => '✅')
    .otherwise(() => '❌');

console.log(fn(7), fn(12)); // logs '✅ ❌'

`P.number.gte`

P.number.gte(min) matches numbers greater than or equal to min.

const fn = (input: number) =>
  match(input)
    .with(P.number.gte(7), () => '✅')
    .otherwise(() => '❌');

console.log(fn(7), fn(2)); // logs '✅ ❌'

`P.number.int`

P.number.int() matches integers.

const fn = (input: number) =>
  match(input)
    .with(P.number.int(), () => '✅')
    .otherwise(() => '❌');

console.log(fn(12), fn(-3.141592)); // logs '✅ ❌'

`P.number.finite`

P.number.finite() matches all numbers except Infinity and -Infinity.

const fn = (input: number) =>
  match(input)
    .with(P.number.finite(), () => '✅')
    .otherwise(() => '❌');

console.log(fn(-3.141592), fn(Infinity)); // logs '✅ ❌'

`P.number.positive`

P.number.positive() matches positive numbers.

const fn = (input: number) =>
  match(input)
    .with(P.number.positive(), () => '✅')
    .otherwise(() => '❌');

console.log(fn(7), fn(-3.141592)); // logs '✅ ❌'

`P.number.negative`

P.number.negative() matches negative numbers.

const fn = (input: number) =>
  match(input)
    .with(P.number.negative(), () => '✅')
    .otherwise(() => '❌');

console.log(fn(-3.141592), fn(7)); // logs '✅ ❌'

Types

`P.infer`

P.infer<typeof somePattern> lets you infer a type of value from a type of pattern.

It's particularly useful when validating an API response.

const postPattern = {
  title: P.string,
  content: P.string,
  stars: P.number.between(1, 5).optional(),
  author: {
    firstName: P.string,
    lastName: P.string.optional(),
    followerCount: P.number,
  },
} as const;

type Post = P.infer<typeof postPattern>;

// posts: Post[]
const posts = await fetch(someUrl)
  .then((res) => res.json())
  .then((res: unknown): Post[] =>
    isMatching({ data: P.array(postPattern) }, res) ? res.data : []
  );

Although not strictly necessary, using as const after the pattern definition ensures that TS-Pattern infers the most precise types possible.

`P.narrow`

P.narrow will narrow the input type to only keep the set of values that are compatible with the provided pattern type.

type Input = ['a' | 'b' | 'c', 'a' | 'b' | 'c'];
const Pattern = ['a', P.union('a', 'b')] as const;

type Narrowed = P.narrow<Input, typeof Pattern>;
//     ^? ['a', 'a' | 'b']

Note that most of the time, the match and isMatching functions perform narrowing for you, and you do not need to narrow types yourself.

`P.Pattern`

P.Pattern<T> is the type of all possible pattern for a generic type T.

type User = { name: string; age: number };

const userPattern: Pattern<User> = {
  name: 'Alice',
};

Type inference

TS-Pattern takes advantage the most advanced features of TypeScript to perform type narrowing and accurate exhaustive matching, even when matching on complex data-structures.

Here are some examples of TS-Pattern's type inference features.

Type narrowing

When pattern-matching on a input containing union types, TS-Pattern will infer the most precise type possible for the argument of your handler function using the pattern you provide.

type Text = { type: 'text'; data: string };
type Img = { type: 'img'; data: { src: string; alt: string } };
type Video = { type: 'video'; data: { src: string; format: 'mp4' | 'webm' } };
type Content = Text | Img | Video;

const formatContent = (content: Content): string =>
  match(content)
    .with({ type: 'text' }, (text /* : Text */) => '<p>...</p>')
    .with({ type: 'img' }, (img /* : Img */) => '<img ... />')
    .with({ type: 'video' }, (video /* : Video */) => '<video ... />')
    .with(
      { type: 'img' },
      { type: 'video' },
      (video /* : Img | Video */) => 'img or video'
    )
    .with(
      { type: P.union('img', 'video') },
      (video /* : Img | Video */) => 'img or video'
    )
    .exhaustive();

When using P.select in a pattern, TS-Pattern will find and inject the selected value in your handler. The type of your handler's argument is inferred accordingly.

const formatContent = (content: Content): string =>
  match(content)
    .with(
      { type: 'text', data: P.select() },
      (content /* : string */) => '<p>...</p>'
    )
    .with(
      { type: 'video', data: { format: P.select() } },
      (format /* : 'mp4' | 'webm' */) => '<video ... />'
    )
    .with(
      { type: P.union('img', 'video'), data: P.select() },
      (data /* : Img['data'] | Video['data'] */) => 'img or video'
    )
    .exhaustive();

Type guard function

If you pass a type guard function to P.when, TS-Pattern will use its return type to narrow the input.

const isString = (x: unknown): x is string => typeof x === 'string';

const isNumber = (x: unknown): x is number => typeof x === 'number';

const fn = (input: { id: number | string }) =>
  match(input)
    .with({ id: P.when(isString) }, (narrowed /* : { id: string } */) => 'yes')
    .with({ id: P.when(isNumber) }, (narrowed /* : { id: number } */) => 'yes')
    .exhaustive();

Exhaustiveness checking

TS-Pattern will keep track of handled and unhandled cases of your input type. Even when pattern-matching on several union types at once, you only need to call .exhaustive() to make sure that all possible cases are correctly handled.

type Permission = 'editor' | 'viewer';
type Plan = 'basic' | 'pro';

const fn = (org: Plan, user: Permission): string =>
  match([org, user])
    .with(['basic', 'viewer'], () => {})
    .with(['basic', 'editor'], () => {})
    .with(['pro', 'viewer'], () => {})
    // Fails with `NonExhaustiveError<['pro', 'editor']>`
    // because the `['pro', 'editor']` case isn't handled.
    .exhaustive();

Inspirations

This library has been heavily inspired by this great article by Wim Jongeneel:
Pattern Matching in TypeScript with Record and Wildcard Patterns.
It made me realize pattern matching could be implemented in userland and we didn't have
to wait for it to be added to the language itself. I'm really grateful for that 🙏

Overview (`benchmarks/compile-time/README.md`)

Compile-time benchmarks

These files measure how expensive ts-pattern's types are for the
TypeScript compiler, as opposed to the runtime benchmarks in the parent
directory. They intentionally contain large match expressions of the
shapes that show up in real codebases:

large-union-exhaustive.ts: a 200-member string literal union (the
same shape as a large string enum), matched member by member.
discriminated-union-exhaustive.ts: a 20-variant discriminated union
of wide object types, matched per-discriminant with refined, 2-pattern
and variadic .with() calls.
The -non-exhaustive variants have one case removed, which simulates
the mid-edit state your editor type-checks while you're still writing
the match. The missing case is reported by .exhaustive() and
silenced with @ts-expect-error so the project still type-checks.

Run all of them:

npm run perf:compile-time

Or measure a single file, which is more informative:

npx tsc --noEmit --strict --skipLibCheck --extendedDiagnostics \
  benchmarks/compile-time/large-union-exhaustive.ts

The metric to watch is Instantiations: it's deterministic for a given
TypeScript version, unlike Check time. For finer-grained data, use
--generateTrace and @typescript/analyze-trace (see the trace and
analyzeTrace scripts in the root package.json).

Roadmap (`docs/roadmap.md`)

Roadmap

P.ExactPattern<Type> to infer the exact pattern you must write to fully cover all possible properties of Type.
Allow calling isMatching with a type parameter to restrain the pattern type: isMatching<Type>(pattern).
better variant attempt.
.narrow() as an opt-in option to narrow the input type after a .with
P.array.includes(x)
P.record({Pkey}, {Pvalue})
P.record
P.unknown alias to any.
P.nonNullable
chainable methods
- string
  - P.string.includes('str')
  - P.string.startsWith('str')
  - P.string.endsWith('str')
  - P.string.regex('[a-z]+')
- numbers
  - P.number.between(1, 10)
  - P.number.lt(12)
  - P.number.gt(12)
  - P.number.gte(12)
  - P.number.lte(12)
  - P.number.int(12)
  - P.number.finite
  - P.number.positive
  - P.number.negative
- all
  - P.number.optional
  - P.string.optional
  - P.number.select()
  - P.string.select()
  - P.number.optional.select()
  - P.string.optional.select()
Add a custom matcher protocol data structures could implement to make them matchable.
(Maybe) add an iterator protocol to P.array to be usable as a variadic tuple pattern. Example of using P.array:

const reverse = <T>(xs: T[]): T[] => {
  return match<T[], T[]>(xs)
    .with([P.any, ...P.array()], ([x, ...xs]) => [...reverse(xs), x])
    .otherwise(() => []);
};

match(xs)
  .with([P.any, ...P.array()], (xs: [unknown, ...unknown[]]) => [])
  .with([42, ...P.array(P.number), '!'], (xs: [42, ...number[], '!']) => [])
  .with(
    [...P.array(P.number), ...P.array(P.string)],
    (xs: [...number[], ...string[]]) => []
  )
  .otherwise(() => []);

update select() and select('name') to accept a pattern the selected value should match.
add a union(...patterns) pattern.
When not provided, maybe compute the output type from all branches
maybe add a lightweight select API for single values
add support matching against several patterns in a single .with() clause.
Find a way to enforce exhaustive pattern matching
Several pattern/when clauses if necessary, with refined type inference from one to the other
Find a way to make the full type inference work
Add an operator to select a part of the data structure
Add not(value) in patterns.
Narrow down to type of value in when if the predicate is a type guard.

V3 To V4 Migration Guide (`docs/v3-to-v4-migration-guide.md`)

TS-Pattern v3 to v4 Migration Guide

Breaking changes

Imports

type-specific wildcard patterns have moved from __. to a new Pattern qualified module, also exported as P by ts-pattern.

diff

- import { match, __ } from 'ts-pattern';
+ import { match, Pattern } from 'ts-pattern';


const toString = (value: string | number) =>
  match(value)
-   .with(__.string, (v) => v)
-   .with(__.number, (v) => `${v}`)
+   .with(Pattern.string, (v) => v)
+   .with(Pattern.number, (v) => `${v}`)
    .exhaustive();

diff

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


const toString = (value: string | number) =>
  match(value)
-   .with(__.string, (v) => v)
-   .with(__.number, (v) => `${v}`)
+   .with(P.string, (v) => v)
+   .with(P.number, (v) => `${v}`)
    .exhaustive();

`__`

The top level __ export was moved to P._ and P.any:

diff

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


const toString = (value: string | number) =>
  match(value)
-   .with(__, (v) => `${v}`)
+   .with(P._, (v) => `${v}`)
    // OR
+   .with(P.any, (v) => `${v}`)
    .exhaustive();

`select()`, `not()`, `when()`

Function to create patterns have been moved to the P module.

diff

- import { match, select, not, when } from 'ts-pattern';
+ import { match, P } from 'ts-pattern';


const toString = (value: number) =>
  match(value)
-   .with({ prop: select() }, (v) => `${v}`)
+   .with({ prop: P.select() }, (v) => `${v}`)

-   .with({ prop: not(10) }, (v) => `${v}`)
+   .with({ prop: P.not(10) }, (v) => `${v}`)

-   .with({ prop: when((x) => x < 5) }, (v) => `${v}`)
+   .with({ prop: P.when((x) => x < 5) }, (v) => `${v}`)
    .exhaustive();

`Pattern` type

the Pattern type which used to be exported at the toplevel is now accessible at P.Pattern.

diff

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

- const pattern: Pattern<number> = P.when(x => x > 2);
+ const pattern: P.Pattern<number> = P.when(x => x > 2);

list patterns

The syntax for matching on a list of elements with an unknown length has changed from [subpattern] to P.array(subpattern).

Example:

diff

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


const parseUsers = (response: unknown) =>
  match(response)
-   .with({ data: [{ name: __.string }] }, (users) => users)
+   .with({ data: P.array({ name: P.string }) }, (users) => users)
    .otherwise(() => []);

Now [subpattern] matches arrays with 1 element in them. This is more consistent with native language features, like destructuring assignment and is overall more intuitive. This will resolve #69, #62 and #46.

NaN

The __.NaN pattern has been replaced by simply using the NaN value in the pattern:

diff

match<number>(NaN)
-   .with(__.NaN, () => "this is not a number")
+   .with(NaN, () => "this is not a number")
    .otherwise((n) => n);

New features

Here is the list of all new features which have been added in TS-Pattern v4.

Arrays and unary tuples

`P.array(pattern)`

To match an array of elements, you can now use P.array:

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

const responsePattern = {
  data: P.array({
    id: P.string,
    post: P.array({
      title: P.string,
      content: P.string,
    }),
  }),
};

fetchSomething().then((value: unknown) =>
  match(value)
    .with(responsePattern, (value) => {
      // value: { data: { id: string, post: { title: string, content: string }[] }[] }
      return value;
    })
    .otherwise(() => {
      throw new Error('unexpected response');
    })
);

Optional object properties

`P.optional(pattern)`

If you want one of the keys of your pattern to be optional, you can now use P.optional(subpattern).

If you P.select() something in an optional pattern, it's type will be infered as T | undefined.

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

const doSomethingWithUser = (user: User | Org) =>
  match(user)
    .with(
      {
        type: 'user',
        detail: {
          bio: P.optional(P.string),
          socialLinks: P.optional({
            twitter: P.select(),
          }),
        },
      },
      (twitterLink, value) => {
        // twitterLink: string | undefined
        /**
         *  value.detail: {
         *      bio?: string,
         *      socialLinks?: {
         *          twitter: string
         *      }
         *  }
         **/
      }
    )
    .otherwise(() => {
      throw new Error('unexpected response');
    });

Union & intersection patterns

P.union(...patterns) and P.intersection(...patterns) combine several patterns into a single one, either by checking that one of them match the input (p.union) or all of them match it (P.intersection).

`P.union(...patterns)`

type Input =
  | { type: 'a'; value: string }
  | { type: 'b'; value: number }
  | {
      type: 'c';
      value:
        | { type: 'd'; value: boolean }
        | { type: 'e'; value: string[] }
        | { type: 'f'; value: number[] };
    };

const f = (input: Input) =>
  match(input)
    .with(
      { type: P.union('a', 'b') },
      // x: { type: 'a'; value: string } | { type: 'b'; value: number }
      (x) => 'branch 1'
    )
    .with(
      // P.union can take any subpattern:
      {
        type: 'c',
        value: { value: P.union(P.boolean, P.array(P.string)) },
      },
      (x) => 'branch 2' // x.value.value: boolean | string[]
    )
    .with({ type: 'c', value: { type: 'f' } }, () => 'branch 3')
    .exhaustive();

`P.intersection(...patterns)`

class A {
  constructor(public foo: 'bar' | 'baz') {}
}

class B {
  constructor(public str: string) {}
}

const f = (input: { prop: A | B }) =>
  match(input)
    .with(
      { prop: P.intersection(P.instanceOf(A), { foo: 'bar' }) },
      // prop: A & { foo: 'bar' }
      ({ prop }) => 'branch 1'
    )
    .with(
      { prop: P.intersection(P.instanceOf(A), { foo: 'baz' }) },
      // prop: A & { foo: 'baz' }
      ({ prop }) => 'branch 2'
    )
    .with(
      { prop: P.instanceOf(B) },
      // prop: B
      ({ prop }) => 'branch 3'
    )
    .exhaustive();

Select with sub pattern

P.select() now can take a subpattern and match only what the subpattern matches:

type Img = { type: 'img'; src: string };
type Text = { type: 'text'; content: string; length: number };
type User = { type: 'user'; username: string };
type Org = { type: 'org'; orgId: number };

const post = (input: { author: User | Org; content: Text | Img }) =>
  match(input)
    .with(
      { author: P.select({ type: 'user' }) },
      // user: User
      (user) => {}
    )
    .with(
      {
        // This also works with named selections
        author: P.select('org', { type: 'org' }),
        content: P.select('text', { type: 'text' }),
      },
      // org: Org, text: Text
      ({ org, text }) => {}
    )
    .otherwise(() => {
      // ...
    });

Infer the matching types from a pattern

`P.infer`

TS-Pattern is pretty handy for parsing unknown payloads like HTTP responses. You can write a pattern for the shape you are expecting, and then use isMatching(pattern, response) to make sure the response has the correct shape.

One limitation TS-Pattern had in its previous version was that it did not provide a way to get the TypeScript type of the value a given pattern matches. This is what P.infer<typeof pattern> does :)

const postPattern = {
  title: P.string,
  description: P.optional(P.string),
  content: P.string,
  likeCount: P.number,
};

type Post = P.infer<typeof postPattern>;
// Post: { title: string, description?: string, content: string, likeCount: number }

const userPattern = {
  name: P.string,
  postCount: P.number,
  bio: P.optional(P.string),
  posts: P.optional(P.array(postPattern)),
};

type User = P.infer<typeof userPattern>;
// User: { name: string, postCount: number, bio?: string, posts?: Post[]  }

const isUserList = isMatching(P.array(userPattern));

const res = await fetchUsers();

if (isUserList(res)) {
  // res: User
}

New type specific wildcards

`P.symbol`

P.symbol is a wildcard pattern matching any symbol.

match(Symbol('Hello'))
  .with(P.symbol, () => 'this is a symbol!')
  .exhaustive();

`P.bigint`

P.bigint is a wildcard pattern matching any bigint.

match(200n)
  .with(P.bigint, () => 'this is a bigint!')
  .exhaustive();

V4 To V5 Migration Guide (`docs/v4-to-v5-migration-guide.md`)

TS-Pattern v4 to v5 Migration Guide

This file contains all breaking changes and new features between the version 4 and 5 of TS-Pattern.

Breaking changes

TypeScript v5

Because it relies on const type parameters, TS-Pattern v5 requires TypeScript v5+!

`.with` is now evaluated eagerly

In the previous version of TS-Pattern, no code would execute until you called .exhaustive() or .otherwise(...). For example, in the following code block, nothing would be logged to the console or thrown:

// TS-Pattern v4
type Input = { type: 'ok'; value: number } | { type: 'error'; error: Error };

// We don't call `.exhaustive`, so handlers don't run.
function someFunction(input: Input) {
  match(input)
    .with({ type: 'ok' }, ({ value }) => {
      console.log(value);
    })
    .with({ type: 'error' }, ({ error }) => {
      throw error;
    });
}

someFunction({ type: 'ok', value: 42 }); // nothing happens

In TS-Pattern v5, however, the library will execute the matching handler as soon as it finds it:

// TS-Pattern v5
someFunction({ type: 'ok', value: 42 }); // logs "42" to the console!

Handlers are now evaluated eagerly instead of lazily. In practice, this shouldn't change anything as long as you always finish your pattern matching expressions by either .exhaustive or .otherwise.

Matching on Map and Sets

Matching Set and Map instances using .with(new Set(...)) and .with(new Map(...)) is no longer supported. If you want to match specific sets and maps, you should now use the P.map(keyPattern, valuePattern) and P.set(valuePattern) patterns:

diff

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


const someFunction = (value: Set<number> | Map<string, number>) =>
  match(value)
-   .with(new Set([P.number]), (set) => `a set of numbers`)
-   .with(new Map([['key', P.number]]), (map) => `map.get('key') is a number`)
+   .with(P.set(P.number), (set) => `a set of numbers`)
+   .with(P.map('key', P.number), (map) => `map.get('key') is a number`)
    .otherwise(() => null);

The subpattern we provide in P.set(subpattern) should match all values in the Set.
The key and value subpatterns we provide in P.map(keyPattern, subpattern) should match all keys and values in the Map.

New features

chainable methods

TS-Pattern v5's major addition is the ability to chain methods to narrow down the values matched by primitive patterns, like P.string or P.number.

Since a few examples is worth a thousand words, here are a few ways you can use chainable methods:

P.number methods

const example = (position: { x: number; y: number }) =>
  match(position)
    .with({ x: P.number.gte(100) }, (value) => '🎮')
    .with({ x: P.number.between(0, 100) }, (value) => '🎮')
    .with(
      {
        x: P.number.positive().int(),
        y: P.number.positive().int(),
      },
      (value) => '🎮'
    )
    .otherwise(() => 'x or y is negative');

Here is the full list of number methods:

P.number.between(min, max): matches numbers between min and max.
P.number.lt(max): matches numbers smaller than max.
P.number.gt(min): matches numbers greater than min.
P.number.lte(max): matches numbers smaller than or equal to max.
P.number.gte(min): matches numbers greater than or equal to min.
P.number.int(): matches integers.
P.number.finite(): matches all numbers except Infinity and -Infinity
P.number.positive(): matches positive numbers.
P.number.negative(): matches negative numbers.

P.string methods

const example = (query: string) =>
  match(query)
    .with(P.string.startsWith('SELECT'), (query) => `selection`)
    .with(P.string.endsWith('FROM user'), (query) => `👯‍♂️`)
    .with(P.string.includes('*'), () => 'contains a star')
    // Methods can be chained:
    .with(P.string.startsWith('SET').includes('*'), (query) => `🤯`)
    .exhaustive();

Here is the full list of string methods:

P.string.startsWith(str): matches strings that start with str.
P.string.endsWith(str): matches strings that end with str.
P.string.minLength(min): matches strings with at least min characters.
P.string.maxLength(max): matches strings with at most max characters.
P.string.includes(str): matches strings that contain str.
P.string.regex(RegExp): matches strings if they match this regular expression.

Global methods

Some methods are available for all primitive type patterns:

P.{..}.optional(): matches even if this property isn't present on the input object.
P.{..}.select(): injects the matched value into the handler function.
P.{..}.and(pattern): matches if the current pattern and the provided pattern match.
P.{..}.or(pattern): matches if either the current pattern or the provided pattern match.

const example = (value: unknown) =>
  match(value)
    .with(
      {
        username: P.string,
        displayName: P.string.optional(),
      },
      () => `{ username:string, displayName?: string }`
    )
    .with(
      {
        title: P.string,
        author: { username: P.string.select() },
      },
      (username) => `author.username is ${username}`
    )
    .with(
      P.instanceOf(Error).and({ source: P.string }),
      () => `Error & { source: string }`
    )
    .with(P.string.or(P.number), () => `string | number`)
    .otherwise(() => null);

Variadic tuple patterns

With TS-Pattern, you are now able to create array (or more accurately tuple) pattern with a variable number of elements:

const example = (value: unknown) =>
  match(value)
    .with(
      // non-empty list of strings
      [P.string, ...P.array(P.string)],
      (value) => `value: [string, ...string[]]`
    )
    .otherwise(() => null);

Array patterns that include a ...P.array are called variadic tuple patterns. You may only have a single ...P.array, but as many fixed-index patterns as you want:

const example = (value: unknown) =>
  match(value)
    .with(
      [P.string, P.string, P.string, ...P.array(P.string)],
      (value) => `value: [string, string, string, ...string[]]`
    )
    .with(
      [P.string, P.string, ...P.array(P.string)],
      (value) => `value: [string, string, ...string[]]`
    )
    .with([], (value) => `value: []`)
    .otherwise(() => null);

Fixed-index patterns can also be set after the ...P.array variadic, or on both sides!

const example = (value: unknown) =>
  match(value)
    .with(
      [...P.array(P.number), P.string, P.number],
      (value) => `value: [...number[], string, number]`
    )
    .with(
      [P.boolean, ...P.array(P.string), P.number, P.symbol],
      (value) => `value: [boolean, ...string[], number, symbol]`
    )
    .otherwise(() => null);

Lastly, argument of P.array is now optional, and will default to P._, which matches anything:

const example = (value: unknown) =>
  match(value)
    //                         👇
    .with([P.string, ...P.array()], (value) => `value: [string, ...unknown[]]`)
    .otherwise(() => null);

`.returnType`

In TS-Pattern v4, the only way to explicitly set the return type of your match expression is to set the two `` type parameters of match:

// TS-Pattern v4
match<
  { isAdmin: boolean; plan: 'free' | 'paid' }, // input type
  number // return type
>({ isAdmin, plan })
  .with({ isAdmin: true }, () => 123)
  .with({ plan: 'free' }, () => 'Oops!');
//                              ~~~~~~ ❌ not a number.

the main drawback is that you need to set the input type explicitly too, even though TypeScript should be able to infer it.

In TS-Pattern v5, you can use the .returnType<Type>() method to only set the return type:

match({ isAdmin, plan })
  .returnType<number>() // 👈 new
  .with({ isAdmin: true }, () => 123)
  .with({ plan: 'free' }, () => 'Oops!');
//                              ~~~~~~ ❌ not a number.

--- METRICS ---

Files Extracted: 5
Estimated Token Budget: ~17891 tokens
Canonical Reference: https://codewiki.google/github.com/gvergnaud/ts-pattern

Technical Documentation: gvergnaud/ts-pattern

Overview (`README.md`) Copy Section

TS-Pattern

About Copy Chapter

Features Copy Chapter

What is Pattern Matching? Copy Chapter

Installation Copy Chapter

Want to become a TypeScript Expert? Copy Chapter

Documentation

Sandbox examples Copy Chapter

Getting Started Copy Chapter

Example: a state reducer with ts-pattern Copy Section

match(value) Copy Section

.returnType\() Copy Section

.with(pattern, handler) Copy Section

P.select(name?) Copy Section

P.not(pattern) Copy Section

`P.when()` and guard functions Copy Section

using P.when(predicate)

Passing a guard function to `.with(...)`

the `P._` wildcard Copy Section

.exhaustive(), .otherwise() and .run() Copy Section

Matching several patterns Copy Section

API Reference Copy Chapter

`match` Copy Section

Signature

Arguments

`.with` Copy Section

Signature

Arguments

`.when` Copy Section

Signature

Arguments

`.returnType` Copy Section

Signature

Type arguments

`.exhaustive` Copy Section

Signature

Example

`.otherwise` Copy Section

Signature

Arguments

`.run` Copy Section

Signature

`.narrow` Copy Section

Signature

Example

`isMatching` Copy Section

Signature

Arguments

Patterns Copy Chapter

Literals Copy Section

Objects Copy Section

Tuples (arrays) Copy Section

Wildcards Copy Section

`P._` wildcard

`P.string` wildcard

`P.number` wildcard

`P.boolean` wildcard

`P.nullish` wildcard

`P.nonNullable` wildcard

`P.bigint` wildcard

`P.symbol` wildcard

`P.array` patterns Copy Section

Matching variadic tuples with `P.array` Copy Section

`P.record` patterns Copy Section

`P.set` patterns Copy Section

`P.map` patterns Copy Section

`P.when` patterns Copy Section

`P.not` patterns Copy Section

`P.select` patterns Copy Section

`P.optional` patterns Copy Section

`P.instanceOf` patterns Copy Section

`P.union` patterns Copy Section

`P.intersection` patterns Copy Section

`P.string` predicates Copy Chapter

`P.string.startsWith` Copy Section

`P.string.endsWith` Copy Section

`P.string.minLength` Copy Section

`P.string.length` Copy Section

Overview (`README.md`)

About

Features

What is Pattern Matching?

Installation

Want to become a TypeScript Expert?

Sandbox examples

Getting Started

Example: a state reducer with ts-pattern

match(value)

.returnType\()

.with(pattern, handler)

P.select(name?)

P.not(pattern)

`P.when()` and guard functions

the `P._` wildcard

.exhaustive(), .otherwise() and .run()

Matching several patterns

API Reference

`match`

`.with`

`.when`

`.returnType`

`.exhaustive`

`.otherwise`

`.run`

`.narrow`

`isMatching`

Patterns

Literals

Objects

Tuples (arrays)

Wildcards

`P.array` patterns

Matching variadic tuples with `P.array`

`P.record` patterns

`P.set` patterns

`P.map` 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.string.startsWith`

`P.string.endsWith`

`P.string.minLength`

`P.string.length`

`P.string.maxLength`

`P.string.includes`

`P.string.regex`

`P.number` and `P.bigint` predicates

`P.number.between`

`P.number.lt`

`P.number.gt`

`P.number.lte`

`P.number.gte`

`P.number.int`

`P.number.finite`

`P.number.positive`

`P.number.negative`

Types

`P.infer`

`P.narrow`

`P.Pattern`

Type inference

Inspirations

Overview (`benchmarks/compile-time/README.md`)

Roadmap (`docs/roadmap.md`)

Roadmap

V3 To V4 Migration Guide (`docs/v3-to-v4-migration-guide.md`)

Breaking changes

Imports

list patterns

NaN

New features

Arrays and unary tuples

Optional object properties