Result

The Result module provides a data type for representing the state of asynchronous operations. It has three states: Initial (not yet started or no value), Success (completed successfully), and Failure (completed with an error). Each state can also have a waiting flag to indicate when a refresh or update is in progress.

Type definitions

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

A result can be in one of three states:

Initial - No value yet, or reset to initial state
Success - Contains a successful value
Failure - Contains an error cause

Initial

interface Initial<A, E = never> extends Result.Proto<A, E> {
  readonly _tag: "Initial"
}

Represents the initial state before a value is available.

Success

interface Success<A, E = never> extends Result.Proto<A, E> {
  readonly _tag: "Success"
  readonly value: A
  readonly timestamp: number
}

Represents a successful result with a value and timestamp.

Failure

interface Failure<A, E = never> extends Result.Proto<A, E> {
  readonly _tag: "Failure"
  readonly cause: Cause.Cause<E>
  readonly previousSuccess: Option.Option<Success<A, E>>
}

Represents a failed result with a cause and optionally the last successful value.

Constructors

initial

Create an Initial result.

const initial: <A = never, E = never>(waiting?: boolean) => Initial<A, E>

waiting

boolean

default:"false"

Whether the result is in a waiting/loading state

Example

import { Result } from "@effect-rx/rx"

const result = Result.initial()
// { _tag: "Initial", waiting: false }

const loading = Result.initial(true)
// { _tag: "Initial", waiting: true }

success

Create a Success result.

const success: <A, E = never>(value: A, options?: {
  readonly waiting?: boolean | undefined
  readonly timestamp?: number | undefined
}) => Success<A, E>

value

The successful value

options.waiting

boolean

default:"false"

Whether a refresh is in progress

options.timestamp

number

default:"Date.now()"

When the value was created

Example

const result = Result.success(42)
// { _tag: "Success", value: 42, waiting: false, timestamp: ... }

const refreshing = Result.success(42, { waiting: true })
// Shows value while refreshing

fail

Create a Failure result from an error.

const fail: <E, A = never>(error: E, options?: {
  readonly previousSuccess?: Option.Option<Success<A, E>> | undefined
  readonly waiting?: boolean | undefined
}) => Failure<A, E>

error

The error value

options.previousSuccess

Option<Success<A, E>>

The last successful value, if any

options.waiting

boolean

Whether a retry is in progress

Example

const result = Result.fail("Network error")
// { _tag: "Failure", cause: Cause.fail("Network error"), ... }

failure

Create a Failure result from a Cause.

const failure: <A, E = never>(
  cause: Cause.Cause<E>,
  options?: {
    readonly previousSuccess?: Option.Option<Success<A, E>> | undefined
    readonly waiting?: boolean | undefined
  }
) => Failure<A, E>

cause

Cause.Cause<E>

The error cause

Example

const result = Result.failure(
  Cause.fail("Error 1").pipe(
    Cause.parallel(Cause.fail("Error 2"))
  )
)

fromExit

Create a Result from an Effect Exit.

const fromExit: <A, E>(exit: Exit.Exit<A, E>) => Success<A, E> | Failure<A, E>

Example

const exit = Exit.succeed(42)
const result = Result.fromExit(exit)
// { _tag: "Success", value: 42 }

waiting

Mark a result as waiting (refreshing).

const waiting: <R extends Result<any, any>>(
  self: R,
  options?: { readonly touch?: boolean | undefined }
) => R

self

Result<A, E>

The result to mark as waiting

options.touch

boolean

If true, updates the timestamp for Success results

Example

const result = Result.success(42)
const refreshing = Result.waiting(result)
// { _tag: "Success", value: 42, waiting: true }

Accessors

value

Extract the value from a Result if available.

const value: <A, E>(self: Result<A, E>) => Option.Option<A>

Returns Some(value) for Success results or if a Failure has a previousSuccess. Returns None for Initial results or Failures without a previous value. Example

const success = Result.success(42)
Result.value(success) // Option.some(42)

const initial = Result.initial()
Result.value(initial) // Option.none()

getOrElse

Get the value or a default.

const getOrElse: {
  <B>(orElse: LazyArg<B>): <A, E>(self: Result<A, E>) => A | B
  <A, E, B>(self: Result<A, E>, orElse: LazyArg<B>): A | B
}

orElse

() => B

Default value provider

Example

const result = Result.initial<number>()
const value = Result.getOrElse(result, () => 0)
// 0

getOrThrow

Get the value or throw an exception.

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

Throws NoSuchElementException if the result has no value.

Example

const result = Result.success(42)
const value = Result.getOrThrow(result)
// 42

error

Extract the error from a Failure.

const error: <A, E>(self: Result<A, E>) => Option.Option<E>

Example

const result = Result.fail("Error")
Result.error(result) // Option.some("Error")

cause

Extract the Cause from a Failure.

const cause: <A, E>(self: Result<A, E>) => Option.Option<Cause.Cause<E>>

isResult

Check if a value is a Result.

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

isInitial

Check if a result is Initial.

const isInitial: <A, E>(result: Result<A, E>) => result is Initial<A, E>

isSuccess

Check if a result is Success.

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

isFailure

Check if a result is Failure.

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

isWaiting

Check if a result is in waiting state.

const isWaiting: <A, E>(result: Result<A, E>) => boolean

Example

const result = Result.success(42, { waiting: true })
Result.isWaiting(result) // true

isNotInitial

Check if a result is not Initial.

const isNotInitial: <A, E>(result: Result<A, E>) => result is Success<A, E> | Failure<A, E>

Transformations

map

Transform the success value.

const map: {
  <A, B>(f: (a: A) => B): <E>(self: Result<A, E>) => Result<B, E>
  <E, A, B>(self: Result<A, E>, f: (a: A) => B): Result<B, E>
}

(a: A) => B

Transform function applied to success values

Example

const result = Result.success(5)
const doubled = Result.map(result, (n) => n * 2)
// { _tag: "Success", value: 10 }

// Also maps previousSuccess in Failure
const failure = Result.fail("error", {
  previousSuccess: Option.some(Result.success(5))
})
const mapped = Result.map(failure, (n) => n * 2)
// previousSuccess.value is now 10

flatMap

Chain Result operations.

const flatMap: {
  <A, E, B, E2>(
    f: (a: A, prev: Success<A, E>) => Result<B, E2>
  ): (self: Result<A, E>) => Result<B, E | E2>
}

Example

const result = Result.success(5)
const chained = Result.flatMap(result, (n) =>
  n > 0 ? Result.success(n * 2) : Result.fail("negative")
)

toExit

Convert a Result to an Effect Exit.

const toExit: <A, E>(
  self: Result<A, E>
) => Exit.Exit<A, E | Cause.NoSuchElementException>

Example

const result = Result.success(42)
const exit = Result.toExit(result)
// Exit.succeed(42)

Pattern matching

match

Pattern match on all three states.

const match: {
  <A, E, X, Y, Z>(options: {
    readonly onInitial: (_: Initial<A, E>) => X
    readonly onFailure: (_: Failure<A, E>) => Y
    readonly onSuccess: (_: Success<A, E>) => Z
  }): (self: Result<A, E>) => X | Y | Z
}

options.onInitial

function

Handler for Initial state

options.onFailure

function

Handler for Failure state

options.onSuccess

function

Handler for Success state

Example

const message = Result.match(result, {
  onInitial: () => "Loading...",
  onFailure: (f) => `Error: ${Cause.pretty(f.cause)}`,
  onSuccess: (s) => `Value: ${s.value}`
})

matchWithError

Pattern match with separate error and defect handlers.

const matchWithError: {
  <A, E, W, X, Y, Z>(options: {
    readonly onInitial: (_: Initial<A, E>) => W
    readonly onError: (error: E, _: Failure<A, E>) => X
    readonly onDefect: (defect: unknown, _: Failure<A, E>) => Y
    readonly onSuccess: (_: Success<A, E>) => Z
  }): (self: Result<A, E>) => W | X | Y | Z
}

Example

const message = Result.matchWithError(result, {
  onInitial: () => "Loading...",
  onError: (error) => `Error: ${error}`,
  onDefect: (defect) => `Unexpected: ${defect}`,
  onSuccess: (s) => `Value: ${s.value}`
})

matchWithWaiting

Pattern match with a special handler for waiting states.

const matchWithWaiting: {
  <A, E, W, X, Y, Z>(options: {
    readonly onWaiting: (_: Result<A, E>) => W
    readonly onError: (error: E, _: Failure<A, E>) => X
    readonly onDefect: (defect: unknown, _: Failure<A, E>) => Y
    readonly onSuccess: (_: Success<A, E>) => Z
  }): (self: Result<A, E>) => W | X | Y | Z
}

Example

const message = Result.matchWithWaiting(result, {
  onWaiting: () => "Refreshing...",
  onError: (error) => `Error: ${error}`,
  onDefect: (defect) => `Unexpected: ${defect}`,
  onSuccess: (s) => `Value: ${s.value}`
})

Builder API

builder

Create a fluent builder for pattern matching.

const builder: <A extends Result<any, any>>(self: A) => Builder<...>

The builder provides a fluent API for pattern matching with automatic type narrowing. Example

const message = Result.builder(result)
  .onSuccess((value) => `Success: ${value}`)
  .onError((error) => `Error: ${error}`)
  .onWaiting(() => "Loading...")
  .orElse(() => "Unknown state")

// With typed errors
type AppError = 
  | { _tag: "NetworkError"; message: string }
  | { _tag: "ValidationError"; field: string }

const result: Result<User, AppError> = fetchUser()

const message = Result.builder(result)
  .onSuccess((user) => `Hello ${user.name}`)
  .onErrorTag("NetworkError", (err) => `Network: ${err.message}`)
  .onErrorTag("ValidationError", (err) => `Invalid ${err.field}`)
  .onWaiting(() => "Loading...")
  .orNull()

Builder methods

onSuccess

function

Handle success case

onFailure

function

Handle failure case

onError

function

Handle error failures

onErrorTag

function

Handle specific tagged errors

onErrorIf

function

Handle errors matching a predicate

onDefect

function

Handle defect failures

onInitial

function

Handle initial state

onWaiting

function

Handle any waiting state

orElse

function

Provide default value

orNull

function

Return null if unhandled

render

function

Return value or throw if unhandled

Combining results

all

Combine multiple results into one.

const all: <const Arg extends Iterable<any> | Record<string, any>>(
  results: Arg
) => Result<...>

Returns a Success only if all results are Success. Preserves the structure (array or object). Example - Array

const results = [
  Result.success(1),
  Result.success(2),
  Result.success(3)
]

const combined = Result.all(results)
// { _tag: "Success", value: [1, 2, 3] }

Example - Object

const results = {
  user: Result.success({ id: 1, name: "Alice" }),
  posts: Result.success([{ id: 1, title: "Hello" }])
}

const combined = Result.all(results)
// { _tag: "Success", value: { user: {...}, posts: [...] } }

Example - Mixed with non-Result values

const combined = Result.all({
  dynamic: Result.success(42),
  static: "constant value"
})
// { _tag: "Success", value: { dynamic: 42, static: "constant value" } }

Schema integration

Schema

Create a Schema for encoding/decoding Result values.

const Schema: <
  Success extends Schema_.Schema.All = typeof Schema_.Never,
  Error extends Schema_.Schema.All = typeof Schema_.Never
>(options: {
  readonly success?: Success | undefined
  readonly error?: Error | undefined
}) => Schema<Success, Error>

options.success

Schema

Schema for the success value

options.error

Schema

Schema for the error value

Example

import { Schema } from "effect"

const UserResultSchema = Result.Schema({
  success: Schema.Struct({
    id: Schema.Number,
    name: Schema.String
  }),
  error: Schema.String
})

// Encode for serialization
const result = Result.success({ id: 1, name: "Alice" })
const encoded = Schema.encodeSync(UserResultSchema)(result)

// Decode from serialized form
const decoded = Schema.decodeSync(UserResultSchema)(encoded)

Type helpers

Result.Success

Extract the success type from a Result type.

type Success<R> = R extends Result<infer A, infer _> ? A : never

Result.Failure

Extract the error type from a Result type.

type Failure<R> = R extends Result<infer _, infer E> ? E : never

Core

Integration

React Hooks

Documentation Index

​Type definitions

​Result

​Initial

​Success

​Failure

​Constructors

​initial

​success

​fail

​failure

​fromExit

​waiting

​Accessors

​value

​getOrElse

​getOrThrow

​error

​cause

​Refinements

​isResult

​isInitial

​isSuccess

​isFailure

​isWaiting

​isNotInitial

​Transformations

​map

​flatMap

​toExit

​Pattern matching

​match

​matchWithError

​matchWithWaiting

​Builder API

​builder

​Combining results

​all

​Schema integration

​Schema

​Type helpers

​Result.Success

​Result.Failure

Build docs developers (and LLMs) love

Type definitions

Result

Initial

Success

Failure

Constructors

initial

success

fail

failure

fromExit

waiting

Accessors

value

getOrElse

getOrThrow

error

cause

Refinements

isResult

isInitial

isSuccess

isFailure

isWaiting

isNotInitial

Transformations

map

flatMap

toExit

Pattern matching

match

matchWithError

matchWithWaiting

Builder API

builder

Combining results

all

Schema integration

Schema

Type helpers

Result.Success

Result.Failure