Value-result NPM

value-result

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

Result type from Elm.
Result type from Rust.

result type flow

@infinitebrahmanuniverse/nolb-valu @everything-registry/sub-chunk-3041 value-decoder

0.0.3

10 years ago

0.0.2

10 years ago

0.0.1

10 years ago