Pattern Matching

Pattern matching is a method that allows developers to handle intricate conditions within a single, concise expression. It simplifies code, making it more concise and easier to understand. Additionally, it includes a process called exhaustiveness checking, which helps to ensure that no possible case has been overlooked.

Originating from functional programming languages, pattern matching stands as a powerful technique for code branching. It often offers a more potent and less verbose solution compared to imperative alternatives such as if/else or switch statements, particularly when dealing with complex conditions.

Although not yet a native feature in JavaScript, there’s an ongoing tc39 proposal in its early stages to introduce pattern matching to JavaScript. However, this proposal is at stage 1 and might take several years to be implemented. Nonetheless, developers can implement pattern matching in their codebase. The effect/Match module provides a reliable, type-safe pattern matching implementation that is available for immediate use.

Example (Handling Different Data Types with Pattern Matching)

1
import { Match } from "effect"
2

3
// Simulated dynamic input that can be a string or a number
4
const input: string | number = "some input"
5

6
//      ┌─── string
7
//      ▼
8
const result = Match.value(input).pipe(
9
  // Match if the value is a number
10
  Match.when(Match.number, (n) => `number: ${n}`),
11
  // Match if the value is a string
12
  Match.when(Match.string, (s) => `string: ${s}`),
13
  // Ensure all possible cases are covered
14
  Match.exhaustive,
15
)
16

17
console.log(result)
18
// Output: "string: some input"

How Pattern Matching Works

Pattern matching follows a structured process:

Creating a matcher. Define a Matcher that operates on either a specific type or value.
Defining patterns. Use combinators such as Match.when, Match.not, and Match.tag to specify matching conditions.
Completing the match. Apply a finalizer such as Match.exhaustive, Match.orElse, or Match.option to determine how unmatched cases should be handled.

Creating a matcher

You can create a Matcher using either:

Match.type<T>(): Matches against a specific type.
Match.value(value): Matches against a specific value.

Matching by Type

The Match.type constructor defines a Matcher that operates on a specific type. Once created, you can use patterns like Match.when to define conditions for handling different cases.

Example (Matching Numbers and Strings)

1
import { Match } from "effect"
2

3
// Create a matcher for values that are either strings or numbers
4
//
5
//      ┌─── (u: string | number) => string
6
//      ▼
7
const match = Match.type<string | number>().pipe(
8
  // Match when the value is a number
9
  Match.when(Match.number, (n) => `number: ${n}`),
10
  // Match when the value is a string
11
  Match.when(Match.string, (s) => `string: ${s}`),
12
  // Ensure all possible cases are handled
13
  Match.exhaustive,
14
)
15

16
console.log(match(0))
17
// Output: "number: 0"
18

19
console.log(match("hello"))
20
// Output: "string: hello"

Matching by Value

Instead of creating a matcher for a type, you can define one directly from a specific value using Match.value.

Example (Matching an Object by Property)

1
import { Match } from "effect"
2

3
const input = { name: "John", age: 30 }
4

5
// Create a matcher for the specific object
6
const result = Match.value(input).pipe(
7
  // Match when the 'name' property is "John"
8
  Match.when({ name: "John" }, (user) => `${user.name} is ${user.age} years old`),
9
  // Provide a fallback if no match is found
10
  Match.orElse(() => "Oh, not John"),
11
)
12

13
console.log(result)
14
// Output: "John is 30 years old"

Enforcing a Return Type

You can use Match.withReturnType<T>() to ensure that all branches return a specific type.

Example (Validating Return Type Consistency)

This example enforces that every matching branch returns a string.

1
import { Match } from "effect"
2

3
const match = Match.type<{ a: number } | { b: string }>().pipe(
4
  // Ensure all branches return a string
5
  Match.withReturnType<string>(),
6
  // ❌ Type error: returns a number
7
  // @errors: 2322
8
  Match.when({ a: Match.number }, (_) => _.a),
9
  // ✅ Correct: returns a string
10
  Match.when({ b: Match.string }, (_) => _.b),
11
  Match.exhaustive,
12
)

Defining patterns

when

The Match.when function allows you to define conditions for matching values. It supports both direct value comparisons and predicate functions.

Example (Matching with Values and Predicates)

1
import { Match } from "effect"
2

3
// Create a matcher for objects with an "age" property
4
const match = Match.type<{ age: number }>().pipe(
5
  // Match when age is greater than 18
6
  Match.when({ age: (age) => age > 18 }, (user) => `Age: ${user.age}`),
7
  // Match when age is exactly 18
8
  Match.when({ age: 18 }, () => "You can vote"),
9
  // Fallback case for all other ages
10
  Match.orElse((user) => `${user.age} is too young`),
11
)
12

13
console.log(match({ age: 20 }))
14
// Output: "Age: 20"
15

16
console.log(match({ age: 18 }))
17
// Output: "You can vote"
18

19
console.log(match({ age: 4 }))
20
// Output: "4 is too young"

not

The Match.not function allows you to exclude specific values while matching all others.

Example (Ignoring a Specific Value)

1
import { Match } from "effect"
2

3
// Create a matcher for string or number values
4
const match = Match.type<string | number>().pipe(
5
  // Match any value except "hi", returning "ok"
6
  Match.not("hi", () => "ok"),
7
  // Fallback case for when the value is "hi"
8
  Match.orElse(() => "fallback"),
9
)
10

11
console.log(match("hello"))
12
// Output: "ok"
13

14
console.log(match("hi"))
15
// Output: "fallback"

tag

The Match.tag function allows pattern matching based on the _tag field in a Discriminated Union. You can specify multiple tags to match within a single pattern.

Example (Matching a Discriminated Union by Tag)

1
import { Match } from "effect"
2

3
type Event =
4
  | { readonly _tag: "fetch" }
5
  | { readonly _tag: "success"; readonly data: string }
6
  | { readonly _tag: "error"; readonly error: Error }
7
  | { readonly _tag: "cancel" }
8

9
// Create a Matcher for Either<number, string>
10
const match = Match.type<Event>().pipe(
11
  // Match either "fetch" or "success"
12
  Match.tag("fetch", "success", () => `Ok!`),
13
  // Match "error" and extract the error message
14
  Match.tag("error", (event) => `Error: ${event.error.message}`),
15
  // Match "cancel"
16
  Match.tag("cancel", () => "Cancelled"),
17
  Match.exhaustive,
18
)
19

20
console.log(match({ _tag: "success", data: "Hello" }))
21
// Output: "Ok!"
22

23
console.log(match({ _tag: "error", error: new Error("Oops!") }))
24
// Output: "Error: Oops!"

Built-in Predicates

The Match module provides built-in predicates for common types, such as Match.number, Match.string, and Match.boolean. These predicates simplify the process of matching against primitive types.

Example (Using Built-in Predicates for Property Keys)

1
import { Match } from "effect"
2

3
const matchPropertyKey = Match.type<PropertyKey>().pipe(
4
  // Match when the value is a number
5
  Match.when(Match.number, (n) => `Key is a number: ${n}`),
6
  // Match when the value is a string
7
  Match.when(Match.string, (s) => `Key is a string: ${s}`),
8
  // Match when the value is a symbol
9
  Match.when(Match.symbol, (s) => `Key is a symbol: ${String(s)}`),
10
  // Ensure all possible cases are handled
11
  Match.exhaustive,
12
)
13

14
console.log(matchPropertyKey(42))
15
// Output: "Key is a number: 42"
16

17
console.log(matchPropertyKey("username"))
18
// Output: "Key is a string: username"
19

20
console.log(matchPropertyKey(Symbol("id")))
21
// Output: "Key is a symbol: Symbol(id)"

Predicate	Description
`Match.string`	Matches values of type `string`.
`Match.nonEmptyString`	Matches non-empty strings.
`Match.number`	Matches values of type `number`.
`Match.boolean`	Matches values of type `boolean`.
`Match.bigint`	Matches values of type `bigint`.
`Match.symbol`	Matches values of type `symbol`.
`Match.date`	Matches values that are instances of `Date`.
`Match.record`	Matches objects where keys are `string` or `symbol` and values are `unknown`.
`Match.null`	Matches the value `null`.
`Match.undefined`	Matches the value `undefined`.
`Match.defined`	Matches any defined (non-null and non-undefined) value.
`Match.any`	Matches any value without restrictions.
`Match.is(...values)`	Matches a specific set of literal values (e.g., `Match.is("a", 42, true)`).
`Match.instanceOf(Class)`	Matches instances of a given class.

Completing the match

exhaustive

The Match.exhaustive method finalizes the pattern matching process by ensuring that all possible cases are accounted for. If any case is missing, TypeScript will produce a type error. This is particularly useful when working with unions, as it helps prevent unintended gaps in pattern matching.

Example (Ensuring All Cases Are Covered)

1
import { Match } from "effect"
2

3
// Create a matcher for string or number values
4
const match = Match.type<string | number>().pipe(
5
  // Match when the value is a number
6
  Match.when(Match.number, (n) => `number: ${n}`),
7
  // Mark the match as exhaustive, ensuring all cases are handled
8
  // TypeScript will throw an error if any case is missing
9
  // @errors: 2345
10
  Match.exhaustive,
11
)

orElse

The Match.orElse method defines a fallback value to return when no other patterns match. This ensures that the matcher always produces a valid result.

Example (Providing a Default Value When No Patterns Match)

1
import { Match } from "effect"
2

3
// Create a matcher for string or number values
4
const match = Match.type<string | number>().pipe(
5
  // Match when the value is "a"
6
  Match.when("a", () => "ok"),
7
  // Fallback when no patterns match
8
  Match.orElse(() => "fallback"),
9
)
10

11
console.log(match("a"))
12
// Output: "ok"
13

14
console.log(match("b"))
15
// Output: "fallback"

option

Match.option wraps the match result in an Option. If a match is found, it returns Some(value), otherwise, it returns None.

Example (Extracting a User Role with Option)

1
import { Match } from "effect"
2

3
type User = { readonly role: "admin" | "editor" | "viewer" }
4

5
// Create a matcher to extract user roles
6
const getRole = Match.type<User>().pipe(
7
  Match.when({ role: "admin" }, () => "Has full access"),
8
  Match.when({ role: "editor" }, () => "Can edit content"),
9
  Match.option, // Wrap the result in an Option
10
)
11

12
console.log(getRole({ role: "admin" }))
13
// Output: { _id: 'Option', _tag: 'Some', value: 'Has full access' }
14

15
console.log(getRole({ role: "viewer" }))
16
// Output: { _id: 'Option', _tag: 'None' }

either

The Match.either method wraps the result in an Either, providing a structured way to distinguish between matched and unmatched cases. If a match is found, it returns Right(value), otherwise, it returns Left(no match).

Example (Extracting a User Role with Either)

1
import { Match } from "effect"
2

3
type User = { readonly role: "admin" | "editor" | "viewer" }
4

5
// Create a matcher to extract user roles
6
const getRole = Match.type<User>().pipe(
7
  Match.when({ role: "admin" }, () => "Has full access"),
8
  Match.when({ role: "editor" }, () => "Can edit content"),
9
  Match.either, // Wrap the result in an Either
10
)
11

12
console.log(getRole({ role: "admin" }))
13
// Output: { _id: 'Either', _tag: 'Right', right: 'Has full access' }
14

15
console.log(getRole({ role: "viewer" }))
16
// Output: { _id: 'Either', _tag: 'Left', left: { role: 'viewer' } }