Value-maybe NPM

value-maybe

This library provides facilities for managing optionals - situations where a value may be absent. Meaning:

There is a value, and it equals x.

There isn’t a value at all

In JS optionals (null and undefined) are ubiquitous and there for flow type checker takes a creative approach (thas is very similar to Swift's) at defining maybe type (as found in many functional languages) for handling optionals.

This library take's flow's definition of "Maybe" type and provides implementations for set APIs typically available for values of maybe type.

Definition

`just` / `nothing`

You can think of optional values as just(x) or nothing() and that is why library exports just & nothing functions. Their existence is purely symbolic and serves nothing else but to communicate optional type of the value:

Maybe.just(5) // => 5
Maybe.nothing() // => null

P.S: Obviously you could have used 5 and null (or undefined) instead.

`isJust` / `isNothing`

Maybe.isJust(null) // => false
Maybe.isJust(undefined) // => false
Maybe.isJust(0) // => true

Maybe.isNothing(null) // => true
Maybe.isNothing(undefined) // => true
Maybe.isNothing(0) // => false

`withDefault`

withDefault can be used to cast optional value into a guaranteed value by providing a default in case value is absent.

Maybe.withDefault(100, Maybe.just(42)) // => 42
Maybe.withDefault(100, Maybe.nothing()) // => 100

`map`

map can be used to apply a function to optional value if it is available one. If value is Nothing, it will just propagate through:

Maybe.map(x => x + 1, Maybe.nothing()) // => null
Maybe.map(x => x + 1, null) // => null
Maybe.map(x => x + 1, Maybe.just(5)) // => 6
Maybe.map(text => text.toUpperCase(), 'hello') // => 'HELLO'

`oneOf`

oneOf maybe used to pick the first maybe that actually has a value. Useful when you want to try a couple different things, but there is no default value:

Maybe.oneOf([ Maybe.nothing(), Maybe.just(42), Maybe.just(71) ]) // =>  42
Maybe.oneOf([ Maybe.nothing(), Maybe.nothing(), Maybe.just(71) ]) // => 71
Maybe.oneOf([ Maybe.nothing(), Maybe.nothing(), Maybe.nothing() ]) // => null

`chain`

chain can be used to chain together multiple computations that return optional value:

const readField = (name/*:string*/, tree/*:{}*/) =>
  ( tree[name] == null
  ? Maybe.nothing()
  : Maybe.just(tree[name])
  )

const readPath = ([first, ...rest], tree) =>
  ( rest.length === 0
  ? readField(first, tree)
  : Maybe.chain
    ( readField(first, tree)
    , branch => readPath(rest, branch)
    )
  )

readPath
  ( ["Users", "gozala", "Documents"]
  , {"Users": {"gozala": {"Documents": ["maybe.js"]}}}
  ); // => ["maybe.js"]

readPath
  ( ["Users", "Dave", "stuff"]
  , {"Users": {"gozala": {"Documents": ["maybe.js"]}}}
  ); // => null