effect 4.0.0-beta.65 → 4.0.0-beta.67

package/dist/Match.d.ts

@@ -6,19 +6,13 @@ import type * as T from "./Types.ts";
 import type { Unify } from "./Unify.ts";
 declare const TypeId = "~effect/match/Match/Matcher";
 /**
- * Pattern matching follows a structured process:
+ * Union type for matchers created by `Match.type` and `Match.value`.
  *
- * - **Creating a matcher**: Define a `Matcher` that operates on either a
- *   specific `Match.type` or `Match.value`.
+ * A `Matcher` carries the input type, accumulated filters, remaining cases,
+ * result type, and, for value matchers, the provided value being matched.
  *
- * - **Defining patterns**: Use combinators such as `Match.when`, `Match.not`,
- *   and `Match.tag` to specify matching conditions.
+ * **Example** (Matching string and number values)
  *
- * - **Completing the match**: Apply a finalizer such as `Match.exhaustive`,
- *   `Match.orElse`, or `Match.option` to determine how unmatched cases should
- *   be handled.
- *
- * @example
  * ```ts
  * import { Match } from "effect"
  *
@@ -52,7 +46,8 @@ export type Matcher<Input, Filters, RemainingApplied, Result, Provided, Return =
  * type-level information about the input type, applied filters, remaining cases,
  * and expected results.
  *
- * @example
+ * **Example** (Creating a type matcher)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -89,7 +84,8 @@ export interface TypeMatcher<in Input, out Filters, out Remaining, out Result, o
  * the actual value to be matched against. It tracks both the provided value
  * and the result of applying patterns to determine matches.
  *
- * @example
+ * **Example** (Creating a value matcher)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -127,21 +123,6 @@ export interface ValueMatcher<in Input, Filters, out Remaining, out Result, Prov
  * Cases are the building blocks of pattern matching logic and determine
  * how values are tested and transformed.
  *
- * @example
- * ```ts
- * import type { Match } from "effect"
- *
- * // Case is a union type representing pattern matching cases
- * // It combines When (positive) and Not (negative) matching logic
- *
- * // When you write this:
- * // Match.when(pattern, handler)  // Creates a When case
- * // Match.not(pattern, handler)   // Creates a Not case
- *
- * // The Match module internally uses Case = When | Not
- * type MyCaseType = Match.Case // When | Not
- * ```
- *
  * @category models
  * @since 4.0.0
  */
@@ -153,7 +134,8 @@ export type Case = When | Not;
  * and the function to evaluate when the pattern matches. It's the primary
  * building block for pattern matching conditions.
  *
- * @example
+ * **Example** (Creating positive match cases)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -183,7 +165,8 @@ export interface When {
  * pattern and the function to evaluate when the pattern doesn't match. It's used
  * for exclusion-based pattern matching.
  *
- * @example
+ * **Example** (Creating negative match cases)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -216,7 +199,7 @@ export interface Not {
  * created, you can use pattern-matching functions like {@link when} to define
  * how different values should be processed.
  *
- * @example (Matching Numbers and Strings)
+ * **Example** (Matching Numbers and Strings)
  *
  * ```ts
  * import { Match } from "effect"
@@ -260,7 +243,7 @@ export declare const type: <I>() => Matcher<I, Types.Without<never>, I, never, n
  * Once the matcher is created, you can use pattern-matching functions like
  * {@link when} to define how different cases should be handled.
  *
- * @example (Matching an Object by Property)
+ * **Example** (Matching an Object by Property)
  *
  * ```ts
  * import { Match } from "effect"
@@ -295,7 +278,8 @@ export declare const value: <const I>(i: I) => Matcher<I, Types.Without<never>,
  * 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.
  *
- * @example
+ * **Example** (Matching value tags)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -322,7 +306,8 @@ export declare const valueTags: {
      * 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.
      *
-     * @example
+     * **Example** (Matching value tags)
+     *
      * ```ts
      * import { Match } from "effect"
      *
@@ -355,7 +340,8 @@ export declare const valueTags: {
      * 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.
      *
-     * @example
+     * **Example** (Matching value tags)
+     *
      * ```ts
      * import { Match } from "effect"
      *
@@ -389,7 +375,8 @@ export declare const valueTags: {
  * by providing handlers for each possible `_tag` value. It ensures type safety and
  * can optionally enforce a specific return type across all branches.
  *
- * @example
+ * **Example** (Matching type tags)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -433,7 +420,8 @@ export declare const typeTags: {
      * by providing handlers for each possible `_tag` value. It ensures type safety and
      * can optionally enforce a specific return type across all branches.
      *
-     * @example
+     * **Example** (Matching type tags)
+     *
      * ```ts
      * import { Match } from "effect"
      *
@@ -483,7 +471,8 @@ export declare const typeTags: {
      * by providing handlers for each possible `_tag` value. It ensures type safety and
      * can optionally enforce a specific return type across all branches.
      *
-     * @example
+     * **Example** (Matching type tags)
+     *
      * ```ts
      * import { Match } from "effect"
      *
@@ -539,7 +528,7 @@ export declare const typeTags: {
  * **Important:** This function must be the first step in the matcher pipeline.
  * If used later, TypeScript will not enforce type consistency correctly.
  *
- * @example (Validating Return Type Consistency)
+ * **Example** (Validating Return Type Consistency)
  *
  * ```ts
  * import { Match } from "effect"
@@ -574,7 +563,7 @@ export declare const withReturnType: <Ret>() => <I, F, R, A, Pr, _>(self: Matche
  * specific values or apply logical conditions to determine a match. It works
  * well with structured objects and primitive types.
  *
- * @example (Matching with Values and Predicates)
+ * **Example** (Matching with Values and Predicates)
  *
  * ```ts
  * import { Match } from "effect"
@@ -624,7 +613,8 @@ export declare const when: <R, const P extends Types.PatternPrimitive<R> | Types
  * this function enables combining them into a single statement, making the
  * matcher more concise.
  *
- * @example
+ * **Example** (Matching one of several patterns)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -668,7 +658,8 @@ export declare const whenOr: <R, const P extends ReadonlyArray<Types.PatternPrim
  * useful when checking for values that need to fulfill multiple criteria at
  * once.
  *
- * @example
+ * **Example** (Matching all provided patterns)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -705,7 +696,8 @@ export declare const whenAnd: <R, const P extends ReadonlyArray<Types.PatternPri
  * multiple values of the discriminant and provides a function to handle the
  * matched cases.
  *
- * @example
+ * **Example** (Matching on a discriminator field)
+ *
  * ```ts
  * import { Match, pipe } from "effect"
  *
@@ -741,7 +733,8 @@ export declare const discriminator: <D extends string>(field: D) => <R, P extend
  * hierarchical names like `"A"`, `"A.A"`, and `"B"`, you can match all values
  * starting with `"A"` using a single rule.
  *
- * @example
+ * **Example** (Matching discriminator prefixes)
+ *
  * ```ts
  * import { Match, pipe } from "effect"
  *
@@ -774,7 +767,8 @@ export declare const discriminatorStartsWith: <D extends string>(field: D) => <R
  * possible values of the field, and the values are the corresponding handler
  * functions.
  *
- * @example
+ * **Example** (Mapping discriminator handlers)
+ *
  * ```ts
  * import { Match, pipe } from "effect"
  *
@@ -803,21 +797,18 @@ export declare const discriminators: <D extends string>(field: D) => <R, Ret, P
     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>) => Matcher<I, Types.AddWithout<F, Extract<R, Record<D, keyof P>>>, Types.ApplyFilters<I, Types.AddWithout<F, Extract<R, Record<D, keyof P>>>>, A | ReturnType<P[keyof P] & {}>, Pr, Ret>;
 /**
- * Matches values based on a discriminator field and **ensures all cases are
- * handled**.
+ * Matches values by a discriminator field and requires every possible case to
+ * be handled.
  *
- * **Details*+
+ * **Details**
  *
- * This function is similar to {@link discriminators}, but **requires that all
- * possible cases** are explicitly handled. It is useful when working with
- * discriminated unions, where a specific field (e.g., `"type"`) determines the
- * shape of an object. Each possible value of the field must have a
- * corresponding handler, ensuring **exhaustiveness checking** at compile time.
+ * This is the exhaustive variant of {@link 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.
  *
- * This function **does not require** `Match.exhaustive` at the end of the
- * pipeline because it enforces exhaustiveness by design.
+ * **Example** (Handling all discriminator cases)
  *
- * @example
  * ```ts
  * import { Match, pipe } from "effect"
  *
@@ -855,7 +846,7 @@ export declare const discriminatorsExhaustive: <D extends string>(field: D) => <
  * of naming the tag field as `"_tag"`. Ensure that your discriminated unions
  * follow this naming convention for proper functionality.
  *
- * @example (Matching a Discriminated Union by Tag)
+ * **Example** (Matching a Discriminated Union by Tag)
  *
  * ```ts
  * import { Match } from "effect"
@@ -897,8 +888,9 @@ export declare const tag: <R, P extends Types.Tags<"_tag", R> & string, Ret, Fn
  * useful for handling hierarchical or namespaced tags, where multiple related
  * cases share a common prefix.
  *
- * @example
-  ```ts
+ * **Example** (Matching tag prefixes)
+ *
+ * ```ts
  * import { pipe } from "effect"
  * import { Match } from "effect"
  *
@@ -929,7 +921,8 @@ export declare const tagStartsWith: <R, P extends string, Ret, Fn extends (_: Ex
  * returns a transformed result. If all possible tags are handled, you can
  * enforce exhaustiveness using `Match.exhaustive` to ensure no case is missed.
  *
- * @example
+ * **Example** (Mapping tag handlers)
+ *
  * ```ts
  * import { Match, pipe } from "effect"
  *
@@ -969,7 +962,8 @@ export declare const tags: <R, Ret, P extends {
  * handled. If a `_tag` value is missing from the mapping, TypeScript will
  * report an error.
  *
- * @example
+ * **Example** (Handling all tag cases)
+ *
  * ```ts
  * import { Match, pipe } from "effect"
  *
@@ -1007,7 +1001,7 @@ export declare const tagsExhaustive: <R, Ret, P extends {
  * Any excluded value will bypass the provided function and continue matching
  * through other cases.
  *
- * @example (Ignoring a Specific Value)
+ * **Example** (Ignoring a Specific Value)
  *
  * ```ts
  * import { Match } from "effect"
@@ -1037,7 +1031,8 @@ export declare const not: <R, const P extends Types.PatternPrimitive<R> | Types.
  * This predicate matches any string that contains at least one character,
  * effectively filtering out empty strings ("").
  *
- * @example
+ * **Example** (Matching non-empty strings)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -1067,7 +1062,8 @@ export declare const nonEmptyString: SafeRefinement<string, never>;
  * 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.
  *
- * @example
+ * **Example** (Matching literal values)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -1105,7 +1101,8 @@ export declare const is: <Literals extends ReadonlyArray<string | number | bigin
  * 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.
  *
- * @example
+ * **Example** (Matching string values)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -1132,7 +1129,8 @@ export declare const string: Predicate.Refinement<unknown, string>;
  * on numeric types. It matches all number values including integers, floats,
  * `Infinity`, `-Infinity`, and `NaN`.
  *
- * @example
+ * **Example** (Matching number values)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -1163,7 +1161,8 @@ export declare const number: Predicate.Refinement<unknown, number>;
  * objects, primitives, functions, etc. It's useful as a catch-all pattern
  * or when you need to match any remaining cases.
  *
- * @example
+ * **Example** (Matching any remaining value)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -1199,7 +1198,8 @@ export declare const any: SafeRefinement<unknown, any>;
  * This predicate matches values that are neither `null` nor `undefined`,
  * effectively filtering out nullish values while preserving all other types.
  *
- * @example
+ * **Example** (Matching defined values)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -1238,7 +1238,8 @@ export declare const defined: <A>(u: A) => u is A & {};
  * This predicate refines unknown values to booleans, allowing pattern matching
  * on boolean types. It only matches the primitive boolean values `true` and `false`.
  *
- * @example
+ * **Example** (Matching boolean values)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -1287,7 +1288,8 @@ _null as null };
  * This predicate refines unknown values to bigints, allowing pattern matching
  * on bigint types. BigInts are used for representing integers with arbitrary precision.
  *
- * @example
+ * **Example** (Matching bigint values)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -1319,7 +1321,8 @@ export declare const bigint: Predicate.Refinement<unknown, bigint>;
  * on symbol types. Symbols are unique identifiers that are often used as
  * object keys or for creating private properties.
  *
- * @example
+ * **Example** (Matching symbol values)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -1353,7 +1356,8 @@ export declare const symbol: Predicate.Refinement<unknown, symbol>;
  * matching on Date objects. It only matches actual Date instances, not
  * date strings or timestamps.
  *
- * @example
+ * **Example** (Matching Date instances)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -1365,17 +1369,13 @@ export declare const symbol: Predicate.Refinement<unknown, symbol>;
  *     return `Date: ${date.toISOString().split("T")[0]}`
  *   }),
  *   Match.when(Match.string, (str) => `Date string: ${str}`),
- *   Match.when(
- *     Match.number,
- *     (num) => `Timestamp: ${new Date(num).toISOString()}`
- *   ),
  *   Match.orElse(() => "Not a date-related value")
  * )
  *
  * console.log(processDateValue(new Date("2024-01-01"))) // "Date: 2024-01-01"
  * console.log(processDateValue(new Date("invalid"))) // "Invalid date"
  * console.log(processDateValue("2024-01-01")) // "Date string: 2024-01-01"
- * console.log(processDateValue(1704067200000)) // "Timestamp: 2024-01-01T00:00:00.000Z"
+ * console.log(processDateValue(1704067200000)) // "Not a date-related value"
  * ```
  *
  * @category predicates
@@ -1383,13 +1383,15 @@ export declare const symbol: Predicate.Refinement<unknown, symbol>;
  */
 export declare const date: Predicate.Refinement<unknown, Date>;
 /**
- * Matches objects where keys are `string` or `symbol` and values are `unknown`.
+ * Matches non-null objects other than arrays.
+ *
+ * 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.
  *
- * This predicate refines unknown values to record objects, allowing pattern
- * matching on plain objects. It excludes arrays, functions, dates, and other
- * special object types, matching only plain objects and object literals.
+ * **Example** (Matching record objects)
  *
- * @example
  * ```ts
  * import { Match } from "effect"
  *
@@ -1403,18 +1405,13 @@ export declare const date: Predicate.Refinement<unknown, Date>;
  *     Match.instanceOf(Array),
  *     (arr) => `Array with ${arr.length} items`
  *   ),
- *   Match.when(Match.date, () => "Date object"),
  *   Match.orElse(() => "Not an object")
  * )
  *
- * console.log(analyzeValue({ name: "Alice", age: 30 }))
- * // "Object with 2 properties: [name, age]"
- * console.log(analyzeValue([1, 2, 3]))
- * // "Array with 3 items"
- * console.log(analyzeValue(new Date()))
- * // "Date object"
- * console.log(analyzeValue("hello"))
- * // "Not an object"
+ * console.log(analyzeValue({ name: "Alice", age: 30 })) // "Object with 2 properties: [name, age]"
+ * console.log(analyzeValue([1, 2, 3])) // "Array with 3 items"
+ * console.log(analyzeValue(null)) // "Not an object"
+ * console.log(analyzeValue("hello")) // "Not an object"
  * ```
  *
  * @category predicates
@@ -1429,7 +1426,8 @@ export declare const record: Predicate.Refinement<unknown, {
  * This predicate checks if a value is an instance of the specified constructor,
  * providing type-safe matching for class instances and built-in objects.
  *
- * @example
+ * **Example** (Matching class instances)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -1449,25 +1447,21 @@ export declare const record: Predicate.Refinement<unknown, {
  *       Match.instanceOf(Error),
  *       (err) => `Standard error: ${err.message}`
  *     ),
- *     Match.when(Match.instanceOf(Date), (date) => `Date: ${date.toISOString()}`),
  *     Match.when(
  *       Match.instanceOf(Array),
  *       (arr) => `Array with ${arr.length} items`
  *     ),
+ *     Match.when(
+ *       Match.instanceOf(Map),
+ *       (map) => `Map with ${map.size} entries`
+ *     ),
  *     Match.orElse((value) => `Other: ${typeof value}`)
  *   )
  *
- * console.log(handleValue(new CustomError("Failed", 404)))
- * // Output: "Custom error: Failed (code: 404)"
- *
- * console.log(handleValue(new Error("Generic error")))
- * // Output: "Standard error: Generic error"
- *
- * console.log(handleValue(new Date()))
- * // Output: "Date: 2024-01-01T00:00:00.000Z"
- *
- * console.log(handleValue([1, 2, 3]))
- * // Output: "Array with 3 items"
+ * console.log(handleValue(new CustomError("Failed", 404))) // "Custom error: Failed (code: 404)"
+ * console.log(handleValue(new Error("Generic error"))) // "Standard error: Generic error"
+ * console.log(handleValue([1, 2, 3])) // "Array with 3 items"
+ * console.log(handleValue(new Map([["count", 1]]))) // "Map with 1 entries"
  * ```
  *
  * @category Predicates
@@ -1481,7 +1475,8 @@ export declare const instanceOf: <A extends abstract new (...args: any) => any>(
  * 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.
  *
- * @example
+ * **Example** (Matching class instances unsafely)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -1516,7 +1511,7 @@ export declare const instanceOfUnsafe: <A extends abstract new (...args: any) =>
  * `default` clause in a `switch` statement or the final `else` in an `if-else`
  * chain.
  *
- * @example (Providing a Default Value When No Patterns Match)
+ * **Example** (Providing a Default Value When No Patterns Match)
  *
  * ```ts
  * import { Match } from "effect"
@@ -1553,7 +1548,8 @@ export declare const orElse: <RA, Ret, F extends (_: RA) => Ret>(f: F) => <I, R,
  * When used, this function removes the need for an explicit fallback case and
  * ensures that an unmatched value is never silently ignored.
  *
- * @example
+ * **Example** (Throwing on unmatched input)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -1590,7 +1586,7 @@ export declare const orElseAbsurd: <I, R, RA, A, Pr, Ret>(self: Matcher<I, R, RA
  * unmatched case should be explicitly handled rather than returning a default
  * value or throwing an error.
  *
- * @example (Extracting a User Role with `Match.result`)
+ * **Example** (Extracting a User Role with `Match.result`)
  *
  * ```ts
  * import { Match } from "effect"
@@ -1628,7 +1624,7 @@ export declare const result: <I, F, R, A, Pr, Ret>(self: Matcher<I, F, R, A, Pr,
  * handled explicitly rather than throwing an error or returning a default
  * value.
  *
- * @example (Extracting a User Role with `Match.option`)
+ * **Example** (Extracting a User Role with `Match.option`)
  *
  * ```ts
  * import { Match } from "effect"
@@ -1659,7 +1655,7 @@ export declare const option: <I, F, R, A, Pr, Ret>(self: Matcher<I, F, R, A, Pr,
  * 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)
+ * **Example** (Ensuring All Cases Are Covered)
  *
  * ```ts
  * import { Match } from "effect"
@@ -1687,7 +1683,8 @@ declare const SafeRefinementId = "~effect/match/Match/SafeRefinement";
  * maintaining type safety. Unlike regular predicates, safe refinements can
  * transform the matched value's type without throwing runtime errors.
  *
- * @example
+ * **Example** (Using safe refinements)
+ *
  * ```ts
  * import { Match } from "effect"
  *
@@ -1721,22 +1718,6 @@ type Fail = typeof Fail;
  * application. These types enable the sophisticated type inference that makes
  * pattern matching both type-safe and ergonomic.
  *
- * @example
- * ```ts
- * import { Match } from "effect"
- *
- * // Most users won't need to use Types directly, but it powers the type system:
- * type MyPattern = Match.Types.PatternBase<{ name: string; age: number }>
- * type MyWhenMatch = Match.Types.WhenMatch<string | number, typeof Match.string>
- *
- * // These types are used internally to provide accurate type inference
- * const matcher = Match.type<string | number>().pipe(
- *   Match.when(Match.string, (s) => s.length), // s is correctly typed as string
- *   Match.when(Match.number, (n) => n * 2), // n is correctly typed as number
- *   Match.exhaustive
- * )
- * ```
- *
  * @category types
  * @since 4.0.0
  */
@@ -1748,7 +1729,8 @@ export declare namespace Types {
      * matching against a pattern. It handles refinements, predicates, and complex
      * object patterns to provide accurate type narrowing.
      *
-     * @example
+     * **Example** (Computing matched types)
+     *
      * ```ts
      * import type { Match } from "effect"
      *
@@ -1779,7 +1761,8 @@ export declare namespace Types {
      * excludes certain values. It's the complement of `WhenMatch`, calculating
      * what's left after removing the matched portion.
      *
-     * @example
+     * **Example** (Computing unmatched types)
+     *
      * ```ts
      * import type { Match } from "effect"
      *
@@ -1806,7 +1789,8 @@ export declare namespace Types {
      * and resolves them to their corresponding matched types. It's used internally
      * to compute type transformations during pattern matching.
      *
-     * @example
+     * **Example** (Resolving match patterns)
+     *
      * ```ts
      * import type { Match } from "effect"
      *
@@ -1829,7 +1813,8 @@ export declare namespace Types {
      * when a pattern is used in filtering operations. It transforms patterns
      * into their exclusion-safe representations.
      *
-     * @example
+     * **Example** (Computing excluded patterns)
+     *
      * ```ts
      * import type { Match } from "effect"
      *
@@ -1866,7 +1851,8 @@ export declare namespace Types {
      * like objects and arrays. It supports nested pattern matching and partial
      * object matching, enabling sophisticated pattern compositions.
      *
-     * @example
+     * **Example** (Describing complex object patterns)
+     *
      * ```ts
      * import { Match } from "effect"
      *
@@ -1902,24 +1888,6 @@ export declare namespace Types {
      * literal values, and safe refinements. These are the atomic patterns that
      * can be composed into more complex matching logic.
      *
-     * @example
-     * ```ts
-     * import { Match } from "effect"
-     *
-     * // PatternPrimitive includes various pattern types:
-     *
-     * // Literal values
-     * Match.when("exact", () => "matched exact")
-     * Match.when(42, () => "matched number")
-     *
-     * // Predicates
-     * Match.when(Match.string, (s) => `string: ${s}`)
-     * Match.when((x: number) => x > 10, (n: number) => `large number: ${n}`)
-     *
-     * // Custom refinements
-     * Match.when(Match.defined, (value) => `defined: ${value}`)
-     * ```
-     *
      * @category types
      * @since 4.0.0
      */
@@ -1931,7 +1899,8 @@ export declare namespace Types {
      * from consideration during pattern matching. It helps implement the
      * type-level logic for `Match.not` and other exclusion operations.
      *
-     * @example
+     * **Example** (Tracking excluded types)
+     *
      * ```ts
      * import { Match } from "effect"
      *
@@ -1957,7 +1926,8 @@ export declare namespace Types {
      * considered during pattern matching. It helps implement the type-level
      * logic for positive matches and type narrowing.
      *
-     * @example
+     * **Example** (Tracking included types)
+     *
      * ```ts
      * import { Match } from "effect"
      *
@@ -1983,7 +1953,8 @@ export declare namespace Types {
      * pattern matching. When multiple exclusions are applied, it combines
      * them into a single filter representation.
      *
-     * @example
+     * **Example** (Accumulating excluded types)
+     *
      * ```ts
      * import { Match } from "effect"
      *
@@ -2007,7 +1978,8 @@ export declare namespace Types {
      * pattern matching. It ensures that only the most specific type
      * constraints are maintained when multiple positive matches are applied.
      *
-     * @example
+     * **Example** (Refining included types)
+     *
      * ```ts
      * import { Match } from "effect"
      *
@@ -2030,7 +2002,8 @@ export declare namespace Types {
      * applies them to the input type to compute the final narrowed result.
      * It's the culmination of the type-level filtering process.
      *
-     * @example
+     * **Example** (Applying accumulated filters)
+     *
      * ```ts
      * import type { Match } from "effect"
      *
@@ -2059,7 +2032,8 @@ export declare namespace Types {
      * from a union type. It's used internally to implement tag-based pattern
      * matching for discriminated unions.
      *
-     * @example
+     * **Example** (Extracting discriminator tags)
+     *
      * ```ts
      * import type { Match } from "effect"
      *
@@ -2090,7 +2064,8 @@ export declare namespace Types {
      * intersection type. It's used internally when multiple patterns need to
      * be satisfied simultaneously (like in `Match.whenAnd`).
      *
-     * @example
+     * **Example** (Converting arrays to intersections)
+     *
      * ```ts
      * import type { Match } from "effect"
      *
@@ -2118,7 +2093,8 @@ export declare namespace Types {
      * and narrowing logic. It handles the complex type-level computation that
      * determines what type results from applying a pattern to an input type.
      *
-     * @example
+     * **Example** (Extracting matched types)
+     *
      * ```ts
      * import { Match } from "effect"
      *