Result

A synchronous, pure type for representing computations that can succeed (Success<A>) or fail (Failure<E>). Unlike Effect, Result is evaluated eagerly and carries no side effects.

Mental Model

Result<A, E> is a discriminated union: Success<A, E> | Failure<A, E>
Success wraps a value of type A, accessed via .success
Failure wraps an error of type E, accessed via .failure
Monad: chain operations with flatMap, compose pipelines with pipe
Immutable: all operations return new Result values; the input is never mutated
Yieldable: in Effect.gen, producing the inner value or short-circuiting on failure

Note: In Effect v3.x, this type was called Either. It has been renamed to Result in v4.

Key Operations

Create

Build Results from values:

import { Result } from "effect"

// Success
const ok = Result.succeed(42)
// { _tag: "Success", success: 42 }

// Failure
const err = Result.fail("something went wrong")
// { _tag: "Failure", failure: "something went wrong" }

// From nullable
const fromNull = Result.fromNullishOr(null, (v) => "was null")
// Failure("was null")

const fromValue = Result.fromNullishOr(42, (v) => "was null")
// Success(42)

// From Option
const fromSome = Result.fromOption(Option.some(1), () => "missing")
// Success(1)

const fromNone = Result.fromOption(Option.none(), () => "missing")
// Failure("missing")

// From throwing function
const parseOk = Result.try(() => JSON.parse('{"x": 1}'))
// Success({ x: 1 })

const parseErr = Result.try({
  try: () => JSON.parse("invalid"),
  catch: (e) => `Parse failed: ${e}`
})
// Failure("Parse failed: ...")

Check

Test and narrow:

import { Result } from "effect"

const value: Result<number, string> = Result.succeed(42)

// Type guards
if (Result.isSuccess(value)) {
  console.log(value.success) // 42 (type narrowed to Success)
}

if (Result.isFailure(value)) {
  console.log(value.failure) // Type narrowed to Failure
}

// Generic check
const isResult = Result.isResult(value) // true

Transform

Map both channels:

import { Result } from "effect"

const value = Result.succeed(5)

// Map success
const doubled = Result.map(value, (n) => n * 2)
// Success(10)

// Map error
const withContext = Result.mapError(
  Result.fail("not found"),
  (e) => `Error: ${e}`
)
// Failure("Error: not found")

// Map both
const both = Result.mapBoth(value, {
  onSuccess: (n) => n * 2,
  onFailure: (e: never) => `Error: ${e}`
})
// Success(10)

Chain

Sequence operations:

import { Result } from "effect"

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

const ensurePositive = (n: number): Result<number, string> =>
  n > 0 ? Result.succeed(n) : Result.fail("not positive")

// FlatMap (short-circuits on first failure)
const result = Result.flatMap(parse("42"), ensurePositive)
// Success(42)

const failed = Result.flatMap(parse("-5"), ensurePositive)
// Failure("not positive")

// AndThen (flexible)
const result2 = Result.andThen(parse("42"), (n) => n * 2)
// Success(84)

Unwrap

Extract the value:

import { Result } from "effect"

const ok = Result.succeed(42)
const err = Result.fail("error")

// With fallback
const value1 = Result.getOrElse(ok, (e) => 0) // 42
const value2 = Result.getOrElse(err, (e) => 0) // 0

// To null/undefined
const asNull = Result.getOrNull(err) // null
const asUndef = Result.getOrUndefined(err) // undefined

// Merge (extract A | E)
const merged1 = Result.merge(ok) // 42
const merged2 = Result.merge(err) // "error"

// Throw on failure
try {
  const value = Result.getOrThrow(err) // throws "error"
} catch (e) {
  console.log(e) // "error"
}

// Custom error
try {
  const value = Result.getOrThrowWith(
    err,
    (e) => new Error(`Failed: ${e}`)
  )
} catch (e) {
  console.log(e.message) // "Failed: error"
}

Match

Pattern match:

import { Result } from "effect"

const value: Result<number, string> = Result.succeed(42)

const message = Result.match(value, {
  onSuccess: (n) => `Got ${n}`,
  onFailure: (e) => `Error: ${e}`
})
// "Got 42"

Filter

Validate values:

import { Result } from "effect"

const value = Result.succeed(5)

// Lift predicate
const positive = Result.liftPredicate(
  5,
  (n: number) => n > 0,
  (n) => `${n} is not positive`
)
// Success(5)

// Filter existing Result
const filtered = Result.filterOrFail(
  value,
  (n) => n > 10,
  (n) => `${n} is too small`
)
// Failure("5 is too small")

Recover

Handle failures:

import { Result } from "effect"

const primary = Result.fail("primary failed")

// Provide fallback
const recovered = Result.orElse(
  primary,
  (e) => Result.succeed(99)
)
// Success(99)

// Still a failure if both fail
const bothFailed = Result.orElse(
  primary,
  (e) => Result.fail("fallback also failed")
)
// Failure("fallback also failed")

Combine

Join multiple Results:

import { Result } from "effect"

const a = Result.succeed(2)
const b = Result.succeed(3)

// Combine all (tuple)
const tuple = Result.all([a, b])
// Success([2, 3])

// Combine all (struct)
const struct = Result.all({ x: a, y: b })
// Success({ x: 2, y: 3 })

// Short-circuits on first failure
const withError = Result.all([a, Result.fail("err"), b])
// Failure("err")

Convert

To/from Option:

import { Option, Result } from "effect"

// To Option (discard error)
const successOpt = Result.getSuccess(Result.succeed(1))
// Some(1)

const failureOpt = Result.getSuccess(Result.fail("err"))
// None

// Extract error as Option
const errorOpt = Result.getFailure(Result.fail("err"))
// Some("err")

Flip

Swap channels:

import { Result } from "effect"

const ok = Result.succeed(42)
const flipped = Result.flip(ok)
// Failure(42)

const err = Result.fail("error")
const flipped2 = Result.flip(err)
// Success("error")

Generator

Compose with generator syntax:

import { Result } from "effect"

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

const failed = Result.gen(function* () {
  const a = yield* Result.succeed(2)
  const b = yield* Result.fail("error") // Short-circuits
  return a + b // Never reached
})
// Failure("error")

Do Notation

Build objects step-by-step:

import { Result, pipe } from "effect"

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

Type Signatures

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

interface Success<A, E> {
  readonly _tag: "Success"
  readonly success: A
}

interface Failure<A, E> {
  readonly _tag: "Failure"
  readonly failure: E
}

// Creation
const succeed: <A>(right: A) => Result<A>
const fail: <E>(left: E) => Result<never, E>
const try: {
  <A, E>(options: {
    readonly try: () => A
    readonly catch: (error: unknown) => E
  }): Result<A, E>
  <A>(evaluate: () => A): Result<A, unknown>
}

// Guards
const isResult: (input: unknown) => input is Result<unknown, unknown>
const isSuccess: <A, E>(self: Result<A, E>) => self is Success<A, E>
const isFailure: <A, E>(self: Result<A, E>) => self is Failure<A, E>

// Transform
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>
}
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>
}

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

// Unwrap
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
}
const getOrThrow: <A, E>(self: Result<A, E>) => A

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

Core Modules

Data Structures

Concurrency

Time & Scheduling

Platform

Unstable Modules

Mental Model

Key Operations

Create

Check

Transform

Chain

Unwrap

Match

Filter

Recover

Combine

Convert

Flip

Generator

Do Notation

Type Signatures

See Also

Build docs developers (and LLMs) love

Core Modules

Data Structures

Concurrency

Time & Scheduling

Platform

Unstable Modules

​Mental Model

​Key Operations

​Create

​Check

​Transform

​Chain

​Unwrap

​Match

​Filter

​Recover

​Combine

​Convert

​Flip

​Generator

​Do Notation

​Type Signatures

​See Also

Build docs developers (and LLMs) love

Mental Model

Key Operations

Create

Check

Transform

Chain

Unwrap

Match

Filter

Recover

Combine

Convert

Flip

Generator

Do Notation

Type Signatures

See Also