effect 4.0.0-beta.0 → 4.0.0-beta.10

package/src/Equal.ts

@@ -1,7 +1,71 @@
 /**
- * This module provides functionality for defining and working with equality between values.
- * It includes the `Equal` interface for types that can determine equality with other values
- * of the same type, and utilities for comparing values.
+ * Structural and custom equality for Effect values.
+ *
+ * The `Equal` module provides deep structural comparison for primitives, plain
+ * objects, arrays, Maps, Sets, Dates, and RegExps. Types that implement the
+ * {@link Equal} interface can supply their own comparison logic while staying
+ * compatible with the rest of the ecosystem (HashMap, HashSet, etc.).
+ *
+ * ## Mental model
+ *
+ * - **Structural equality** — two values are equal when their contents match,
+ *   not when they share the same reference.
+ * - **Hash-first shortcut** — before comparing fields, the module checks
+ *   {@link Hash.hash}. If the hashes differ the objects are unequal without
+ *   further traversal.
+ * - **Equal interface** — any object that implements both {@link symbol} (the
+ *   equality method) and `Hash.symbol` (the hash method) can define custom
+ *   comparison logic.
+ * - **Caching** — comparison results for object pairs are cached in a WeakMap.
+ *   This makes repeated checks fast but **requires immutability** after the
+ *   first comparison.
+ * - **By-reference opt-out** — {@link byReference} and {@link byReferenceUnsafe}
+ *   let you switch individual objects back to reference equality when you need
+ *   mutable identity semantics.
+ *
+ * ## Common tasks
+ *
+ * - Compare two values → {@link equals}
+ * - Check if a value implements `Equal` → {@link isEqual}
+ * - Use `equals` where an `Equivalence` is expected → {@link asEquivalence}
+ * - Implement custom equality on a class → implement {@link Equal} (see
+ *   example on the interface)
+ * - Opt an object out of structural equality → {@link byReference} /
+ *   {@link byReferenceUnsafe}
+ *
+ * ## Gotchas
+ *
+ * - Objects **must be treated as immutable** after their first equality check.
+ *   Results are cached; mutating an object afterwards yields stale results.
+ * - `NaN` is considered equal to `NaN` (unlike `===`).
+ * - Functions without an `Equal` implementation are compared by reference.
+ * - Map and Set comparisons are order-independent but O(n²) in size.
+ * - If only one of two objects implements `Equal`, they are never equal.
+ *
+ * ## Quickstart
+ *
+ * **Example** (basic structural comparison)
+ *
+ * ```ts
+ * import { Equal } from "effect"
+ *
+ * // Primitives
+ * console.log(Equal.equals(1, 1))       // true
+ * console.log(Equal.equals("a", "b"))   // false
+ *
+ * // Objects and arrays
+ * console.log(Equal.equals({ x: 1 }, { x: 1 })) // true
+ * console.log(Equal.equals([1, 2], [1, 2]))       // true
+ *
+ * // Curried form
+ * const is42 = Equal.equals(42)
+ * console.log(is42(42)) // true
+ * console.log(is42(0))  // false
+ * ```
+ *
+ * @see {@link equals} — the main comparison function
+ * @see {@link Equal} — the interface for custom equality
+ * @see {@link Hash} — the companion hashing module
  *
  * @since 2.0.0
  */
@@ -11,17 +75,67 @@ import { byReferenceInstances, getAllObjectKeys } from "./internal/equal.ts"
 import { hasProperty } from "./Predicate.ts"
 
 /**
- * The unique identifier used to identify objects that implement the `Equal` interface.
+ * The unique string identifier for the {@link Equal} interface.
+ *
+ * Use this as a computed property key when implementing custom equality on a
+ * class or object literal.
+ *
+ * When to use:
+ * - As the method name when implementing the {@link Equal} interface.
+ * - To check manually whether an object carries an equality method (prefer
+ *   {@link isEqual} instead).
+ *
+ * Behavior:
+ * - Pure constant — no allocation or side effects.
+ *
+ * **Example** (implementing Equal on a class)
+ *
+ * ```ts
+ * import { Equal, Hash } from "effect"
+ *
+ * class UserId implements Equal.Equal {
+ *   constructor(readonly id: string) {}
+ *
+ *   [Equal.symbol](that: Equal.Equal): boolean {
+ *     return that instanceof UserId && this.id === that.id
+ *   }
+ *
+ *   [Hash.symbol](): number {
+ *     return Hash.string(this.id)
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Equal} — the interface that uses this symbol
+ * @see {@link isEqual} — type guard for `Equal` implementors
  *
  * @since 2.0.0
  */
 export const symbol = "~effect/interfaces/Equal"
 
 /**
- * An interface defining objects that can determine equality with other `Equal` objects.
- * Objects implementing this interface must also implement `Hash` for consistency.
+ * The interface for types that define their own equality logic.
+ *
+ * Any object that implements both `[Equal.symbol]` (equality) and
+ * `[Hash.symbol]` (hashing) is recognized by {@link equals} and by
+ * hash-based collections such as `HashMap` and `HashSet`.
+ *
+ * When to use:
+ * - When you need value-based equality for a class (e.g. domain IDs,
+ *   coordinates, money values).
+ * - When your type will be stored in `HashMap` or `HashSet`.
+ * - When the default structural comparison is too broad or too narrow for
+ *   your type.
+ *
+ * Behavior:
+ * - Extends `Hash.Hash`, so implementors **must** also provide `[Hash.symbol]`.
+ * - The hash contract: if `a[Equal.symbol](b)` returns `true`, then
+ *   `Hash.hash(a)` must equal `Hash.hash(b)`.
+ * - {@link equals} delegates to this method when both operands implement it.
+ *   If only one operand implements `Equal`, they are considered unequal.
+ *
+ * **Example** (coordinate with value equality)
  *
- * @example
  * ```ts
  * import { Equal, Hash } from "effect"
  *
@@ -38,8 +152,15 @@ export const symbol = "~effect/interfaces/Equal"
  *     return Hash.string(`${this.x},${this.y}`)
  *   }
  * }
+ *
+ * console.log(Equal.equals(new Coordinate(1, 2), new Coordinate(1, 2))) // true
+ * console.log(Equal.equals(new Coordinate(1, 2), new Coordinate(3, 4))) // false
  * ```
  *
+ * @see {@link symbol} — the property key used by the equality method
+ * @see {@link equals} — the main comparison function
+ * @see {@link isEqual} — type guard for `Equal` implementors
+ *
  * @category models
  * @since 2.0.0
  */
@@ -48,65 +169,67 @@ export interface Equal extends Hash.Hash {
 }
 
 /**
- * Compares two values for structural equality. Returns `true` if the values are structurally equal, `false` otherwise.
- *
- * This function performs deep structural comparison:
- * - For primitive values: uses value equality (including NaN === NaN)
- * - For objects implementing `Equal` interface: uses their custom equality logic
- * - For Date objects: compares ISO string representations
- * - For RegExp objects: compares string representations
- * - For Arrays: recursively compares each element
- * - For Maps: compares keys and values structurally (order-independent)
- * - For Sets: compares values structurally (order-independent)
- * - For plain objects: compares all properties recursively
- * - Handles circular references correctly
- *
- * **Performance**: Results of object comparisons are cached using WeakMaps to optimize
- * repeated equality checks between the same object pairs.
- *
- * **⚠️ CRITICAL IMMUTABILITY REQUIREMENT**: Objects being compared must be treated as
- * immutable after their first equality computation. Equality results are cached, so
- * mutating an object after comparison will lead to stale cached values and incorrect
- * equality results. For mutable objects, use referential equality by implementing
- * custom `Equal` interface that compares object references, not content.
- *
- * **FORBIDDEN**: Modifying objects after `Equal.equals()` has been called on them
- * **ALLOWED**: Using immutable objects, or mutable objects with custom `Equal` interface
- * that uses referential equality (compares object references, not content)
- *
- * @example
+ * Compares two values for deep structural equality.
+ *
+ * When to use:
+ * - As the default equality check throughout Effect code.
+ * - In data-level assertions or conditional logic where structural comparison
+ *   is needed.
+ * - In its curried (single-argument) form to build reusable predicates.
+ *
+ * Behavior:
+ * - Returns a `boolean`; never throws.
+ * - Primitives: compared by value. `NaN` equals `NaN`.
+ * - Objects implementing {@link Equal}: delegates to their
+ *   `[Equal.symbol]` method. If only one operand implements `Equal`, the
+ *   result is `false`.
+ * - Dates: compared by ISO string representation.
+ * - RegExps: compared by string representation.
+ * - Arrays: element-by-element recursive comparison (order matters).
+ * - Maps / Sets: structural comparison of entries (order-independent, O(n²)).
+ * - Plain objects: all own and inherited enumerable keys are compared
+ *   recursively.
+ * - Functions without an `Equal` implementation are compared by reference.
+ * - Circular references are handled; two structures that are circular at the
+ *   same depth are considered equal.
+ * - Hash values are checked first as a fast-path rejection.
+ * - Results are cached per object pair in a WeakMap. **Objects must not be
+ *   mutated after their first comparison.**
+ * - Supports dual (data-last) usage: call with one argument to get a curried
+ *   predicate.
+ *
+ * **Example** (comparing values)
+ *
  * ```ts
  * import { Equal } from "effect"
- * import * as assert from "node:assert"
- *
- * // Primitive values
- * assert(Equal.equals(1, 1) === true)
- * assert(Equal.equals(NaN, NaN) === true)
- *
- * // Objects - structural comparison
- * assert(Equal.equals({ a: 1, b: 2 }, { a: 1, b: 2 }) === true)
- * assert(Equal.equals({ a: 1 }, { a: 1, b: 2 }) === false)
- *
- * // Arrays - recursive comparison
- * assert(Equal.equals([1, [2, 3]], [1, [2, 3]]) === true)
- * assert(Equal.equals([1, 2], [1, 3]) === false)
- *
- * // Date equality by ISO string
- * const date1 = new Date("2023-01-01")
- * const date2 = new Date("2023-01-01")
- * assert(Equal.equals(date1, date2) === true)
- *
- * // Maps and Sets - structural comparison
- * const map1 = new Map([["a", 1], ["b", 2]])
- * const map2 = new Map([["b", 2], ["a", 1]]) // different order
- * assert(Equal.equals(map1, map2) === true)
- *
- * // Curried version
- * const isEqualTo5 = Equal.equals(5)
- * assert(isEqualTo5(5) === true)
- * assert(isEqualTo5(3) === false)
+ *
+ * // Primitives
+ * console.log(Equal.equals(1, 1))         // true
+ * console.log(Equal.equals(NaN, NaN))     // true
+ * console.log(Equal.equals("a", "b"))     // false
+ *
+ * // Objects and arrays
+ * console.log(Equal.equals({ a: 1, b: 2 }, { a: 1, b: 2 })) // true
+ * console.log(Equal.equals([1, [2, 3]], [1, [2, 3]]))         // true
+ *
+ * // Dates
+ * console.log(Equal.equals(new Date("2024-01-01"), new Date("2024-01-01"))) // true
+ *
+ * // Maps (order-independent)
+ * const m1 = new Map([["a", 1], ["b", 2]])
+ * const m2 = new Map([["b", 2], ["a", 1]])
+ * console.log(Equal.equals(m1, m2)) // true
+ *
+ * // Curried form
+ * const is5 = Equal.equals(5)
+ * console.log(is5(5)) // true
+ * console.log(is5(3)) // false
  * ```
  *
+ * @see {@link Equal} — the interface for custom equality
+ * @see {@link isEqual} — check whether a value implements `Equal`
+ * @see {@link asEquivalence} — wrap `equals` as an `Equivalence`
+ *
  * @category equality
  * @since 2.0.0
  */
@@ -269,7 +392,7 @@ function compareRecords(
 
 /** @internal */
 export function makeCompareMap<K, V>(keyEquivalence: Equivalence<K>, valueEquivalence: Equivalence<V>) {
-  return function compareMaps(self: ReadonlyMap<K, V>, that: ReadonlyMap<K, V>): boolean {
+  return function compareMaps(self: Iterable<[K, V]>, that: Iterable<[K, V]>): boolean {
     for (const [selfKey, selfValue] of self) {
       let found = false
       for (const [thatKey, thatValue] of that) {
@@ -291,7 +414,7 @@ const compareMaps = makeCompareMap(compareBoth, compareBoth)
 
 /** @internal */
 export function makeCompareSet<A>(equivalence: Equivalence<A>) {
-  return function compareSets(self: ReadonlySet<A>, that: ReadonlySet<A>): boolean {
+  return function compareSets(self: Iterable<A>, that: Iterable<A>): boolean {
     for (const selfValue of self) {
       let found = false
       for (const thatValue of that) {
@@ -312,38 +435,62 @@ export function makeCompareSet<A>(equivalence: Equivalence<A>) {
 const compareSets = makeCompareSet(compareBoth)
 
 /**
- * Determines if a value implements the `Equal` interface.
+ * Checks whether a value implements the {@link Equal} interface.
+ *
+ * When to use:
+ * - To branch on whether a value supports custom equality before calling
+ *   its `[Equal.symbol]` method directly.
+ * - In generic utility code that needs to distinguish `Equal` implementors
+ *   from plain values.
+ *
+ * Behavior:
+ * - Pure function, no side effects.
+ * - Returns `true` if and only if `u` has a property keyed by
+ *   {@link symbol}.
+ * - Acts as a TypeScript type guard, narrowing the input to {@link Equal}.
+ *
+ * **Example** (type guard)
  *
- * @example
  * ```ts
  * import { Equal, Hash } from "effect"
- * import * as assert from "node:assert"
  *
- * class MyClass implements Equal.Equal {
+ * class Token implements Equal.Equal {
+ *   constructor(readonly value: string) {}
  *   [Equal.symbol](that: Equal.Equal): boolean {
- *     return that instanceof MyClass
+ *     return that instanceof Token && this.value === that.value
  *   }
  *   [Hash.symbol](): number {
- *     return 0
+ *     return Hash.string(this.value)
  *   }
  * }
  *
- * const instance = new MyClass()
- * assert(Equal.isEqual(instance) === true)
- * assert(Equal.isEqual({}) === false)
- * assert(Equal.isEqual(42) === false)
+ * console.log(Equal.isEqual(new Token("abc"))) // true
+ * console.log(Equal.isEqual({ x: 1 }))         // false
+ * console.log(Equal.isEqual(42))                // false
  * ```
  *
+ * @see {@link Equal} — the interface being checked
+ * @see {@link symbol} — the property key that signals `Equal` support
+ *
  * @category guards
  * @since 2.0.0
  */
 export const isEqual = (u: unknown): u is Equal => hasProperty(u, symbol)
 
 /**
- * Creates an `Equivalence` instance using the `equals` function.
- * This allows the equality logic to be used with APIs that expect an `Equivalence`.
+ * Wraps {@link equals} as an `Equivalence<A>`.
+ *
+ * When to use:
+ * - When an API (e.g. `Array.dedupeWith`, `Equivalence.mapInput`) requires an
+ *   `Equivalence` and you want to reuse `Equal.equals`.
+ *
+ * Behavior:
+ * - Returns a function `(a: A, b: A) => boolean` that delegates to
+ *   {@link equals}.
+ * - Pure; allocates a thin wrapper on each call.
+ *
+ * **Example** (deduplicating with Equal semantics)
  *
- * @example
  * ```ts
  * import { Array, Equal } from "effect"
  *
@@ -352,72 +499,92 @@ export const isEqual = (u: unknown): u is Equal => hasProperty(u, symbol)
  * console.log(result) // [1, 2, 3]
  * ```
  *
+ * @see {@link equals} — the underlying comparison function
+ *
  * @category instances
  * @since 2.0.0
  */
 export const asEquivalence: <A>() => Equivalence<A> = () => equals
 
 /**
- * Creates a proxy of an object that uses reference equality instead of structural equality.
+ * Creates a proxy that uses reference equality instead of structural equality.
  *
- * By default, plain objects and arrays use structural equality. This function creates
- * a proxy that behaves exactly like the original object but uses reference equality
- * for comparison purposes.
+ * When to use:
+ * - When you have a plain object or array that should be compared by identity
+ *   (reference), not by contents.
+ * - When you want to preserve the original object unchanged and get a new
+ *   reference-equal handle.
  *
- * @example
- * ```ts
- * import { Equal } from "effect"
- * import * as assert from "node:assert"
+ * Behavior:
+ * - Returns a `Proxy` wrapping `obj`. The proxy reads through to the
+ *   original, so property access is unchanged.
+ * - The proxy is registered in an internal WeakSet; {@link equals} returns
+ *   `false` for any pair where at least one operand is in that set (unless
+ *   they are the same reference).
+ * - Each call creates a **new** proxy, so `byReference(x) !== byReference(x)`.
+ * - Does **not** mutate the original object (unlike {@link byReferenceUnsafe}).
  *
- * const obj1 = { a: 1, b: 2 }
- * const obj2 = { a: 1, b: 2 }
+ * **Example** (opting out of structural equality)
  *
- * // Normal structural equality
- * assert(Equal.equals(obj1, obj2) === true)
+ * ```ts
+ * import { Equal } from "effect"
  *
- * // Create reference equality version
- * const obj1ByRef = Equal.byReference(obj1)
- * assert(Equal.equals(obj1ByRef, obj2) === false) // uses reference equality
- * assert(Equal.equals(obj1ByRef, obj1ByRef) === true) // same reference
+ * const a = { x: 1 }
+ * const b = { x: 1 }
  *
- * // Each call creates a new proxy instance
- * const obj1ByRef2 = Equal.byReference(obj1)
- * assert(Equal.equals(obj1ByRef, obj1ByRef2) === false) // different instances
+ * console.log(Equal.equals(a, b)) // true  (structural)
  *
- * // Proxy behaves like the original
- * assert(obj1ByRef.a === 1)
+ * const aRef = Equal.byReference(a)
+ * console.log(Equal.equals(aRef, b))    // false (reference)
+ * console.log(Equal.equals(aRef, aRef)) // true  (same reference)
+ * console.log(aRef.x)                   // 1     (proxy reads through)
  * ```
  *
+ * @see {@link byReferenceUnsafe} — same effect without a proxy (mutates the
+ *   original)
+ * @see {@link equals} — the comparison function affected by this opt-out
+ *
  * @category utility
  * @since 2.0.0
  */
 export const byReference = <T extends object>(obj: T): T => byReferenceUnsafe(new Proxy(obj, {}))
 
 /**
- * Marks an object to use reference equality instead of structural equality, without creating a proxy.
+ * Permanently marks an object to use reference equality, without creating a
+ * proxy.
  *
- * Unlike `byReference`, this function directly modifies the object's equality behavior
- * without creating a proxy wrapper. This is more performant but "unsafe" because
- * it permanently changes how the object is compared.
+ * When to use:
+ * - When you want reference equality semantics and can accept that the
+ *   original object is **permanently** modified.
+ * - When proxy overhead is unacceptable (hot paths, large collections).
+ *
+ * Behavior:
+ * - Adds `obj` to an internal WeakSet. From that point on, {@link equals}
+ *   treats it as reference-only.
+ * - Returns the **same** object (not a copy or proxy), so
+ *   `byReferenceUnsafe(x) === x`.
+ * - The marking is irreversible for the lifetime of the object.
+ * - Does **not** affect the object's prototype, properties, or behavior
+ *   beyond equality checks.
+ *
+ * **Example** (marking an object for reference equality)
  *
- * @example
  * ```ts
  * import { Equal } from "effect"
- * import * as assert from "node:assert"
  *
  * const obj1 = { a: 1, b: 2 }
  * const obj2 = { a: 1, b: 2 }
  *
- * // Mark obj1 for reference equality (modifies obj1 directly)
- * const obj1ByRef = Equal.byReferenceUnsafe(obj1)
- * assert(obj1ByRef === obj1) // Same object, no proxy created
- * assert(Equal.equals(obj1ByRef, obj2) === false) // uses reference equality
- * assert(Equal.equals(obj1ByRef, obj1ByRef) === true) // same reference
+ * Equal.byReferenceUnsafe(obj1)
  *
- * // The original obj1 is now permanently marked for reference equality
- * assert(Equal.equals(obj1, obj2) === false) // obj1 uses reference equality
+ * console.log(Equal.equals(obj1, obj2))   // false (reference)
+ * console.log(Equal.equals(obj1, obj1))   // true  (same reference)
+ * console.log(obj1 === Equal.byReferenceUnsafe(obj1)) // true (same object)
  * ```
  *
+ * @see {@link byReference} — safer alternative that creates a proxy
+ * @see {@link equals} — the comparison function affected by this opt-out
+ *
  * @category utility
  * @since 2.0.0
  */

package/src/FileSystem.ts

@@ -733,8 +733,7 @@ export const make = (
         Effect.as(true),
         Effect.catchTag(
           "PlatformError",
-          (e) =>
-            e.reason._tag === "SystemError" && e.reason.kind === "NotFound" ? Effect.succeed(false) : Effect.fail(e)
+          (e) => e.reason._tag === "NotFound" ? Effect.succeed(false) : Effect.fail(e)
         )
       ),
     readFileString: (path, encoding) =>
@@ -757,16 +756,16 @@ export const make = (
       const bytesToRead = options?.bytesToRead !== undefined ? Size(options.bytesToRead) : undefined
       let totalBytesRead = BigInt(0)
       const chunkSize = Size(options?.chunkSize ?? 64 * 1024)
+      const readChunk = file.readAlloc(chunkSize)
       return Stream.fromPull(Effect.succeed(
         Effect.flatMap(
           Effect.suspend((): Pull.Pull<Uint8Array | undefined, PlatformError> => {
             if (bytesToRead !== undefined && bytesToRead <= totalBytesRead) {
               return Cause.done()
             }
-            const toRead = bytesToRead !== undefined && (bytesToRead - totalBytesRead) < chunkSize
-              ? bytesToRead - totalBytesRead
-              : chunkSize
-            return file.readAlloc(toRead)
+            return bytesToRead !== undefined && (bytesToRead - totalBytesRead) < chunkSize
+              ? file.readAlloc(bytesToRead - totalBytesRead)
+              : readChunk
           }),
           (buf) => {
             if (!buf) return Cause.done()
@@ -802,7 +801,7 @@ const notFound = (method: string, path: string) =>
   systemError({
     module: "FileSystem",
     method,
-    kind: "NotFound",
+    _tag: "NotFound",
     description: "No such file or directory",
     pathOrDescriptor: path
   })
@@ -829,9 +828,9 @@ const notFound = (method: string, path: string) =>
  *     }
  *     return Effect.fail(
  *       PlatformError.systemError({
+ *         _tag: "NotFound",
  *         module: "FileSystem",
  *         method: "readFileString",
- *         kind: "NotFound",
  *         description: "File not found",
  *         pathOrDescriptor: path
  *       })

package/src/Filter.ts

@@ -7,7 +7,7 @@ import { dual } from "./Function.ts"
 import * as Option from "./Option.ts"
 import * as Predicate from "./Predicate.ts"
 import * as Result from "./Result.ts"
-import type { EqualsWith, ExcludeTag, ExtractTag, Tags } from "./Types.ts"
+import type { EqualsWith, ExcludeTag, ExtractReason, ExtractTag, ReasonTags, Tags } from "./Types.ts"
 
 /**
  * Represents a filter function that can transform inputs to outputs or filter them out.
@@ -456,6 +456,53 @@ const taggedImpl =
   <Input>(input: Input): Result.Result<ExtractTag<Input, Tag>, ExcludeTag<Input, Tag>> =>
     Predicate.isTagged(input, tag) ? Result.succeed(input as any) : Result.fail(input as ExcludeTag<Input, Tag>)
 
+/**
+ * Creates a filter that extracts a reason from a tagged error.
+ *
+ * @since 4.0.0
+ * @category Constructors
+ */
+export const reason: {
+  /**
+   * Creates a filter that extracts a reason from a tagged error.
+   *
+   * @since 4.0.0
+   * @category Constructors
+   */
+  <Input>(): <const Tag extends Tags<Input>, const ReasonTag extends ReasonTags<ExtractTag<Input, Tag>>>(
+    tag: Tag,
+    reasonTag: ReasonTag
+  ) => Filter<Input, ExtractReason<ExtractTag<Input, Tag>, ReasonTag>, Input>
+  /**
+   * Creates a filter that extracts a reason from a tagged error.
+   *
+   * @since 4.0.0
+   * @category Constructors
+   */
+  <Input, const Tag extends Tags<Input>, const ReasonTag extends ReasonTags<ExtractTag<Input, Tag>>>(tag: Tag, reasonTag: ReasonTag): Filter<Input, ExtractReason<ExtractTag<Input, Tag>, ReasonTag>, Input>
+  /**
+   * Creates a filter that extracts a reason from a tagged error.
+   *
+   * @since 4.0.0
+   * @category Constructors
+   */
+  <const Tag extends string, const ReasonTag extends string>(tag: Tag, reasonTag: ReasonTag): <Input>(input: Input) => Result.Result<ExtractReason<ExtractTag<Input, Tag>, ReasonTag>, Input>
+} = function() {
+  return arguments.length === 0 ? reasonImpl : reasonImpl(arguments[0] as any, arguments[1] as any)
+} as any
+
+const reasonImpl =
+  <const Tag extends string, const ReasonTag extends string>(tag: Tag, reasonTag: ReasonTag) =>
+  <Input>(input: Input): Result.Result<ExtractTag<Input, Tag>, ExcludeTag<Input, Tag>> => {
+    if (
+      Predicate.isTagged(input, tag) && Predicate.hasProperty(input, "reason") &&
+      Predicate.isTagged(input.reason, reasonTag)
+    ) {
+      return Result.succeed(input.reason as any)
+    }
+    return Result.fail(input as any)
+  }
+
 /**
  * Creates a filter that only passes values equal to the specified value using structural equality.
  *