effect 4.0.0-beta.70 → 4.0.0-beta.71

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,6 +663,12 @@ export const withReturnType: <Ret>() => <I, F, R, A, Pr, _>(
 /**
  * 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**
  *
  * This function enables pattern matching by checking whether a given value
@@ -668,10 +708,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 +856,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 +886,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,6 +910,10 @@ export const discriminator: <D extends string>(
 /**
  * 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**
  *
  * This function is useful for working with discriminated unions where the
@@ -892,6 +943,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 +968,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 +1003,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 +1034,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 +1066,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
  */
@@ -1232,6 +1300,11 @@ export const tagsExhaustive: <
 /**
  * Excludes a specific value from matching 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
@@ -1260,6 +1333,8 @@ export const tagsExhaustive: <
  * // Output: "fallback"
  * ```
  *
+ * @see {@link when} for adding a positive pattern case
+ *
  * @category Defining patterns
  * @since 4.0.0
  */
@@ -1285,6 +1360,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 +1390,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 +1400,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 +1478,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 +1509,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 +1519,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 +1561,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 +1572,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 +1611,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 +1621,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 +1652,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 +1664,19 @@ export {
   /**
    * Matches the value `undefined`.
    *
+   * **When to use**
+   *
+   * Use when a matcher should handle only inputs whose value is exactly
+   * `undefined`.
+   *
+   * **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 +1688,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 +1709,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 +1740,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 +1788,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 +1820,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 +1830,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 +1865,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 +1875,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 +1923,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
  */
@@ -1770,6 +1936,10 @@ export const instanceOf: <A extends abstract new(...args: any) => any>(
 /**
  * Unsafe variant of `instanceOf` that allows matching without type narrowing.
  *
+ * **When to use**
+ *
+ * Use when constructor matching needs the unsafe refinement type.
+ *
  * **Details**
  *
  * This predicate checks if a value is an instance of the specified constructor
@@ -1798,6 +1968,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 +1980,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 +2011,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
  */
@@ -1848,6 +2028,11 @@ export const orElse: <RA, Ret, F extends (_: RA) => Ret>(
 /**
  * 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
@@ -1877,6 +2062,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 +2118,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 +2154,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
  */