Effect vs neverthrow

When working with error handling in TypeScript, both neverthrow and Effect provide useful abstractions for modeling success and failure without exceptions. They share many concepts, such as wrapping computations in a safe container, transforming values with map, handling errors with mapErr/mapLeft, and offering utilities to combine or unwrap results.

This page shows a side-by-side comparison of neverthrow and Effect APIs for common use cases. If you’re already familiar with neverthrow, the examples will help you understand how to achieve the same patterns with Effect. If you’re starting fresh, the comparison highlights the similarities and differences so you can decide which library better fits your project.

neverthrow exposes instance methods (for example, result.map(...)). Effect exposes functions on Either (for example, Either.map(result, ...)) and supports a pipe style for readability and better tree shaking.

Synchronous API

ok

Example (Creating a success result)

1
import { ok } from "neverthrow"
2

3
const result = ok({ myData: "test" })
4

5
result.isOk() // true
6
result.isErr() // false

1
import * as Either from "effect/Either"
2

3
const result = Either.right({ myData: "test" })
4

5
Either.isRight(result) // true
6
Either.isLeft(result) // false

err

Example (Creating a failure result)

1
import { err } from "neverthrow"
2

3
const result = err("Oh no")
4

5
result.isOk() // false
6
result.isErr() // true

1
import * as Either from "effect/Either"
2

3
const result = Either.left("Oh no")
4

5
Either.isRight(result) // false
6
Either.isLeft(result) // true

map

Example (Transforming the success value)

1
import { Result } from "neverthrow"
2

3
declare function getLines(s: string): Result<Array<string>, Error>
4

5
const result = getLines("1\n2\n3\n4\n")
6

7
// this Result now has a Array<number> inside it
8
const newResult = result.map((arr) => arr.map(parseInt))
9

10
newResult.isOk() // true

1
import * as Either from "effect/Either"
2

3
declare function getLines(s: string): Either.Either<Array<string>, Error>
4

5
const result = getLines("1\n2\n3\n4\n")
6

7
// this Either now has a Array<number> inside it
8
const newResult = result.pipe(Either.map((arr) => arr.map(parseInt)))
9

10
Either.isRight(newResult) // true

mapErr

Example (Transforming the error value)

1
import { Result } from "neverthrow"
2

3
declare function parseHeaders(raw: string): Result<Record<string, string>, string>
4

5
const rawHeaders = "nonsensical gibberish and badly formatted stuff"
6

7
const result = parseHeaders(rawHeaders)
8

9
// const newResult: Result<Record<string, string>, Error>
10
const newResult = result.mapErr((err) => new Error(err))

1
import * as Either from "effect/Either"
2

3
declare function parseHeaders(raw: string): Either.Either<Record<string, string>, string>
4

5
const rawHeaders = "nonsensical gibberish and badly formatted stuff"
6

7
const result = parseHeaders(rawHeaders)
8

9
// const newResult: Either<Record<string, string>, Error>
10
const newResult = result.pipe(Either.mapLeft((err) => new Error(err)))

unwrapOr

Example (Providing a default value)

1
import { err } from "neverthrow"
2

3
const result = err("Oh no")
4

5
const multiply = (value: number): number => value * 2
6

7
const unwrapped = result.map(multiply).unwrapOr(10)

1
import * as Either from "effect/Either"
2

3
const result = Either.left("Oh no")
4

5
const multiply = (value: number): number => value * 2
6

7
const unwrapped = result.pipe(
8
  Either.map(multiply),
9
  Either.getOrElse(() => 10),
10
)

andThen

Example (Chaining computations that may fail)

1
import { ok, Result, err } from "neverthrow"
2

3
const sqrt = (n: number): Result<number, string> =>
4
  n > 0 ? ok(Math.sqrt(n)) : err("n must be positive")
5

6
ok(16).andThen(sqrt).andThen(sqrt)
7
// Ok(2)

1
import * as Either from "effect/Either"
2

3
const sqrt = (n: number): Either.Either<number, string> =>
4
  n > 0 ? Either.right(Math.sqrt(n)) : Either.left("n must be positive")
5

6
Either.right(16).pipe(Either.andThen(sqrt), Either.andThen(sqrt))
7
// Right(2)

asyncAndThen

Example (Chaining asynchronous computations that may fail)

1
import { ok, okAsync } from "neverthrow"
2

3
// const result: ResultAsync<number, never>
4
const result = ok(1).asyncAndThen((n) => okAsync(n + 1))

1
import * as Either from "effect/Either"
2
import * as Effect from "effect/Effect"
3

4
// const result: Effect<number, never, never>
5
const result = Either.right(1).pipe(Effect.andThen((n) => Effect.succeed(n + 1)))

orElse

Example (Providing an alternative on failure)

1
import { Result, err, ok } from "neverthrow"
2

3
enum DatabaseError {
4
  PoolExhausted = "PoolExhausted",
5
  NotFound = "NotFound",
6
}
7

8
const dbQueryResult: Result<string, DatabaseError> = err(DatabaseError.NotFound)
9

10
const updatedQueryResult = dbQueryResult.orElse((dbError) =>
11
  dbError === DatabaseError.NotFound ? ok("User does not exist") : err(500),
12
)

1
import * as Either from "effect/Either"
2

3
enum DatabaseError {
4
  PoolExhausted = "PoolExhausted",
5
  NotFound = "NotFound",
6
}
7

8
const dbQueryResult: Either.Either<string, DatabaseError> = Either.left(DatabaseError.NotFound)
9

10
const updatedQueryResult = dbQueryResult.pipe(
11
  Either.orElse((dbError) =>
12
    dbError === DatabaseError.NotFound ? Either.right("User does not exist") : Either.left(500),
13
  ),
14
)

match

Example (Pattern matching on success or failure)

1
import { Result } from "neverthrow"
2

3
declare const myResult: Result<number, string>
4

5
myResult.match(
6
  (value) => `The value is ${value}`,
7
  (error) => `The error is ${error}`,
8
)

1
import * as Either from "effect/Either"
2

3
declare const myResult: Either.Either<number, string>
4

5
myResult.pipe(
6
  Either.match({
7
    onLeft: (error) => `The error is ${error}`,
8
    onRight: (value) => `The value is ${value}`,
9
  }),
10
)

asyncMap

Example (Parsing headers and looking up a user)

1
import { Result } from "neverthrow"
2

3
interface User {}
4
declare function parseHeaders(raw: string): Result<Record<string, string>, string>
5
declare function findUserInDatabase(authorization: string): Promise<User | undefined>
6

7
const rawHeader = "Authorization: Bearer 1234567890"
8

9
// const asyncResult: ResultAsync<User | undefined, string>
10
const asyncResult = parseHeaders(rawHeader)
11
  .map((kvMap) => kvMap["Authorization"])
12
  .asyncMap((authorization) =>
13
    authorization === undefined ? Promise.resolve(undefined) : findUserInDatabase(authorization),
14
  )

1
import * as Either from "effect/Either"
2
import * as Effect from "effect/Effect"
3

4
interface User {}
5
declare function parseHeaders(raw: string): Either.Either<Record<string, string>, string>
6
declare function findUserInDatabase(authorization: string): Promise<User | undefined>
7

8
const rawHeader = "Authorization: Bearer 1234567890"
9

10
// const asyncResult: Effect<User | undefined, string | UnknownException>
11
const asyncResult = parseHeaders(rawHeader).pipe(
12
  Either.map((kvMap) => kvMap["Authorization"]),
13
  Effect.andThen((authorization) =>
14
    authorization === undefined ? Promise.resolve(undefined) : findUserInDatabase(authorization),
15
  ),
16
)

Note. In neverthrow, asyncMap works with Promises directly. In Effect, passing a Promise to combinators like Effect.andThen automatically lifts it into an Effect. If the Promise rejects, the rejection is turned into an UnknownException, which is why the error type is widened to string | UnknownException.

combine

Example (Combining multiple results)

1
import { Result, ok } from "neverthrow"
2

3
const results: Result<number, string>[] = [ok(1), ok(2)]
4

5
// const combined: Result<number[], string>
6
const combined = Result.combine(results)

1
import * as Either from "effect/Either"
2

3
const results: Either.Either<number, string>[] = [Either.right(1), Either.right(2)]
4

5
// const combined: Either<number[], string>
6
const combined = Either.all(results)

combineWithAllErrors

Example (Collecting all errors and successes)

1
import { Result, ok, err } from "neverthrow"
2

3
const results: Result<number, string>[] = [ok(123), err("boooom!"), ok(456), err("ahhhhh!")]
4

5
const result = Result.combineWithAllErrors(results)
6
// result is Err(['boooom!', 'ahhhhh!'])

1
import * as Either from "effect/Either"
2
import * as Array from "effect/Array"
3

4
const results: Either.Either<number, string>[] = [
5
  Either.right(123),
6
  Either.left("boooom!"),
7
  Either.right(456),
8
  Either.left("ahhhhh!"),
9
]
10

11
const errors = Array.getLefts(results)
12
// errors is ['boooom!', 'ahhhhh!']
13

14
const successes = Array.getRights(results)
15
// successes is [123, 456]

Note. There is no exact equivalent of Result.combineWithAllErrors in Effect. Use Array.getLefts to collect all errors and Array.getRights to collect all successes.

Asynchronous API

In the examples below we use Effect.runPromise to run an effect and return a Promise. You can also use other APIs such as Effect.runPromiseExit, which can capture additional cases like defects (runtime errors) and interruptions.

okAsync

Example (Creating a successful async result)

1
import { okAsync } from "neverthrow"
2

3
const myResultAsync = okAsync({ myData: "test" })
4

5
const result = await myResultAsync
6

7
result.isOk() // true
8
result.isErr() // false

1
import * as Either from "effect/Either"
2
import * as Effect from "effect/Effect"
3

4
const myResultAsync = Effect.succeed({ myData: "test" })
5

6
const result = await Effect.runPromise(Effect.either(myResultAsync))
7

8
Either.isRight(result) // true
9
Either.isLeft(result) // false

errAsync

Example (Creating a failed async result)

1
import { errAsync } from "neverthrow"
2

3
const myResultAsync = errAsync("Oh no")
4

5
const myResult = await myResultAsync
6

7
myResult.isOk() // false
8
myResult.isErr() // true

1
import * as Either from "effect/Either"
2
import * as Effect from "effect/Effect"
3

4
const myResultAsync = Effect.fail("Oh no")
5

6
const result = await Effect.runPromise(Effect.either(myResultAsync))
7

8
Either.isRight(result) // false
9
Either.isLeft(result) // true

fromThrowable

Example (Wrapping a Promise-returning function that may throw)

1
import { ResultAsync } from "neverthrow"
2

3
interface User {}
4
declare function insertIntoDb(user: User): Promise<User>
5

6
// (user: User) => ResultAsync<User, Error>
7
const insertUser = ResultAsync.fromThrowable(insertIntoDb, () => new Error("Database error"))

1
import * as Effect from "effect/Effect"
2

3
interface User {}
4
declare function insertIntoDb(user: User): Promise<User>
5

6
// (user: User) => Effect<User, Error>
7
const insertUser = (user: User) =>
8
  Effect.tryPromise({
9
    try: () => insertIntoDb(user),
10
    catch: () => new Error("Database error"),
11
  })

map

Example (Transforming the success value)

1
import { Result, ResultAsync } from "neverthrow"
2

3
interface User {
4
  readonly name: string
5
}
6
declare function findUsersIn(country: string): ResultAsync<Array<User>, Error>
7

8
const usersInCanada = findUsersIn("Canada")
9

10
const namesInCanada = usersInCanada.map((users: Array<User>) => users.map((user) => user.name))
11

12
// We can extract the Result using .then() or await
13
namesInCanada.then((namesResult: Result<Array<string>, Error>) => {
14
  if (namesResult.isErr()) {
15
    console.log("Couldn't get the users from the database", namesResult.error)
16
  } else {
17
    console.log("Users in Canada are named: " + namesResult.value.join(","))
18
  }
19
})

1
import * as Effect from "effect/Effect"
2
import * as Either from "effect/Either"
3

4
interface User {
5
  readonly name: string
6
}
7
declare function findUsersIn(country: string): Effect.Effect<Array<User>, Error>
8

9
const usersInCanada = findUsersIn("Canada")
10

11
const namesInCanada = usersInCanada.pipe(
12
  Effect.map((users: Array<User>) => users.map((user) => user.name)),
13
)
14

15
// We can extract the Either using Effect.either
16
Effect.runPromise(Effect.either(namesInCanada)).then(
17
  (namesResult: Either.Either<Array<string>, Error>) => {
18
    if (Either.isLeft(namesResult)) {
19
      console.log("Couldn't get the users from the database", namesResult.left)
20
    } else {
21
      console.log("Users in Canada are named: " + namesResult.right.join(","))
22
    }
23
  },
24
)

mapErr

Example (Transforming the error value)

1
import { Result, ResultAsync } from "neverthrow"
2

3
interface User {
4
  readonly name: string
5
}
6
declare function findUsersIn(country: string): ResultAsync<Array<User>, Error>
7

8
const usersInCanada = findUsersIn("Canada").mapErr((error: Error) => {
9
  // The only error we want to pass to the user is "Unknown country"
10
  if (error.message === "Unknown country") {
11
    return error.message
12
  }
13
  // All other errors will be labelled as a system error
14
  return "System error, please contact an administrator."
15
})
16

17
usersInCanada.then((usersResult: Result<Array<User>, string>) => {
18
  if (usersResult.isErr()) {
19
    console.log("Couldn't get the users from the database", usersResult.error)
20
  } else {
21
    console.log("Users in Canada are: " + usersResult.value.join(","))
22
  }
23
})

1
import * as Effect from "effect/Effect"
2
import * as Either from "effect/Either"
3

4
interface User {
5
  readonly name: string
6
}
7
declare function findUsersIn(country: string): Effect.Effect<Array<User>, Error>
8

9
const usersInCanada = findUsersIn("Canada").pipe(
10
  Effect.mapError((error: Error) => {
11
    // The only error we want to pass to the user is "Unknown country"
12
    if (error.message === "Unknown country") {
13
      return error.message
14
    }
15
    // All other errors will be labelled as a system error
16
    return "System error, please contact an administrator."
17
  }),
18
)
19

20
Effect.runPromise(Effect.either(usersInCanada)).then(
21
  (usersResult: Either.Either<Array<User>, string>) => {
22
    if (Either.isLeft(usersResult)) {
23
      console.log("Couldn't get the users from the database", usersResult.left)
24
    } else {
25
      console.log("Users in Canada are: " + usersResult.right.join(","))
26
    }
27
  },
28
)

unwrapOr

Example (Providing a default value when async fails)

1
import { errAsync } from "neverthrow"
2

3
const unwrapped = await errAsync(0).unwrapOr(10)
4
// unwrapped = 10

1
import * as Effect from "effect/Effect"
2

3
const unwrapped = await Effect.runPromise(Effect.fail(0).pipe(Effect.orElseSucceed(() => 10)))
4
// unwrapped = 10

andThen

Example (Chaining multiple async computations)

1
import { Result, ResultAsync } from "neverthrow"
2

3
interface User {}
4
declare function validateUser(user: User): ResultAsync<User, Error>
5
declare function insertUser(user: User): ResultAsync<User, Error>
6
declare function sendNotification(user: User): ResultAsync<void, Error>
7

8
const user: User = {}
9

10
const resAsync = validateUser(user).andThen(insertUser).andThen(sendNotification)
11

12
resAsync.then((res: Result<void, Error>) => {
13
  if (res.isErr()) {
14
    console.log("Oops, at least one step failed", res.error)
15
  } else {
16
    console.log("User has been validated, inserted and notified successfully.")
17
  }
18
})

1
import * as Effect from "effect/Effect"
2
import * as Either from "effect/Either"
3

4
interface User {}
5
declare function validateUser(user: User): Effect.Effect<User, Error>
6
declare function insertUser(user: User): Effect.Effect<User, Error>
7
declare function sendNotification(user: User): Effect.Effect<void, Error>
8

9
const user: User = {}
10

11
const resAsync = validateUser(user).pipe(
12
  Effect.andThen(insertUser),
13
  Effect.andThen(sendNotification),
14
)
15

16
Effect.runPromise(Effect.either(resAsync)).then((res: Either.Either<void, Error>) => {
17
  if (Either.isLeft(res)) {
18
    console.log("Oops, at least one step failed", res.left)
19
  } else {
20
    console.log("User has been validated, inserted and notified successfully.")
21
  }
22
})

orElse

Example (Fallback when an async operation fails)

1
import { ResultAsync, ok } from "neverthrow"
2

3
interface User {}
4
declare function fetchUserData(id: string): ResultAsync<User, Error>
5
declare function getDefaultUser(): User
6

7
const userId = "123"
8

9
// Try to fetch user data, but provide a default if it fails
10
const userResult = fetchUserData(userId).orElse(() => ok(getDefaultUser()))
11

12
userResult.then((result) => {
13
  if (result.isOk()) {
14
    console.log("User data:", result.value)
15
  }
16
})

1
import * as Effect from "effect/Effect"
2
import * as Either from "effect/Either"
3

4
interface User {}
5
declare function fetchUserData(id: string): Effect.Effect<User, Error>
6
declare function getDefaultUser(): User
7

8
const userId = "123"
9

10
// Try to fetch user data, but provide a default if it fails
11
const userResult = fetchUserData(userId).pipe(Effect.orElse(() => Effect.succeed(getDefaultUser())))
12

13
Effect.runPromise(Effect.either(userResult)).then((result) => {
14
  if (Either.isRight(result)) {
15
    console.log("User data:", result.right)
16
  }
17
})

match

Example (Handling success and failure at the end of a chain)

1
import { ResultAsync } from "neverthrow"
2

3
interface User {
4
  readonly name: string
5
}
6
declare function validateUser(user: User): ResultAsync<User, Error>
7
declare function insertUser(user: User): ResultAsync<User, Error>
8

9
const user: User = { name: "John" }
10

11
// Handle both cases at the end of the chain using match
12
const resultMessage = await validateUser(user)
13
  .andThen(insertUser)
14
  .match(
15
    (user: User) => `User ${user.name} has been successfully created`,
16
    (error: Error) => `User could not be created because ${error.message}`,
17
  )

1
import * as Effect from "effect/Effect"
2

3
interface User {
4
  readonly name: string
5
}
6
declare function validateUser(user: User): Effect.Effect<User, Error>
7
declare function insertUser(user: User): Effect.Effect<User, Error>
8

9
const user: User = { name: "John" }
10

11
// Handle both cases at the end of the chain using match
12
const resultMessage = await Effect.runPromise(
13
  validateUser(user).pipe(
14
    Effect.andThen(insertUser),
15
    Effect.match({
16
      onSuccess: (user) => `User ${user.name} has been successfully created`,
17
      onFailure: (error) => `User could not be created because ${error.message}`,
18
    }),
19
  ),
20
)

combine

Example (Combining multiple async results)

1
import { ResultAsync, okAsync } from "neverthrow"
2

3
const resultList: ResultAsync<number, string>[] = [okAsync(1), okAsync(2)]
4

5
// const combinedList: ResultAsync<number[], string>
6
const combinedList = ResultAsync.combine(resultList)

1
import * as Effect from "effect/Effect"
2

3
const resultList: Effect.Effect<number, string>[] = [Effect.succeed(1), Effect.succeed(2)]
4

5
// const combinedList: Effect<number[], string>
6
const combinedList = Effect.all(resultList)

combineWithAllErrors

Example (Collecting all errors instead of failing fast)

1
import { ResultAsync, okAsync, errAsync } from "neverthrow"
2

3
const resultList: ResultAsync<number, string>[] = [
4
  okAsync(123),
5
  errAsync("boooom!"),
6
  okAsync(456),
7
  errAsync("ahhhhh!"),
8
]
9

10
const result = await ResultAsync.combineWithAllErrors(resultList)
11
// result is Err(['boooom!', 'ahhhhh!'])

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

3
const resultList: Effect.Effect<number, string>[] = [
4
  Effect.succeed(123),
5
  Effect.fail("boooom!"),
6
  Effect.succeed(456),
7
  Effect.fail("ahhhhh!"),
8
]
9

10
const result = await Effect.runPromise(Effect.either(Effect.validateAll(resultList, identity)))
11
// result is left(['boooom!', 'ahhhhh!'])

Utilities

fromThrowable

Example (Safely wrapping a throwing function)

1
import { Result } from "neverthrow"
2

3
type ParseError = { message: string }
4
const toParseError = (): ParseError => ({ message: "Parse Error" })
5

6
const safeJsonParse = Result.fromThrowable(JSON.parse, toParseError)
7

8
// the function can now be used safely,
9
// if the function throws, the result will be an Err
10
const result = safeJsonParse("{")

1
import * as Either from "effect/Either"
2

3
type ParseError = { message: string }
4
const toParseError = (): ParseError => ({ message: "Parse Error" })
5

6
const safeJsonParse = (s: string) => Either.try({ try: () => JSON.parse(s), catch: toParseError })
7

8
// the function can now be used safely,
9
// if the function throws, the result will be an Either
10
const result = safeJsonParse("{")

safeTry

Example (Using generators to simplify error handling)

1
import { Result, ok, safeTry } from "neverthrow"
2

3
declare function mayFail1(): Result<number, string>
4
declare function mayFail2(): Result<number, string>
5

6
function myFunc(): Result<number, string> {
7
  return safeTry<number, string>(function* () {
8
    return ok(
9
      (yield* mayFail1().mapErr((e) => `aborted by an error from 1st function, ${e}`)) +
10
        (yield* mayFail2().mapErr((e) => `aborted by an error from 2nd function, ${e}`)),
11
    )
12
  })
13
}

1
import * as Either from "effect/Either"
2

3
declare function mayFail1(): Either.Either<number, string>
4
declare function mayFail2(): Either.Either<number, string>
5

6
function myFunc(): Either.Either<number, string> {
7
  return Either.gen(function* () {
8
    return (
9
      (yield* mayFail1().pipe(
10
        Either.mapLeft((e) => `aborted by an error from 1st function, ${e}`),
11
      )) +
12
      (yield* mayFail2().pipe(Either.mapLeft((e) => `aborted by an error from 2nd function, ${e}`)))
13
    )
14
  })
15
}

Note. With Either.gen, you do not need to wrap the final value with Either.right. The generator’s return value becomes the Right.

You can also use an async generator function with safeTry to represent an asynchronous block. On the Effect side, the same pattern is written with Effect.gen instead of Either.gen.

Example (Using async generators to handle multiple failures)

1
import { ResultAsync, safeTry, ok } from "neverthrow"
2

3
declare function mayFail1(): ResultAsync<number, string>
4
declare function mayFail2(): ResultAsync<number, string>
5

6
function myFunc(): ResultAsync<number, string> {
7
  return safeTry<number, string>(async function* () {
8
    return ok(
9
      (yield* mayFail1().mapErr((e) => `aborted by an error from 1st function, ${e}`)) +
10
        (yield* mayFail2().mapErr((e) => `aborted by an error from 2nd function, ${e}`)),
11
    )
12
  })
13
}

1
import { Effect } from "effect"
2

3
declare function mayFail1(): Effect.Effect<number, string>
4
declare function mayFail2(): Effect.Effect<number, string>
5

6
function myFunc(): Effect.Effect<number, string> {
7
  return Effect.gen(function* () {
8
    return (
9
      (yield* mayFail1().pipe(
10
        Effect.mapError((e) => `aborted by an error from 1st function, ${e}`),
11
      )) +
12
      (yield* mayFail2().pipe(
13
        Effect.mapError((e) => `aborted by an error from 2nd function, ${e}`),
14
      ))
15
    )
16
  })
17
}

Note. With Effect.gen, you do not need to wrap the final value with Effect.succeed. The generator’s return value becomes the Success.