Additional Methods

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

import { match } from 'ts-pattern';
 
type Input = { score: number };
 
const output = match<Input>({ score: 85 })
  .when(
    (input) => input.score >= 90,
    () => 'A - Excellent'
  )
  .when(
    (input) => input.score >= 80,
    () => 'B - Good'
  )
  .when(
    (input) => input.score >= 70,
    () => 'C - Average'
  )
  .otherwise(() => 'F - Fail');
 
console.log(output); // => 'B - Good'

// Using .when() - matches entire input
match(input)
  .when((x) => x > 10, () => 'Greater than 10')
  .exhaustive();
 
// Using P.when() - matches nested property
match(input)
  .with({ value: P.when((x) => x > 10) }, () => 'Value > 10')
  .exhaustive();

match(data)
  .with({ type: 'user' }, () => 'User type')
  .when((d) => d.priority > 5, () => 'High priority')
  .when((d) => d.items.length === 0, () => 'Empty items')
  .otherwise(() => 'Default');

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

match({ isAdmin, plan })
  .returnType<number>() // All branches must return number
  .with({ isAdmin: true }, () => 100)
  .with({ plan: 'premium' }, () => 50)
  .with({ plan: 'free' }, () => 'Oops!') // ❌ Type error: not a number
  .exhaustive();

// Had to specify both input and output types
match<
  { isAdmin: boolean; plan: 'free' | 'premium' },  // ⚠️ Input type
  number                                           // Output type
>({ isAdmin, plan })
  .with({ isAdmin: true }, () => 100)
  .exhaustive();

// Only specify output type, input is inferred
match({ isAdmin, plan })
  .returnType<number>() // ✅ Just the output type
  .with({ isAdmin: true }, () => 100)
  .exhaustive();

type Result =
  | { success: true; data: string }
  | { success: false; error: Error };
 
const process = (input: unknown) =>
  match(input)
    .returnType<Result>()
    .with(P.string, (str) => ({ success: true, data: str }))
    .with(P.number, () => ({ success: true, data: 'number' }))
    .otherwise(() => ({ success: false, error: new Error('Invalid') }));

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

type Input = { color: 'red' | 'blue'; size: 'small' | 'large' };
 
declare const input: Input;
 
const result = match(input)
  .with({ color: 'red', size: 'small' }, () => 'Red small')
  .with({ color: 'blue', size: 'large' }, () => 'Blue large')
  .narrow() // 👈 Narrows remaining cases
  .otherwise((narrowedInput) => {
    // narrowedInput type:
    // | { color: 'red'; size: 'large' }
    // | { color: 'blue'; size: 'small' }
    return 'Other combination';
  });

type Status = 'idle' | 'loading' | 'success' | 'error';
 
declare const status: Status;
 
match(status)
  .with('idle', () => 'Not started')
  .with('loading', () => 'In progress')
  .narrow()
  .otherwise((remaining) => {
    // remaining: 'success' | 'error'
    return `Final state: ${remaining}`;
  });

type Message =
  | { type: 'text'; content: string; priority: 'high' | 'low' }
  | { type: 'image'; url: string };
 
declare const message: Message;
 
match(message)
  .with({ type: 'text', priority: 'high' }, () => 'High priority text')
  .narrow()
  .with({ type: 'text' }, (msg) => {
    // msg: { type: 'text'; content: string; priority: 'low' }
    // priority is narrowed to 'low'
    return `Low priority: ${msg.content}`;
  })
  .with({ type: 'image' }, (msg) => `Image: ${msg.url}`)
  .exhaustive();

// TypeScript doesn't automatically narrow nested properties
match(input)
  .with({ color: 'red', size: 'small' }, ...)
  .otherwise((input) => {
    // input still has full type:
    // { color: 'red' | 'blue'; size: 'small' | 'large' }
    // ⚠️ Not narrowed!
  });

match(input)
  .with({ color: 'red', size: 'small' }, ...)
  .narrow() // 👈
  .otherwise((input) => {
    // input is narrowed:
    // | { color: 'red'; size: 'large' }
    // | { color: 'blue'; size: 'small' }
    // | { color: 'blue'; size: 'large' }
    // ✅ Previous case excluded!
  });

function run(): TOutput;

const output = match(input)
  .with(pattern1, handler1)
  .with(pattern2, handler2)
  .run(); // ⚠️ May throw if no pattern matches

// ✅ Safe: TypeScript ensures all cases are covered
type Status = 'idle' | 'loading' | 'success';
 
match(status)
  .with('idle', () => 'Not started')
  .with('loading', () => 'In progress')
  .with('success', () => 'Done')
  .exhaustive(); // TypeScript checks all Status values are handled

// When input type is very broad (unknown, any)
const processUnknown = (input: unknown) =>
  match(input)
    .with(P.string, (s) => s.toUpperCase())
    .with(P.number, (n) => n * 2)
    .run(); // Exhaustiveness checking isn't practical here

try {
  match(input)
    .with({ type: 'a' }, () => 'A')
    .run(); // Throws if input.type !== 'a'
} catch (error) {
  console.error('No pattern matched');
}

type Data = {
  status: 'pending' | 'approved' | 'rejected';
  priority: 'low' | 'medium' | 'high';
  value: number;
};
 
const process = (data: Data) =>
  match(data)
    .returnType<string>() // Specify return type
    .with({ status: 'approved', priority: 'high' }, () => 'Fast track')
    .narrow() // Narrow remaining cases
    .when(
      (d) => d.value > 1000, // Custom predicate
      () => 'High value item'
    )
    .with({ status: 'rejected' }, () => 'Rejected')
    .exhaustive(); // Ensure all cases covered

// ✅ Good: Exhaustiveness checking
match(status)
  .with('idle', ...)
  .with('loading', ...)
  .exhaustive();
 
// ❌ Avoid in production
match(status)
  .with('idle', ...)
  .run(); // May throw at runtime

// ✅ Good: Return type is explicit
function getUserRole(user: User): 'admin' | 'user' | 'guest' {
  return match(user)
    .returnType<'admin' | 'user' | 'guest'>()
    .with({ role: 'admin' }, () => 'admin')
    .with({ role: 'user' }, () => 'user')
    .otherwise(() => 'guest');
}

// ✅ Good: Narrow for precise types in .otherwise()
match(complexUnion)
  .with(specificCase1, ...)
  .with(specificCase2, ...)
  .narrow()
  .otherwise((remaining) => {
    // remaining is precisely typed
  });