effect 4.0.1 → 4.0.3

package/src/Result.ts

@@ -7,6 +7,7 @@
  * for creating, checking, mapping, combining, and extracting results, plus
  * conversions to and from `Option` and nullable values.
  *
+ * @stability stable
  * @since 4.0.0
  */
 
@@ -60,6 +61,7 @@ const TypeId = "~effect/Result"
  * @see {@link match} to fold both branches
  * @see {@link isSuccess} / {@link isFailure} for type guards
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -90,6 +92,7 @@ export type Result<A, E = never> = Success<A, E> | Failure<A, E>
  * @see {@link isFailure} to narrow the type
  * @see {@link Success} for the other variant
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -118,6 +121,7 @@ export interface Failure<out A, out E> extends Pipeable, Inspectable {
  *
  * @see {@link gen} for writing generator-based `Result` code that consumes this iterator protocol
  *
+ * @stability stable
  * @category generators
  * @since 4.0.0
  */
@@ -152,6 +156,7 @@ export interface ResultIterator<T extends Result<any, any>> {
  * @see {@link isSuccess} to narrow the type
  * @see {@link Failure} for the other variant
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -177,6 +182,7 @@ export interface Success<out A, out E> extends Pipeable, Inspectable {
  * This is an internal interface used by the Effect type system. You typically
  * do not need to reference it directly.
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -192,6 +198,7 @@ export interface ResultUnify<T extends { [Unify.typeSymbol]?: any }> {
  * This is an internal interface used by the Effect type system. You typically
  * do not need to reference it directly.
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -206,6 +213,7 @@ export interface ResultUnifyIgnore {}
  * (e.g., `map`, `flatMap` abstractions). You typically do not need to
  * reference this directly.
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -234,6 +242,7 @@ export interface ResultTypeLambda extends TypeLambda {
  * const failure: E = "error"
  * ```
  *
+ * @stability stable
  * @since 4.0.0
  */
 export declare namespace Result {
@@ -272,6 +281,7 @@ export declare namespace Result {
  * @see {@link fail} to create a Failure
  * @see {@link void_ void} for a pre-built `Success<void>`
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -299,6 +309,7 @@ export const succeed: <A>(right: A) => Result<A> = result.succeed
  * @see {@link succeed} to create a Success
  * @see {@link mapError} to transform the error
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -329,6 +340,7 @@ export {
    *
    * @see {@link succeed} to create a Success with a specific value
    *
+   * @stability stable
    * @category constructors
    * @since 3.13.0
    */
@@ -359,6 +371,7 @@ export {
  *
  * @see {@link fail} to create a Failure with a specific value
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -392,6 +405,7 @@ export const failVoid: Result<never, void> = fail(void 0)
  * @see {@link fromOption} to convert from an Option
  * @see {@link succeed} / {@link fail} for direct construction
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -424,6 +438,7 @@ export const fromNullishOr: {
    * @see {@link fromOption} to convert from an Option
    * @see {@link succeed} / {@link fail} for direct construction
    *
+   * @stability stable
    * @category constructors
    * @since 4.0.0
    */
@@ -456,6 +471,7 @@ export const fromNullishOr: {
    * @see {@link fromOption} to convert from an Option
    * @see {@link succeed} / {@link fail} for direct construction
    *
+   * @stability stable
    * @category constructors
    * @since 4.0.0
    */
@@ -494,6 +510,7 @@ export const fromNullishOr: {
  * @see {@link getFailure} to extract the failure value as an Option
  * @see {@link fromNullishOr} to build a Result from nullable values
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -526,6 +543,7 @@ export const fromOption: {
    * @see {@link getFailure} to extract the failure value as an Option
    * @see {@link fromNullishOr} to build a Result from nullable values
    *
+   * @stability stable
    * @category constructors
    * @since 2.0.0
    */
@@ -558,6 +576,7 @@ export const fromOption: {
    * @see {@link getFailure} to extract the failure value as an Option
    * @see {@link fromNullishOr} to build a Result from nullable values
    *
+   * @stability stable
    * @category constructors
    * @since 2.0.0
    */
@@ -621,6 +640,7 @@ export {
    * @see {@link succeed} / {@link fail} for direct construction
    * @see {@link fromNullishOr} for nullable values
    *
+   * @stability stable
    * @category constructors
    * @since 2.0.0
    */
@@ -651,6 +671,7 @@ export {
  *
  * @see {@link isSuccess} / {@link isFailure} to narrow to a specific variant
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -683,6 +704,7 @@ export const isResult: (input: unknown) => input is Result<unknown, unknown> = r
  * @see {@link isSuccess} for the opposite check
  * @see {@link isResult} to check if a value is any Result
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -715,6 +737,7 @@ export const isFailure: <A, E>(self: Result<A, E>) => self is Failure<A, E> = re
  * @see {@link isFailure} for the opposite check
  * @see {@link isResult} to check if a value is any Result
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -746,6 +769,7 @@ export const isSuccess: <A, E>(self: Result<A, E>) => self is Success<A, E> = re
  * @see {@link getFailure} to extract the error instead
  * @see {@link fromOption} for the reverse conversion
  *
+ * @stability stable
  * @category getters
  * @since 4.0.0
  */
@@ -777,6 +801,7 @@ export const getSuccess: <A, E>(self: Result<A, E>) => Option<A> = result.getSuc
  * @see {@link getSuccess} to extract the success instead
  * @see {@link fromOption} for the reverse conversion
  *
+ * @stability stable
  * @category getters
  * @since 4.0.0
  */
@@ -806,6 +831,7 @@ export const getFailure: <A, E>(self: Result<A, E>) => Option<E> = result.getFai
  * eq(Result.succeed(1), Result.fail("x")) // => false
  * ```
  *
+ * @stability stable
  * @category instances
  * @since 4.0.0
  */
@@ -850,6 +876,7 @@ export const makeEquivalence = <A, E>(
  * @see {@link mapError} to transform only the error value
  * @see {@link match} to fold into a single value
  *
+ * @stability stable
  * @category mapping
  * @since 2.0.0
  */
@@ -885,6 +912,7 @@ export const mapBoth: {
    * @see {@link mapError} to transform only the error value
    * @see {@link match} to fold into a single value
    *
+   * @stability stable
    * @category mapping
    * @since 2.0.0
    */
@@ -925,6 +953,7 @@ export const mapBoth: {
    * @see {@link mapError} to transform only the error value
    * @see {@link match} to fold into a single value
    *
+   * @stability stable
    * @category mapping
    * @since 2.0.0
    */
@@ -969,6 +998,7 @@ export const mapBoth: {
  * @see {@link map} to transform only the success value
  * @see {@link mapBoth} to transform both channels
  *
+ * @stability stable
  * @category mapping
  * @since 4.0.0
  */
@@ -999,6 +1029,7 @@ export const mapError: {
    * @see {@link map} to transform only the success value
    * @see {@link mapBoth} to transform both channels
    *
+   * @stability stable
    * @category mapping
    * @since 4.0.0
    */
@@ -1029,6 +1060,7 @@ export const mapError: {
    * @see {@link map} to transform only the success value
    * @see {@link mapBoth} to transform both channels
    *
+   * @stability stable
    * @category mapping
    * @since 4.0.0
    */
@@ -1068,6 +1100,7 @@ export const mapError: {
  * @see {@link mapBoth} to transform both channels
  * @see {@link flatMap} when `f` returns a `Result`
  *
+ * @stability stable
  * @category mapping
  * @since 2.0.0
  */
@@ -1101,6 +1134,7 @@ export const map: {
    * @see {@link mapBoth} to transform both channels
    * @see {@link flatMap} when `f` returns a `Result`
    *
+   * @stability stable
    * @category mapping
    * @since 2.0.0
    */
@@ -1134,6 +1168,7 @@ export const map: {
    * @see {@link mapBoth} to transform both channels
    * @see {@link flatMap} when `f` returns a `Result`
    *
+   * @stability stable
    * @category mapping
    * @since 2.0.0
    */
@@ -1176,6 +1211,7 @@ export const map: {
  * @see {@link merge} to extract `A | E` without mapping
  * @see {@link getOrElse} to unwrap only the success with a fallback
  *
+ * @stability stable
  * @category pattern matching
  * @since 2.0.0
  */
@@ -1212,6 +1248,7 @@ export const match: {
    * @see {@link merge} to extract `A | E` without mapping
    * @see {@link getOrElse} to unwrap only the success with a fallback
    *
+   * @stability stable
    * @category pattern matching
    * @since 2.0.0
    */
@@ -1253,6 +1290,7 @@ export const match: {
    * @see {@link merge} to extract `A | E` without mapping
    * @see {@link getOrElse} to unwrap only the success with a fallback
    *
+   * @stability stable
    * @category pattern matching
    * @since 2.0.0
    */
@@ -1303,6 +1341,7 @@ export const match: {
  * @see {@link filterOrFail} to validate a value that is already in a `Result`
  * @see {@link fromNullishOr} for nullable-based construction
  *
+ * @stability stable
  * @category constructors
  * @since 3.4.0
  */
@@ -1339,6 +1378,7 @@ export const liftPredicate: {
    * @see {@link filterOrFail} to validate a value that is already in a `Result`
    * @see {@link fromNullishOr} for nullable-based construction
    *
+   * @stability stable
    * @category constructors
    * @since 3.4.0
    */
@@ -1375,6 +1415,7 @@ export const liftPredicate: {
    * @see {@link filterOrFail} to validate a value that is already in a `Result`
    * @see {@link fromNullishOr} for nullable-based construction
    *
+   * @stability stable
    * @category constructors
    * @since 3.4.0
    */
@@ -1411,6 +1452,7 @@ export const liftPredicate: {
    * @see {@link filterOrFail} to validate a value that is already in a `Result`
    * @see {@link fromNullishOr} for nullable-based construction
    *
+   * @stability stable
    * @category constructors
    * @since 3.4.0
    */
@@ -1447,6 +1489,7 @@ export const liftPredicate: {
    * @see {@link filterOrFail} to validate a value that is already in a `Result`
    * @see {@link fromNullishOr} for nullable-based construction
    *
+   * @stability stable
    * @category constructors
    * @since 3.4.0
    */
@@ -1491,6 +1534,7 @@ export const liftPredicate: {
  * @see {@link liftPredicate} to create a `Result` from a raw value with a predicate
  * @see {@link flatMap} for general conditional chaining
  *
+ * @stability stable
  * @category filtering
  * @since 4.0.0
  */
@@ -1529,6 +1573,7 @@ export const filterOrFail: {
    * @see {@link liftPredicate} to create a `Result` from a raw value with a predicate
    * @see {@link flatMap} for general conditional chaining
    *
+   * @stability stable
    * @category filtering
    * @since 4.0.0
    */
@@ -1570,6 +1615,7 @@ export const filterOrFail: {
    * @see {@link liftPredicate} to create a `Result` from a raw value with a predicate
    * @see {@link flatMap} for general conditional chaining
    *
+   * @stability stable
    * @category filtering
    * @since 4.0.0
    */
@@ -1608,6 +1654,7 @@ export const filterOrFail: {
    * @see {@link liftPredicate} to create a `Result` from a raw value with a predicate
    * @see {@link flatMap} for general conditional chaining
    *
+   * @stability stable
    * @category filtering
    * @since 4.0.0
    */
@@ -1650,6 +1697,7 @@ export const filterOrFail: {
    * @see {@link liftPredicate} to create a `Result` from a raw value with a predicate
    * @see {@link flatMap} for general conditional chaining
    *
+   * @stability stable
    * @category filtering
    * @since 4.0.0
    */
@@ -1683,6 +1731,7 @@ export const filterOrFail: {
  * @see {@link match} to map each branch to a common type
  * @see {@link getOrElse} to provide a fallback for failures
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -1717,6 +1766,7 @@ export const merge: <A, E>(self: Result<A, E>) => E | A = match({ onFailure: ide
  * @see {@link match} to map both branches
  * @see {@link orElse} to recover with another Result instead of unwrapping
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -1750,6 +1800,7 @@ export const getOrElse: {
    * @see {@link match} to map both branches
    * @see {@link orElse} to recover with another Result instead of unwrapping
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -1783,6 +1834,7 @@ export const getOrElse: {
    * @see {@link match} to map both branches
    * @see {@link orElse} to recover with another Result instead of unwrapping
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -1819,6 +1871,7 @@ export const getOrElse: {
  * @see {@link getOrUndefined} to return `undefined` instead
  * @see {@link getOrElse} for a custom fallback
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -1850,6 +1903,7 @@ export const getOrNull: <A, E>(self: Result<A, E>) => A | null = getOrElse(const
  * @see {@link getOrNull} to return `null` instead
  * @see {@link getOrElse} for a custom fallback
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -1888,6 +1942,7 @@ export const getOrUndefined: <A, E>(self: Result<A, E>) => A | undefined = getOr
  * @see {@link getOrThrow} to throw the raw failure value
  * @see {@link getOrElse} for a non-throwing alternative
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -1925,6 +1980,7 @@ export const getOrThrowWith: {
    * @see {@link getOrThrow} to throw the raw failure value
    * @see {@link getOrElse} for a non-throwing alternative
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -1962,6 +2018,7 @@ export const getOrThrowWith: {
    * @see {@link getOrThrow} to throw the raw failure value
    * @see {@link getOrElse} for a non-throwing alternative
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -2000,6 +2057,7 @@ export const getOrThrowWith: {
  * @see {@link getOrThrowWith} for custom error mapping
  * @see {@link getOrElse} for a non-throwing alternative
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -2033,6 +2091,7 @@ export const getOrThrow: <A, E>(self: Result<A, E>) => A = getOrThrowWith(identi
  * @see {@link getOrElse} to unwrap with a fallback value (not a Result)
  * @see {@link mapError} to transform the error without recovering
  *
+ * @stability stable
  * @category error handling
  * @since 2.0.0
  */
@@ -2065,6 +2124,7 @@ export const orElse: {
    * @see {@link getOrElse} to unwrap with a fallback value (not a Result)
    * @see {@link mapError} to transform the error without recovering
    *
+   * @stability stable
    * @category error handling
    * @since 2.0.0
    */
@@ -2097,6 +2157,7 @@ export const orElse: {
    * @see {@link getOrElse} to unwrap with a fallback value (not a Result)
    * @see {@link mapError} to transform the error without recovering
    *
+   * @stability stable
    * @category error handling
    * @since 2.0.0
    */
@@ -2138,6 +2199,7 @@ export const orElse: {
  * @see {@link andThen} for a more flexible variant that also accepts plain values
  * @see {@link map} when `f` does not return a `Result`
  *
+ * @stability stable
  * @category sequencing
  * @since 2.0.0
  */
@@ -2173,6 +2235,7 @@ export const flatMap: {
    * @see {@link andThen} for a more flexible variant that also accepts plain values
    * @see {@link map} when `f` does not return a `Result`
    *
+   * @stability stable
    * @category sequencing
    * @since 2.0.0
    */
@@ -2208,6 +2271,7 @@ export const flatMap: {
    * @see {@link andThen} for a more flexible variant that also accepts plain values
    * @see {@link map} when `f` does not return a `Result`
    *
+   * @stability stable
    * @category sequencing
    * @since 2.0.0
    */
@@ -2260,6 +2324,7 @@ export const flatMap: {
  * @see {@link flatMap} for the stricter variant (function returning Result only)
  * @see {@link map} when you always return a plain value
  *
+ * @stability stable
  * @category sequencing
  * @since 2.0.0
  */
@@ -2306,6 +2371,7 @@ export const andThen: {
    * @see {@link flatMap} for the stricter variant (function returning Result only)
    * @see {@link map} when you always return a plain value
    *
+   * @stability stable
    * @category sequencing
    * @since 2.0.0
    */
@@ -2352,6 +2418,7 @@ export const andThen: {
    * @see {@link flatMap} for the stricter variant (function returning Result only)
    * @see {@link map} when you always return a plain value
    *
+   * @stability stable
    * @category sequencing
    * @since 2.0.0
    */
@@ -2398,6 +2465,7 @@ export const andThen: {
    * @see {@link flatMap} for the stricter variant (function returning Result only)
    * @see {@link map} when you always return a plain value
    *
+   * @stability stable
    * @category sequencing
    * @since 2.0.0
    */
@@ -2444,6 +2512,7 @@ export const andThen: {
    * @see {@link flatMap} for the stricter variant (function returning Result only)
    * @see {@link map} when you always return a plain value
    *
+   * @stability stable
    * @category sequencing
    * @since 2.0.0
    */
@@ -2490,6 +2559,7 @@ export const andThen: {
    * @see {@link flatMap} for the stricter variant (function returning Result only)
    * @see {@link map} when you always return a plain value
    *
+   * @stability stable
    * @category sequencing
    * @since 2.0.0
    */
@@ -2536,6 +2606,7 @@ export const andThen: {
    * @see {@link flatMap} for the stricter variant (function returning Result only)
    * @see {@link map} when you always return a plain value
    *
+   * @stability stable
    * @category sequencing
    * @since 2.0.0
    */
@@ -2582,6 +2653,7 @@ export const andThen: {
    * @see {@link flatMap} for the stricter variant (function returning Result only)
    * @see {@link map} when you always return a plain value
    *
+   * @stability stable
    * @category sequencing
    * @since 2.0.0
    */
@@ -2628,6 +2700,7 @@ export const andThen: {
    * @see {@link flatMap} for the stricter variant (function returning Result only)
    * @see {@link map} when you always return a plain value
    *
+   * @stability stable
    * @category sequencing
    * @since 2.0.0
    */
@@ -2676,6 +2749,7 @@ export const andThen: {
  * @see {@link flatMap} for chaining two Results sequentially
  * @see {@link gen} for generator-based composition of multiple Results
  *
+ * @stability stable
  * @category sequencing
  * @since 2.0.0
  */
@@ -2742,6 +2816,7 @@ export const all: <const I extends Iterable<Result<any, any>> | Record<string, R
  *
  * @see {@link mapError} to transform the error without swapping
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -2778,6 +2853,7 @@ export const flip = <A, E>(self: Result<A, E>): Result<E, A> =>
  * @see {@link flatMap} for point-free sequential composition
  * @see {@link all} to collect multiple independent Results
  *
+ * @stability stable
  * @category generators
  * @since 2.0.0
  */
@@ -2832,6 +2908,7 @@ export const gen: Gen.Gen<ResultTypeLambda> = (...args) => {
  * @see {@link gen} for an alternative generator-based syntax
  * @see {@link bindTo} for starting a do-notation chain from an existing Result
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -2869,6 +2946,7 @@ export const Do: Result<{}> = succeed({})
  * @see {@link let_ let} for pure computed fields
  * @see {@link bindTo} to wrap an initial Result into a named field
  *
+ * @stability stable
  * @category sequencing
  * @since 2.0.0
  */
@@ -2905,6 +2983,7 @@ export const bind: {
    * @see {@link let_ let} for pure computed fields
    * @see {@link bindTo} to wrap an initial Result into a named field
    *
+   * @stability stable
    * @category sequencing
    * @since 2.0.0
    */
@@ -2941,6 +3020,7 @@ export const bind: {
    * @see {@link let_ let} for pure computed fields
    * @see {@link bindTo} to wrap an initial Result into a named field
    *
+   * @stability stable
    * @category sequencing
    * @since 2.0.0
    */
@@ -2979,6 +3059,7 @@ export const bind: {
  * @see {@link Do} to start from an empty object
  * @see {@link bind} to add more fields
  *
+ * @stability stable
  * @category mapping
  * @since 2.0.0
  */
@@ -3011,6 +3092,7 @@ export const bindTo: {
    * @see {@link Do} to start from an empty object
    * @see {@link bind} to add more fields
    *
+   * @stability stable
    * @category mapping
    * @since 2.0.0
    */
@@ -3043,6 +3125,7 @@ export const bindTo: {
    * @see {@link Do} to start from an empty object
    * @see {@link bind} to add more fields
    *
+   * @stability stable
    * @category mapping
    * @since 2.0.0
    */
@@ -3092,6 +3175,7 @@ export {
    * @see {@link Do} to start the do-notation chain
    * @see {@link bind} for Result-producing fields
    *
+   * @stability stable
    * @category mapping
    * @since 2.0.0
    */
@@ -3124,6 +3208,7 @@ export {
  *
  * @see {@link transposeMapOption} to map and transpose in one step
  *
+ * @stability stable
  * @category transposing
  * @since 3.14.0
  */
@@ -3165,6 +3250,7 @@ export const transposeOption = <A = never, E = never>(
  *
  * @see {@link transposeOption} when the Option already contains a Result
  *
+ * @stability stable
  * @category transposing
  * @since 3.15.0
  */
@@ -3201,6 +3287,7 @@ export const transposeMapOption = dual<
    *
    * @see {@link transposeOption} when the Option already contains a Result
    *
+   * @stability stable
    * @category transposing
    * @since 3.15.0
    */
@@ -3237,6 +3324,7 @@ export const transposeMapOption = dual<
    *
    * @see {@link transposeOption} when the Option already contains a Result
    *
+   * @stability stable
    * @category transposing
    * @since 3.15.0
    */
@@ -3268,6 +3356,7 @@ export const transposeMapOption = dual<
  * @see {@link transposeOption} to transpose an Option that already contains a Result
  * @see {@link transposeMapOption} to map and transpose an Option in one step
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -3291,6 +3380,7 @@ export const succeedNone = succeed(option_.none)
  *
  * @see {@link succeedNone} for the `None` counterpart
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -3323,6 +3413,7 @@ export const succeedSome = <A, E = never>(a: A): Result<Option<A>, E> => succeed
  *
  * @see {@link map} to transform the success value
  *
+ * @stability stable
  * @category mapping
  * @since 4.0.0
  */
@@ -3354,6 +3445,7 @@ export const tap: {
    *
    * @see {@link map} to transform the success value
    *
+   * @stability stable
    * @category mapping
    * @since 4.0.0
    */
@@ -3385,6 +3477,7 @@ export const tap: {
    *
    * @see {@link map} to transform the success value
    *
+   * @stability stable
    * @category mapping
    * @since 4.0.0
    */