perchance
A simple maybe monad for JavaScript. Handle null
s and undefined
s more
gracefully with a maybe monad similar to functional languages like Haskell.
Install
$ npm install perchance
Usage
Perchance comes with three functions, maybe
, Just
, and Nothing
. You can
use these functions to create more functional code that avoids lots of if-else
checks for null
or undefined
. The real beauty of the maybe monad comes from
being able to wrap a value, apply transformations to it, and then unwrap the
final value whether it's a real value or null
or undefined
.
Just
Just
is a function that returns an internal _Just
object that wraps regular
values ike numbers, strings, objects, etc. The only two values that you can't
wrap are null
and undefined
. When you try to wrap them, you get back a
_Nothing
singleton instead. We'll see more of _Nothing
later below.
; ; // returns 84 ; // map in unwrap to return 'hello world!'
Nothing
Nothing
is a function that returns an internal singleton object _Nothing
.
_Nothing
acts as a placeholder for null
and undefined
but has the same API
as _Just
objects. This allows you to use OO-type functional code to deal with
null
s and undefined
s in your code without if-else checks.
The real power comes in the unwrap
method. The unwrap
method actually takes
two functions. The first function will only be invoked if the receiver is an
instance of _Just
. If the receiver is _Nothing
, then the second function
will be invoked. With the syntactical sugar of ES2015 arrow functions, this
allows you to write code close to pattern matching in functional languages.
Without the second function, unwrap
will throw an error on Nothing
.
; ; // return 'Got nothing' ; // throws an error
maybe
maybe
is a convenience function for wrapping values without using Just
or
Nothing
explicitly. As you might guess, if you wrap null
or undefined
with
maybe
, then you'll get back _Nothing
. Otherwise, you'll get back that value
wrapped with _Just
.
; const half = { if n % 2 === 0 return n / 2; return null;} ; // returns 2 ; // returns 'Could not halve integer'
API
maybe
: _Nothing: _Just<T>
Just
: _Nothing: _Just<T>
_Just#map
Transforms the wrapped value, returning a new instance of _Just
. If the
mapping function returns null
or undefined
, then it returns _Nothing
.
alias: fmap
_Just<T> #: _Just<U> _Just<T> #: _Nothing
_Just#ap
Applies a wrapped function to the wrapped value of another _Just
instance or a
no-op if passed _Nothing
.
alias: apply
_Just< U> #: _Nothing _Just< U> #: _Just<U>
_Just#bind
Takes a function that returns a _Just
or _Nothing
, applies that function to
the wrapped value, and returns a new _Just
with that wrapped value (or
_Nothing
if the function argument returned _Nothing
).
_Just<T> #: _Just<U> _Just<T> #: _Nothing
_Just#unwrap
Unwraps the inner value if no arguments are passed. Invokes and returns the return value of the first function argument otherwise, passing in the wrapped value to the function.
_Just<T> #: T _Just<T> #: U
Nothing
: _Nothing
_Nothing
methods
aliases:
method | alias name |
---|---|
map |
fmap |
ap |
apply |
_Nothing<T> #: _Nothing _Nothing< U> #: _Nothing _Nothing<T> #: _Nothing _Nothing<T> #: _Nothing
_Nothing#unwrap
Invokes and returns the return value of the second function argument. Throws an error if the second function argument is missing.
_Nothing<T> #: throws _Nothing<T> #: T