effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/Match.ts

@@ -1,28 +1,46 @@
 /**
- * The `effect/match` module provides a type-safe pattern matching system for
- * TypeScript. Inspired by functional programming, it simplifies conditional
- * logic by replacing verbose if/else or switch statements with a structured and
- * expressive API.
+ * Pattern matching for TypeScript values, predicates, and tagged unions.
  *
- * This module supports matching against types, values, and discriminated unions
- * while enforcing exhaustiveness checking to ensure all cases are handled.
+ * `Match` turns branching logic into a matcher that is built from ordered
+ * cases and finished with an explicit finalizer. Use `Match.type` to define a
+ * reusable matcher for a type, or `Match.value` to classify one value
+ * immediately. Cases can match literal values, predicates, object patterns,
+ * discriminators, tags, or negated patterns.
  *
- * Although pattern matching is not yet a native JavaScript feature,
- * `effect/match` offers a reliable implementation that is available today.
+ * **Mental model**
  *
- * **How Pattern Matching Works**
+ * A matcher checks cases in the order they are added and evaluates the handler
+ * for the first match. Type matchers produce a function that can be reused with
+ * different inputs, while value matchers already contain the input value. As
+ * cases are added, the type system tracks which inputs remain unmatched, so
+ * `Match.exhaustive` is only available when every remaining case has been
+ * handled.
  *
- * Pattern matching follows a structured process:
+ * **Common tasks**
  *
- * - **Creating a matcher**: Define a `Matcher` that operates on either a
- *   specific `Match.type` or `Match.value`.
+ * - Use `Match.type<Union>()` when a branch table should be reusable and
+ *   exhaustiveness-checked.
+ * - Use `Match.value(value)` when a single value should be matched immediately.
+ * - Use `Match.tag`, `Match.tags`, or `Match.discriminator` for discriminated
+ *   unions and domain objects with tag fields.
+ * - Use `Match.orElse`, `Match.option`, or `Match.result` when unmatched input
+ *   should be handled explicitly instead of requiring full exhaustiveness.
  *
- * - **Defining patterns**: Use combinators such as `Match.when`, `Match.not`,
- *   and `Match.tag` to specify matching conditions.
+ * **Example** (Matching a tagged union)
  *
- * - **Completing the match**: Apply a finalizer such as `Match.exhaustive`,
- *   `Match.orElse`, or `Match.option` to determine how unmatched cases should
- *   be handled.
+ * ```ts
+ * import { Match } from "effect"
+ *
+ * type Event =
+ *   | { readonly _tag: "UserCreated"; readonly id: string }
+ *   | { readonly _tag: "UserDeleted"; readonly id: string }
+ *
+ * const describe = Match.type<Event>().pipe(
+ *   Match.tag("UserCreated", (event) => `created ${event.id}`),
+ *   Match.tag("UserDeleted", (event) => `deleted ${event.id}`),
+ *   Match.exhaustive
+ * )
+ * ```
  *
  * @since 4.0.0
  */
@@ -163,12 +181,20 @@ export interface ValueMatcher<in Input, Filters, out Remaining, out Result, Prov
 /**
  * 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 {@link When} for positive cases
+ * @see {@link Not} for negative cases
+ *
  * @category models
  * @since 4.0.0
  */
@@ -245,6 +271,10 @@ export interface Not {
 /**
  * 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
@@ -287,6 +317,10 @@ export const type: <I>() => Matcher<I, Types.Without<never>, I, never, never> =
 /**
  * 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,
@@ -629,16 +663,17 @@ export const withReturnType: <Ret>() => <I, F, R, A, Pr, _>(
 /**
  * Defines a condition for matching values.
  *
- * **Details**
+ * **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.
  *
- * This function enables pattern matching by checking whether a given value
- * satisfies a condition. It supports both direct value comparisons and
- * predicate functions. If the condition is met, the associated function is
- * executed.
+ * **Details**
  *
- * This function is useful when defining matchers that need to check for
- * specific values or apply logical conditions to determine a match. It works
- * well with structured objects and primitive types.
+ * 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.
  *
  * **Example** (Matching with Values and Predicates)
  *
@@ -668,10 +703,10 @@ export const withReturnType: <Ret>() => <I, F, R, A, Pr, _>(
  * // Output: "4 is too young"
  * ```
  *
- * @see {@link whenOr} Use this when multiple patterns should match in a single
- * condition.
- * @see {@link whenAnd} Use this when a value must match all provided patterns.
- * @see {@link orElse} Provides a fallback when no patterns match.
+ * @see {@link whenOr} for handling any one of several patterns with the same handler
+ * @see {@link whenAnd} for requiring all provided patterns to match before running a handler
+ * @see {@link not} for handling inputs that do not match a pattern
+ * @see {@link orElse} for providing a fallback when no pattern case matches
  *
  * @category Defining patterns
  * @since 4.0.0
@@ -816,6 +851,10 @@ export const whenAnd: <
 /**
  * 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
@@ -842,6 +881,9 @@ export const whenAnd: <
  * )
  * ```
  *
+ * @see {@link discriminators} for defining several discriminator handlers at once
+ * @see {@link discriminatorStartsWith} for matching string discriminator values by prefix
+ *
  * @category Defining patterns
  * @since 4.0.0
  */
@@ -863,17 +905,16 @@ export const discriminator: <D extends string>(
 /**
  * Matches values where a specified field starts with a given prefix.
  *
- * **Details**
+ * **When to use**
+ *
+ * Use to match string discriminator values by prefix instead of exact value.
  *
- * This function is useful for working with discriminated unions where the
- * discriminant field follows a hierarchical or namespaced structure. It allows
- * you to match values based on whether the specified field starts with a given
- * prefix, making it easier to handle grouped cases.
+ * **Details**
  *
- * Instead of checking for exact matches, this function lets you match values
- * that share a common prefix. For example, if your discriminant field contains
- * hierarchical names like `"A"`, `"A.A"`, and `"B"`, you can match all values
- * starting with `"A"` using a single rule.
+ * 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"`.
  *
  * **Example** (Matching discriminator prefixes)
  *
@@ -892,6 +933,8 @@ export const discriminator: <D extends string>(
  * console.log(match({ type: "A.A" })) // 1
  * ```
  *
+ * @see {@link discriminator} for matching exact discriminator values
+ *
  * @category Defining patterns
  * @since 4.0.0
  */
@@ -915,6 +958,11 @@ export const discriminatorStartsWith: <D extends string>(
  * 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
@@ -945,6 +993,9 @@ export const discriminatorStartsWith: <D extends string>(
  * )
  * ```
  *
+ * @see {@link discriminator} for adding one discriminator case to a matcher pipeline
+ * @see {@link discriminatorsExhaustive} for handling every discriminator value and finalizing the matcher
+ *
  * @category Defining patterns
  * @since 4.0.0
  */
@@ -973,6 +1024,11 @@ export const discriminators: <D extends string>(
  * 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 {@link discriminators}. Each possible
@@ -1000,6 +1056,8 @@ export const discriminators: <D extends string>(
  * )
  * ```
  *
+ * @see {@link discriminators} for defining discriminator handlers without finalizing the matcher
+ *
  * @category Defining patterns
  * @since 4.0.0
  */
@@ -1019,15 +1077,17 @@ export const discriminatorsExhaustive: <D extends string>(
   internal.discriminatorsExhaustive
 
 /**
- * The `Match.tag` function allows pattern matching based on the `_tag` field in
- * a [Discriminated Union](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes-func.html#discriminated-unions).
- * You can specify multiple tags to match within a single pattern.
+ * 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**
  *
- * The `Match.tag` function relies on the convention within the Effect ecosystem
- * of naming the tag field as `"_tag"`. Ensure that your discriminated unions
- * follow this naming convention for proper functionality.
+ * This helper follows the Effect convention that discriminated unions use
+ * `"_tag"` as their discriminator field. Use {@link discriminator} for a
+ * different discriminator field.
  *
  * **Example** (Matching a Discriminated Union by Tag)
  *
@@ -1230,15 +1290,17 @@ export const tagsExhaustive: <
   internal.tagsExhaustive
 
 /**
- * Excludes a specific value from matching while allowing all others.
+ * 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**
  *
- * This function is useful when you need to **handle all values except one or
- * more specific cases**. Instead of listing all possible matches manually, this
- * function simplifies the logic by allowing you to specify values to exclude.
- * Any excluded value will bypass the provided function and continue matching
- * through other cases.
+ * Any excluded value bypasses the provided function and continues matching
+ * through later cases.
  *
  * **Example** (Ignoring a Specific Value)
  *
@@ -1260,6 +1322,8 @@ export const tagsExhaustive: <
  * // Output: "fallback"
  * ```
  *
+ * @see {@link when} for adding a positive pattern case
+ *
  * @category Defining patterns
  * @since 4.0.0
  */
@@ -1285,6 +1349,10 @@ export const not: <
 /**
  * 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,
@@ -1311,6 +1379,8 @@ export const not: <
  * // Output: "Valid input:    " (whitespace-only strings are considered non-empty)
  * ```
  *
+ * @see {@link string} for matching any string
+ *
  * @category Predicates
  * @since 4.0.0
  */
@@ -1319,6 +1389,10 @@ export const nonEmptyString: SafeRefinement<string, never> = internal.nonEmptySt
 /**
  * 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.
@@ -1393,6 +1467,10 @@ export const string: Predicate.Refinement<unknown, string> = Predicate.isString
 /**
  * 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
@@ -1420,6 +1498,8 @@ export const string: Predicate.Refinement<unknown, string> = Predicate.isString
  * console.log(categorizeNumber("hello")) // "Not a number type"
  * ```
  *
+ * @see {@link bigint} for matching primitive bigint values
+ *
  * @category predicates
  * @since 4.0.0
  */
@@ -1428,11 +1508,20 @@ export const number: Predicate.Refinement<unknown, number> = Predicate.isNumber
 /**
  * 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 absolutely any value, including `undefined`, `null`,
- * objects, primitives, functions, etc. It's useful as a catch-all pattern
- * or when you need to match any remaining cases.
+ * 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.
  *
  * **Example** (Matching any remaining value)
  *
@@ -1461,6 +1550,9 @@ export const number: Predicate.Refinement<unknown, number> = Predicate.isNumber
  * // Output: "Other: object"
  * ```
  *
+ * @see {@link defined} for matching only non-nullish values
+ * @see {@link orElse} for providing a fallback after earlier cases
+ *
  * @category Predicates
  * @since 4.0.0
  */
@@ -1469,6 +1561,10 @@ export const any: SafeRefinement<unknown, any> = internal.any
 /**
  * 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`,
@@ -1504,6 +1600,8 @@ export const any: SafeRefinement<unknown, any> = internal.any
  * // Output: "Value is null or undefined"
  * ```
  *
+ * @see {@link any} for matching every value without excluding nullish inputs
+ *
  * @category Predicates
  * @since 4.0.0
  */
@@ -1512,6 +1610,10 @@ export const defined: <A>(u: A) => u is A & {} = internal.defined
 /**
  * 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
@@ -1539,6 +1641,8 @@ export const defined: <A>(u: A) => u is A & {} = internal.defined
  * console.log(describeTruthiness(1)) // "Some other truthy value"
  * ```
  *
+ * @see {@link is} for matching specific literal boolean values
+ *
  * @category predicates
  * @since 4.0.0
  */
@@ -1549,6 +1653,18 @@ export {
   /**
    * Matches the value `undefined`.
    *
+   * **When to use**
+   *
+   * Use when a matcher should handle only inputs with no defined value.
+   *
+   * **Details**
+   *
+   * This refinement is backed by `Predicate.isUndefined`, which checks
+   * `input === undefined`.
+   *
+   * @see {@link defined} for matching non-nullish values
+   * @see {@link is} for matching literal values
+   *
    * @category Predicates
    * @since 4.0.0
    */
@@ -1560,6 +1676,18 @@ export {
   /**
    * Matches the value `null`.
    *
+   * **When to use**
+   *
+   * Use when a match branch should handle only the literal `null` value.
+   *
+   * **Details**
+   *
+   * This refinement is backed by `Predicate.isNull`, which checks
+   * `input === null`.
+   *
+   * @see {@link defined} for matching non-nullish values
+   * @see {@link is} for matching literal values
+   *
    * @category Predicates
    * @since 4.0.0
    */
@@ -1569,6 +1697,10 @@ export {
 /**
  * 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
@@ -1596,6 +1728,8 @@ export {
  * console.log(processLargeNumber("123")) // "Not a numeric type"
  * ```
  *
+ * @see {@link number} for matching primitive number values
+ *
  * @category predicates
  * @since 4.0.0
  */
@@ -1642,6 +1776,10 @@ export const symbol: Predicate.Refinement<unknown, symbol> = Predicate.isSymbol
 /**
  * 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
@@ -1670,6 +1808,8 @@ export const symbol: Predicate.Refinement<unknown, symbol> = Predicate.isSymbol
  * console.log(processDateValue(1704067200000)) // "Not a date-related value"
  * ```
  *
+ * @see {@link instanceOf} for matching instances of any constructor
+ *
  * @category predicates
  * @since 4.0.0
  */
@@ -1678,6 +1818,10 @@ export const date: Predicate.Refinement<unknown, Date> = Predicate.isDate
 /**
  * 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
@@ -1709,6 +1853,8 @@ export const date: Predicate.Refinement<unknown, Date> = Predicate.isDate
  * console.log(analyzeValue("hello")) // "Not an object"
  * ```
  *
+ * @see {@link instanceOf} for matching a specific constructor
+ *
  * @category predicates
  * @since 4.0.0
  */
@@ -1717,6 +1863,11 @@ export const record: Predicate.Refinement<unknown, { [x: PropertyKey]: unknown }
 /**
  * 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,
@@ -1760,6 +1911,9 @@ export const record: Predicate.Refinement<unknown, { [x: PropertyKey]: unknown }
  * console.log(handleValue(new Map([["count", 1]]))) // "Map with 1 entries"
  * ```
  *
+ * @see {@link instanceOfUnsafe} for constructor matching without the same type-safety guarantee
+ * @see {@link record} for matching broad non-null, non-array objects
+ *
  * @category Predicates
  * @since 4.0.0
  */
@@ -1768,7 +1922,11 @@ export const instanceOf: <A extends abstract new(...args: any) => any>(
 ) => SafeRefinement<InstanceType<A>, never> = internal.instanceOf
 
 /**
- * Unsafe variant of `instanceOf` that allows matching without type narrowing.
+ * Checks whether a value is an instance of a constructor without type-safe narrowing.
+ *
+ * **When to use**
+ *
+ * Use when constructor matching needs the unsafe refinement type.
  *
  * **Details**
  *
@@ -1798,6 +1956,8 @@ export const instanceOf: <A extends abstract new(...args: any) => any>(
  * )
  * ```
  *
+ * @see {@link instanceOf} for type-safe constructor matching
+ *
  * @category predicates
  * @since 4.0.0
  */
@@ -1808,6 +1968,10 @@ export const instanceOfUnsafe: <A extends abstract new(...args: any) => any>(
 /**
  * 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
@@ -1835,6 +1999,10 @@ export const instanceOfUnsafe: <A extends abstract new(...args: any) => any>(
  * // Output: "fallback"
  * ```
  *
+ * @see {@link option} for finalizing unmatched input as `Option.none`
+ * @see {@link result} for returning unmatched input as a `Result` failure
+ * @see {@link orElseAbsurd} for finalizing when unmatched input should be impossible
+ *
  * @category Completion
  * @since 4.0.0
  */
@@ -1846,7 +2014,12 @@ export const orElse: <RA, Ret, F extends (_: RA) => Ret>(
 
 // TODO(4.0): Rename to "orThrow"? Like Result.getOrThrow
 /**
- * Throws an error if no pattern matches.
+ * 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**
  *
@@ -1877,6 +2050,9 @@ export const orElse: <RA, Ret, F extends (_: RA) => Ret>(
  * // strictMatcher("c" as any) // throws
  * ```
  *
+ * @see {@link exhaustive} for compile-time exhaustive matcher finalization
+ * @see {@link orElse} for providing a fallback for unmatched input
+ *
  * @category completion
  * @since 4.0.0
  */
@@ -1930,6 +2106,11 @@ export const result: <I, F, R, A, Pr, Ret>(
 /**
  * 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`,
@@ -1961,6 +2142,9 @@ export const result: <I, F, R, A, Pr, Ret>(
  * // Output: { _id: 'Option', _tag: 'None' }
  * ```
  *
+ * @see {@link result} for preserving unmatched input as a `Result` failure
+ * @see {@link orElse} for replacing unmatched input with a fallback value
+ *
  * @category Completion
  * @since 4.0.0
  */
@@ -1969,10 +2153,17 @@ export const option: <I, F, R, A, Pr, Ret>(
 ) => [Pr] extends [never] ? (input: I) => Option.Option<Unify<A>> : Option.Option<Unify<A>> = internal.option
 
 /**
- * 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.
+ * 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.
  *
  * **Example** (Ensuring All Cases Are Covered)
  *