Skip to content
Effect Days 2026 Get your ticket

Result

Models a value that has already succeeded or failed.

A Result<A, E> is Success<A, E> when a value is available and Failure<A, E> when an error is available. It is plain data, so inspecting or transforming it does not run side effects. This module includes helpers for creating, checking, mapping, combining, and extracting results, plus conversions to and from Option and nullable values.

48 exports Added in v2.0.0 Source

Constructors

Do

Added in v2.0.0 Source

Provides the starting point for the "do notation" simulation with Result.

When to use

Use to start a Result do-notation pipeline from an empty successful record before adding named fields from Result-producing computations and pure computed values.

Details

Creates a Result<{}> (success with an empty object). Use with bind to add Result-producing fields and let to add pure computed fields.

See

  • bind to add Result-producing fields
  • let to add pure computed fields
  • gen for an alternative generator-based syntax
  • bindTo for starting a do-notation chain from an existing Result

Signature

declare const Do: Result<{}>

Example

(Building an object step by step)

import { pipe, Result } from "effect"


pipe(
  Result.Do,
  Result.bind("x", () => Result.succeed(2)),
  Result.bind("y", () => Result.succeed(3)),
  Result.let("sum", ({ x, y }) => x + y)
) // => Result.succeed({ x: 2, y: 3, sum: 5 })

fail

Added in v4.0.0 Source

Creates a Result holding a Failure value.

When to use

Use to represent a failed Result with a typed failure value.

Details

  • The success type A defaults to never

See

Signature

declare const fail: <E>(left: E) => Result<never, E>

Example

(Creating a failure)

import { Result } from "effect"


Result.fail("Something went wrong") // => Result.fail("Something went wrong")

failVoid

Added in v4.0.0 Source

Provides a pre-built failed Result whose failure value is undefined.

When to use

Use when you need a failed Result value that acts only as a control signal without failure data.

Details

This is equivalent to Result.fail(undefined) with type Result<never, void>, but reuses a shared Failure wrapper instead of allocating one each time.

See

  • fail to create a Failure with a specific value

Signature

declare const failVoid: Result<never, void>

Example

(Failing without a payload)

import { Result } from "effect"


Result.failVoid // => Result.fail(undefined)

fromNullishOr

Added in v4.0.0 Source

Converts a possibly null or undefined value into a Result.

When to use

Use when you need null or undefined input to become a Failure while present values remain available as Success.

Details

  • Non-nullish values become Success<NonNullable<A>>
  • null or undefined becomes Failure<E> using the provided function
  • Supports both data-first and data-last (piped) usage
  • The onNullish callback receives the original value

See

Signature

declare const fromNullishOr: {
  <A, E>(onNullish: (a: A) => E): (self: A) => Result<NonNullable<A>, E>;
  <A, E>(self: A, onNullish: (a: A) => E): Result<NonNullable<A>, E>;
}

Example

(Handling nullable values)

import { Result } from "effect"


Result.fromNullishOr(1, () => "fallback") // => Result.succeed(1)


Result.fromNullishOr(null, () => "fallback") // => Result.fail("fallback")

fromOption

Added in v2.0.0 Source

Converts an Option<A> into a Result<A, E>.

When to use

Use when an existing Option should become a Result, preserving Some as success and turning None into a caller-provided failure.

Details

  • Some<A> becomes Success<A>
  • None becomes Failure<E> using the provided function
  • Supports both data-first and data-last (piped) usage

See

Signature

declare const fromOption: {
  <E>(onNone: () => E): <A>(self: Option<A>) => Result<A, E>;
  <A, E>(self: Option<A>, onNone: () => E): Result<A, E>;
}

Example

(Converting an Option to a Result)

import { Option, Result } from "effect"


Result.fromOption(Option.some(1), () => "missing") // => Result.succeed(1)


Result.fromOption(Option.none(), () => "missing") // => Result.fail("missing")

liftPredicate

Added in v3.4.0 Source

Lifts a value into a Result based on a predicate or refinement.

When to use

Use to construct a Result from a raw value guarded by a predicate or refinement.

Details

  • If the predicate returns true, the value becomes Success<A>
  • If the predicate returns false, orFailWith produces the error for Failure<E>
  • Also accepts a Refinement to narrow the success type
  • Supports both data-first and data-last (piped) usage

See

Signature

declare const liftPredicate: {
  <A, B, E>(refinement: Refinement<A, B>, orFailWith: (a: A) => E): (a: A) => Result<B, E>;
  <B, E, A = B>(predicate: Predicate<A>, orFailWith: (a: A) => E): (a: B) => Result<B, E>;
  <A, E, B>(self: A, refinement: Refinement<A, B>, orFailWith: (a: A) => E): Result<B, E>;
  <B, E, A = B>(self: B, predicate: Predicate<A>, orFailWith: (a: A) => E): Result<B, E>;
}

Example

(Validating a number)

import { pipe, Result } from "effect"


pipe(
  5,
  Result.liftPredicate(
    (n: number) => n > 0,
    (n) => `${n} is not positive`
  )
) // => Result.succeed(5)

succeed

Added in v4.0.0 Source

Creates a Result holding a Success value.

Details

  • Use when you have a value and want to lift it into the Result type
  • The error type E defaults to never

See

  • fail to create a Failure
  • void for a pre-built Success<void>

Signature

declare const succeed: <A>(right: A) => Result<A>

Example

(Wrapping a value)

import { Result } from "effect"


Result.succeed(42) // => Result.succeed(42)

succeedNone

Added in v4.0.0 Source

Provides a pre-built Result<Option<never>> that succeeds with None.

When to use

Use when an optional success should be absent, such as the None branch of transposeOption or transposeMapOption.

Details

This is equivalent to Result.succeed(Option.none()), but reuses a shared Success wrapper instead of allocating one each time.

See

Signature

declare const succeedNone: Result<Option<never>, never>

Example

(Succeeding with None)

import { Option, Result } from "effect"


Result.succeedNone // => Result.succeed(Option.none())

succeedSome

Added in v4.0.0 Source

Creates a Result<Option<A>> that succeeds with Some(a).

Details

  • Equivalent to Result.succeed(Option.some(a))
  • Useful with transposeOption patterns

See

Signature

declare function succeedSome<A, E = never>(a: A): Result<Option<A>, E>

Example

(Wrapping a value in Some inside a Result)

import { Option, Result } from "effect"


Result.succeedSome(42) // => Result.succeed(Option.some(42))

Error Handling

orElse

Added in v2.0.0 Source

Returns the original Result if it is a Success, otherwise applies that to the error and returns the resulting Result.

When to use

Use when a failure should recover into another Result while keeping successes unchanged.

Details

  • Success<A> is returned unchanged
  • Failure<E> calls that(e) to produce a new Result

See

  • getOrElse to unwrap with a fallback value (not a Result)
  • mapError to transform the error without recovering

Signature

declare const orElse: {
  <E, A2, E2>(that: (err: E) => Result<A2, E2>): <A>(self: Result<A, E>) => Result<A2 | A, E2>;
  <A, E, A2, E2>(self: Result<A, E>, that: (err: E) => Result<A2, E2>): Result<A | A2, E2>;
}

Example

(Recovering from a failure)

import { pipe, Result } from "effect"


pipe(
  Result.fail("primary failed"),
  Result.orElse(() => Result.succeed(99))
) // => Result.succeed(99)

Filtering

filterOrFail

Added in v4.0.0 Source

Validates the success value of a Result using a predicate, failing with a custom error if the predicate returns false.

When to use

Use to validate an already-successful Result value with a predicate or refinement.

Details

  • If the result is already a Failure, it is returned as-is
  • If the predicate passes, the Success is returned unchanged
  • If the predicate fails, orFailWith produces the error for a new Failure
  • Also accepts a Refinement to narrow the success type
  • The error type of the output is the union of both error types

See

  • liftPredicate to create a Result from a raw value with a predicate
  • flatMap for general conditional chaining

Signature

declare const filterOrFail: {
  <A, B, E2>(refinement: Refinement<NoInfer<A>, B>, orFailWith: (value: NoInfer<A>) => E2): <E>(self: Result<A, E>) => Result<B, E2 | E>;
  <A, E2>(predicate: Predicate<NoInfer<A>>, orFailWith: (value: NoInfer<A>) => E2): <E>(self: Result<A, E>) => Result<A, E2 | E>;
  <A, E, B, E2>(self: Result<A, E>, refinement: Refinement<A, B>, orFailWith: (value: A) => E2): Result<B, E | E2>;
  <A, E, E2>(self: Result<A, E>, predicate: Predicate<A>, orFailWith: (value: A) => E2): Result<A, E | E2>;
}

Example

(Filtering a success value)

import { pipe, Result } from "effect"


pipe(
  Result.succeed(0),
  Result.filterOrFail(
    (n) => n > 0,
    (n) => `${n} is not positive`
  )
) // => Result.fail("0 is not positive")

Generators

gen

Added in v2.0.0 Source

Provides generator-based syntax for composing Result values sequentially.

When to use

Use when you need generator syntax to compose sequential Result computations instead of nested flatMap calls.

Details

  • Use yield* to unwrap a Result inside the generator; if any yielded Result is a Failure, the generator short-circuits and returns that failure
  • The return value of the generator is wrapped in Success
  • Evaluated eagerly and synchronously (unlike Effect.gen)

See

  • flatMap for point-free sequential composition
  • all to collect multiple independent Results

Signature

declare const gen: Gen.Gen<ResultTypeLambda>

Example

(Composing multiple Results)

import { Result } from "effect"


Result.gen(function*() {
  const a = yield* Result.succeed(1)
  const b = yield* Result.succeed(2)
  return a + b
}) // => Result.succeed(3)

ResultIterator interface

Added in v4.0.0 Source

Iterator protocol used to yield a Result inside gen, returning the success value type back to the generator.

When to use

Use when defining or typing [Symbol.iterator]() for Result values so yield* can pass the success value type back into Result.gen.

See

  • gen for writing generator-based Result code that consumes this iterator protocol

Signature

interface ResultIterator<T extends Result<any, any>> {
  next(...args: readonly Array<any>): IteratorResult<T, Success<T>>;
}

Getters

getFailure

Added in v4.0.0 Source

Extracts the failure value as an Option, discarding the success.

When to use

Use when you need to extract the failure value from a Result as an Option and discard successful values.

Details

  • Failure<E> becomes Some<E>
  • Success<A> becomes None

See

Signature

declare const getFailure: <A, E>(self: Result<A, E>) => Option<E>

Example

(Extracting the failure as an Option)

import { Option, Result } from "effect"


Result.getFailure(Result.succeed("ok")) // => Option.none()


Result.getFailure(Result.fail("err")) // => Option.some("err")

getOrElse

Added in v2.0.0 Source

Extracts the success value, or computes a fallback from the error.

When to use

Use when you need the success value from a Result, with a fallback computed from the failure value.

Details

  • Success<A> returns the inner value
  • Failure<E> applies onFailure to the error and returns the result
  • The return type is A | A2 (union of both branches)

See

Signature

declare const getOrElse: {
  <E, A2>(onFailure: (err: E) => A2): <A>(self: Result<A, E>) => A2 | A;
  <A, E, A2>(self: Result<A, E>, onFailure: (err: E) => A2): A | A2;
}

Example

(Providing a fallback)

import { Result } from "effect"


Result.getOrElse(Result.succeed(1), () => 0) // => 1


Result.getOrElse(Result.fail("err"), () => 0) // => 0

getOrNull

Added in v2.0.0 Source

Extracts the success value, or returns null on failure.

When to use

Use when you need to pass failed Result values to APIs that represent absence as null.

Details

  • Success<A> returns A
  • Failure<E> returns null

See

Signature

declare const getOrNull: <A, E>(self: Result<A, E>) => A | null

Example

(Unwrapping to nullable)

import { Result } from "effect"


Result.getOrNull(Result.succeed(1)) // => 1


Result.getOrNull(Result.fail("err")) // => null

getOrThrow

Added in v2.0.0 Source

Extracts the success value or throws the raw failure value E.

When to use

Use when unchecked boundaries should turn failures into thrown exceptions.

Details

  • Success<A> returns A
  • Failure<E> throws E directly
  • Use getOrThrowWith for a custom error object

See

Signature

declare const getOrThrow: <A, E>(self: Result<A, E>) => A

Example

(Unwrapping or throwing)

import { Result } from "effect"


Result.getOrThrow(Result.succeed(1)) // => 1


const failure = Result.try(() => Result.getOrThrow(Result.fail("error")))
Result.merge(failure) // => "error"

getOrThrowWith

Added in v2.0.0 Source

Extracts the success value or throws a custom error derived from the failure.

When to use

Use when converting a Result into a thrown exception with a custom error message or error type.

Details

  • Success<A> returns A
  • Failure<E> throws the value returned by onFailure(e)

See

Signature

declare const getOrThrowWith: {
  <E>(onFailure: (err: E) => unknown): <A>(self: Result<A, E>) => A;
  <A, E>(self: Result<A, E>, onFailure: (err: E) => unknown): A;
}

Example

(Throwing a custom error)

import { Result } from "effect"


Result.getOrThrowWith(Result.succeed(1), () => new Error("fail")) // => 1


const failure = Result.try({
  try: () => Result.getOrThrowWith(
    Result.fail("oops"),
    (error) => new Error(`Unexpected: ${error}`)
  ),
  catch: (error) => (error as Error).message
})
Result.merge(failure) // => "Unexpected: oops"

getOrUndefined

Added in v2.0.0 Source

Extracts the success value, or returns undefined on failure.

When to use

Use when you need to pass failed Result values to APIs that represent absence as undefined.

Details

  • Success<A> returns A
  • Failure<E> returns undefined

See

Signature

declare const getOrUndefined: <A, E>(self: Result<A, E>) => A | undefined

Example

(Unwrapping to optional)

import { Result } from "effect"


Result.getOrUndefined(Result.succeed(1)) // => 1


Result.getOrUndefined(Result.fail("err")) // => undefined

getSuccess

Added in v4.0.0 Source

Extracts the success value as an Option, discarding the failure.

When to use

Use when you need to extract the success value from a Result as an Option and discard failure information.

Details

  • Success<A> becomes Some<A>
  • Failure<E> becomes None

See

Signature

declare const getSuccess: <A, E>(self: Result<A, E>) => Option<A>

Example

(Extracting the success as an Option)

import { Option, Result } from "effect"


Result.getSuccess(Result.succeed("ok")) // => Option.some("ok")


Result.getSuccess(Result.fail("err")) // => Option.none()

merge

Added in v2.0.0 Source

Unwraps a Result into A | E by returning the inner value regardless of whether it is a success or failure.

Details

  • Success<A> returns A
  • Failure<E> returns E
  • Useful when both channels share a compatible type

See

  • match to map each branch to a common type
  • getOrElse to provide a fallback for failures

Signature

declare const merge: <A, E>(self: Result<A, E>) => E | A

Example

(Extracting the inner value)

import { Result } from "effect"


Result.merge(Result.succeed(42)) // => 42


Result.merge(Result.fail("error")) // => "error"

Guards

isFailure

Added in v4.0.0 Source

Checks whether a Result is a Failure.

When to use

Use to narrow a known Result to the Failure variant.

Details

  • Acts as a TypeScript type guard, narrowing to Failure<A, E>
  • After narrowing, you can access .failure to read the error value

See

Signature

declare const isFailure: <A, E>(self: Result<A, E>) => self is Failure<A, E>

Example

(Narrowing to failure)

import { Result } from "effect"


const result = Result.fail("oops")


if (Result.isFailure(result)) {
  result.failure // => "oops"
}

isResult

Added in v4.0.0 Source

Checks whether a value is a Result (either Success or Failure).

When to use

Use to validate unknown input before operating on it as a Result.

Details

  • Returns true for both Success and Failure variants
  • Acts as a TypeScript type guard, narrowing to Result<unknown, unknown>

See

Signature

declare const isResult: (input: unknown) => input is Result<unknown, unknown>

Example

(Checking if a value is a Result)

import { Result } from "effect"


Result.isResult(Result.succeed(1)) // => true


Result.isResult({ value: 1 }) // => false

isSuccess

Added in v4.0.0 Source

Checks whether a Result is a Success.

When to use

Use to narrow a known Result to the Success variant.

Details

  • Acts as a TypeScript type guard, narrowing to Success<A, E>
  • After narrowing, you can access .success to read the value

See

Signature

declare const isSuccess: <A, E>(self: Result<A, E>) => self is Success<A, E>

Example

(Narrowing to success)

import { Result } from "effect"


const result = Result.succeed(42)


if (Result.isSuccess(result)) {
  result.success // => 42
}

Instances

makeEquivalence

Added in v4.0.0 Source

Creates an Equivalence for comparing two Result values.

Details

  • Two Success values are equal when the success equivalence says so
  • Two Failure values are equal when the failure equivalence says so
  • A Success and a Failure are never equal

Signature

declare function makeEquivalence<A, E>(success: Equivalence<A>, failure: Equivalence<E>): Equivalence<Result<A, E>>

Example

(Comparing Results for equality)

import { Equivalence, Result } from "effect"


const eq = Result.makeEquivalence(
  Equivalence.strictEqual<number>(),
  Equivalence.strictEqual<string>()
)


eq(Result.succeed(1), Result.succeed(1)) // => true


eq(Result.succeed(1), Result.fail("x")) // => false

Mapping

bindTo

Added in v2.0.0 Source

Wraps the success value of a Result into a named field, producing a Result<Record<N, A>>.

When to use

Use to name the success value of an existing Result before continuing a do-notation pipeline.

Details

This is typically used to start a do-notation chain from an existing Result.

See

  • Do to start from an empty object
  • bind to add more fields

Signature

declare const bindTo: {
  <N extends string>(name: N): <R, L>(self: Result<R, L>) => Result<Record<N, R>, L>;
  <R, L, N extends string>(self: Result<R, L>, name: N): Result<Record<N, R>, L>;
}

Example

(Wrapping a value into a named field)

import { pipe, Result } from "effect"


pipe(
  Result.succeed(42),
  Result.bindTo("answer")
) // => Result.succeed({ answer: 42 })

map

Added in v2.0.0 Source

Transforms the success channel of a Result, leaving the failure channel unchanged.

When to use

Use to apply a transformation to the success value of a Result while preserving any existing failure.

Details

  • If the result is a Success, applies f to the value and returns a new Success
  • If the result is a Failure, returns it as-is
  • Use flatMap if f returns a Result (to avoid nested Results)

See

  • mapError to transform only the error value
  • mapBoth to transform both channels
  • flatMap when f returns a Result

Signature

declare const map: {
  <A, A2>(f: (ok: A) => A2): <E>(self: Result<A, E>) => Result<A2, E>;
  <A, E, A2>(self: Result<A, E>, f: (ok: A) => A2): Result<A2, E>;
}

Example

(Doubling the success value)

import { pipe, Result } from "effect"


pipe(
  Result.succeed(3),
  Result.map((n) => n * 2)
) // => Result.succeed(6)

mapBoth

Added in v2.0.0 Source

Transforms both the success and failure channels of a Result.

When to use

Use to transform both success and failure values without changing whether the result succeeds or fails.

Details

  • Applies onSuccess if the result is a Success
  • Applies onFailure if the result is a Failure

See

  • map to transform only the success value
  • mapError to transform only the error value
  • match to fold into a single value

Signature

declare const mapBoth: {
  <E, E2, A, A2>(options: {
    readonly onFailure: (left: E) => E2;
    readonly onSuccess: (right: A) => A2;
  }): (self: Result<A, E>) => Result<A2, E2>;
  <E, A, E2, A2>(self: Result<A, E>, options: {
    readonly onFailure: (left: E) => E2;
    readonly onSuccess: (right: A) => A2;
  }): Result<A2, E2>;
}

Example

(Mapping both channels)

import { pipe, Result } from "effect"


pipe(
  Result.succeed(1),
  Result.mapBoth({
    onSuccess: (n) => n + 1,
    onFailure: (e) => `Error: ${e}`
  })
) // => Result.succeed(2)

mapError

Added in v4.0.0 Source

Transforms the failure channel of a Result, leaving the success channel unchanged.

When to use

Use to transform only the failure channel while preserving success values.

Details

  • If the result is a Failure, applies f to the error and returns a new Failure
  • If the result is a Success, returns it as-is

See

  • map to transform only the success value
  • mapBoth to transform both channels

Signature

declare const mapError: {
  <E, E2>(f: (err: E) => E2): <A>(self: Result<A, E>) => Result<A, E2>;
  <A, E, E2>(self: Result<A, E>, f: (err: E) => E2): Result<A, E2>;
}

Example

(Adding context to an error)

import { pipe, Result } from "effect"


pipe(
  Result.fail("not found"),
  Result.mapError((e) => `Error: ${e}`)
) // => Result.fail("Error: not found")

tap

Added in v4.0.0 Source

Runs a side-effect on the success value without altering the Result.

Details

  • If the result is a Success, calls f with the value (return value is ignored)
  • If the result is a Failure, f is not called
  • Returns the original Result unchanged (same reference)
  • Useful for logging, debugging, or performing mutations outside the Result chain

See

  • map to transform the success value

Signature

declare const tap: {
  <A>(f: (a: A) => void): <E>(self: Result<A, E>) => Result<A, E>;
  <A, E>(self: Result<A, E>, f: (a: A) => void): Result<A, E>;
}

Example

(Logging a success value)

import { pipe, Result } from "effect"


const values: Array<number> = []
const result = pipe(
  Result.succeed(42),
  Result.tap((n) => values.push(n))
)


values // => [42]
result // => Result.succeed(42)

Models

Failure interface

Added in v4.0.0 Source

The failure variant of Result. Wraps an error of type E.

Details

  • Access the error via the .failure property
  • Use isFailure to narrow a Result to Failure
  • Create with fail

See

Signature

interface Failure<out A, out E> extends Pipeable, Inspectable {
  readonly _op: "Failure";
  readonly _tag: "Failure";
  [ignoreSymbol]?: ResultUnifyIgnore;
  [typeSymbol]?: unknown;
  [unifySymbol]?: ResultUnify<Failure<A, E>>;
  readonly "~effect/data/Result": {
    readonly _A: Covariant<E>;
    readonly _E: Covariant<A>;
  };
  readonly failure: E;
  [iterator](): ResultIterator<Result<A, E>>;
}

Example

(Accessing the failure value)

import { Result } from "effect"


const failure = Result.fail("Network error")


if (Result.isFailure(failure)) {
  failure.failure // => "Network error"
}

Result type

Added in v4.0.0 Source

A value that is either Success<A, E> or Failure<A, E>.

When to use

Use when both success and failure should remain available as data and Option would lose failure information.

Details

E defaults to never, so Result<number> means a result that cannot fail.

See

Signature

type Result<A, E = never> = Success<A, E> | Failure<A, E>

Example

(Creating and matching a Result)

import { Result } from "effect"


Result.match(Result.succeed(42), {
  onSuccess: (value) => `Success: ${value}`,
  onFailure: (error) => `Error: ${error}`
}) // => "Success: 42"

ResultUnify interface

Added in v4.0.0 Source

Type-level utility for unifying Result types in generic contexts.

Details

This is an internal interface used by the Effect type system. You typically do not need to reference it directly.

Signature

interface ResultUnify<T extends {
  [typeSymbol]?: any;
}> {
  Result?: () => T[typeof typeSymbol] extends Result<A, E> | _ ? Result<A, E> : never;
}

ResultUnifyIgnore interface

Added in v4.0.0 Source

Marker interface for ignoring unification in Result types.

Details

This is an internal interface used by the Effect type system. You typically do not need to reference it directly.

Signature

interface ResultUnifyIgnore {}

Success interface

Added in v4.0.0 Source

The success variant of Result. Wraps a value of type A.

Details

  • Access the value via the .success property
  • Use isSuccess to narrow a Result to Success
  • Create with succeed

See

Signature

interface Success<out A, out E> extends Pipeable, Inspectable {
  readonly _op: "Success";
  readonly _tag: "Success";
  [ignoreSymbol]?: ResultUnifyIgnore;
  [typeSymbol]?: unknown;
  [unifySymbol]?: ResultUnify<Success<A, E>>;
  readonly "~effect/data/Result": {
    readonly _A: Covariant<E>;
    readonly _E: Covariant<A>;
  };
  readonly success: A;
  [iterator](): ResultIterator<Result<A, E>>;
}

Example

(Accessing the success value)

import { Result } from "effect"


const success = Result.succeed(42)


if (Result.isSuccess(success)) {
  success.success // => 42
}

Other

let

Source

Signature

declare const let: {
  <N extends string, R extends object, B>(name: Exclude<N, keyof R>, f: (r: NoInfer<R>) => B): <L>(self: Result<R, L>) => Result<{ [K in string | number | symbol]: K extends keyof R ? R[K] : B }, L>;
  <R extends object, L, N extends string, B>(self: Result<R, L>, name: Exclude<N, keyof R>, f: (r: NoInfer<R>) => B): Result<{ [K in string | number | symbol]: K extends keyof R ? R[K] : B }, L>;
}

Result

Added in v4.0.0 Source

Namespace containing type-level utilities for extracting the inner types of a Result.

Example

(Extracting inner types)

import { Result } from "effect"


type R = Result.Result<number, string>


// number
type A = Result.Result.Success<R>


// string
type E = Result.Result.Failure<R>


const success: A = 42
const failure: E = "error"

try

Source

Signature

declare const try: {
  <A, E>(options: {
    readonly catch: (error: unknown) => E;
    readonly try: LazyArg<A>;
  }): Result<A, E>;
  <A>(evaluate: LazyArg<A>): Result<A, unknown>;
}

void

Source

Signature

declare const void: Result<void>

Pattern Matching

match

Added in v2.0.0 Source

Folds a Result into a single value by applying one of two functions.

When to use

Use when a Result's success and failure branches should be collapsed into one plain output type.

Details

  • Applies onSuccess if the result is a Success
  • Applies onFailure if the result is a Failure
  • Both branches must return the same type (or a common supertype)

See

  • merge to extract A | E without mapping
  • getOrElse to unwrap only the success with a fallback

Signature

declare const match: {
  <E, B, A, C = B>(options: {
    readonly onFailure: (error: E) => B;
    readonly onSuccess: (ok: A) => C;
  }): (self: Result<A, E>) => B | C;
  <A, E, B, C = B>(self: Result<A, E>, options: {
    readonly onFailure: (error: E) => B;
    readonly onSuccess: (ok: A) => C;
  }): B | C;
}

Example

(Folding to a string)

import { pipe, Result } from "effect"


const format = Result.match({
  onSuccess: (n: number) => `Got ${n}`,
  onFailure: (e: string) => `Err: ${e}`
})


format(Result.succeed(42)) // => "Got 42"


format(Result.fail("timeout")) // => "Err: timeout"

Sequencing

all

Added in v2.0.0 Source

Collects a structure of Results into a single Result of collected values.

When to use

Use to collect independent Result values into one Result while preserving the original structure.

Details

Accepts:

  • A tuple/array: returns Result with a tuple/array of success values
  • A struct (record): returns Result with a struct of success values
  • An iterable: returns Result with an array of success values

Short-circuits on the first Failure encountered; later elements are not inspected.

See

  • flatMap for chaining two Results sequentially
  • gen for generator-based composition of multiple Results

Signature

declare const all: <I extends Iterable<Result<any, any>> | Record<string, Result<any, any>>>(input: I) => [I] extends [ReadonlyArray<Result<any, any>>] ? Result<{ [K in keyof I]: [I[K]] extends [Result<infer R, any>] ? R : never }, I[number] extends never ? never : [I[number]] extends [Result<any, infer L>] ? L : never> : [I] extends [Iterable<Result<infer R, infer L>>] ? Result<Array<R>, L> : Result<{ [K in keyof I]: [I[K]] extends [Result<infer R, any>] ? R : never }, I[keyof I] extends never ? never : [I[keyof I]] extends [Result<any, infer L>] ? L : never>

Example

(Collecting a tuple and a struct)

import { Result } from "effect"


// Tuple
Result.all([Result.succeed(1), Result.succeed("two")]) // => Result.succeed([1, "two"])


// Struct
Result.all({ x: Result.succeed(1), y: Result.fail("err") }) // => Result.fail("err")

andThen

Added in v2.0.0 Source

Provides a flexible variant of flatMap that accepts multiple input shapes.

When to use

Use to sequence a next step that may be a Result, a function, or a plain value.

Details

The second argument can be:

  • A function (a: A) => Result<A2, E2> (same as flatMap)
  • A function (a: A) => A2 (auto-wrapped in succeed)
  • A Result<A2, E2> value (ignores the success of self)
  • A plain value A2 (auto-wrapped in succeed, ignores self)

If self is a Failure, the second argument is never evaluated.

See

  • flatMap for the stricter variant (function returning Result only)
  • map when you always return a plain value

Signature

declare const andThen: {
  <A, A2, E2>(f: (a: A) => Result<A2, E2>): <E>(self: Result<A, E>) => Result<A2, E2 | E>;
  <A2, E2>(f: Result<A2, E2>): <A, E>(self: Result<A, E>) => Result<A2, E2 | E>;
  <A, A2>(f: (a: A) => A2): <E>(self: Result<A, E>) => Result<A2, E>;
  <A2>(right: NotFunction<A2>): <A, E>(self: Result<A, E>) => Result<A2, E>;
  <A, E, A2, E2>(self: Result<A, E>, f: (a: A) => Result<A2, E2>): Result<A2, E | E2>;
  <A, E, A2, E2>(self: Result<A, E>, f: Result<A2, E2>): Result<A2, E | E2>;
  <A, E, A2>(self: Result<A, E>, f: (a: A) => A2): Result<A2, E>;
  <A, E, A2>(self: Result<A, E>, f: NotFunction<A2>): Result<A2, E>;
}

Example

(Chaining Result values with different argument types)

import { pipe, Result } from "effect"


// With a function returning a Result
const a = pipe(
  Result.succeed(1),
  Result.andThen((n) => Result.succeed(n + 1))
) // => Result.succeed(2)


// With a plain mapping function
const b = pipe(
  Result.succeed(1),
  Result.andThen((n) => n + 1)
) // => Result.succeed(2)


// With a constant value
const c = pipe(Result.succeed(1), Result.andThen("done")) // => Result.succeed("done")

bind

Added in v2.0.0 Source

Adds a named field to the do-notation accumulator by running a Result-producing function that receives the current accumulated object.

When to use

Use when you need to add a Result-producing step to a Result do-notation pipeline and store its successful value under a named field in the accumulated object.

Details

  • Short-circuits on the first Failure
  • The field name must not collide with existing keys
  • Use let for pure (non-Result) computed fields

See

  • Do to start the do-notation chain
  • let for pure computed fields
  • bindTo to wrap an initial Result into a named field

Signature

declare const bind: {
  <N extends string, A extends object, B, L2>(name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => Result<B, L2>): <L1>(self: Result<A, L1>) => Result<{ [K in string | number | symbol]: K extends keyof A ? A[K] : B }, L2 | L1>;
  <A extends object, L1, N extends string, B, L2>(self: Result<A, L1>, name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => Result<B, L2>): Result<{ [K in string | number | symbol]: K extends keyof A ? A[K] : B }, L1 | L2>;
}

Example

(Binding Result values)

import { pipe, Result } from "effect"


pipe(
  Result.Do,
  Result.bind("x", () => Result.succeed(2)),
  Result.bind("y", ({ x }) => Result.succeed(x + 3))
) // => Result.succeed({ x: 2, y: 5 })

flatMap

Added in v2.0.0 Source

Chains a function that returns a Result onto a successful value.

When to use

Use to sequence Result-returning computations that should short-circuit on failure.

Details

  • If self is a Success, applies f to the value and returns the resulting Result
  • If self is a Failure, short-circuits and returns it unchanged
  • The error types are merged into a union (E | E2)
  • This is the monadic bind / >>= for Result

See

  • andThen for a more flexible variant that also accepts plain values
  • map when f does not return a Result

Signature

declare const flatMap: {
  <A, A2, E2>(f: (a: A) => Result<A2, E2>): <E>(self: Result<A, E>) => Result<A2, E2 | E>;
  <A, E, A2, E2>(self: Result<A, E>, f: (a: A) => Result<A2, E2>): Result<A2, E | E2>;
}

Example

(Validating sequentially)

import { pipe, Result } from "effect"


pipe(
  Result.succeed(5),
  Result.flatMap((n) =>
    n > 0 ? Result.succeed(n * 2) : Result.fail("not positive")
  )
) // => Result.succeed(10)

Transforming

flip

Added in v2.0.0 Source

Swaps the success and failure channels of a Result.

When to use

Use to swap channels when failure-focused operations are easier through success-oriented combinators.

Details

  • Success<A> becomes Failure<A> (i.e., Result<E, A>)
  • Failure<E> becomes Success<E> (i.e., Result<E, A>)
  • Useful when you want to apply success-oriented operations (like map) to the error channel, then flip back

See

  • mapError to transform the error without swapping

Signature

declare function flip<A, E>(self: Result<A, E>): Result<E, A>

Example

(Swapping channels)

import { Result } from "effect"


Result.flip(Result.succeed(42)) // => Result.fail(42)


Result.flip(Result.fail("error")) // => Result.succeed("error")

Transposing

transposeMapOption

Added in v3.15.0 Source

Maps an Option value with a Result-producing function, then transposes the structure from Option<Result<B, E>> to Result<Option<B>, E>.

When to use

Use when an optional value should be validated only when present, preserving absence as a successful None.

Details

  • None becomes Success(None) (the function is never called)
  • Some(a) where f(a) is Success(b) becomes Success(Some(b))
  • Some(a) where f(a) is Failure(e) becomes Failure(e)

See

Signature

declare const transposeMapOption: <A, B, E = never>(f: (self: A) => Result<B, E>) => (self: Option<A>) => Result<Option<B>, E> & <A, B, E = never>(self: Option<A>, f: (self: A) => Result<B, E>) => Result<Option<B>, E>

Example

(Mapping and transposing in one step)

import { Option, Result } from "effect"


const parse = (s: string) =>
  isNaN(Number(s))
    ? Result.fail("not a number" as const)
    : Result.succeed(Number(s))


Result.transposeMapOption(Option.some("42"), parse) // => Result.succeed(Option.some(42))


Result.transposeMapOption(Option.none(), parse) // => Result.succeed(Option.none())

transposeOption

Added in v3.14.0 Source

Transforms Option<Result<A, E>> into Result<Option<A>, E>.

When to use

Use when optional absence should be treated as a successful None, while an inner Result failure should still fail the whole result.

Details

  • None becomes Success(None)
  • Some(Success(a)) becomes Success(Some(a))
  • Some(Failure(e)) becomes Failure(e)

See

Signature

declare function transposeOption<A = never, E = never>(self: Option<Result<A, E>>): Result<Option<A>, E>

Example

(Transposing an Option of a Result)

import { Option, Result } from "effect"


Result.transposeOption(Option.some(Result.succeed(42))) // => Result.succeed(Option.some(42))


Result.transposeOption(Option.none<Result.Result<number, string>>()) // => Result.succeed(Option.none())

Utility Types

ResultTypeLambda interface

Added in v4.0.0 Source

Higher-kinded type representation for Result.

Details

Used internally to integrate Result with generic type-class utilities (e.g., map, flatMap abstractions). You typically do not need to reference this directly.

Signature

interface ResultTypeLambda extends TypeLambda {
  readonly type: Result<unknown, unknown>;
}