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

package/dist/Match.d.ts

@@ -125,12 +125,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
  */
@@ -204,6 +212,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
@@ -245,6 +257,10 @@ export declare const type: <I>() => Matcher<I, Types.Without<never>, I, never, n
 /**
  * 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,
@@ -576,16 +592,17 @@ export declare const withReturnType: <Ret>() => <I, F, R, A, Pr, _>(self: Matche
 /**
  * Defines a condition for matching values.
  *
- * **Details**
+ * **When to use**
  *
- * 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.
+ * 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 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.
+ * **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.
  *
  * **Example** (Matching with Values and Predicates)
  *
@@ -615,10 +632,10 @@ export declare const withReturnType: <Ret>() => <I, F, R, A, Pr, _>(self: Matche
  * // 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
@@ -712,6 +729,10 @@ export declare const whenAnd: <R, const P extends ReadonlyArray<Types.PatternPri
 /**
  * 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
@@ -738,6 +759,9 @@ export declare const whenAnd: <R, const P extends ReadonlyArray<Types.PatternPri
  * )
  * ```
  *
+ * @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
  */
@@ -745,17 +769,16 @@ export declare const discriminator: <D extends string>(field: D) => <R, P extend
 /**
  * Matches values where a specified field starts with a given prefix.
  *
- * **Details**
+ * **When to use**
  *
- * 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.
+ * Use to match string discriminator values by prefix instead of exact value.
  *
- * 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.
+ * **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"`.
  *
  * **Example** (Matching discriminator prefixes)
  *
@@ -774,6 +797,8 @@ export declare const discriminator: <D extends string>(field: D) => <R, P extend
  * console.log(match({ type: "A.A" })) // 1
  * ```
  *
+ * @see {@link discriminator} for matching exact discriminator values
+ *
  * @category Defining patterns
  * @since 4.0.0
  */
@@ -782,6 +807,11 @@ export declare const discriminatorStartsWith: <D extends string>(field: D) => <R
  * 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
@@ -812,6 +842,9 @@ export declare const discriminatorStartsWith: <D extends string>(field: D) => <R
  * )
  * ```
  *
+ * @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
  */
@@ -824,6 +857,11 @@ export declare const discriminators: <D extends string>(field: D) => <R, Ret, P
  * 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
@@ -851,6 +889,8 @@ export declare const discriminators: <D extends string>(field: D) => <R, Ret, P
  * )
  * ```
  *
+ * @see {@link discriminators} for defining discriminator handlers without finalizing the matcher
+ *
  * @category Defining patterns
  * @since 4.0.0
  */
@@ -860,15 +900,17 @@ export declare const discriminatorsExhaustive: <D extends string>(field: D) => <
     readonly [Tag in Exclude<keyof P, Types.Tags<D, R>>]: never;
 }>(fields: P) => <I, F, A, Pr>(self: Matcher<I, F, R, A, Pr, Ret>) => [Pr] extends [never] ? (u: I) => Unify<A | ReturnType<P[keyof P]>> : Unify<A | ReturnType<P[keyof P]>>;
 /**
- * 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)
  *
@@ -1014,15 +1056,17 @@ export declare const tagsExhaustive: <R, Ret, P extends {
     readonly [Tag in Exclude<keyof P, Types.Tags<"_tag", R>>]: never;
 }>(fields: P) => <I, F, A, Pr>(self: Matcher<I, F, R, A, Pr, Ret>) => [Pr] extends [never] ? (u: I) => Unify<A | ReturnType<P[keyof P]>> : Unify<A | ReturnType<P[keyof P]>>;
 /**
- * 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)
  *
@@ -1044,6 +1088,8 @@ export declare const tagsExhaustive: <R, Ret, P extends {
  * // Output: "fallback"
  * ```
  *
+ * @see {@link when} for adding a positive pattern case
+ *
  * @category Defining patterns
  * @since 4.0.0
  */
@@ -1051,6 +1097,10 @@ export declare const not: <R, const P extends Types.PatternPrimitive<R> | Types.
 /**
  * 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,
@@ -1077,6 +1127,8 @@ export declare const not: <R, const P extends Types.PatternPrimitive<R> | Types.
  * // Output: "Valid input:    " (whitespace-only strings are considered non-empty)
  * ```
  *
+ * @see {@link string} for matching any string
+ *
  * @category Predicates
  * @since 4.0.0
  */
@@ -1084,6 +1136,10 @@ export declare const nonEmptyString: SafeRefinement<string, never>;
 /**
  * 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.
@@ -1154,6 +1210,10 @@ export declare const string: Predicate.Refinement<unknown, 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
@@ -1181,6 +1241,8 @@ export declare const string: Predicate.Refinement<unknown, string>;
  * console.log(categorizeNumber("hello")) // "Not a number type"
  * ```
  *
+ * @see {@link bigint} for matching primitive bigint values
+ *
  * @category predicates
  * @since 4.0.0
  */
@@ -1188,11 +1250,20 @@ export declare const number: Predicate.Refinement<unknown, number>;
 /**
  * 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)
  *
@@ -1221,6 +1292,9 @@ export declare const number: Predicate.Refinement<unknown, number>;
  * // 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
  */
@@ -1228,6 +1302,10 @@ export declare const any: SafeRefinement<unknown, 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`,
@@ -1263,6 +1341,8 @@ export declare const any: SafeRefinement<unknown, any>;
  * // Output: "Value is null or undefined"
  * ```
  *
+ * @see {@link any} for matching every value without excluding nullish inputs
+ *
  * @category Predicates
  * @since 4.0.0
  */
@@ -1270,6 +1350,10 @@ export declare const defined: <A>(u: A) => u is A & {};
 /**
  * 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
@@ -1297,6 +1381,8 @@ export declare const defined: <A>(u: A) => u is A & {};
  * console.log(describeTruthiness(1)) // "Some other truthy value"
  * ```
  *
+ * @see {@link is} for matching specific literal boolean values
+ *
  * @category predicates
  * @since 4.0.0
  */
@@ -1306,6 +1392,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
  */
@@ -1315,6 +1413,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
  */
@@ -1322,6 +1432,10 @@ _null as null };
 /**
  * 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
@@ -1349,6 +1463,8 @@ _null as null };
  * console.log(processLargeNumber("123")) // "Not a numeric type"
  * ```
  *
+ * @see {@link number} for matching primitive number values
+ *
  * @category predicates
  * @since 4.0.0
  */
@@ -1393,6 +1509,10 @@ export declare const symbol: Predicate.Refinement<unknown, symbol>;
 /**
  * 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
@@ -1421,6 +1541,8 @@ export declare const symbol: Predicate.Refinement<unknown, symbol>;
  * console.log(processDateValue(1704067200000)) // "Not a date-related value"
  * ```
  *
+ * @see {@link instanceOf} for matching instances of any constructor
+ *
  * @category predicates
  * @since 4.0.0
  */
@@ -1428,6 +1550,10 @@ export declare const date: Predicate.Refinement<unknown, Date>;
 /**
  * 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
@@ -1459,6 +1585,8 @@ export declare const date: Predicate.Refinement<unknown, Date>;
  * console.log(analyzeValue("hello")) // "Not an object"
  * ```
  *
+ * @see {@link instanceOf} for matching a specific constructor
+ *
  * @category predicates
  * @since 4.0.0
  */
@@ -1468,6 +1596,11 @@ export declare const record: Predicate.Refinement<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,
@@ -1511,12 +1644,19 @@ export declare const record: Predicate.Refinement<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
  */
 export declare const instanceOf: <A extends abstract new (...args: any) => any>(constructor: A) => SafeRefinement<InstanceType<A>, never>;
 /**
- * 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**
  *
@@ -1546,6 +1686,8 @@ export declare const instanceOf: <A extends abstract new (...args: any) => any>(
  * )
  * ```
  *
+ * @see {@link instanceOf} for type-safe constructor matching
+ *
  * @category predicates
  * @since 4.0.0
  */
@@ -1553,6 +1695,10 @@ export declare const instanceOfUnsafe: <A extends abstract new (...args: 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
@@ -1580,12 +1726,21 @@ export declare const instanceOfUnsafe: <A extends abstract new (...args: 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
  */
 export declare const orElse: <RA, Ret, F extends (_: RA) => Ret>(f: F) => <I, R, A, Pr>(self: Matcher<I, R, RA, A, Pr, Ret>) => [Pr] extends [never] ? (input: I) => Unify<ReturnType<F> | A> : Unify<ReturnType<F> | A>;
 /**
- * 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**
  *
@@ -1616,6 +1771,9 @@ export declare const orElse: <RA, Ret, F extends (_: RA) => Ret>(f: F) => <I, R,
  * // 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
  */
@@ -1663,6 +1821,11 @@ export declare const result: <I, F, R, A, Pr, Ret>(self: Matcher<I, F, R, A, Pr,
 /**
  * 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`,
@@ -1694,15 +1857,25 @@ export declare const result: <I, F, R, A, Pr, Ret>(self: Matcher<I, F, R, A, Pr,
  * // 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
  */
 export declare const option: <I, F, R, A, Pr, Ret>(self: Matcher<I, F, R, A, Pr, Ret>) => [Pr] extends [never] ? (input: I) => Option.Option<Unify<A>> : Option.Option<Unify<A>>;
 /**
- * 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)
  *