return-style

Non-intrusively convert the result of any function or promise to the user's desired style.

Install

npm install --save return-style
# or
yarn add return-style

API

All functions whose names are suffixed with Async can handle synchronous errors. If you only need to catch asynchronous errors, use functions with the suffix Promise.

isSuccess

function isSuccess(fn: () => unknown): boolean
function isSuccessAsync(fn: () => Awaitable): Promise
function isSuccessPromise(promise: PromiseLike): Promise

Return true when returning, false when throwing.

if (isSuccess(() => fn())) {
  ...
}

if (await isSuccessAsync(() => asyncFn())) {
  ...
}

if (await isSuccessPromise(promise)) {
  ...
}

isFailure

function isFailure(fn: () => unknown): boolean
function isFailureAsync(fn: () => Awaitable): Promise
function isFailurePromise(promise: PromiseLike): Promise

Return true when throwing, true when returning.

if (isFailure(() => fn())) {
  ...
}

if (await isFailureAsync(() => asyncFn())) {
  ...
}

if (await isFailurePromise(promise)) {
  ...
}

getResult

function getResult(fn: () => T): T | undefined
function getResultAsync(fn: () => Awaitable): Promise
function getResultPromise(promise: PromiseLike): Promise

const result = getResult(() => fn())
if (result) {
  ...
}

const result = await getResultAsync(() => asyncFn())
if (result) {
  ...
}

const result = await getResultPromise(promise)
if (result) {
  ...
}

getError

function getError(fn: () => unknown): E | undefined
function getErrorAsync(fn: () => Awaitable): Promise
function getErrorPromise(promise: PromiseLike): Promise
function getErrorAsyncIterable(iterable: AsyncIterable): Promise

Designed for testing, helping to achieve Arrange-Act-Assert pattern.

// BAD: try...catch
test('divided by zero', () => {
  expect.hasAssertions()

  const calc = createCalculator()

  try {
    calc.eval('1 / 0')
  } catch (err) {
    expect(err).toInstanceOf(Error)
  }
})

// BAD: toThrow
test('divided by zero', () => {
  const calc = createCalculator()

  expect(() => calc.eval('1 / 0')).toThrow(Error)
})

// GOOD: Arrange, Act, Assert
test('divided by zero', () => {
  const calc = createCalculator()

  const err = getError(() => calc.eval('1 / 0'))

  expect(err).toInstanceOf(Error)
})

Tuple / Go-like

Since modern JavaScript does not advocate repeated declarations of variables (var), this style can sometimes be difficult to use.

[Error, Result]

function getErrorResult(fn: () => T): [undefined, T] | [E, undefined]
function getErrorResultAsync(fn: () => Awaitable): Promise<[undefined, T] | [E, undefined]>
function getErrorResultPromise(promise: PromiseLike): Promise<[undefined, T] | [E, undefined]>

Return tuple (Error, Result).

const [err, ret] = getErrorResult(() => fn())
const [err] = getErrorResult(() => fn())

const [err, ret] = await getErrorResultAsync(() => fnAsync())
const [err] = await getErrorResultAsync(() => fnAsync())

const [err, ret] = await getErrorResultAsync(promise)
const [err] = await getErrorResultAsync(promise)

[Result, Error]

function getResultError(fn: () => T): [T, undefined] | [undefined, E]
function getResultErrorAsync(fn: () => Awaitable): Promise<[T, undefined] | [undefined, E]>
function getResultErrorPromise(promise: PromiseLike): Promise<[T, undefined] | [undefined, E]>

Return tuple (Result, Error).

const [ret, err] = getResultError(() => fn())
const [ret] = getResultError(() => fn())

const [ret, err] = await getResultErrorAsync(() => fn())
const [ret] = await getResultErrorAsync(() => fn())

const [ret, err] = await getResultErrorPromise(promise)
const [ret] = await getResultErrorPromise(promise)

[isSuccess, Result | undefined]

function getSuccess(fn: () => T): [true, T] | [false, undefined]
function getSuccessAsync(fn: () => Awaitable): Promise<[true, T] | [false, undefined]>
function getSuccessPromise(promise: PromiseLike): Promise<[true, T] | [false, undefined]>

Return tuple (isSuccess, Result | undefined)

const [succ, ret] = getSuccess(() => fn())

const [succ, ret] = await getSuccessAsync(() => asyncFn())

const [succ, ret] = await getSuccessPromise(promise)

[isFailure, Error | undefined]

function getFailure(fn: () => unknown): [true, E] | [false, undefined]
function getFailureAsync(fn: () => Awaitable): Promise<[true, E] | [false, undefined]>
function getFailurePromise(promise: PromiseLike): Promise<[true, E] | [false, undefined]>

Return tuple (isFailure, Error | undefined)

const [fail, ret] = getFailure(() => fn())

const [fail, ret] = await getFailureAsync(() => asyncFn())

const [fail, ret] = await getFailurePromise(promise)

ADT / Rust-like / Haskell-like

Result = Ok | Err

function toResult(fn: () => T): Result
function toResultAsync(fn: () => Awaitable): Promise>
function toResultPromise(promise: PromiseLike): Promise>

Result is designed according to Rust's enumeration of the same name, please refer to the relevant documentation.

class Result {
  static Ok(val: T) => Result
  static Err(err: E) => Result

  isOk(): boolean
  isErr(): boolean

  map<u>(mapper: (val: T) =&gt; U): Result
  mapOr<u>(defaultValue: U, mapper: (val: T) =&gt; U): Result
  mapOrElse<u>(createDefaultValue: (err: E) =&gt; U, mapper: (val: T) =&gt; U): Result
  mapErr<u>(mapper: (err: E) =&gt; U): Result

  /**
   * @throws {E}
   */
  unwrap(): T

  unwrapOr<u>(defaultValue: U): T | U
  unwrapOrElse<u>(createDefaultValue: (err: E) =&gt; U): T | U

  /**
   * @throws {Error}
   */
  unwrapErr(): E

  /**
   * @throws {Error}
   */
  expect(message: string): T

  /**
   * @throws {Error}
   */
  expectErr(message: string): E

  ok(): Option
  err(): Option
}

Option = Some | None

function toOption(fn: () => T): Option
function toOptionAsync(fn: () => Awaitable): Promise>
function toOptionPromise(promise: PromiseLike): Promise>

Option is designed according to Rust's enumeration of the same name, please refer to the relevant documentation.

class Option {
  static Some(val: T) => Option
  static None() => Option

  isSome(): boolean
  isNone(): boolean

  map<u>(mapper: (val: T) =&gt; U): Option<u>
  mapOr<u>(defaultValue: U, mapper: (val: T) =&gt; U): Option<u>
  mapOrElse<u>(createDefaultValue: () =&gt; U, mapper: (val: T) =&gt; U): Option<u>

  filter<u>(predicate: (val: T) =&gt; boolean): Option<u>

  /**
   * @throws {Error}
   */
  unwrap(): T

  unwrapOr<u>(defaultValue: U): T | U
  unwrapOrElse<u>(createDefaultValue: () =&gt; U): T | U

  /**
   * @throws {Error}
   */
  expect(message: string): T

  okOr(err: E): Result
  okOrElse(createErr: () =&gt; E): Result
}
```</u></u></u></u></u></u></u></u></u></u></u></u></u></u></u></u>