TypeScript Pattern Matching Library

Common errors

• Property 'run' does not exist on type 'PatternMatcher<...>'

  cause The `.run()` method, which executes the pattern matching, was omitted from the method chain.
  fix Ensure that every pattern matching chain explicitly ends with `.run()` or `.otherwise()`.

• Argument of type '...' is not assignable to parameter of type '...'

  cause Type inference issues or a pattern not precisely matching the expected input type, often when `any` is not explicitly used or when patterns are too broad/narrow.
  fix Review the type definitions of your input and patterns. Explicitly cast types if necessary, or simplify patterns to ensure clearer type inference. For complex types, consider using type predicates in custom `when` clauses.

Warnings

• breaking This library has not been updated since December 2019, making it potentially incompatible with newer TypeScript versions or modern module resolutions (ESM, NodeNext).
  Fix: Consider migrating to more actively maintained pattern matching libraries like `ts-pattern` for better compatibility, features, and continued support.
• gotcha The library explicitly requires TypeScript 3.7.3 or higher. Using older TypeScript versions will result in compilation errors or unexpected behavior due to advanced type features utilized.
  Fix: Ensure your project uses TypeScript version 3.7.3 or newer in `tsconfig.json`.
• gotcha Unlike some modern pattern matching libraries, `typescript-pattern-matching` does not offer compile-time exhaustiveness checking for all possible cases. This means it's possible to miss a case without a TypeScript error, potentially leading to runtime issues if `.otherwise()` is not used.
  Fix: Always include an `.otherwise()` clause or thoroughly review your patterns to ensure all possible input shapes are handled.

Install

• npm install typescript-pattern-matching npm
• yarn add typescript-pattern-matching yarn
• pnpm add typescript-pattern-matching pnpm

Imports

• match
  wrong:

  const match = require('typescript-pattern-matching')

  correct:

  import { match } from 'typescript-pattern-matching'

  The library primarily uses ES Module imports. CommonJS `require` syntax is generally not recommended in modern TypeScript projects and may not be fully supported for type inference.
• match().with()
  wrong:

  match(value, pattern, handler)

  correct:

  match(value).with(pattern, handler).run()

  The pattern matching API is fluent, requiring method chaining starting with `match(value)`, followed by one or more `.with(pattern, handler)` clauses, and terminated by `.run()` or `.otherwise()`.

Quickstart

This quickstart demonstrates basic pattern matching on a discriminated union (`Option<T>`) and using `.otherwise()` for a default case.

import { match } from 'typescript-pattern-matching';

type Option<T> = { kind: 'none' } | { kind: 'some', value: T };

/**
 * Processes an Option type using pattern matching to extract its value
 * or handle the 'none' case.
 */
function processOption<T>(opt: Option<T>): T | string {
  const result = match(opt)
    .with({ kind: 'some' }, o => `Value is: ${o.value}`)
    .with({ kind: 'none' }, () => 'No value present.')
    .run();
  return result as T | string; // Type assertion needed for example simplicity
}

const someValue: Option<string> = { kind: 'some', value: 'hello world' };
const noneValue: Option<number> = { kind: 'none' };

console.log(processOption(someValue));
console.log(processOption(noneValue));

// Example demonstrating .otherwise() for a default case
const unknownValue = { type: 'unknown' };
const processedUnknown = match(unknownValue)
  .with({ type: 'known' }, v => `Known type: ${v.type}`)
  .otherwise(() => 'Unknown type encountered.')
  .run();

console.log(processedUnknown);