return-style

return-style

Non-intrusively convert the return value of any function or promise into the style that the user needs.

Install

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

API

[Error, Result]

Return tuple (Error, Result).

• function getErrorResult<X, T>(fn: () => T): [undefined, T] | [X, undefined]
• function getErrorResultAsync<X, T>(promise: PromiseLike<T>): Promise<[undefined, T] | [X, undefined]>

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

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

[Result, Error]

Return tuple (Result, Error).

• function getResultError<X, T>(fn: () => T): [T, undefined] | [undefined, X]
• function getResultErrorAsync<X, T>(promise: PromiseLike<T>): Promise<[T, undefined] | [undefined, X]>

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

const [ret, err] = await getResultErrorAsync(fnAsync())
const [ret] = await getResultErrorAsync(fnAsync())

[isSuccess, Result | Error]

Return tuple (isSuccess, Result | Error)

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

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

const [succ, ret] = await getSuccessAsync(fnAsync())

[isFailure, Result | Error]

Return tuple (isFailure, Result | Error)

• function getFailure<X, T>(fn: () => T): [false, T] | [true, X]
• function getFailureAsync<X, T>(promise: PromiseLike<T>): Promise<[false, T] | [true, X]>

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

const [fail, ret] = await getFailureAsync(fnAsync())

isSuccess

Return true when returning, false when throwing.

• function isSuccess(fn: () => unknown): boolean
• function isSuccessAsync(promise: PromiseLike<unknown>): Promise<boolean>

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

if (await isSuccessAsync(fnAsync())) {
  ...
}

isFailure

Return true when throwing, true when returning.

• function isFailure(fn: () => unknown): boolean
• function isFailureAsync(promise: PromiseLike<unknown>): Promise<boolean>

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

if (await isFailureAsync(fnAsync())) {
  ...
}

getError / getErrorAsync / getErrorAsyncIterable

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

• function getError<T>(fn: () => unknown): T | undefined
• function getErrorAsync<T>(promise: PromiseLike<unknown>): Promise<T | undefined>
• function getErrorAsyncIterable<T>(iterable: AsyncIterable<unknown>): Promise<T | undefined>

// 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)
})

Result: Ok / Err

• function getResult<T, X>(fn: () => T): Result<T, X>
• function getResultAsync<T, X>(promise: PromiseLike<T>): AsyncResult<T, X>

interface Result<T, X> {
  [Symbol.iterator](): Iterator<T>

  onOk(callback: (val: T) => void): Result<T, X>
  onErr(callback: (err: X) => void): Result<T, X>

  isOk(): boolean
  isErr(): boolean

  orElse<U>(defaultValue: U): Result<T | U, never>
  map<U>(mapper: (val: T) => U): Result<U, X>

  get(): T
}

interface AsyncResult<T, X> {
  [Symbol.asyncIterator](): AsyncIterator<T>

  onOk(callback: (val: T) => void): AsyncResult<T, X>
  onErr(callback: (err: X) => void): AsyncResult<T, X>

  isOk(): Promise<boolean>
  isErr(): Promise<boolean>

  orElse<U>(defaultValue: U): AsyncResult<T | U, never>
  map<U>(mapper: (val: T) => U): AsyncResult<U, X>

  get(): Promise<T>
}

Optional: Some / None

• function getOptional<T>(fn: () => T | U, isNone: (val: T) => boolean): Option<T>
• function getOptionalPartial<T>(isNone: (val: T) => boolean): (fn: () => T | U) => Option<T>
• function getOptionalAsync<T>(promise: PromiseLike<T>, isNone: (val: T) => boolean): AsyncOptional<T>
• function getOptionalAsyncPartial<T>(isNone: (val: T) => boolean): (promise: PromiseLike<T>) => AsyncOptional<T>

interface Optional<T> {
  [Symbol.iterator](): Iterator<T>

  onSome(callback: (val: T) => void): this
  onNone(callback: () => void): this

  isSome(): boolean
  isNone(): boolean

  orElse<U>(defaultValue: U): Optional<T | U>
  map<U>(mapper: (val: T) => U): Optional<U>
  filter<U extends T = T>(predicate: (val: T) => boolean): Optional<U>

  get(): T
}

interface AsyncOptional<T> {
  [Symbol.asyncIterator](): AsyncIterator<T>

  onSome(callback: (val: T) => void): this
  onNone(callback: () => void): this

  isSome(): Promise<boolean>
  isNone(): Promise<boolean>

  orElse<U>(defaultValue: U): AsyncOptional<T | U>
  map<U>(mapper: (val: T) => U): AsyncOptional<U>
  filter<U extends T = T>(predicate: (val: T) => boolean): AsyncOptional<U>

  get(): Promise<T>
}