ts-pattern

ts-pattern provides a typesafe way to express complex branching logic with the following capabilities:

• Data Structure Matching: Match on Objects, Arrays, Tuples, Sets, Maps, and primitives.
• Exhaustiveness Checking: Use .exhaustive() to enforce that all possible cases are covered.
• Validation: Use isMatching to validate if data matches a specific pattern.
• Expressive Wildcards: Use P._ for catch-all or type-specific wildcards like P.string and P.number.
• Advanced Logic: Supports predicates (P.when), unions, intersections, and exclusions (P.not).
• Property Selection: Use P.select() to extract specific values from a matched pattern into the callback argument.
• Small Footprint: The library is approximately 2kB.

An object pattern matches if and only if the input value is an object, contains all properties defined in the pattern, and each property matches its 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'

A tuple pattern matches 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

You can install ts-pattern using npm or any of your preferred package managers.

npm install ts-pattern

Or using other managers:

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

You can match against primitive JavaScript values like numbers, strings, booleans, bigints, symbols, null, undefined, or NaN. When using match(input), the .with() method accepts these literals to trigger specific handler functions.

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'

Use match(value) to start a pattern matching expression. You can chain .with(pattern, callback) to handle specific cases. To ensure you have handled every possible case in a union type, terminate the chain with .exhaustive(). This provides compile-time safety by alerting you if a case is missing.

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();

P.optional(subpattern) allows you to match an object key that might be undefined, but if it is present, it must match the provided subpattern.

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

type Input = { key?: string | number };
const input: Input = { key: 'hello' };

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

The P.number and P.bigint predicates allow for precise numeric matching:

• P.number.between(min, max): Matches numbers between min and max (inclusive).
• P.number.lt(max): Matches numbers strictly less than max.
• P.number.gt(min): Matches numbers strictly greater than min.
• P.number.lte(max): Matches numbers less 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.

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

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