value-result

Library for managing results of computation that may fail

Usage no npm install needed!

<script type="module">
  import valueResult from 'https://cdn.skypack.dev/value-result';
</script>

README

value-result NPM version Build Status

This library provides facilities for managing Results. A Result is a data value representing result of a computation that may fail.

Result<error, value> is the type used for returning and propagating errors. It is either Ok<value>, representing success and containing a value or an Error<error>, representing error and containing an error value.

Result is a handy for representing results of computations that may fail, most prominently used for I/O.

Mapping

map

map can be used to apply a function to a result. If the result is Ok, it will be converted. If the result is an Error, the same error value will propagate through.

Result.map(parseInt, Result.ok('17')) // => Ok(17)
Result
  .ok('17')
  .map(parseInt) // => Ok(17)

Result.map(parseInt, Result.error('Bad input')) // Error('Bad input')
Result
  .error('Bad input')
  .map(parseInt) // Error('Bad input')

map2

Apply a function to two results, if both results are Ok. If not, the first argument which is an Error will propagate through.

Result.map2
( (x, y) => x + y
, Result.ok(1)
, Result.ok(2)
) // => Ok(3)

Result.map2
( (x, y) => x + y
, Result.ok(1)
, Result.error('NaN')
) // => Error('NaN')

Result.map2
( (x, y) => x + y
, Result.error('Boom')
, Result.ok(2)
) // => Error('Boom')

Result.map2
( (x, y) => x + y
, Result.error('Boom')
, Result.error('NaN')
) // => Error('Boom')

map3

Apply a function to three results, if all results are Ok. If not, the first result that is Error will propagate through.

Result.map3
( (a, b, c) => a + b + c
, Result.ok(1)
, Result.ok(2)
, Result.ok(10)
) // => Ok(13)

Result.map3
( (a, b, c) => a + b + c
, Result.ok(1)
, Result.error('NaN')
, Result.ok(10)
) // => Error('NaN')

Result.map3
( (a, b, c) => a + b + c
, Result.error('Boom')
, Result.ok(2)
, Result.ok(10)
) // => Error('Boom')

Result.map3
( (a, b, c) => a + b + c
, Result.error('Boom')
, Result.error('NaN')
, Result.ok(10)
) // => Error('Boom')


Result.map3
( (a, b, c) => a + b + c
, Result.ok(2)
, Result.ok(10)
, Result.error('Oops')
) // => Error('Oops')

map4

Apply a function to four results, if all results are Ok. If not, the first result that is Error will propagate through.

Result.map4
( (a, b, c, d) => a + b + c + d
, Result.ok(1)
, Result.ok(2)
, Result.ok(10)
, Result.ok(7)
) // => Ok(20)

Result.map4
( (a, b, c, d) => a + b + c + d
, Result.ok(1)
, Result.ok(2)
, Result.error('Oops')
, Result.ok(7)
) // => Error('Oops')

Result.map4
( (a, b, c, d) => a + b + c + d
, Result.ok(1)
, Result.ok(2)
, Result.ok(7)
, Result.error('Oops')
) // => Error('Oops')


Result.map4
( (a, b, c, d) => a + b + c + d
, Result.ok(1)
, Result.error('Oops')
, Result.ok(2)
, Result.error('Boom')
) // => Error('Oops')

map5

Apply a function to five results, if all results are Ok. If not, the first result that is Error will propagate through.

Result.map5
( (a, b, c, d, e) => a + b + c + d + e
, Result.ok(1)
, Result.ok(2)
, Result.ok(10)
, Result.ok(7)
, Result.ok(3)
) // => Ok(23)

Result.map5
( (a, b, c, d, e) => a + b + c + d + e
, Result.ok(1)
, Result.ok(2)
, Result.error('Oops')
, Result.ok(7)
, Result.ok(3)
) // => Error('Oops')

Result.map5
( (a, b, c, d, e) => a + b + c + d + e
, Result.ok(1)
, Result.ok(2)
, Result.ok(7)
, Result.ok(3)
, Result.error('Oops')
) // => Error('Oops')


Result.map5
( (a, b, c, d, e) => a + b + c + d + e
, Result.ok(1)
, Result.error('Oops')
, Result.ok(2)
, Result.error('Boom')
, Result.ok(7)
) // => Error('Oops')

Chaining

chain

chain can be used to chain together a sequence of computations that may fail.

const toValidMonth = month =>
  ( (month >= 1 && month <= 12)
  ? Result.ok(month)
  : Result.error("months must be between 1 and 12")
  )

const toInt = text => {
  const int = parseInt(text, 10)
  const result =
    ( (int | 0) === int
    ? Result.ok(int)
    : Result.error('Is not an Integer')
    )
  return result
}

Result.chain(toInt("9"), toValidMonth) // Ok(9)
toInt("4")
  .chain(toValidMonth) // => Ok(4)

toInt("a")
  .chain(toValidMonth) // => Error('Is not an Integer')

toInt("0")
  .chain(toValidMonth) // => Error('months must be between 1 and 12')

Handling Errors

withDefault

withDefault can be used to extract the potential Ok value from the Result. But since Result maybe be an Error you need to provide a default value to be returned instead for such cases:

Result.withDefault(0, toInt("123")) // => 123
toInt("abc")
  .withDefault(0) // => 0

format Format the error value of a result. If the result is Ok, it stays exactly the same, but if the result is an Err we will format the error. For example, say the errors we get have too much information:

format

format lets format the error value of a result. If the result is Ok, it stays exactly the same, but if the result is an Error it will format the error. For example, say the errors we get have too much information:

const readInt = input => {
  const match = input.match(/[^\d]/);
  const result =
    ( match == null
    ? Result.ok(parseInt(input))
    : Result.error({
        message: `Character "${match[0]}" is not a number`,
        character: match[0],
        position: match.index
      })
    )
  return result
}

const toMessage = error =>
  error.message;

Result.format(toMessage, readInt("123")) // => Ok(123)
readInt("1234")
  .format(toMessage) // => Ok(1234)

readInt("abc")
  .format(toMessage) // => Error('Character "a" is not a number')

capture

capture can be used to control flow based on result values:

const square = x => Result.ok(x * x)
const fail = x => Result.error(x - 10)

Result
  .ok(2)
  .capture(square)
  .capture(square) // => Ok(2)

Result
  .ok(2)
  .capture(fail)
  .capture(square) // => Ok(2)

Result
  .error(3)
  .capture(square)
  .capture(fail) // => Ok(9)

Result
  .error(3)
  .capture(fail)
  .capture(fail) // => Error(-17)

Other

and

Returns right result if the left result is Ok, otherwise returns the Error value of the left.

const two = Result.ok(2)
const late = Result.error("Late error")

two.and(late) // => Error('Late error')
Result.and(two, late) // => Error('Late error')

const early = Result.error("Early error")

early.and(two) // => Error('Early error')
Result.and(early, two) // => Error('Early error')

early.and(late) // => Error('Early error')
Result.and(early, late) // => Error('Early error')

const other = Result.ok("Another")

two.and(other) // => Ok("Another")
Result.and(two, other) // => Ok("Another")

or

Returns right if the result is Error, otherwise returns the Ok value of the left.

const two = Result.ok(2)
const late = Result.error("Late error")

two.or(late) // => Ok(2)
Result.or(two, late) // => Ok(2)

const early = Result.error("Early error")

early.or(two) // => Ok(2)
Result.or(early, two) // => Ok(2)

early.or(late) // => Error('Late error')
Result.or(early, late) // => Error('Late error')

const other = Result.ok("Another")
two.or(other) // => Ok(2)
Result.or(two, other) // => Ok(2)

Install

npm install value-result

Prior art