neverthrow

safeTry allows you to write complex logic involving multiple Result or ResultAsync returns using generator functions, avoiding repetitive manual error checks and unwrapping.

Usage Pattern:

1. Wrap your logic in a generator function or async generator function.
2. Use yield* <RESULT> to indicate: 'If this is an Err, return it immediately from the safeTry block; otherwise, unwrap it to its value.'
3. If using Promise<Result>, you must await the promise before using yield*.
4. If using ResultAsync, you can use yield* directly.

declare function mayFail1(): Promise<Result<number, string>>;
declare function mayFail2(): ResultAsync<number, string>;

function myFunc(): Promise<Result<number, string>> {
    return safeTry<number, string>(async function*() {
        return ok(
            (yield* (await mayFail1())
                .mapErr(e => `aborted by an error from 1st function, ${e}`))
            +
            (yield* mayFail2()
                .mapErr(e => `aborted by an error from 2nd function, ${e}`))
        )
    })
}

Use mapErr to transform the contained Err value of a ResultAsync<T, E> into a new error type F. The transformation function can be synchronous or asynchronous. If the ResultAsync is an Ok, the value remains untouched. This is useful for converting low-level errors into more readable or domain-specific error messages.

import { findUsersIn } from 'imaginary-database'
// assume findUsersIn(country: string): ResultAsync<Array<User>, Error>

const usersInCanada = findUsersIn("Canada").mapErr((error: Error) => {
  if(error.message === "Unknown country"){
    return error.message
  }
  return "System error, please contact an administrator."
})

// usersInCanada is of type ResultAsync<Array<User>, string>

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

Use Result.combine to merge a list of Results into a single Result.

• Behavior: It works like Promise.all. If all results are Ok, it returns an Ok containing a list (or tuple) of all values. If any result is an Err, it short-circuits and returns the first Err encountered.
• Compatibility: Supports both homogeneous (same type) and heterogeneous (different types) lists.
• Constraint: You cannot combine a list containing both Result and ResultAsync types.

// Homogeneous list
const resultList: Result<number, never>[] = [ok(1), ok(2)]
const combinedList: Result<number[], unknown> = Result.combine(resultList)

// Heterogeneous list (tuples)
const tuple = <T extends any[]>(...args: T): T => args
const resultTuple: [Result<string, never>, Result<string, never>] = tuple(ok('a'), ok('b'))
const combinedTuple: Result<[string, string], unknown> = Result.combine(resultTuple)

Use andThen to sequence operations where the next step depends on the success of the previous one and might also fail. The callback must return a Result or ResultAsync. andThen flattens nested results, turning a ResultAsync<ResultAsync<A, E2>, E1> into a ResultAsync<A, E2>.

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

// assume signatures:
// validateUser(user: User): Result<User, Error>
// insertUser(user): ResultAsync<User, Error>
// sendNotification(user): ResultAsync<void, Error>

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

// resAsync is a ResultAsync<void, Error>

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