Result

The Result data type represents two exclusive values: a Result<A, E> can be a Success value or a Failure value, where A is the type of the Success value, and E is the type of the Failure value.

Understanding Result and Exit

Result is primarily used as a simple discriminated union and is not recommended as the main result type for operations requiring detailed error information.

Exit is the preferred result type within Effect for capturing comprehensive details about failures. It encapsulates the outcomes of effectful computations, distinguishing between success and various failure modes, such as errors, defects and interruptions.

Creating Results

You can create a Result using the Result.succeed and Result.fail constructors.

Use Result.succeed to create a Success value of type A.

Example (Creating a Success Value)

1
import { Result } from "effect"
2

3
const successValue = Result.succeed(42)
4

5
console.log(successValue)
6
successValue // => Result.succeed(42)

Use Result.fail to create a Failure value of type E.

Example (Creating a Failure Value)

1
import { Result } from "effect"
2

3
const failureValue = Result.fail("not a number")
4

5
console.log(failureValue)
6
failureValue // => Result.fail("not a number")

Guards

Use Result.isFailure and Result.isSuccess to check whether a Result is a Failure or Success value.

Example (Using Guards to Check the Type of Result)

1
import { Result } from "effect"
2

3
const foo = Result.succeed(42)
4

5
if (Result.isFailure(foo)) {
6
  console.log(`The failure value is: ${foo.failure}`)
7
} else {
8
  console.log(`The Success value is: ${foo.success}`)
9
  foo.success // => 42
10
}
11
// Output: "The Success value is: 42"

Pattern Matching

Use Result.match to handle both cases of a Result by specifying separate callbacks for Failure and Success.

Example (Pattern Matching with Result)

1
import { Result } from "effect"
2

3
const foo = Result.succeed(42)
4

5
const message = Result.match(foo, {
6
  onFailure: (failure) => `The failure value is: ${failure}`,
7
  onSuccess: (success) => `The Success value is: ${success}`,
8
})
9

10
console.log(message)
11
message // => "The Success value is: 42"

Mapping

Mapping over the Success Value

Use Result.map to transform the Success value of a Result. The function you provide will only apply to the Success value, leaving any Failure value unchanged.

Example (Transforming the Success Value)

1
import { Result } from "effect"
2

3
// Transform the Success value by adding 1
4
const successResult = Result.map(Result.succeed(1), (n) => n + 1)
5
console.log(successResult)
6
successResult // => Result.succeed(2)
7

8
// The transformation is ignored for Failure values
9
const failureResult = Result.map(Result.fail("not a number"), (n) => n + 1)
10
console.log(failureResult)
11
failureResult // => Result.fail("not a number")

Mapping over the Failure Value

Use Result.mapError to transform the Failure value of a Result. The provided function only applies to the Failure value, leaving any Success value unchanged.

Example (Transforming the Failure Value)

1
import { Result } from "effect"
2

3
// The transformation is ignored for Success values
4
const successResult = Result.mapError(Result.succeed(1), (s) => s + "!")
5
console.log(successResult)
6
successResult // => Result.succeed(1)
7

8
// Transform the Failure value by appending "!"
9
const failureResult = Result.mapError(
10
  Result.fail("not a number"),
11
  (s) => s + "!",
12
)
13
console.log(failureResult)
14
failureResult // => Result.fail("not a number!")

Mapping over Both Values

Use Result.mapBoth to transform both the Failure and Success values of a Result. This function takes two separate transformation functions: one for the Failure value and another for the Success value.

Example (Transforming Both Failure and Success Values)

1
import { Result } from "effect"
2

3
const transformedSuccess = Result.mapBoth(Result.succeed(1), {
4
  onFailure: (s) => s + "!",
5
  onSuccess: (n) => n + 1,
6
})
7
console.log(transformedSuccess)
8
transformedSuccess // => Result.succeed(2)
9

10
const transformedFailure = Result.mapBoth(Result.fail("not a number"), {
11
  onFailure: (s) => s + "!",
12
  onSuccess: (n) => n + 1,
13
})
14
console.log(transformedFailure)
15
transformedFailure // => Result.fail("not a number!")

Interop with Effect

Result implements the Yieldable trait, so it can be yielded directly inside Effect.gen. To pass a Result to an Effect combinator such as Effect.all, convert it explicitly with Effect.fromResult.

How Result Maps to Effect

Result Variant	Mapped to Effect	Description
`Failure<E>`	`Effect<never, E>`	Represents a failure
`Success<A>`	`Effect<A>`	Represents a success

Example (Combining Result with Effect)

1
import { Effect, Result } from "effect"
2

3
// Function to get the head of an array, returning Result
4
const head = <A>(array: ReadonlyArray<A>): Result.Result<A, string> =>
5
  array.length > 0 ? Result.succeed(array[0]!) : Result.fail("empty array")
6

7
head([1, 2, 3]) // => Result.succeed(1)
8

9
// Simulated fetch function that returns Effect
10
const fetchData = (): Effect.Effect<string, string> => {
11
  const success = Math.random() > 0.5
12
  return success
13
    ? Effect.succeed("some data")
14
    : Effect.fail("Failed to fetch data")
15
}
16

17
// Result is not an Effect subtype - convert explicitly with Effect.fromResult
18
const program = Effect.all([Effect.fromResult(head([1, 2, 3])), fetchData()])
19

20
Effect.runPromise(program).then(console.log, console.error)
21
/*
22
Example Output:
23
[ 1, 'some data' ]
24
*/

Combining Two or More Results

Combining with flatMap and map

Combine two Result values with a provided function by chaining Result.flatMap and Result.map. This creates a new Result that holds the combined value of both original Result values.

Example (Combining Two Results into an Object)

1
import { Result } from "effect"
2

3
const maybeName: Result.Result<string, string> = Result.succeed("John")
4
const maybeAge: Result.Result<number, string> = Result.succeed(25)
5

6
// Combine the name and age into a person object
7
const person = Result.flatMap(maybeName, (name) =>
8
  Result.map(maybeAge, (age) => ({
9
    name: name.toUpperCase(),
10
    age,
11
  })),
12
)
13

14
console.log(person)
15
person // => Result.succeed({ name: "JOHN", age: 25 })

If either of the Result values is a Failure, the result will be a Failure, holding the first encountered Failure value:

Example (Combining Results with a Failure Value)

1
import { Result } from "effect"
2

3
const maybeName: Result.Result<string, string> = Result.succeed("John")
4
const maybeAge: Result.Result<number, string> = Result.fail("Oh no!")
5

6
// Since maybeAge is a Failure, the result will also be a Failure
7
const person = Result.flatMap(maybeName, (name) =>
8
  Result.map(maybeAge, (age) => ({
9
    name: name.toUpperCase(),
10
    age,
11
  })),
12
)
13

14
console.log(person)
15
/*
16
Output:
17
{ _id: 'Result', _tag: 'Failure', failure: 'Oh no!' }
18
*/

all

To combine multiple Result values without transforming their contents, you can use Result.all. This function returns a Result with a structure matching the input:

If you pass a tuple, the result will be a tuple of the same length.
If you pass a struct, the result will be a struct with the same keys.
If you pass an Iterable, the result will be an array.

Example (Combining Multiple Results into a Tuple and Struct)

1
import { Result } from "effect"
2

3
const maybeName: Result.Result<string, string> = Result.succeed("John")
4
const maybeAge: Result.Result<number, string> = Result.succeed(25)
5

6
//      ┌─── Result<[string, number], string>
7
//      ▼
8
const tuple = Result.all([maybeName, maybeAge])
9
console.log(tuple)
10
tuple // => Result.succeed(["John", 25])
11

12
//      ┌─── Result<{ name: string; age: number; }, string>
13
//      ▼
14
const struct = Result.all({ name: maybeName, age: maybeAge })
15
console.log(struct)
16
struct // => Result.succeed({ name: "John", age: 25 })

If one or more Result values are a Failure, the first Failure encountered is returned:

Example (Handling Multiple Failure Values)

1
import { Result } from "effect"
2

3
const maybeName: Result.Result<string, string> = Result.fail("name not found")
4
const maybeAge: Result.Result<number, string> = Result.fail("age not found")
5

6
// The first Failure value will be returned
7
console.log(Result.all([maybeName, maybeAge]))
8
Result.all([maybeName, maybeAge]) // => Result.fail("name not found")

gen

Similar to Effect.gen, Result.gen provides a more readable, generator-based syntax for working with Result values, making code that involves Result easier to write and understand. This approach is similar to using async/await but tailored for Result.

Example (Using Result.gen to Create a Combined Value)

1
import { Result } from "effect"
2

3
const maybeName: Result.Result<string, string> = Result.succeed("John")
4
const maybeAge: Result.Result<number, string> = Result.succeed(25)
5

6
const program = Result.gen(function* () {
7
  const name = (yield* maybeName).toUpperCase()
8
  const age = yield* maybeAge
9
  return { name, age }
10
})
11

12
console.log(program)
13
program // => Result.succeed({ name: "JOHN", age: 25 })

When any of the Result values in the sequence is a Failure, the generator immediately returns the Failure value, skipping further operations:

Example (Handling a Failure Value with Result.gen)

In this example, Result.gen halts execution as soon as it encounters the Failure value, effectively propagating the error without performing further operations.

1
import { Result } from "effect"
2

3
const maybeName: Result.Result<string, string> = Result.fail("Oh no!")
4
const maybeAge: Result.Result<number, string> = Result.succeed(25)
5

6
const program = Result.gen(function* () {
7
  console.log("Retrieving name...")
8
  const name = (yield* maybeName).toUpperCase()
9
  console.log("Retrieving age...")
10
  const age = yield* maybeAge
11
  return { name, age }
12
})
13

14
console.log(program)
15
/*
16
Output:
17
Retrieving name...
18
*/
19
program // => Result.fail("Oh no!")

The use of console.log in these example is for demonstration purposes only. When using Result.gen, avoid including side effects in your generator functions, as Result should remain a pure data structure.