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 { 
import ok
ok } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

5
const result: any
result.
any
isOk() // true
6
const result: any
result.
any
isErr() // false

1
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
2

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

5
import Either
Either.
any
isRight(
const result: any
result) // true
6
import Either
Either.
any
isLeft(
const result: any
result) // false

err

Example (Creating a failure result)

1
import { 
import err
err } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

3
const 
const result: any
result = 
import err
err("Oh no")
4

5
const result: any
result.
any
isOk() // false
6
const result: any
result.
any
isErr() // true

1
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
2

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

5
import Either
Either.
any
isRight(
const result: any
result) // false
6
import Either
Either.
any
isLeft(
const result: any
result) // true

map

Example (Transforming the success value)

1
import { 
import Result
Result } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

5
const 
const result: Result<string[], Error>
result = 
function getLines(s: string): Result<Array<string>, Error>
getLines("1\n2\n3\n4\n")
6

7
// this Result now has a Array<number> inside it
8
const 
const newResult: any
newResult = 
const result: Result<string[], Error>
result.
any
map((arr) => 
arr: any
arr.
any
map(
function parseInt(string: string, radix?: number): number
parseInt))Error ts(7006)  ― Parameter 'arr' implicitly has an 'any' type.
9

10
const newResult: any
newResult.
any
isOk() // true

1
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
2

3
declare function 
function getLines(s: string): Either.Either<Array<string>, Error>
getLines(
s: string
s: string): 
import Either
Either.
type Either.Either = /*unresolved*/ any
Either<
interface Array<T>
Array<string>, 
interface Error
Error>
4

5
const 
const result: Either.Either<string[], Error>
result = 
function getLines(s: string): Either.Either<Array<string>, Error>
getLines("1\n2\n3\n4\n")
6

7
// this Either now has a Array<number> inside it
8
const 
const newResult: any
newResult = 
const result: Either.Either<string[], Error>
result.
any
pipe(
import Either
Either.
any
map((arr) => 
arr: any
arr.
any
map(
function parseInt(string: string, radix?: number): number
parseInt)))Error ts(7006)  ― Parameter 'arr' implicitly has an 'any' type.
9

10
import Either
Either.
any
isRight(
const newResult: any
newResult) // true

mapErr

Example (Transforming the error value)

1
import { 
import Result
Result } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

3
declare function 
function parseHeaders(raw: string): Result<Record<string, string>, string>
parseHeaders(
4
  
raw: string
raw: string,
5
): 
import Result
Result<
type Record<K extends keyof any, T> = { [P in K]: T; }
Record<string, string>, string>
6

7
const 
const rawHeaders: "nonsensical gibberish and badly formatted stuff"
rawHeaders = "nonsensical gibberish and badly formatted stuff"
8

9
const 
const result: Result<Record<string, string>, string>
result = 
function parseHeaders(raw: string): Result<Record<string, string>, string>
parseHeaders(
const rawHeaders: "nonsensical gibberish and badly formatted stuff"
rawHeaders)
10

11
// const newResult: Result<Record<string, string>, Error>
12
const 
const newResult: any
newResult = 
const result: Result<Record<string, string>, string>
result.
any
mapErr((err) => new 
var Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)
Error(
err: any
err))Error ts(7006)  ― Parameter 'err' implicitly has an 'any' type.

1
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
2

3
declare function 
function parseHeaders(raw: string): Either.Either<Record<string, string>, string>
parseHeaders(
4
  
raw: string
raw: string,
5
): 
import Either
Either.
type Either.Either = /*unresolved*/ any
Either<
type Record<K extends keyof any, T> = { [P in K]: T; }
Record<string, string>, string>
6

7
const 
const rawHeaders: "nonsensical gibberish and badly formatted stuff"
rawHeaders = "nonsensical gibberish and badly formatted stuff"
8

9
const 
const result: Either.Either<Record<string, string>, string>
result = 
function parseHeaders(raw: string): Either.Either<Record<string, string>, string>
parseHeaders(
const rawHeaders: "nonsensical gibberish and badly formatted stuff"
rawHeaders)
10

11
// const newResult: Either<Record<string, string>, Error>
12
const 
const newResult: any
newResult = 
const result: Either.Either<Record<string, string>, string>
result.
any
pipe(
import Either
Either.
any
mapLeft((err) => new 
var Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)
Error(
err: any
err)))Error ts(7006)  ― Parameter 'err' implicitly has an 'any' type.

unwrapOr

Example (Providing a default value)

1
import { 
import err
err } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

3
const 
const result: any
result = 
import err
err("Oh no")
4

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

7
const 
const unwrapped: any
unwrapped = 
const result: any
result.
any
map(
const multiply: (value: number) => number
multiply).
any
unwrapOr(10)

1
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
2

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

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

7
const 
const unwrapped: any
unwrapped = 
const result: any
result.
any
pipe(
8
  
import Either
Either.
any
map(
const multiply: (value: number) => number
multiply),
9
  
import Either
Either.
any
getOrElse(() => 10),
10
)

andThen

Example (Chaining computations that may fail)

1
import { 
import ok
ok, 
import Result
Result, 
import err
err } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

6
import ok
ok(16).
any
andThen(
const sqrt: (n: number) => Result<number, string>
sqrt).
any
andThen(
const sqrt: (n: number) => Result<number, string>
sqrt)
7
// Ok(2)

1
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
2

3
const 
const sqrt: (n: number) => Either.Either<number, string>
sqrt = (
n: number
n: number): 
import Either
Either.
type Either.Either = /*unresolved*/ any
Either<number, string> =>
4
  
n: number
n > 0 ? 
import Either
Either.
any
right(
var Math: Math
Math.
Math.sqrt(x: number): number
sqrt(
n: number
n)) : 
import Either
Either.
any
left("n must be positive")
5

6
import Either
Either.
any
right(16).
any
pipe(
import Either
Either.
any
andThen(
const sqrt: (n: number) => Either.Either<number, string>
sqrt), 
import Either
Either.
any
andThen(
const sqrt: (n: number) => Either.Either<number, string>
sqrt))
7
// Right(2)

asyncAndThen

Example (Chaining asynchronous computations that may fail)

1
import { 
import ok
ok, 
import okAsync
okAsync } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

3
// const result: ResultAsync<number, never>
4
const 
const result: any
result = 
import ok
ok(1).
any
asyncAndThen((n) => 
import okAsync
okAsync(
n: any
n + 1))Error ts(7006)  ― Parameter 'n' implicitly has an 'any' type.

1
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
2
import * as 
import Effect
Effect from "effect/Effect"
3

4
// const result: Effect<number, never, never>
5
const 
const result: any
result = 
import Either
Either.
any
right(1).
any
pipe(
6
  
import Effect
Effect.
const andThen: <unknown, any, never, never>(f: (a: unknown) => Effect.Effect<any, never, never>) => <E, R>(self: Effect.Effect<unknown, E, R>) => Effect.Effect<any, E, R> (+3 overloads)
andThen((
n: unknown
n) => 
import Effect
Effect.
const succeed: <any>(value: any) => Effect.Effect<any, never, never>
succeed(n + 1)),Error ts(18046)  ― 'n' is of type 'unknown'.
7
)

orElse

Example (Providing an alternative on failure)

1
import { 
import Result
Result, 
import err
err, 
import ok
ok } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

3
enum 
enum DatabaseError
DatabaseError {
4
  
function (enum member) DatabaseError.PoolExhausted = "PoolExhausted"
PoolExhausted = "PoolExhausted",
5
  
function (enum member) DatabaseError.NotFound = "NotFound"
NotFound = "NotFound",
6
}
7

8
const 
const dbQueryResult: Result<string, DatabaseError>
dbQueryResult: 
import Result
Result<string, 
enum DatabaseError
DatabaseError> = 
import err
err(
enum DatabaseError
DatabaseError.
function (enum member) DatabaseError.NotFound = "NotFound"
NotFound)
9

10
const 
const updatedQueryResult: any
updatedQueryResult = 
const dbQueryResult: Result<string, DatabaseError>
dbQueryResult.
any
orElse((dbError) =>Error ts(7006)  ― Parameter 'dbError' implicitly has an 'any' type.
11
  
dbError: any
dbError === 
enum DatabaseError
DatabaseError.
function (enum member) DatabaseError.NotFound = "NotFound"
NotFound ? 
import ok
ok("User does not exist") : 
import err
err(500),
12
)

1
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
2

3
enum 
enum DatabaseError
DatabaseError {
4
  
function (enum member) DatabaseError.PoolExhausted = "PoolExhausted"
PoolExhausted = "PoolExhausted",
5
  
function (enum member) DatabaseError.NotFound = "NotFound"
NotFound = "NotFound",
6
}
7

8
const 
const dbQueryResult: Either.Either<string, DatabaseError>
dbQueryResult: 
import Either
Either.
type Either.Either = /*unresolved*/ any
Either<string, 
enum DatabaseError
DatabaseError> = 
import Either
Either.
any
left(
9
  
enum DatabaseError
DatabaseError.
function (enum member) DatabaseError.NotFound = "NotFound"
NotFound,
10
)
11

12
const 
const updatedQueryResult: any
updatedQueryResult = 
const dbQueryResult: Either.Either<string, DatabaseError>
dbQueryResult.
any
pipe(
13
  
import Either
Either.
any
orElse((dbError) =>Error ts(7006)  ― Parameter 'dbError' implicitly has an 'any' type.
14
    
dbError: any
dbError === 
enum DatabaseError
DatabaseError.
function (enum member) DatabaseError.NotFound = "NotFound"
NotFound
15
      ? 
import Either
Either.
any
right("User does not exist")
16
      : 
import Either
Either.
any
left(500),
17
  ),
18
)

match

Example (Pattern matching on success or failure)

1
import { 
import Result
Result } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

5
const myResult: Result<number, string>
myResult.
any
match(
6
  (value) => `The value is ${
value: any
value}`,Error ts(7006)  ― Parameter 'value' implicitly has an 'any' type.
7
  (error) => `The error is ${
error: any
error}`,Error ts(7006)  ― Parameter 'error' implicitly has an 'any' type.
8
)

1
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
2

3
declare const 
const myResult: Either.Either<number, string>
myResult: 
import Either
Either.
type Either.Either = /*unresolved*/ any
Either<number, string>
4

5
const myResult: Either.Either<number, string>
myResult.
any
pipe(
6
  
import Either
Either.
any
match({
7
    
onLeft: (error: any) => string
onLeft: (error) => `The error is ${
error: any
error}`,Error ts(7006)  ― Parameter 'error' implicitly has an 'any' type.
8
    
onRight: (value: any) => string
onRight: (value) => `The value is ${
value: any
value}`,Error ts(7006)  ― Parameter 'value' implicitly has an 'any' type.
9
  }),
10
)

asyncMap

Example (Parsing headers and looking up a user)

1
import { 
import Result
Result } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

3
interface 
interface User
User {}
4
declare function 
function parseHeaders(raw: string): Result<Record<string, string>, string>
parseHeaders(
5
  
raw: string
raw: string,
6
): 
import Result
Result<
type Record<K extends keyof any, T> = { [P in K]: T; }
Record<string, string>, string>
7
declare function 
function findUserInDatabase(authorization: string): Promise<User | undefined>
findUserInDatabase(
8
  
authorization: string
authorization: string,
9
): 
interface Promise<T>
Promise<
interface User
User | undefined>
10

11
const 
const rawHeader: "Authorization: Bearer 1234567890"
rawHeader = "Authorization: Bearer 1234567890"
12

13
// const asyncResult: ResultAsync<User | undefined, string>
14
const 
const asyncResult: any
asyncResult = 
function parseHeaders(raw: string): Result<Record<string, string>, string>
parseHeaders(
const rawHeader: "Authorization: Bearer 1234567890"
rawHeader)
15
  .
any
map((kvMap) => 
kvMap: any
kvMap["Authorization"])Error ts(7006)  ― Parameter 'kvMap' implicitly has an 'any' type.
16
  .
any
asyncMap((authorization) =>Error ts(7006)  ― Parameter 'authorization' implicitly has an 'any' type.
17
    
authorization: any
authorization === 
var undefined
undefined
18
      ? 
var Promise: PromiseConstructor
Promise.
PromiseConstructor.resolve<undefined>(value: undefined): Promise<undefined> (+2 overloads)
resolve(
var undefined
undefined)
19
      : 
function findUserInDatabase(authorization: string): Promise<User | undefined>
findUserInDatabase(
authorization: any
authorization),
20
  )

1
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
2
import * as 
import Effect
Effect from "effect/Effect"
3

4
interface 
interface User
User {}
5
declare function 
function parseHeaders(raw: string): Either.Either<Record<string, string>, string>
parseHeaders(
6
  
raw: string
raw: string,
7
): 
import Either
Either.
type Either.Either = /*unresolved*/ any
Either<
type Record<K extends keyof any, T> = { [P in K]: T; }
Record<string, string>, string>
8
declare function 
function findUserInDatabase(authorization: string): Promise<User | undefined>
findUserInDatabase(
9
  
authorization: string
authorization: string,
10
): 
interface Promise<T>
Promise<
interface User
User | undefined>
11

12
const 
const rawHeader: "Authorization: Bearer 1234567890"
rawHeader = "Authorization: Bearer 1234567890"
13

14
// const asyncResult: Effect<User | undefined, string | UnknownException>
15
const 
const asyncResult: any
asyncResult = 
function parseHeaders(raw: string): Either.Either<Record<string, string>, string>
parseHeaders(
const rawHeader: "Authorization: Bearer 1234567890"
rawHeader).
any
pipe(
16
  
import Either
Either.
any
map((kvMap) => 
kvMap: any
kvMap["Authorization"]),Error ts(7006)  ― Parameter 'kvMap' implicitly has an 'any' type.
17
  
import Effect
Effect.andThen((
authorization: unknown
authorization) =>Error ts(2769)  ― No overload matches this call.
  Overload 1 of 4, '(f: (a: unknown) => Effect<unknown, unknown, unknown>): <E, R>(self: Effect<unknown, E, R>) => Effect<unknown, unknown, unknown>', gave the following error.
    Type 'Promise<User | undefined>' is missing the following properties from type 'Effect<unknown, unknown, unknown>': [TypeId], [Symbol.iterator], pipe, toJSON, [NodeInspectSymbol]
  Overload 2 of 4, '(f: Effect<unknown, unknown, unknown>): <A, E, R>(self: Effect<A, E, R>) => Effect<unknown, unknown, unknown>', gave the following error.
    Argument of type '(authorization: unknown) => Promise<User | undefined>' is not assignable to parameter of type 'Effect<unknown, unknown, unknown>'.
18
    
authorization: unknown
authorization === 
var undefined
undefined
19
      ? 
var Promise: PromiseConstructor
Promise.
PromiseConstructor.resolve<undefined>(value: undefined): Promise<undefined> (+2 overloads)
resolve(
var undefined
undefined)
20
      : 
function findUserInDatabase(authorization: string): Promise<User | undefined>
findUserInDatabase(authorization),Error ts(2345)  ― Argument of type '{} | null' is not assignable to parameter of type 'string'.
  Type 'null' is not assignable to type 'string'.
21
  ),
22
)

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 { 
import Result
Result, 
import ok
ok } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

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

1
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
2

3
const 
const results: Either.Either<number, string>[]
results: 
import Either
Either.
type Either.Either = /*unresolved*/ any
Either<number, string>[] = [
4
  
import Either
Either.
any
right(1),
5
  
import Either
Either.
any
right(2),
6
]
7

8
// const combined: Either<number[], string>
9
const 
const combined: any
combined = 
import Either
Either.
any
all(
const results: Either.Either<number, string>[]
results)

combineWithAllErrors

Example (Collecting all errors and successes)

1
import { 
import Result
Result, 
import ok
ok, 
import err
err } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

10
const 
const result: any
result = 
import Result
Result.
any
combineWithAllErrors(
const results: Result<number, string>[]
results)
11
// result is Err(['boooom!', 'ahhhhh!'])

1
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
2
import * as 
import Array
Array from "effect/Array"
3

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

11
const 
const errors: any
errors = 
import Array
Array.getLefts(
const results: Either.Either<number, string>[]
results)Error ts(2339)  ― Property 'getLefts' does not exist on type 'typeof import("/home/runner/work/website/website/node_modules/.pnpm/effect@4.0.0-rc.115/node_modules/effect/dist/Array")'.
12
// errors is ['boooom!', 'ahhhhh!']
13

14
const 
const successes: any
successes = 
import Array
Array.getRights(
const results: Either.Either<number, string>[]
results)Error ts(2339)  ― Property 'getRights' does not exist on type 'typeof import("/home/runner/work/website/website/node_modules/.pnpm/effect@4.0.0-rc.115/node_modules/effect/dist/Array")'.
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 { 
import okAsync
okAsync } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

5
const 
const result: any
result = await 
const myResultAsync: any
myResultAsync
6

7
const result: any
result.
any
isOk() // true
8
const result: any
result.
any
isErr() // false

1
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
2
import * as 
import Effect
Effect from "effect/Effect"
3

4
const 
const myResultAsync: Effect.Effect<{
    myData: string;
}, never, never>
myResultAsync = 
import Effect
Effect.
const succeed: <{
    myData: string;
}>(value: {
    myData: string;
}) => Effect.Effect<{
    myData: string;
}, never, never>
succeed({ 
myData: string
myData: "test" })
5

6
const 
const result: unknown
result = await 
import Effect
Effect.
const runPromise: <unknown, unknown>(effect: Effect.Effect<unknown, unknown, never>, options?: Effect.RunOptions | undefined) => Promise<unknown>
runPromise(
import Effect
Effect.either(
const myResultAsync: Effect.Effect<{
    myData: string;
}, never, never>
myResultAsync))Error ts(2339)  ― Property 'either' does not exist on type 'typeof import("/home/runner/work/website/website/node_modules/.pnpm/effect@4.0.0-rc.115/node_modules/effect/dist/Effect")'.
7

8
import Either
Either.
any
isRight(
const result: unknown
result) // true
9
import Either
Either.
any
isLeft(
const result: unknown
result) // false

errAsync

Example (Creating a failed async result)

1
import { 
import errAsync
errAsync } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

3
const 
const myResultAsync: any
myResultAsync = 
import errAsync
errAsync("Oh no")
4

5
const 
const myResult: any
myResult = await 
const myResultAsync: any
myResultAsync
6

7
const myResult: any
myResult.
any
isOk() // false
8
const myResult: any
myResult.
any
isErr() // true

1
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
2
import * as 
import Effect
Effect from "effect/Effect"
3

4
const 
const myResultAsync: Effect.Effect<never, string, never>
myResultAsync = 
import Effect
Effect.
const fail: <string>(error: string) => Effect.Effect<never, string, never>
fail("Oh no")
5

6
const 
const result: unknown
result = await 
import Effect
Effect.
const runPromise: <unknown, unknown>(effect: Effect.Effect<unknown, unknown, never>, options?: Effect.RunOptions | undefined) => Promise<unknown>
runPromise(
import Effect
Effect.either(
const myResultAsync: Effect.Effect<never, string, never>
myResultAsync))Error ts(2339)  ― Property 'either' does not exist on type 'typeof import("/home/runner/work/website/website/node_modules/.pnpm/effect@4.0.0-rc.115/node_modules/effect/dist/Effect")'.
7

8
import Either
Either.
any
isRight(
const result: unknown
result) // false
9
import Either
Either.
any
isLeft(
const result: unknown
result) // true

fromThrowable

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

1
import { 
import ResultAsync
ResultAsync } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

6
// (user: User) => ResultAsync<User, Error>
7
const 
const insertUser: any
insertUser = 
import ResultAsync
ResultAsync.
any
fromThrowable(
8
  
function insertIntoDb(user: User): Promise<User>
insertIntoDb,
9
  () => new 
var Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)
Error("Database error"),
10
)

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

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

6
// (user: User) => Effect<User, Error>
7
const 
const insertUser: (user: User) => Effect.Effect<User, Error, never>
insertUser = (
user: User
user: 
interface User
User) =>
8
  
import Effect
Effect.
const tryPromise: <User, Error>(options: {
    readonly try: (signal: AbortSignal) => PromiseLike<User>;
    readonly catch: (error: unknown) => Error;
}) => Effect.Effect<User, Error, never> (+1 overload)
tryPromise({
9
    
try: (signal: AbortSignal) => PromiseLike<User>
try: () => 
function insertIntoDb(user: User): Promise<User>
insertIntoDb(
user: User
user),
10
    
catch: (error: unknown) => Error
catch: () => new 
var Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)
Error("Database error"),
11
  })

map

Example (Transforming the success value)

1
import { 
import Result
Result, 
import ResultAsync
ResultAsync } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

8
const 
const usersInCanada: ResultAsync<User[], Error>
usersInCanada = 
function findUsersIn(country: string): ResultAsync<Array<User>, Error>
findUsersIn("Canada")
9

10
const 
const namesInCanada: any
namesInCanada = 
const usersInCanada: ResultAsync<User[], Error>
usersInCanada.
any
map((
users: User[]
users: 
interface Array<T>
Array<
interface User
User>) =>
11
  
users: User[]
users.
Array<User>.map<string>(callbackfn: (value: User, index: number, array: User[]) => string, thisArg?: any): string[]
map((
user: User
user) => 
user: User
user.
User.name: string
name),
12
)
13

14
// We can extract the Result using .then() or await
15
const namesInCanada: any
namesInCanada.
any
then((
namesResult: Result<string[], Error>
namesResult: 
import Result
Result<
interface Array<T>
Array<string>, 
interface Error
Error>) => {
16
  if (
namesResult: Result<string[], Error>
namesResult.
any
isErr()) {
17
    
var console: Console
console.
Console.log(...data: any[]): void
log("Couldn't get the users from the database", 
namesResult: Result<string[], Error>
namesResult.
any
error)
18
  } else {
19
    
var console: Console
console.
Console.log(...data: any[]): void
log("Users in Canada are named: " + 
namesResult: Result<string[], Error>
namesResult.
any
value.
any
join(","))
20
  }
21
})

1
import * as 
import Effect
Effect from "effect/Effect"
2
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
3

4
interface 
interface User
User {
5
  readonly 
User.name: string
name: string
6
}
7
declare function 
function findUsersIn(country: string): Effect.Effect<Array<User>, Error>
findUsersIn(
country: string
country: string): 
import Effect
Effect.
interface Effect<out A, out E = never, out R = never>
Effect<
interface Array<T>
Array<
interface User
User>, 
interface Error
Error>
8

9
const 
const usersInCanada: Effect.Effect<User[], Error, never>
usersInCanada = 
function findUsersIn(country: string): Effect.Effect<Array<User>, Error>
findUsersIn("Canada")
10

11
const 
const namesInCanada: Effect.Effect<string[], Error, never>
namesInCanada = 
const usersInCanada: Effect.Effect<User[], Error, never>
usersInCanada.
Pipeable.pipe<Effect.Effect<User[], Error, never>, Effect.Effect<string[], Error, never>>(this: Effect.Effect<User[], Error, never>, ab: (_: Effect.Effect<User[], Error, never>) => Effect.Effect<string[], Error, never>): Effect.Effect<string[], Error, never> (+21 overloads)
pipe(
12
  
import Effect
Effect.
const map: <User[], string[]>(f: (a: User[]) => string[]) => <E, R>(self: Effect.Effect<User[], E, R>) => Effect.Effect<string[], E, R> (+1 overload)
map((
users: User[]
users: 
interface Array<T>
Array<
interface User
User>) => 
users: User[]
users.
Array<User>.map<string>(callbackfn: (value: User, index: number, array: User[]) => string, thisArg?: any): string[]
map((
user: User
user) => 
user: User
user.
User.name: string
name)),
13
)
14

15
// We can extract the Either using Effect.either
16
import Effect
Effect.
const runPromise: <unknown, unknown>(effect: Effect.Effect<unknown, unknown, never>, options?: Effect.RunOptions | undefined) => Promise<unknown>
runPromise(
import Effect
Effect.either(
const namesInCanada: Effect.Effect<string[], Error, never>
namesInCanada)).
Promise<unknown>.then<void, never>(onfulfilled?: ((value: unknown) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<void>
then(Error ts(2339)  ― Property 'either' does not exist on type 'typeof import("/home/runner/work/website/website/node_modules/.pnpm/effect@4.0.0-rc.115/node_modules/effect/dist/Effect")'.
17
  (
namesResult: Either.Either<string[], Error>
namesResult: 
import Either
Either.
type Either.Either = /*unresolved*/ any
Either<
interface Array<T>
Array<string>, 
interface Error
Error>) => {
18
    if (
import Either
Either.
any
isLeft(
namesResult: Either.Either<string[], Error>
namesResult)) {
19
      
var console: Console
console.
Console.log(...data: any[]): void
log("Couldn't get the users from the database", 
namesResult: Either.Either<string[], Error>
namesResult.
any
left)
20
    } else {
21
      
var console: Console
console.
Console.log(...data: any[]): void
log("Users in Canada are named: " + 
namesResult: Either.Either<string[], Error>
namesResult.
any
right.
any
join(","))
22
    }
23
  },
24
)

mapErr

Example (Transforming the error value)

1
import { 
import Result
Result, 
import ResultAsync
ResultAsync } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

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

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

1
import * as 
import Effect
Effect from "effect/Effect"
2
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
3

4
interface 
interface User
User {
5
  readonly 
User.name: string
name: string
6
}
7
declare function 
function findUsersIn(country: string): Effect.Effect<Array<User>, Error>
findUsersIn(
country: string
country: string): 
import Effect
Effect.
interface Effect<out A, out E = never, out R = never>
Effect<
interface Array<T>
Array<
interface User
User>, 
interface Error
Error>
8

9
const 
const usersInCanada: Effect.Effect<User[], "Unknown country" | "System error, please contact an administrator.", never>
usersInCanada = 
function findUsersIn(country: string): Effect.Effect<Array<User>, Error>
findUsersIn("Canada").
Pipeable.pipe<Effect.Effect<User[], Error, never>, Effect.Effect<User[], "Unknown country" | "System error, please contact an administrator.", never>>(this: Effect.Effect<User[], Error, never>, ab: (_: Effect.Effect<User[], Error, never>) => Effect.Effect<User[], "Unknown country" | "System error, please contact an administrator.", never>): Effect.Effect<User[], "Unknown country" | "System error, please contact an administrator.", never> (+21 overloads)
pipe(
10
  
import Effect
Effect.
const mapError: <Error, "Unknown country" | "System error, please contact an administrator.">(f: (e: Error) => "Unknown country" | "System error, please contact an administrator.") => <A, R>(self: Effect.Effect<A, Error, R>) => Effect.Effect<A, "Unknown country" | "System error, please contact an administrator.", R> (+1 overload)
mapError((
error: Error
error: 
interface Error
Error) => {
11
    // The only error we want to pass to the user is "Unknown country"
12
    if (
error: Error
error.
Error.message: string
message === "Unknown country") {
13
      return 
error: Error
error.
Error.message: "Unknown country"
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
import Effect
Effect.
const runPromise: <unknown, unknown>(effect: Effect.Effect<unknown, unknown, never>, options?: Effect.RunOptions | undefined) => Promise<unknown>
runPromise(
import Effect
Effect.either(
const usersInCanada: Effect.Effect<User[], "Unknown country" | "System error, please contact an administrator.", never>
usersInCanada)).
Promise<unknown>.then<void, never>(onfulfilled?: ((value: unknown) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<void>
then(Error ts(2339)  ― Property 'either' does not exist on type 'typeof import("/home/runner/work/website/website/node_modules/.pnpm/effect@4.0.0-rc.115/node_modules/effect/dist/Effect")'.
21
  (
usersResult: Either.Either<User[], string>
usersResult: 
import Either
Either.
type Either.Either = /*unresolved*/ any
Either<
interface Array<T>
Array<
interface User
User>, string>) => {
22
    if (
import Either
Either.
any
isLeft(
usersResult: Either.Either<User[], string>
usersResult)) {
23
      
var console: Console
console.
Console.log(...data: any[]): void
log("Couldn't get the users from the database", 
usersResult: Either.Either<User[], string>
usersResult.
any
left)
24
    } else {
25
      
var console: Console
console.
Console.log(...data: any[]): void
log("Users in Canada are: " + 
usersResult: Either.Either<User[], string>
usersResult.
any
right.
any
join(","))
26
    }
27
  },
28
)

unwrapOr

Example (Providing a default value when async fails)

1
import { 
import errAsync
errAsync } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

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

3
const 
const unwrapped: number
unwrapped = await 
import Effect
Effect.
const runPromise: <number, never>(effect: Effect.Effect<number, never, never>, options?: Effect.RunOptions | undefined) => Promise<number>
runPromise(
4
  
import Effect
Effect.
const fail: <number>(error: number) => Effect.Effect<never, number, never>
fail(0).
Pipeable.pipe<Effect.Effect<never, number, never>, Effect.Effect<number, never, never>>(this: Effect.Effect<never, number, never>, ab: (_: Effect.Effect<never, number, never>) => Effect.Effect<number, never, never>): Effect.Effect<number, never, never> (+21 overloads)
pipe(
import Effect
Effect.
const orElseSucceed: <number>(evaluate: LazyArg<number>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<number | A, never, R> (+1 overload)
orElseSucceed(() => 10)),
5
)
6
// unwrapped = 10

andThen

Example (Chaining multiple async computations)

1
import { 
import Result
Result, 
import ResultAsync
ResultAsync } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

8
const 
const user: User
user: 
interface User
User = {}
9

10
const 
const resAsync: any
resAsync = 
function validateUser(user: User): ResultAsync<User, Error>
validateUser(
const user: User
user)
11
  .
any
andThen(
function insertUser(user: User): ResultAsync<User, Error>
insertUser)
12
  .
any
andThen(
function sendNotification(user: User): ResultAsync<void, Error>
sendNotification)
13

14
const resAsync: any
resAsync.
any
then((
res: Result<void, Error>
res: 
import Result
Result<void, 
interface Error
Error>) => {
15
  if (
res: Result<void, Error>
res.
any
isErr()) {
16
    
var console: Console
console.
Console.log(...data: any[]): void
log("Oops, at least one step failed", 
res: Result<void, Error>
res.
any
error)
17
  } else {
18
    
var console: Console
console.
Console.log(...data: any[]): void
log("User has been validated, inserted and notified successfully.")
19
  }
20
})

1
import * as 
import Effect
Effect from "effect/Effect"
2
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
3

4
interface 
interface User
User {}
5
declare function 
function validateUser(user: User): Effect.Effect<User, Error>
validateUser(
user: User
user: 
interface User
User): 
import Effect
Effect.
interface Effect<out A, out E = never, out R = never>
Effect<
interface User
User, 
interface Error
Error>
6
declare function 
function insertUser(user: User): Effect.Effect<User, Error>
insertUser(
user: User
user: 
interface User
User): 
import Effect
Effect.
interface Effect<out A, out E = never, out R = never>
Effect<
interface User
User, 
interface Error
Error>
7
declare function 
function sendNotification(user: User): Effect.Effect<void, Error>
sendNotification(
user: User
user: 
interface User
User): 
import Effect
Effect.
interface Effect<out A, out E = never, out R = never>
Effect<void, 
interface Error
Error>
8

9
const 
const user: User
user: 
interface User
User = {}
10

11
const 
const resAsync: Effect.Effect<void, Error, never>
resAsync = 
function validateUser(user: User): Effect.Effect<User, Error>
validateUser(
const user: User
user).
Pipeable.pipe<Effect.Effect<User, Error, never>, Effect.Effect<User, Error, never>, Effect.Effect<void, Error, never>>(this: Effect.Effect<User, Error, never>, ab: (_: Effect.Effect<User, Error, never>) => Effect.Effect<User, Error, never>, bc: (_: Effect.Effect<User, Error, never>) => Effect.Effect<void, Error, never>): Effect.Effect<void, Error, never> (+21 overloads)
pipe(
12
  
import Effect
Effect.
const andThen: <User, User, Error, never>(f: (a: User) => Effect.Effect<User, Error, never>) => <E, R>(self: Effect.Effect<User, E, R>) => Effect.Effect<User, Error | E, R> (+3 overloads)
andThen(
function insertUser(user: User): Effect.Effect<User, Error>
insertUser),
13
  
import Effect
Effect.
const andThen: <User, void, Error, never>(f: (a: User) => Effect.Effect<void, Error, never>) => <E, R>(self: Effect.Effect<User, E, R>) => Effect.Effect<void, Error | E, R> (+3 overloads)
andThen(
function sendNotification(user: User): Effect.Effect<void, Error>
sendNotification),
14
)
15

16
import Effect
Effect.
const runPromise: <unknown, unknown>(effect: Effect.Effect<unknown, unknown, never>, options?: Effect.RunOptions | undefined) => Promise<unknown>
runPromise(
import Effect
Effect.either(
const resAsync: Effect.Effect<void, Error, never>
resAsync)).
Promise<unknown>.then<void, never>(onfulfilled?: ((value: unknown) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<void>
then(Error ts(2339)  ― Property 'either' does not exist on type 'typeof import("/home/runner/work/website/website/node_modules/.pnpm/effect@4.0.0-rc.115/node_modules/effect/dist/Effect")'.
17
  (
res: Either.Either<void, Error>
res: 
import Either
Either.
type Either.Either = /*unresolved*/ any
Either<void, 
interface Error
Error>) => {
18
    if (
import Either
Either.
any
isLeft(
res: Either.Either<void, Error>
res)) {
19
      
var console: Console
console.
Console.log(...data: any[]): void
log("Oops, at least one step failed", 
res: Either.Either<void, Error>
res.
any
left)
20
    } else {
21
      
var console: Console
console.
Console.log(...data: any[]): void
log(
22
        "User has been validated, inserted and notified successfully.",
23
      )
24
    }
25
  },
26
)

orElse

Example (Fallback when an async operation fails)

1
import { 
import ResultAsync
ResultAsync, 
import ok
ok } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

7
const 
const userId: "123"
userId = "123"
8

9
// Try to fetch user data, but provide a default if it fails
10
const 
const userResult: any
userResult = 
function fetchUserData(id: string): ResultAsync<User, Error>
fetchUserData(
const userId: "123"
userId).
any
orElse(() => 
import ok
ok(
function getDefaultUser(): User
getDefaultUser()))
11

12
const userResult: any
userResult.
any
then((result) => {Error ts(7006)  ― Parameter 'result' implicitly has an 'any' type.
13
  if (
result: any
result.
any
isOk()) {
14
    
var console: Console
console.
Console.log(...data: any[]): void
log("User data:", 
result: any
result.
any
value)
15
  }
16
})

1
import * as 
import Effect
Effect from "effect/Effect"
2
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
3

4
interface 
interface User
User {}
5
declare function 
function fetchUserData(id: string): Effect.Effect<User, Error>
fetchUserData(
id: string
id: string): 
import Effect
Effect.
interface Effect<out A, out E = never, out R = never>
Effect<
interface User
User, 
interface Error
Error>
6
declare function 
function getDefaultUser(): User
getDefaultUser(): 
interface User
User
7

8
const 
const userId: "123"
userId = "123"
9

10
// Try to fetch user data, but provide a default if it fails
11
const 
const userResult: never
userResult = 
function fetchUserData(id: string): Effect.Effect<User, Error>
fetchUserData(
const userId: "123"
userId).
Pipeable.pipe<Effect.Effect<User, Error, never>, never>(this: Effect.Effect<User, Error, never>, ab: (_: Effect.Effect<User, Error, never>) => never): never (+21 overloads)
pipe(
12
  
import Effect
Effect.orElse(() => 
import Effect
Effect.
const succeed: <User>(value: User) => Effect.Effect<User, never, never>
succeed(
function getDefaultUser(): User
getDefaultUser())),Error ts(2339)  ― Property 'orElse' does not exist on type 'typeof import("/home/runner/work/website/website/node_modules/.pnpm/effect@4.0.0-rc.115/node_modules/effect/dist/Effect")'.
13
)
14

15
import Effect
Effect.
const runPromise: <unknown, unknown>(effect: Effect.Effect<unknown, unknown, never>, options?: Effect.RunOptions | undefined) => Promise<unknown>
runPromise(
import Effect
Effect.either(
const userResult: never
userResult)).
Promise<unknown>.then<void, never>(onfulfilled?: ((value: unknown) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<void>
then((
result: unknown
result) => {Error ts(2339)  ― Property 'either' does not exist on type 'typeof import("/home/runner/work/website/website/node_modules/.pnpm/effect@4.0.0-rc.115/node_modules/effect/dist/Effect")'.
16
  if (
import Either
Either.
any
isRight(
result: unknown
result)) {
17
    
var console: Console
console.
Console.log(...data: any[]): void
log("User data:", result.
any
right)Error ts(18046)  ― 'result' is of type 'unknown'.
18
  }
19
})

match

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

1
import { 
import ResultAsync
ResultAsync } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

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

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

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

3
interface 
interface User
User {
4
  readonly 
User.name: string
name: string
5
}
6
declare function 
function validateUser(user: User): Effect.Effect<User, Error>
validateUser(
user: User
user: 
interface User
User): 
import Effect
Effect.
interface Effect<out A, out E = never, out R = never>
Effect<
interface User
User, 
interface Error
Error>
7
declare function 
function insertUser(user: User): Effect.Effect<User, Error>
insertUser(
user: User
user: 
interface User
User): 
import Effect
Effect.
interface Effect<out A, out E = never, out R = never>
Effect<
interface User
User, 
interface Error
Error>
8

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

11
// Handle both cases at the end of the chain using match
12
const 
const resultMessage: string
resultMessage = await 
import Effect
Effect.
const runPromise: <string, never>(effect: Effect.Effect<string, never, never>, options?: Effect.RunOptions | undefined) => Promise<string>
runPromise(
13
  
function validateUser(user: User): Effect.Effect<User, Error>
validateUser(
const user: User
user).
Pipeable.pipe<Effect.Effect<User, Error, never>, Effect.Effect<User, Error, never>, Effect.Effect<string, never, never>>(this: Effect.Effect<User, Error, never>, ab: (_: Effect.Effect<User, Error, never>) => Effect.Effect<User, Error, never>, bc: (_: Effect.Effect<User, Error, never>) => Effect.Effect<string, never, never>): Effect.Effect<string, never, never> (+21 overloads)
pipe(
14
    
import Effect
Effect.
const andThen: <User, User, Error, never>(f: (a: User) => Effect.Effect<User, Error, never>) => <E, R>(self: Effect.Effect<User, E, R>) => Effect.Effect<User, Error | E, R> (+3 overloads)
andThen(
function insertUser(user: User): Effect.Effect<User, Error>
insertUser),
15
    
import Effect
Effect.
const match: <Error, string, User, string>(options: {
    readonly onFailure: (error: Error) => string;
    readonly onSuccess: (value: User) => string;
}) => <R>(self: Effect.Effect<User, Error, R>) => Effect.Effect<string, never, R> (+1 overload)
match({
16
      
onSuccess: (value: User) => string
onSuccess: (
user: User
user) => `User ${
user: User
user.
User.name: string
name} has been successfully created`,
17
      
onFailure: (error: Error) => string
onFailure: (
error: Error
error) =>
18
        `User could not be created because ${
error: Error
error.
Error.message: string
message}`,
19
    }),
20
  ),
21
)

combine

Example (Combining multiple async results)

1
import { 
import ResultAsync
ResultAsync, 
import okAsync
okAsync } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

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

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

3
const 
const resultList: Effect.Effect<number, string, never>[]
resultList: 
import Effect
Effect.
interface Effect<out A, out E = never, out R = never>
Effect<number, string>[] = [
4
  
import Effect
Effect.
const succeed: <number>(value: number) => Effect.Effect<number, never, never>
succeed(1),
5
  
import Effect
Effect.
const succeed: <number>(value: number) => Effect.Effect<number, never, never>
succeed(2),
6
]
7

8
// const combinedList: Effect<number[], string>
9
const 
const combinedList: Effect.Effect<number[], string, never>
combinedList = 
import Effect
Effect.
const all: <Effect.Effect<number, string, never>[], {
    readonly concurrency?: Concurrency | undefined;
    readonly discard?: boolean | undefined;
    readonly mode?: "default" | "result" | undefined;
}>(arg: Effect.Effect<number, string, never>[], options?: {
    readonly concurrency?: Concurrency | undefined;
    readonly discard?: boolean | undefined;
    readonly mode?: "default" | "result" | undefined;
} | undefined) => Effect.Effect<number[], string, never>
all(
const resultList: Effect.Effect<number, string, never>[]
resultList)

combineWithAllErrors

Example (Collecting all errors instead of failing fast)

1
import { 
import ResultAsync
ResultAsync, 
import okAsync
okAsync, 
import errAsync
errAsync } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

10
const 
const result: any
result = await 
import ResultAsync
ResultAsync.
any
combineWithAllErrors(
const resultList: ResultAsync<number, string>[]
resultList)
11
// result is Err(['boooom!', 'ahhhhh!'])

1
import { 
import Effect
Effect, 
const identity: <A>(a: A) => A
identity } from "effect"
2

3
const 
const resultList: Effect.Effect<number, string, never>[]
resultList: 
import Effect
Effect.
interface Effect<out A, out E = never, out R = never>
Effect<number, string>[] = [
4
  
import Effect
Effect.
const succeed: <number>(value: number) => Effect.Effect<number, never, never>
succeed(123),
5
  
import Effect
Effect.
const fail: <string>(error: string) => Effect.Effect<never, string, never>
fail("boooom!"),
6
  
import Effect
Effect.
const succeed: <number>(value: number) => Effect.Effect<number, never, never>
succeed(456),
7
  
import Effect
Effect.
const fail: <string>(error: string) => Effect.Effect<never, string, never>
fail("ahhhhh!"),
8
]
9

10
const 
const result: unknown
result = await 
import Effect
Effect.
const runPromise: <unknown, unknown>(effect: Effect.Effect<unknown, unknown, never>, options?: Effect.RunOptions | undefined) => Promise<unknown>
runPromise(
11
  
import Effect
Effect.either(
import Effect
Effect.validateAll(
const resultList: Effect.Effect<number, string, never>[]
resultList, 
const identity: <A>(a: A) => A
identity)),Error ts(2339)  ― Property 'either' does not exist on type 'typeof import("/home/runner/work/website/website/node_modules/.pnpm/effect@4.0.0-rc.115/node_modules/effect/dist/Effect")'.Error ts(2551)  ― Property 'validateAll' does not exist on type 'typeof import("/home/runner/work/website/website/node_modules/.pnpm/effect@4.0.0-rc.115/node_modules/effect/dist/Effect")'. Did you mean 'validate'?
12
)
13
// result is left(['boooom!', 'ahhhhh!'])

Utilities

fromThrowable

Example (Safely wrapping a throwing function)

1
import { 
import Result
Result } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

6
const 
const safeJsonParse: any
safeJsonParse = 
import Result
Result.
any
fromThrowable(
var JSON: JSON
JSON.
JSON.parse(text: string, reviver?: (this: any, key: string, value: any) => any): any
parse, 
const toParseError: () => ParseError
toParseError)
7

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

1
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
2

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

6
const 
const safeJsonParse: (s: string) => any
safeJsonParse = (
s: string
s: string) =>
7
  
import Either
Either.
any
try({ 
try: () => any
try: () => 
var JSON: JSON
JSON.
JSON.parse(text: string, reviver?: (this: any, key: string, value: any) => any): any
parse(
s: string
s), 
catch: () => ParseError
catch: 
const toParseError: () => ParseError
toParseError })
8

9
// the function can now be used safely,
10
// if the function throws, the result will be an Either
11
const 
const result: any
result = 
const safeJsonParse: (s: string) => any
safeJsonParse("{")

safeTry

Example (Using generators to simplify error handling)

1
import { 
import Result
Result, 
import ok
ok, 
import safeTry
safeTry } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

6
function 
function myFunc(): Result<number, string>
myFunc(): 
import Result
Result<number, string> {
7
  return 
import safeTry
safeTry<number, string>(function* () {
8
    return 
import ok
ok(
9
      (yield* 
function mayFail1(): Result<number, string>
mayFail1().
any
mapErr(
10
        (e) => `aborted by an error from 1st function, ${
e: any
e}`,Error ts(7006)  ― Parameter 'e' implicitly has an 'any' type.
11
      )) +
12
        (yield* 
function mayFail2(): Result<number, string>
mayFail2().
any
mapErr(
13
          (e) => `aborted by an error from 2nd function, ${
e: any
e}`,Error ts(7006)  ― Parameter 'e' implicitly has an 'any' type.
14
        )),
15
    )
16
  })
17
}

1
import * as 
import Either
Either from "effect/Either"Error ts(2307)  ― Cannot find module 'effect/Either' or its corresponding type declarations.
2

3
declare function 
function mayFail1(): Either.Either<number, string>
mayFail1(): 
import Either
Either.
type Either.Either = /*unresolved*/ any
Either<number, string>
4
declare function 
function mayFail2(): Either.Either<number, string>
mayFail2(): 
import Either
Either.
type Either.Either = /*unresolved*/ any
Either<number, string>
5

6
function 
function myFunc(): Either.Either<number, string>
myFunc(): 
import Either
Either.
type Either.Either = /*unresolved*/ any
Either<number, string> {
7
  return 
import Either
Either.
any
gen(function* () {
8
    return (
9
      (yield* 
function mayFail1(): Either.Either<number, string>
mayFail1().
any
pipe(
10
        
import Either
Either.
any
mapLeft((e) => `aborted by an error from 1st function, ${
e: any
e}`),Error ts(7006)  ― Parameter 'e' implicitly has an 'any' type.
11
      )) +
12
      (yield* 
function mayFail2(): Either.Either<number, string>
mayFail2().
any
pipe(
13
        
import Either
Either.
any
mapLeft((e) => `aborted by an error from 2nd function, ${
e: any
e}`),Error ts(7006)  ― Parameter 'e' implicitly has an 'any' type.
14
      ))
15
    )
16
  })
17
}

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 { 
import ResultAsync
ResultAsync, 
import safeTry
safeTry, 
import ok
ok } from "neverthrow"Error ts(2307)  ― Cannot find module 'neverthrow' or its corresponding type declarations.
2

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

6
function 
function myFunc(): ResultAsync<number, string>
myFunc(): 
import ResultAsync
ResultAsync<number, string> {
7
  return 
import safeTry
safeTry<number, string>(async function* () {
8
    return 
import ok
ok(
9
      (yield* 
function mayFail1(): ResultAsync<number, string>
mayFail1().
any
mapErr(
10
        (e) => `aborted by an error from 1st function, ${
e: any
e}`,Error ts(7006)  ― Parameter 'e' implicitly has an 'any' type.
11
      )) +
12
        (yield* 
function mayFail2(): ResultAsync<number, string>
mayFail2().
any
mapErr(
13
          (e) => `aborted by an error from 2nd function, ${
e: any
e}`,Error ts(7006)  ― Parameter 'e' implicitly has an 'any' type.
14
        )),
15
    )
16
  })
17
}

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

3
declare function 
function mayFail1(): Effect.Effect<number, string>
mayFail1(): 
import Effect
Effect.
interface Effect<out A, out E = never, out R = never>
Effect<number, string>
4
declare function 
function mayFail2(): Effect.Effect<number, string>
mayFail2(): 
import Effect
Effect.
interface Effect<out A, out E = never, out R = never>
Effect<number, string>
5

6
function 
function myFunc(): Effect.Effect<number, string>
myFunc(): 
import Effect
Effect.
interface Effect<out A, out E = never, out R = never>
Effect<number, string> {
7
  return 
import Effect
Effect.
const gen: <Effect.Effect<number, string, never>, number>(f: () => Generator<Effect.Effect<number, string, never>, number, never>) => Effect.Effect<number, string, never> (+1 overload)
gen(function* () {
8
    return (
9
      (yield* 
function mayFail1(): Effect.Effect<number, string>
mayFail1().
Pipeable.pipe<Effect.Effect<number, string, never>, Effect.Effect<number, string, never>>(this: Effect.Effect<number, string, never>, ab: (_: Effect.Effect<number, string, never>) => Effect.Effect<number, string, never>): Effect.Effect<number, string, never> (+21 overloads)
pipe(
10
        
import Effect
Effect.
const mapError: <string, string>(f: (e: string) => string) => <A, R>(self: Effect.Effect<A, string, R>) => Effect.Effect<A, string, R> (+1 overload)
mapError((
e: string
e) => `aborted by an error from 1st function, ${
e: string
e}`),
11
      )) +
12
      (yield* 
function mayFail2(): Effect.Effect<number, string>
mayFail2().
Pipeable.pipe<Effect.Effect<number, string, never>, Effect.Effect<number, string, never>>(this: Effect.Effect<number, string, never>, ab: (_: Effect.Effect<number, string, never>) => Effect.Effect<number, string, never>): Effect.Effect<number, string, never> (+21 overloads)
pipe(
13
        
import Effect
Effect.
const mapError: <string, string>(f: (e: string) => string) => <A, R>(self: Effect.Effect<A, string, R>) => Effect.Effect<A, string, R> (+1 overload)
mapError((
e: string
e) => `aborted by an error from 2nd function, ${
e: string
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.