Resultar

About

Resultar is a TypeScript library for robust, type-safe error handling without throwing exceptions. It's a fork of the excellent neverthrow library, adding features for more flexibility in error handling

In the spirit of open-source development, resultar builds upon the solid foundation laid by neverthrow, extending its functionality to better suit specific needs. It introduces additional methods and functions such as tap, safeTryAsync, and fromThrowableAsync and finally providing more flexibility and control in error handling.

Description

Encode failure into your program.

This package contains a Result type that represents either success (Ok) or failure (Err).

For asynchronous tasks, resultar offers a ResultAsync class which wraps a Promise> and gives you the same level of expressivity and control as a regular Result.

ResultAsync is thenable meaning it behaves exactly like a native Promise ... except you have access to the same methods that Result provides without having to await or .then the promise!

$3

Table Of Contents

* Installation
* Top-Level API
* API Documentation
+ Synchronous API (Result)
- ok
- err
- unit
- Result.isOk (method)
- Result.isErr (method)
- Result.map (method)
- Result.mapErr (method)
- Result.unwrapOr (method)
- Result.andThen (method)
- Result.asyncAndThen (method)
- Result.orElse (method)
- Result.tap (method)
- Result.tapError (method)
- Result.log (method)
- Result.finally (method)
- Result.match (method)
- Result.asyncMap (method)
- Result.fromThrowable (static class method)
- Result.combine (static class method)
- Result.combineWithAllErrors (static class method)
- Result.safeUnwrap()
- Result.tryCatch (static class method)
+ Asynchronous API (ResultAsync)
- okAsync
- errAsync
- unitAsync
- ResultAsync.fromPromise (static class method)
- ResultAsync.fromSafePromise (static class method)
- ResultAsync.fromThrowable (static class method)
- ResultAsync.map (method)
- ResultAsync.mapErr (method)
- ResultAsync.unwrapOr (method)
- ResultAsync.andThen (method)
- ResultAsync.orElse (method)
- ResultAsync.tap (method)
- ResultAsync.tapError (method)
- ResultAsync.finally (method)
- ResultAsync.match (method)
- ResultAsync.combine (static class method)
- ResultAsync.combineWithAllErrors (static class method)
- ResultAsync.safeUnwrap()
- ResultAsync.tryCatch (static class method)
+ Utilities
- fromThrowable
- fromThrowableAsync
- fromPromise
- fromSafePromise
- safeTry
- tryCatch
- tryCatchAsync
+ Testing
* A note on the Package Name

Installation

``sh
> npm install resultar
`

Top-Level API

resultar exposes the following:

- ok convenience function to create an Ok variant of Result
- err convenience function to create an Err variant of Result
- Ok class and type
- Err class and type
- Result Type as well as namespace / object from which to call Result.fromThrowable, Result.combine.
- ResultAsync class
- okAsync convenience function to create a ResultAsync containing an Ok type Result
- errAsync convenience function to create a ResultAsync containing an Err type Result

`typescript
import {
ok,
Ok,
err,
Err,
Result,
okAsync,
errAsync,
ResultAsync,
fromThrowable,
fromPromise,
fromSafePromise,
safeTry,
} from 'resultar'
`

---

Check out the wiki for help on how to make the most of resultar.

---

API Documentation

$3

#### ok

Constructs an Ok variant of Result

Signature:

`typescript
ok(value: T): Ok { ... }
`

Example:

`typescript
import { ok } from 'resultar'

const myResult = ok({ myData: 'test' }) // instance of Ok

myResult.isOk() // true
myResult.isErr() // false
`

⬆️ Back to top

---

#### err

Constructs an Err variant of Result

Signature:

`typescript
err(error: E): Err { ... }
`

Example:

`typescript
import { err } from 'resultar'

const myResult = err('Oh noooo') // instance of Err

myResult.isOk() // false
myResult.isErr() // true
`

⬆️ Back to top
---

#### unit

Returns a Result with a value of undefined.

Signature:
`typescript
unit(): Result { ... }
`
⬆️ Back to top
---

#### Result.isOk (method)

Returns true if the result is an Ok variant

Signature:

`typescript
isOk(): boolean { ... }
`

⬆️ Back to top

---

#### Result.isErr (method)

Returns true if the result is an Err variant

Signature:

`typescript
isErr(): boolean { ... }
`

⬆️ Back to top

---

#### Result.map (method)

Maps a Result to Result by applying a function to a contained Ok value, leaving an Err value untouched.

This function can be used to compose the results of two functions.

Signature:

`typescript
class Result {
map(callback: (value: T) => U): Result { ... }
}
`

Example:

`typescript
import { getLines } from 'imaginary-parser'
// ^ assume getLines has the following signature:
// getLines(str: string): Result, Error>

// since the formatting is deemed correct by getLines
// then it means that linesResult is an Ok
// containing an Array of strings for each line of code
const linesResult = getLines('1\n2\n3\n4\n')

// this Result now has a Array inside it
const newResult = linesResult.map(
(arr: Array) => arr.map(parseInt)
)

newResult.isOk() // true
`

⬆️ Back to top

---

#### Result.mapErr (method)

Maps a Result to Result by applying a function to a contained Err value, leaving an Ok value untouched.

This function can be used to pass through a successful result while handling an error.

Signature:

`typescript
class Result {
mapErr(callback: (error: E) => F): Result { ... }
}
`

Example:

`typescript
import { parseHeaders } from 'imaginary-http-parser'
// imagine that parseHeaders has the following signature:
// parseHeaders(raw: string): Result

const rawHeaders = 'nonsensical gibberish and badly formatted stuff'

const parseResult = parseHeaders(rawHeaders)

parseResult.mapErr(parseError => {
res.status(400).json({
error: parseError
})
})

parseResult.isErr() // true
`

⬆️ Back to top

---

#### Result.unwrapOr (method)

Unwrap the Ok value, or return the default if there is an Err

Signature:

`typescript
class Result {
unwrapOr(value: T): T { ... }
}
`

Example:

`typescript
const myResult = err('Oh noooo')

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

const unwrapped: number = myResult.map(multiply).unwrapOr(10)
`

⬆️ Back to top

---

#### Result.andThen (method)

Same idea as map above. Except you must return a new Result.

The returned value will be a Result. As of v4.1.0-beta, you are able to return distinct error types (see signature below). Prior to v4.1.0-beta, the error type could not be distinct.

This is useful for when you need to do a subsequent computation using the inner T value, but that computation might fail.

Additionally, andThen is really useful as a tool to flatten a Result, E1> into a Result (see example below).

Signature:

`typescript
class Result {
// Note that the latest version lets you return distinct errors as well.
// If the error types (E and F) are the same (like string | string)
// then they will be merged into one type (string)
andThen(
callback: (value: T) => Result
): Result { ... }
}
`

Example 1: Chaining Results

`typescript
import { err, ok } from 'resultar'

const sq = (n: number): Result => ok(n ** 2)

ok(2)
.andThen(sq)
.andThen(sq) // Ok(16)

ok(2)
.andThen(sq)
.andThen(err) // Err(4)

ok(2)
.andThen(err)
.andThen(sq) // Err(2)

err(3)
.andThen(sq)
.andThen(sq) // Err(3)
`

Example 2: Flattening Nested Results

`typescript
// It's common to have nested Results
const nested = ok(ok(1234))

// notNested is a Ok(1234)
const notNested = nested.andThen((innerResult) => innerResult)
`

⬆️ Back to top

---

#### Result.asyncAndThen (method)

Same idea as andThen above, except you must return a new ResultAsync.

The returned value will be a ResultAsync.

Signature:

`typescript
class Result {
asyncAndThen(
callback: (value: T) => ResultAsync
): ResultAsync { ... }
}
`

⬆️ Back to top

---

#### Result.orElse (method)

Takes an Err value and maps it to a Result. This is useful for error recovery.

Signature:

`typescript
class Result {
orElse(
callback: (error: E) => Result
): Result { ... }
}
`

Example:

`typescript
enum DatabaseError {
PoolExhausted = 'PoolExhausted',
NotFound = 'NotFound',
}

const dbQueryResult: Result = err(DatabaseError.NotFound)

const updatedQueryResult = dbQueryResult.orElse((dbError) =>
dbError === DatabaseError.NotFound
? ok('User does not exist') // error recovery branch: ok() must be called with a value of type string
//
//
// err() can be called with a value of any new type that you want
// it could also be called with the same error value
//
// err(dbError)
: err(500)
)
`

⬆️ Back to top

---

#### Result.match (method)

Given 2 functions (one for the Ok variant and one for the Err variant) execute the function that matches the Result variant.

Match callbacks do not necessitate to return a Result, however you can return a Result if you want to.

Signature:

`typescript
class Result {
match(
okCallback: (value: T) => A,
errorCallback: (error: E) => A
): A => { ... }
}
`

match is like chaining map and mapErr, with the distinction that with match both functions must have the same return type.
The differences between match and chaining map and mapErr are that:
- with match both functions must have the same return type A
- match unwraps the Result into an A (the match functions' return type)
- This makes no difference if you are performing side effects only

Example:

`typescript
// map/mapErr api
// note that you DON'T have to append mapErr
// after map which means that you are not required to do
// error handling
computationThatMightFail().map(console.log).mapErr(console.error)

// match api
// works exactly the same as above since both callbacks
// only perform side effects,
// except, now you HAVE to do error handling :)
computationThatMightFail().match(console.log, console.error)

// Returning values
const attempt = computationThatMightFail()
.map((str) => str.toUpperCase())
.mapErr((err) => Error: ${err})
// attempt is of type Result

const answer = computationThatMightFail().match(
(str) => str.toUpperCase(),
(err) => Error: ${err}
)
// answer is of type string
`

If you don't use the error parameter in your match callback then match is equivalent to chaining map with unwrapOr:
`ts
const answer = computationThatMightFail().match(
(str) => str.toUpperCase(),
() => 'ComputationError'
)
// answer is of type string

const answer = computationThatMightFail()
.map((str) => str.toUpperCase())
.unwrapOr('ComputationError')
`


⬆️ Back to top

---

#### Result.asyncMap (method)

Similar to map except for two things:

- the mapping function must return a Promise
- asyncMap returns a ResultAsync

You can then chain the result of asyncMap using the ResultAsync apis (like map, mapErr, andThen, etc.)

Signature:

`typescript
class Result {
asyncMap(
callback: (value: T) => Promise
): ResultAsync { ... }
}
`

Example:

`typescript
import { parseHeaders } from 'imaginary-http-parser'
// imagine that parseHeaders has the following signature:
// parseHeaders(raw: string): Result

const asyncRes = parseHeaders(rawHeader)
.map(headerKvMap => headerKvMap.Authorization)
.asyncMap(findUserInDatabase)
`

Note that in the above example if parseHeaders returns an Err then .map and .asyncMap will not be invoked, and asyncRes variable will resolve to an Err when turned into a Result using await or .then().

⬆️ Back to top

---

#### Result.fromThrowable (static class method)

> Although Result is not an actual JS class, the way that fromThrowable has been implemented requires that you call fromThrowable as though it were a static method on Result. See examples below.

The JavaScript community has agreed on the convention of throwing exceptions.
As such, when interfacing with third party libraries it's imperative that you
wrap third-party code in try / catch blocks.

This function will create a new function that returns an Err when the original
function throws.

It is not possible to know the types of the errors thrown in the original
function, therefore it is recommended to use the second argument errorFn to
map what is thrown to a known type.

Example:

`typescript
import { Result } from 'resultar'

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

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

// the function can now be used safely, if the function throws, the result will be an Err
const res = safeJsonParse("{");
`

⬆️ Back to top

---

#### Result.combine (static class method)

> Although Result is not an actual JS class, the way that combine has been implemented requires that you call combine as though it were a static method on Result. See examples below.

Combine lists of Results.

If you're familiar with Promise.all, the combine function works conceptually the same.

combine works on both heterogeneous and homogeneous lists. This means that you can have lists that contain different kinds of Results and still be able to combine them. Note that you cannot combine lists that contain both Results and ResultAsyncs.

The combine function takes a list of results and returns a single result. If all the results in the list are Ok, then the return value will be a Ok containing a list of all the individual Ok values.

If just one of the results in the list is an Err then the combine function returns that Err value (it short circuits and returns the first Err that it finds).

Formally speaking:

`typescript
// homogeneous lists
function combine(resultList: Result[]): Result

// heterogeneous lists
function combine(resultList: [ Result, Result ]): Result<[ T1, T2 ], E1 | E2>
function combine => Result<[ T1, T2, T3 ], E1 | E2 | E3>
function combine => Result<[ T1, T2, T3, T4 ], E1 | E2 | E3 | E4>
// ... etc etc ad infinitum

`

Example:
`typescript
const resultList: Result[] =
[ok(1), ok(2)]

const combinedList: Result =
Result.combine(resultList)
`

Example with tuples:
`typescript
/* @example tuple(1, 2, 3) === [1, 2, 3] // with type [number, number, number] /
const tuple = (...args: T): T => args

const resultTuple: [Result, Result] =
tuple(ok('a'), ok('b'))

const combinedTuple: Result<[string, string], unknown> =
Result.combine(resultTuple)
`

⬆️ Back to top

---

#### Result.combineWithAllErrors (static class method)

> Although Result is not an actual JS class, the way that combineWithAllErrors has been implemented requires that you call combineWithAllErrors as though it were a static method on Result. See examples below.

Like combine but without short-circuiting. Instead of just the first error value, you get a list of all error values of the input result list.

If only some results fail, the new combined error list will only contain the error value of the failed results, meaning that there is no guarantee of the length of the new error list.

Function signature:

`typescript
// homogeneous lists
function combineWithAllErrors(resultList: Result[]): Result

// heterogeneous lists
function combineWithAllErrors(resultList: [ Result, Result ]): Result<[ T1, T2 ], (E1 | E2)[]>
function combineWithAllErrors => Result<[ T1, T2, T3 ], (E1 | E2 | E3)[]>
function combineWithAllErrors => Result<[ T1, T2, T3, T4 ], (E1 | E2 | E3 | E4)[]>
// ... etc etc ad infinitum
`

Example usage:

`typescript
const resultList: Result[] = [
ok(123),
err('boooom!'),
ok(456),
err('ahhhhh!'),
]

const result = Result.combineWithAllErrors(resultList)

// result is Err(['boooom!', 'ahhhhh!'])
`

⬆️ Back to top

#### Result.safeUnwrap()

Allows for unwrapping a Result or returning an Err implicitly, thereby reducing boilerplate.

⬆️ Back to top

#### Result.tryCatch() (static class method)

Provides a convenient way to handle errors in a procedural style, similar to Go's error handling pattern. It wraps a synchronous function call in a try-catch block and returns a Result that can be destructured to access the value or error.

Signature:
`typescript
static tryCatch(fn: () => Exclude>, errorFn?: (e: unknown) => E): Result
`

Example:
`typescript
const divide = (a: number, b: number) => {
if (b === 0) throw new Error("Cannot divide by zero");
return a / b;
};

// Using destructuring to handle errors procedurally
const { value, error } = Result.tryCatch(() => divide(10, 2));
if (error) {
console.error("Division failed:", error);
} else {
console.log("Result:", value); // Result: 5
}

// With custom error handling
const result = Result.tryCatch(
() => divide(10, 0),
(e) => Division error: ${e.message}
);
if (result.isErr()) {
console.error(result.error); // Division error: Cannot divide by zero
}
`


⬆️ Back to top

---

$3

#### okAsync

Constructs an Ok variant of ResultAsync

Signature:

`typescript
okAsync(value: T): ResultAsync
`

Example:

`typescript
import { okAsync } from 'resultar'

const myResultAsync = okAsync({ myData: 'test' }) // instance of ResultAsync

const myResult = await myResultAsync // instance of Ok

myResult.isOk() // true
myResult.isErr() // false
`

⬆️ Back to top

---

#### errAsync

Constructs an Err variant of ResultAsync

Signature:

`typescript
errAsync(error: E): ResultAsync
`

Example:

`typescript
import { errAsync } from 'resultar'

const myResultAsync = errAsync('Oh nooo') // instance of ResultAsync

const myResult = await myResultAsync // instance of Err

myResult.isOk() // false
myResult.isErr() // true
`

⬆️ Back to top

---

#### unitAsync

Constructs a ResultAsync with a value of undefined.

Signature:

`typescript
unit(error: E): ResultAsync
`

Example:

`typescript
import { errAsync } from 'resultar'

const myResultAsync =unitAsync() // instance of ResultAsync

const myResult = await myResultAsync // instance of Err

myResult.isOk() // false
myResult.value() // undefined
`

⬆️ Back to top

---

#### ResultAsync.fromThrowable (static class method)

Similar to Result.fromThrowable, but for functions that return a Promise.

Example:

`typescript
import { ResultAsync } from 'neverthrow'
import { insertIntoDb } from 'imaginary-database'
// insertIntoDb(user: User): Promise

const insertUser = ResultAsync.fromThrowable(insertIntoDb, () => new Error('Database error'))
// res has a type of (user: User) => ResultAsync
`

Note that this can be safer than using ResultAsync.fromPromise with
the result of a function call, because not all functions that return a Promise are async, and thus they can throw
errors synchronously rather than returning a rejected Promise. For example:

`typescript
import { readFile } from 'node:fs/promises'
import { fromThrowableAsync } from 'resultar'

const safeFileReader = fromThrowableAsync(
async (file: string) => readFile(file),
e => new Error('Oops: '.concat(String(e))),
)
const value = await safeFileReader('foo.txt')

if (value.isOk()) {
console.log(value.value.toString())
}
`

⬆️ Back to top

---

#### ResultAsync.fromPromise (static class method)

Transforms a PromiseLike (that may throw) into a ResultAsync.

The second argument handles the rejection case of the promise and maps the error from unknown into some type E.


Signature:

`typescript
// fromPromise is a static class method
// also available as a standalone function
// import { fromPromise } from 'resultar'
ResultAsync.fromPromise(
promise: PromiseLike,
errorHandler: (unknownError: unknown) => E)
): ResultAsync { ... }
`

If you are working with PromiseLike objects that you know for a fact will not throw, then use fromSafePromise in order to avoid having to pass a redundant errorHandler argument.

Example:

`typescript
import { ResultAsync } from 'resultar'
import { insertIntoDb } from 'imaginary-database'
// insertIntoDb(user: User): Promise

const res = ResultAsync.fromPromise(insertIntoDb(myUser), () => new Error('Database error'))
// res has a type of ResultAsync
`

⬆️ Back to top

---

#### ResultAsync.fromSafePromise (static class method)

Same as ResultAsync.fromPromise except that it does not handle the rejection of the promise. Ensure you know what you're doing, otherwise a thrown exception within this promise will cause ResultAsync to reject, instead of resolve to a Result.

Signature:

`typescript
// fromPromise is a static class method
// also available as a standalone function
// import { fromPromise } from 'resultar'
ResultAsync.fromSafePromise(
promise: PromiseLike
): ResultAsync { ... }
`

Example:

`typescript
import { RouteError } from 'routes/error'

// simulate slow routes in an http server that works in a Result / ResultAsync context
// Adopted from https://github.com/parlez-vous/server/blob/2496bacf55a2acbebc30631b5562f34272794d76/src/routes/common/signup.ts
export const slowDown = (ms: number) => (value: T) =>
ResultAsync.fromSafePromise(
new Promise((resolve) => {
setTimeout(() => {
resolve(value)
}, ms)
})
)

export const signupHandler = route((req, sessionManager) =>
decode(userSignupDecoder, req.body, 'Invalid request body').map((parsed) => {
return createUser(parsed)
.andThen(slowDown(3000)) // slowdown by 3 seconds
.andThen(sessionManager.createSession)
.map(({ sessionToken, admin }) => AppData.init(admin, sessionToken))
})
)
`


⬆️ Back to top

---

#### ResultAsync.map (method)

Maps a ResultAsync to ResultAsync by applying a function to a contained Ok value, leaving an Err value untouched.

The applied function can be synchronous or asynchronous (returning a Promise) with no impact to the return type.

This function can be used to compose the results of two functions.

Signature:

`typescript
class ResultAsync {
map(
callback: (value: T) => U | Promise
): ResultAsync { ... }
}
`

Example:

`typescript
import { findUsersIn } from 'imaginary-database'
// ^ assume findUsersIn has the following signature:
// findUsersIn(country: string): ResultAsync, Error>

const usersInCanada = findUsersIn("Canada")

// Let's assume we only need their names
const namesInCanada = usersInCanada.map((users: Array) => users.map(user => user.name))
// namesInCanada is of type ResultAsync, Error>

// We can extract the Result using .then() or await
namesInCanada.then((namesResult: Result, Error>) => {
if(namesResult.isErr()){
console.log("Couldn't get the users from the database", namesResult.error)
}
else{
console.log("Users in Canada are named: " + namesResult.value.join(','))
}
})
`

⬆️ Back to top

---

#### ResultAsync.mapErr (method)

Maps a ResultAsync to ResultAsync by applying a function to a contained Err value, leaving an Ok value untouched.

The applied function can be synchronous or asynchronous (returning a Promise) with no impact to the return type.

This function can be used to pass through a successful result while handling an error.

Signature:

`typescript
class ResultAsync {
mapErr(
callback: (error: E) => F | Promise
): ResultAsync { ... }
}
`

Example:

`typescript
import { findUsersIn } from 'imaginary-database'
// ^ assume findUsersIn has the following signature:
// findUsersIn(country: string): ResultAsync, Error>

// Let's say we need to low-level errors from findUsersIn to be more readable
const usersInCanada = findUsersIn("Canada").mapErr((error: Error) => {
// The only error we want to pass to the user is "Unknown country"
if(error.message === "Unknown country"){
return error.message
}
// All other errors will be labelled as a system error
return "System error, please contact an administrator."
})

// usersInCanada is of type ResultAsync, string>

usersInCanada.then((usersResult: Result, string>) => {
if(usersResult.isErr()){
res.status(400).json({
error: usersResult.error
})
}
else{
res.status(200).json({
users: usersResult.value
})
}
})
`

⬆️ Back to top

---

#### ResultAsync.unwrapOr (method)

Unwrap the Ok value, or return the default if there is an Err.
Works just like Result.unwrapOr but returns a Promise instead of T.

Signature:

`typescript
class ResultAsync {
unwrapOr(value: T): Promise { ... }
}
`

Example:

`typescript
const unwrapped: number = await errAsync(0).unwrapOr(10)
// unwrapped = 10
`

⬆️ Back to top

---

#### ResultAsync.andThen (method)

Same idea as map above. Except the applied function must return a Result or ResultAsync.

ResultAsync.andThen always returns a ResultAsync no matter the return type of the applied function.

This is useful for when you need to do a subsequent computation using the inner T value, but that computation might fail.

andThen is really useful as a tool to flatten a ResultAsync, E1> into a ResultAsync (see example below).

Signature:

`typescript
// Note that the latest version (v4.1.0-beta) lets you return distinct errors as well.
// If the error types (E and F) are the same (like string | string)
// then they will be merged into one type (string)

class ResultAsync {
andThen(
callback: (value: T) => Result | ResultAsync
): ResultAsync { ... }
}
`

Example

`typescript

import { validateUser } from 'imaginary-validator'
import { insertUser } from 'imaginary-database'
import { sendNotification } from 'imaginary-service'

// ^ assume validateUser, insertUser and sendNotification have the following signatures:
// validateUser(user: User): Result
// insertUser(user): ResultAsync
// sendNotification(user): ResultAsync

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

// resAsync is a ResultAsync

resAsync.then((res: Result) => {
if(res.isErr()){
console.log("Oops, at least one step failed", res.error)
}
else{
console.log("User has been validated, inserted and notified successfully.")
}
})
`

⬆️ Back to top

---
#### Result.tap (method)
Executes a side effect function with the Ok value and returns the original Result.
This method is useful for performing actions that do not modify the Result itself, such as logging or updating external state.
Signature:
`typescript
class ResultAsync {
tap(fn: (t: T) => void): Result {
}
`

Example:
`typescript
import { ok } from "resultar"
import { equal } from 'node:assert'

const foo = ok("foo")
const value = foo
.tap(console.error) // Prints "foo"
.map((value) => value.toUpperCase())
.tap(console.error) // Prints "FOO"
.match((v)=> v, (error) => "")
equal(value, "FOO")
`
⬆️ Back to top

---
#### Result.tapError (method)
Executes a side effect function with the Err value and returns the original Result.
This method is useful for performing actions that do not modify the Result itself, such as logging or updating external state.
Signature:
`typescript
class ResultAsync {
tapError(fn: (e: E) => void): Result {
}
`

Example:
`typescript
import { err } from "resultar"
import { equal } from 'node:assert'

const fooError = err("foo")
const value = fooError
.tapError(console.error) // Prints "foo"
.orElse((error) => {
return err("bar")
})
.tapError(console.error) // Prints "bar"
.match(()=> "", (error) => error)
equal(value, "bar")
// mapped.value === 'foo'
`
⬆️ Back to top

---

---
#### Result.log (method)

**Executes a side effect function with the Ok or Err value and returns the original Result.
This method is useful for performing actions that do not modify the Result itself, such as logging or updating external state.**

Signature:
`typescript
class Result {
log(fn: (t?: T, e?: E) => void): this {
`

Example:
`typescript

const reader = ok(file) // content file is line 01

reader
.log((value, error) => {
console.log("Logging file content:", error ? error : value)
})
.map(it => it.content)
.finally(_ => {
console.info('Closing file handle')
file.close()
})
.match((value) => {
console.log(value) // print line 01
}, (error) => {
console.error("Oops, something went wrong", error)
})
`
⬆️ Back to top

---

#### Result.finally (method)
Executes a cleanup function wether the is ok or error. This method is usefull to cleanup resources.
Signature:
`typescript
class Result {
finally(f: (value: T, error: E) => void): DisposableResult {..}
}
`

Example:
`typescript
const reader = ok(file) // content file is line 01

const result = reader.map(it => it.content).finally(_ => {
file.close()
})

if (resul.isOk()) {
console.log(result.value) // print line 01
}

`
⬆️ Back to top

---

#### ResultAsync.orElse (method)

Takes an Err value and maps it to a ResultAsync. This is useful for error recovery.

Signature:

`typescript
class ResultAsync {
orElse(
callback: (error: E) => Result | ResultAsync
): ResultAsync { ... }
}
`

⬆️ Back to top

---

#### ResultAsync.tap (method)

Executes a side effect function with the Ok value and returns the original ResultAsync.
This method is useful for performing actions that do not modify the ResultAsyn itself, such as logging or updating external state.
Signature:
`typescript
class ResultAsync {
tap(f: (t: T) => void | Promise): ResultAsync {...}
}
`

Example:
See Result.tap (method)


⬆️ Back to top

---

#### ResultAsync.tapError (method)

Executes a side effect function with the Ok value and returns the original ResultAsync.
This method is useful for performing actions that do not modify the ResultAsyn itself, such as logging or updating external state.
Signature:
`typescript
class ResultAsync {
tapError(f: (e: E) => void | Promise): ResultAsync {...}
}
`

Example:
See Result.tapError (method)


⬆️ Back to top


---

#### ResultAsync.finally (method)
Executes a cleanup function wether the is ok or error. This method is usefull to cleanup resources for async operations.
Signature:
`typescript
class ResultAsync {
finally(f: (value: T, error: E) => void): DisposableResultAsync {...}
}
`

Example:
`typescript
const fileHandle = await fs.open('foo.txt', 'w')

const result
= await fromPromise(fileHandle.write('A new line of text'), String)
.finally(async () => {
console.info('Closing file handle')
await fileHandle.close()
})

if (result.isOk()) {
console.log(result.value) // == 'A new line of text'
}

`

⬆️ Back to top

---

#### ResultAsync.match (method)

Given 2 functions (one for the Ok variant and one for the Err variant) execute the function that matches the ResultAsync variant.

The difference with Result.match is that it always returns a Promise because of the asynchronous nature of the ResultAsync.

Signature:

`typescript
class ResultAsync {
match(
okCallback: (value: T) => A,
errorCallback: (error: E) => A
): Promise => { ... }
}
`

Example:

`typescript

import { validateUser } from 'imaginary-validator'
import { insertUser } from 'imaginary-database'

// ^ assume validateUser and insertUser have the following signatures:
// validateUser(user: User): Result
// insertUser(user): ResultAsync

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

// resultMessage is a string
`

⬆️ Back to top

---

#### ResultAsync.combine (static class method)

Combine lists of ResultAsyncs.

If you're familiar with Promise.all, the combine function works conceptually the same.

combine works on both heterogeneous and homogeneous lists. This means that you can have lists that contain different kinds of ResultAsyncs and still be able to combine them. Note that you cannot combine lists that contain both Results and ResultAsyncs.

The combine function takes a list of results and returns a single result. If all the results in the list are Ok, then the return value will be a Ok containing a list of all the individual Ok values.

If just one of the results in the list is an Err then the combine function returns that Err value (it short circuits and returns the first Err that it finds).

Formally speaking:

`typescript
// homogeneous lists
function combine(resultList: ResultAsync[]): ResultAsync

// heterogeneous lists
function combine(resultList: [ ResultAsync, ResultAsync ]): ResultAsync<[ T1, T2 ], E1 | E2>
function combine => ResultAsync<[ T1, T2, T3 ], E1 | E2 | E3>
function combine => ResultAsync<[ T1, T2, T3, T4 ], E1 | E2 | E3 | E4>
// ... etc etc ad infinitum

`

Example:
`typescript
const resultList: ResultAsync[] =
[okAsync(1), okAsync(2)]

const combinedList: ResultAsync =
ResultAsync.combine(resultList)
`

Example with tuples:
`typescript
/* @example tuple(1, 2, 3) === [1, 2, 3] // with type [number, number, number] /
const tuple = (...args: T): T => args

const resultTuple: [ResultAsync, ResultAsync] =
tuple(okAsync('a'), okAsync('b'))

const combinedTuple: ResultAsync<[string, string], unknown> =
ResultAsync.combine(resultTuple)
`
⬆️ Back to top

---

#### ResultAsync.combineWithAllErrors (static class method)

Like combine but without short-circuiting. Instead of just the first error value, you get a list of all error values of the input result list.

If only some results fail, the new combined error list will only contain the error value of the failed results, meaning that there is no guarantee of the length of the new error list.

Function signature:

`typescript
// homogeneous lists
function combineWithAllErrors(resultList: ResultAsync[]): ResultAsync

// heterogeneous lists
function combineWithAllErrors(resultList: [ ResultAsync, ResultAsync ]): ResultAsync<[ T1, T2 ], (E1 | E2)[]>
function combineWithAllErrors => ResultAsync<[ T1, T2, T3 ], (E1 | E2 | E3)[]>
function combineWithAllErrors => ResultAsync<[ T1, T2, T3, T4 ], (E1 | E2 | E3 | E4)[]>
// ... etc etc ad infinitum
`

Example usage:

`typescript
const resultList: ResultAsync[] = [
okAsync(123),
errAsync('boooom!'),
okAsync(456),
errAsync('ahhhhh!'),
]

const result = ResultAsync.combineWithAllErrors(resultList)

// result is Err(['boooom!', 'ahhhhh!'])
`

#### ResultAsync.safeUnwrap()

Allows for unwrapping a Result or returning an Err implicitly, thereby reducing boilerplate.

⬆️ Back to top

#### ResultAsync.tryCatch() (static class method)

Similar to Result.tryCatch, but for handling asynchronous operations. It wraps a Promise in a try-catch block and returns a ResultAsync that can be awaited and destructured to access the value or error.

Signature:
`typescript
static tryCatch(fn: Promise, errorFn?: (e: unknown) => E): ResultAsync
`

Example:
`typescript
const divideAsync = async (a: number, b: number) => {
await new Promise(resolve => setTimeout(resolve, 100)); // Simulate async operation
if (b === 0) throw new Error("Cannot divide by zero");
return a / b;
};

// Using async/await with destructuring
const { value, error } = await ResultAsync.tryCatch(divideAsync(10, 2));
if (error) {
console.error("Async division failed:", error);
} else {
console.log("Result:", value); // Result: 5
}

// With custom error handling
const result = await ResultAsync.tryCatch(
divideAsync(10, 0),
(e) => Async division error: ${e.message}
);
if (result.isErr()) {
console.error(result.error); // Async division error: Cannot divide by zero
}
`

The tryCatch methods provide a more familiar error handling pattern for developers coming from languages like Go, while still maintaining the type safety and composability of the Result type.

⬆️ Back to top

---

$3

#### fromThrowable

Top level export of Result.fromThrowable.
Please find documentation at Result.fromThrowable

⬆️ Back to top

---

#### fromThrowableAsync

Top level export of ResultAsync.fromThrowable.
Please find documentation at ResultAsync.fromThrowable

⬆️ Back to top

---

#### fromPromise

Top level export of ResultAsync.fromPromise.
Please find documentation at ResultAsync.fromPromise

⬆️ Back to top

---

#### tryCatch

Top level export of Result.tryCatch.
Please find documentation at Result.tryCatch

⬆️ Back to top

---

#### tryCatchAsync

Top level export of ResultAsync.tryCatch.
Please find documentation at ResultAsync.tryCatch

⬆️ Back to top

#### fromSafePromise

Top level export of ResultAsync.fromSafePromise.
Please find documentation at ResultAsync.fromSafePromise

⬆️ Back to top


#### safeTry

Used to implicityly return errors and reduce boilerplate.

Let's say we are writing a function that returns a Result, and in that function we call some functions which also return Results and we check those results to see whether we shold keep going or abort. Usually, we will write like the following.
`typescript
declare function mayFail1(): Result;
declare function mayFail2(): Result;

function myFunc(): Result {
// We have to define a constant to hold the result to check and unwrap its value.
const result1 = mayFail1();
if (result1.isErr()) {
return err(aborted by an error from 1st function, ${result1.error});
}
const value1 = result1.value

// Again, we need to define a constant and then check and unwrap.
const result2 = mayFail2();
if (result2.isErr()) {
return err(aborted by an error from 2nd function, ${result2.error});
}
const value2 = result2.value

// And finally we return what we want to calculate
return ok(value1 + value2);
}
`
Basically, we need to define a constant for each result to check whether it's a Ok and read its .value or .error.

With safeTry, we can state 'Return here if its an Err, otherwise unwrap it here and keep going.' in just one expression.
`typescript
declare function mayFail1(): Result;
declare function mayFail2(): Result;

function myFunc(): Result {
return safeTry(function*() {
return ok(
// If the result of mayFail1().mapErr() is an Err, the evaluation is
// aborted here and the enclosing safeTry block is evaluated to that Err.
// Otherwise, this (yield* ...) is evaluated to its .value.
(yield* mayFail1()
.mapErr(e => aborted by an error from 1st function, ${e})
.safeUnwrap())
+
// The same as above.
(yield* mayFail2()
.mapErr(e => aborted by an error from 2nd function, ${e})
.safeUnwrap())
)
})
}
`

To use safeTry, the points are as follows.
Wrap the entire block in a generator function
In that block, you can use yield to state 'Return if it's an Err, otherwise evaluate to its .value'
* Pass the generator function to safeTry

You can also use async generator function to pass an async block to safeTry.
`typescript
// You can use either Promise or ResultAsync.
declare function mayFail1(): Promise>;
declare function mayFail2(): ResultAsync;

function myFunc(): Promise> {
return safeTry(async function*() {
return ok(
// You have to await if the expression is Promise
(yield* (await mayFail1())
.mapErr(e => aborted by an error from 1st function, ${e})
.safeUnwrap())
+
// You can call safeUnwrap directly if its ResultAsync
(yield* mayFail2()
.mapErr(e => aborted by an error from 2nd function, ${e})
.safeUnwrap())
)
})
}
`

For more information, see https://github.com/supermacro/neverthrow/pull/448 and https://github.com/supermacro/neverthrow/issues/444

⬆️ Back to top

---

$3

Result instances have two unsafe methods, aptly called _unsafeUnwrap and _unsafeUnwrapErr which should only be used in a test environment.

_unsafeUnwrap takes a Result and returns a T when the result is an Ok, otherwise it throws a custom object.

_unsafeUnwrapErr takes a Result and returns a E when the result is an Err, otherwise it throws a custom object.

That way you can do something like:

`typescript
expect(myResult._unsafeUnwrap()).toBe(someExpectation)
`

However, do note that Result instances are comparable. So you don't necessarily need to unwrap them in order to assert expectations in your tests. So you could also do something like this:

`typescript
import { ok } from 'resultar'

// ...

expect(callSomeFunctionThatReturnsAResult("with", "some", "args")).toEqual(ok(someExpectation));
`

By default, the thrown value does not contain a stack trace. This is because stack trace generation makes error messages in Jest harder to understand. If you want stack traces to be generated, call _unsafeUnwrap and / or _unsafeUnwrapErr with a config object:

`typescript
_unsafeUnwrapErr({
withStackTrace: true,
})

// ^ Now the error object will have a .stack property containing the current stack
``

---

$3

The resultar project is available as open source under the terms of the MIT license.