Match

Completes a matcher that handles every remaining input case.

When to use

Use to require TypeScript to reject incomplete matcher definitions before the matcher is turned into a function.

Details

If any case is still unmatched, the matcher does not type-check as exhaustive.

Wraps the match result in an Option, representing an optional match.

When to use

Use to finalize a matcher when unmatched input is expected and should become Option.none.

Details

This function ensures that the result of a matcher is wrapped in an Option, making it easy to handle cases where no pattern matches. If a match is found, it returns Some(value), otherwise, it returns None.

This is useful in cases where a missing match is expected and should be handled explicitly rather than throwing an error or returning a default value.

See

• result for preserving unmatched input as a Result failure
• orElse for replacing unmatched input with a fallback value

Provides a fallback value when no patterns match.

When to use

Use to finalize a matcher with a fallback for unmatched input.

Details

This function ensures that a matcher always returns a valid result, even if no defined patterns match. It acts as a default case, similar to the default clause in a switch statement or the final else in an if-else chain.

See

• option for finalizing unmatched input as Option.none
• result for returning unmatched input as a Result failure
• orElseAbsurd for finalizing when unmatched input should be impossible

Returns a matcher that throws an error if no pattern matches.

When to use

Use to finalize a matcher when every remaining unmatched case should be impossible.

Details

This function finalizes a matcher by ensuring that if no patterns match, an error is thrown. It is useful when all cases should be covered, and any unexpected input should trigger an error instead of returning a default value.

When used, this function removes the need for an explicit fallback case and ensures that an unmatched value is never silently ignored.

See

• exhaustive for compile-time exhaustive matcher finalization
• orElse for providing a fallback for unmatched input

Wraps the match result in a Result, distinguishing matched and unmatched cases.

Details

This function ensures that the result of a matcher is always wrapped in an Result, allowing clear differentiation between successful matches (Ok(value)) and cases where no pattern matched (Err(unmatched value)).

This approach is particularly useful when handling optional values or when an unmatched case should be explicitly handled rather than returning a default value or throwing an error.

Creates a matcher for a specific type.

When to use

Use to build a reusable matcher function for values of a known input type.

Details

This function defines a Matcher that operates on a given type, allowing you to specify conditions for handling different cases. Once the matcher is created, you can use pattern-matching functions like when to define how different values should be processed.

See

• value for creating a matcher from a specific value.

Creates a type-safe match function for discriminated unions based on _tag field.

Details

This function allows you to define exhaustive pattern matching for discriminated unions by providing handlers for each possible _tag value. It ensures type safety and can optionally enforce a specific return type across all branches.

Creates a matcher from a specific value.

When to use

Use to match one concrete input immediately.

Details

This function allows you to define a Matcher directly from a given value, rather than from a type. This is useful when working with known values, enabling structured pattern matching on objects, primitives, or any data structure.

Once the matcher is created, you can use pattern-matching functions like when to define how different cases should be handled.

See

• type for creating a matcher from a specific type.

Creates a match function for a specific value with discriminated union handling.

Details

This function provides a convenient way to pattern match on discriminated unions by providing an object that maps each _tag value to its corresponding handler. It's similar to a switch statement but with better type safety and exhaustiveness checking.

Matches values based on a specified discriminant field.

When to use

Use to match one or more exact values of a discriminator field.

Details

This function is used to define pattern matching on objects that follow a discriminated union structure, where a specific field (e.g., type, kind, _tag) determines the variant of the object. It allows matching multiple values of the discriminant and provides a function to handle the matched cases.

See

• discriminators for defining several discriminator handlers at once
• discriminatorStartsWith for matching string discriminator values by prefix

Matches values based on a field that serves as a discriminator, mapping each possible value to a corresponding handler.

When to use

Use to define several discriminator handlers at once without finalizing the matcher.

Details

This function simplifies working with discriminated unions by letting you define a set of handlers for each possible value of a given field. Instead of chaining multiple calls to discriminator, this function allows defining all possible cases at once using an object where the keys are the possible values of the field, and the values are the corresponding handler functions.

See

• discriminator for adding one discriminator case to a matcher pipeline
• discriminatorsExhaustive for handling every discriminator value and finalizing the matcher

Matches values by a discriminator field and requires every possible case to be handled.

When to use

Use to define an exhaustive discriminator handler map that finalizes the matcher.

Details

This is the exhaustive variant of discriminators. Each possible discriminator value must have a corresponding handler, so the matcher is finalized directly and does not require Match.exhaustive at the end of the pipeline.

See

• discriminators for defining discriminator handlers without finalizing the matcher

Matches values where a specified field starts with a given prefix.

When to use

Use to match string discriminator values by prefix instead of exact value.

Details

Instead of checking for exact matches, this helper matches values that share a common prefix. For example, if the discriminant field contains hierarchical names like "A", "A.A", and "B", a single "A" rule can match both "A" and "A.A".

See

• discriminator for matching exact discriminator values

Creates a pattern that excludes a specific value while allowing all others.

When to use

Use to add a negative pattern case for inputs that should match when another pattern does not.

Details

Any excluded value bypasses the provided function and continues matching through later cases.

See

• when for adding a positive pattern case

Matches discriminated union members by their _tag field.

When to use

Use to handle one or more _tag cases with the same matcher branch.

Details

This helper follows the Effect convention that discriminated unions use "_tag" as their discriminator field. Use discriminator for a different discriminator field.

Matches values based on their _tag field, mapping each tag to a corresponding handler.

Details

This function provides a way to handle discriminated unions by mapping _tag values to specific functions. Each handler receives the matched value and returns a transformed result. If all possible tags are handled, you can enforce exhaustiveness using Match.exhaustive to ensure no case is missed.

Matches values based on their _tag field and requires handling of all possible cases.

Details

This function is designed for discriminated unions where every possible _tag value must have a corresponding handler. Unlike tags, this function ensures exhaustiveness, meaning all cases must be explicitly handled. If a _tag value is missing from the mapping, TypeScript will report an error.

Matches values where the _tag field starts with a given prefix.

Details

This function allows you to match on values in a discriminated union based on whether the _tag field starts with a specified prefix. It is useful for handling hierarchical or namespaced tags, where multiple related cases share a common prefix.

Defines a condition for matching values.

When to use

Use to add one positive pattern case to a Match.type or Match.value pipeline when a direct value, predicate, or structured object pattern should run a handler for matching input.

Details

Supports both direct value comparisons and predicate functions. If the pattern matches, the associated function is executed and the matched input is removed from the remaining cases tracked by the matcher.

See

• whenOr for handling any one of several patterns with the same handler
• whenAnd for requiring all provided patterns to match before running a handler
• not for handling inputs that do not match a pattern
• orElse for providing a fallback when no pattern case matches

Matches a value that satisfies all provided patterns.

Details

This function allows defining a condition where a value must match all the given patterns simultaneously. If the value satisfies every pattern, the associated function is executed.

Unlike when, which matches a single pattern at a time, this function ensures that multiple conditions are met before executing the callback. It is useful when checking for values that need to fulfill multiple criteria at once.

Matches one of multiple patterns in a single condition.

Details

This function allows defining a condition where a value matches any of the provided patterns. If a match is found, the associated function is executed. It simplifies cases where multiple patterns share the same handling logic.

Unlike when, which requires separate conditions for each pattern, this function enables combining them into a single statement, making the matcher more concise.

Matches any value without restrictions.

When to use

Use to define an explicit catch-all pattern when the handler should receive the unmatched value.

Details

This predicate matches every input, including undefined, null, objects, primitives, and functions.

Gotchas

Match.any should usually be last because cases are checked in order and the first matching case wins.

See

• defined for matching only non-nullish values
• orElse for providing a fallback after earlier cases

Matches values of type bigint.

When to use

Use to match primitive bigint values.

Details

This predicate refines unknown values to bigints, allowing pattern matching on bigint types. BigInts are used for representing integers with arbitrary precision.

See

• number for matching primitive number values

Matches values of type boolean.

When to use

Use to match primitive boolean values.

Details

This predicate refines unknown values to booleans, allowing pattern matching on boolean types. It only matches the primitive boolean values true and false.

See

• is for matching specific literal boolean values

Matches values that are instances of Date.

When to use

Use to match Date instances.

Details

This predicate refines unknown values to Date instances, allowing pattern matching on Date objects. It only matches actual Date instances, not date strings or timestamps.

See

• instanceOf for matching instances of any constructor

Matches any defined (non-null and non-undefined) value.

When to use

Use to exclude only null and undefined from a match branch.

Details

This predicate matches values that are neither null nor undefined, effectively filtering out nullish values while preserving all other types.

See

• any for matching every value without excluding nullish inputs

Matches instances of a given class.

When to use

Use to match values that are instances of a constructor with type-safe narrowing.

Details

This predicate checks if a value is an instance of the specified constructor, providing type-safe matching for class instances and built-in objects.

See

• instanceOfUnsafe for constructor matching without the same type-safety guarantee
• record for matching broad non-null, non-array objects

Checks whether a value is an instance of a constructor without type-safe narrowing.

When to use

Use when you need constructor matching to use the unsafe refinement type.

Details

This predicate checks if a value is an instance of the specified constructor but doesn't provide the same type safety guarantees as the regular instanceOf. Use this when you need more flexibility but understand the type safety implications.

See

• instanceOf for type-safe constructor matching

Matches a specific set of literal values (e.g., Match.is("a", 42, true)).

When to use

Use to match one of several literal primitive or null values.

Details

This function creates a predicate that matches any of the provided literal values. It's useful for matching against multiple specific values in a single pattern.

Matches non-empty strings.

When to use

Use to match strings whose length is greater than zero.

Details

This predicate matches any string that contains at least one character, effectively filtering out empty strings ("").

See

• string for matching any string

Matches values of type number.

When to use

Use to match primitive number values, including NaN and infinities.

Details

This predicate refines unknown values to numbers, allowing pattern matching on numeric types. It matches all number values including integers, floats, Infinity, -Infinity, and NaN.

See

• bigint for matching primitive bigint values

Matches non-null objects other than arrays.

When to use

Use to match broad non-null, non-array object values.

Details

This predicate uses Predicate.isObject: it returns true for values whose runtime type is "object", are not null, and are not arrays. It can match Date, RegExp, and class instances; use instanceOf or a more specific pattern when those cases need to be distinguished.

See

• instanceOf for matching a specific constructor

Matches values of type string.

Details

This predicate refines unknown values to strings, allowing pattern matching on string types. It's commonly used in type-based matchers to handle string cases.

Matches values of type symbol.

Details

This predicate refines unknown values to symbols, allowing pattern matching on symbol types. Symbols are unique identifiers that are often used as object keys or for creating private properties.

Represents a single pattern matching case.

When to use

Use as the common public type for code that needs to inspect, store, or pass either positive or negative pattern matching cases.

Details

A Case can be either a positive match (When) or a negative match (Not). Cases are the building blocks of pattern matching logic and determine how values are tested and transformed.

See

• When for positive cases
• Not for negative cases

Union type for matchers created by Match.type and Match.value.

Details

A Matcher carries the input type, accumulated filters, remaining cases, result type, and, for value matchers, the provided value being matched.

Represents a negative pattern matching case.

Details

A Not case contains the logic to test if a value does NOT match a specific pattern and the function to evaluate when the pattern doesn't match. It's used for exclusion-based pattern matching.

A safe refinement that narrows types without runtime errors.

Details

SafeRefinement provides a way to refine types in pattern matching while maintaining type safety. Unlike regular predicates, safe refinements can transform the matched value's type without throwing runtime errors.

Represents a pattern matcher that operates on types rather than specific values.

Details

A TypeMatcher is created when using Match.type<T>() and allows you to define patterns that will be applied to values of the specified type. It maintains type-level information about the input type, applied filters, remaining cases, and expected results.

Represents a pattern matcher that operates on a specific provided value.

Details

A ValueMatcher is created when using Match.value(someValue) and contains the actual value to be matched against. It tracks both the provided value and the result of applying patterns to determine matches.

Represents a positive pattern matching case.

Details

A When case contains the logic to test if a value matches a specific pattern and the function to evaluate when the pattern matches. It's the primary building block for pattern matching conditions.

A namespace containing utility types for Match operations.

Details

This namespace provides advanced type-level utilities used internally by the Match module to perform complex pattern matching, type narrowing, and filter application. These types enable the sophisticated type inference that makes pattern matching both type-safe and ergonomic.

Ensures that all branches of a matcher return a specific type.

Details

This function enforces a consistent return type across all pattern-matching branches. By specifying a return type, TypeScript will check that every matching condition produces a value of the expected type.

Important: This function must be the first step in the matcher pipeline. If used later, TypeScript will not enforce type consistency correctly.