Skip to content

Latest commit

 

History

History
659 lines (531 loc) · 13.5 KB

README.md

File metadata and controls

659 lines (531 loc) · 13.5 KB
Raw

result-type-ts

A modern TypeScript library for the so-called Result type.

Features

  • 0 dependencies
  • Provides many utility functions about the Result type
  • Well-tested
  • Works on both browsers and Node.js
  • Strict type inference

Usage

Here's a simple example of how to use this library:

import { Result } from 'result-type-ts'

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

if (result.isSuccess) {
  console.log(result.value) // 123
} else {
  console.log(result.error) // error
}

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
console.log(result.isSuccess) // true
console.log(result.isFailure) // false

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
console.log(result.isFailure) // true
console.log(result.isSuccess) // false

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>
Represents a successful result type with a payload of type T.

Example

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

Result.Failure<E>
Represents a failed result type with 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.flatMapAsync(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 async Result function.

Example

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

const result2 = await Result.failure('error').flatMapAsync(async (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(ctor)
Type <C extends abstract new (..._: any) => any>(ctor: C) => Result<T, InstanceType<C>>
Description Asserts that the error value is an instance of the given class. If the error value is not an instance of the given class, it 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