result-type-ts

A TypeScript library for the Result<T, E> type, which is supported in modern languages like Rust, Swift, Kotlin.

Features

• 0 dependencies
• Provides many sophisticated functions, properties, and methods
• Well-tested
• Works on both browsers and Node.js
• Strict type inference

API

Functions

Result.success(value)

Type	<T>(value: T) => Result.Success<T>
Description	Creates a successful result.

Example

const result = Result.success(123)
console.log(result.value) // 123

Result.failure(error)

Type	<E>(error: E) => Result.Failure<E>
Description	Creates a failed result.

Example

const result = Result.failure('error')
console.log(result.error) // error

Result.tryCatch(f)

Type	<T>(f: () => T) => Result<T, unknown>
Description	If the given function returns a value, a successful result is created. If it throws an exception, a failed result is created.

Example

const result = Result.tryCatch(() => 123)
console.log(result.value) // 123

const result2 = Result.tryCatch(() => {
  throw 'error'
})
console.log(result2.error) // error

Result.fromNullish(value)

Type	<T>(value: T | null | undefined) => Result<T, null | undefined>
Description	Convert a nullish value to a Result value.

Example

const result = Result.fromNullish(123);
console.log(result.value) // 123

const result2 = Result.fromNullish(null);
console.log(result2.error) // null
console.log(result2.isFailure) // true

Result.fromPromise(promise)

Type	<T>(promise: PromiseLike<T>) => Promise<Result<T>>
Description	Convert a Promise value to a Result value.

Example

const result = await Result.fromPromise(Promise.resolve(123))
console.log(result.value) // 123

const result2 = await Result.fromPromise(Promise.reject('error'))
console.log(result2.error) // error

Result.all(results)

Type	<T, E>(results: Result<T, E>[]) => Result<T[], E>
Description	Converts an array of Results into a single Result. If all results are successful, it returns a successful result of an array of values. Otherwise, it returns the first failed result.

Example

const result = await Result.all([Result.success(123), Result.success(456)])
console.log(result.value) // 123

const result2 = await Result.all([Result.success(123), Result.failure('error')])
console.log(result2.error) // error

const result3 = await Result.all([Result.failure('error'), Result.failure('error2')])
console.log(result3.error) // error

Types

Result.Success<T>

The type of a successful result holding a value of type T.

Example

const result: Result.Success<number> = Result.success(123)

Result.Failure<E>

The type of a failed result holding an error value of type E.

Example

const result: Result.Failure<string> = Result.failure('error')

Result<T, E>

Shorthand for Result.Success<T> | Result.Failure<E> type. E is optional with a default value of unknown.

Example

const result: Result<number, string> = Math.random() > 0.5 ? Result.success(123) : Result.failure('error')

Properties

result.value

Type	T | undefined
Description	The payload of the successful result. If the result is a failure, it's undefined.

Example

const result = Result.success(123)
console.log(result.value) // 123

const result2 = Result.failure('error')
console.log(result2.value) // undefined

result.error

Type	E | undefined
Description	The payload of the failed result.

Example

const result = Result.success(123)
console.log(result.error) // undefined

const result2 = Result.failure('error')
console.log(result2.error) // error

result.isSuccess

Type	boolean
Description	Whether it is a successful result.

Example

const result = Result.success(123)
console.log(result.isSuccess) // true

const result2 = Result.failure('error')
console.log(result2.isSuccess) // false

result.isFailure

Type	boolean
Description	Whether it is a failed result.

Example

const result = Result.success(123)
console.log(result.isFailure) // false

const result2 = Result.failure('error')
console.log(result2.isFailure) // true

Methods

result.getOrThrow()

Type	() => T
Description	Returns this.value if it's a successful result, otherwise throws this.error.

Example

const result = Result.success(123)
console.log(result.getOrThrow()) // 123

const result2 = Result.failure('error')
try {
  result2.getOrThrow()
} catch (e) {
  console.log(e) // error
}

result.toUnion()

Type	() => T | E
Description	Returns the payload of the result value.

Example

const result = Result.success(123)
console.log(result.toUnion()) // 123

const result2 = Result.failure('error')
console.log(result2.toUnion()) // error

result.ifSuccess(f)

Type	<T2>(f: (value: T) => T2) => T2 | undefined
Description	Applies the given function to this.value if it's a successful result, otherwise returns undefined.

Example

const result = Result.success(123)
console.log(result.ifSuccess((value) => value * 2)) // 246

const result2 = Result.failure('error')
console.log(result2.ifSuccess((value) => value * 2)) // undefined

result.ifFailure(f)

Type	<E2>(f: (error: E) => E2) => E2 | undefined
Description	Applies the given function to result.error if it's a failed result, otherwise returns undefined.

Example

const result = Result.success(123)
console.log(result.ifFailure((error) => error + '!')) // undefined

const result2 = Result.failure('error')
console.log(result2.ifFailure((error) => error + '!')) // error!

result.match(f, g)

Type	<T2, E2>((value: T) => T2, (error: E) => E2) => T2 | E2
Description	Return the result of applying one of the given functions to the payload.

Example

const result = Result.success(123)
console.log(result.match((value) => value * 2, (error) => error + '!')) // 246

const result2 = Result.failure('error')
console.log(result2.match((value) => value * 2, (error) => error + '!')) // error!

result.map(f)

Type	<T2>(f: (value: T) => T2) => Result<T2, E>
Description	Creates a Result value by modifying the payload of the successful result using the given function

Example

const result = Result.success(123).map((value) => value * 2)
console.log(result.value) // 246

const result2 = Result.failure('error').map((value) => value * 2)
console.log(result2.error) // error

result.mapError(f)

Type	<E2>(f: (error: E) => E2) => Result<T, E2>
Description	Creates a Result value by modifying the payload of the failed result using the given function

Example

const result = Result.success(123).mapError((error) => error + '!')
console.log(result.value) // 123

const result2 = Result.failure('error').mapError((error) => error + '!')
console.log(result2.error) // error!

result.flatMap(f)

Type	<T2, E2>(f: (value: T) => Result<T2, E2>) => Result<T2, E | E2>
Description	Maps the payload of the successful result and flattens the nested Result type.

Example

const result = Result.success(123).flatMap((value) => Result.success(value * 2))
console.log(result.value) // 246

const result2 = Result.failure('error').flatMap((value) => Result.failure(value * 2))
console.log(result2.error) // error

result.flatten()

Type	() => Result<T, E | E2>
Description	Flattens the nested Result type. For instance, it converts Result<Result<T, E>, E2> into Result<T, E | E2>.

Example

const result = Result.success(Result.success(123)).flatten()
console.log(result.value) // 246

const result2 = Result.success(Result.failure('error')).flatten()
console.log(result2.error) // error

const result3 = Result.failure('error').flatten()
console.log(result3.error) // error

result.assertErrorInstanceOf(constructor)

Type	<C extends abstract new (..._: any) => any>(constructor: C) => Result<T, InstanceType<C>>
Description	Perform a safe cast of the error type to the given class. If the payload of the failed result is not instance of constructor, throws TypeError

Example

const result: Result<number, Error> = Result.tryCatch(() => {
  if (Math.random() >= 0) {
    throw new Error('error')
  } else {
    return 123
  }
}).assertErrorInstanceOf(Error)
console.log(result.isFailure && result.error.message) // error