existence

Existence
=========


Fantasy Land Compliant!

Indigenous Complaint!

A monadic wrapper around values that may or may not exist. Inspired by
Scala's Option monad. Unlike Scala's implementation, we have a really
small interface and we purposefully don't implement Existence#get().

The problem with Existence#get() is it lets you side step the contextual
bounds by unsafely detaching the value from the context. This results in
the same NPE try/catch soup that Option is intended to avoid.

Examples
--------

Monoid concatenation example:
``javascript
var Some = require("existence/some");
var None = require("existence/none");

var list = [new Some([1, 2, 3]), new None(), new Some([4, 5, 6])];
var added = list.reduce(function(memo, item) {
return memo.concat(item);
});

console.log("value: " + JSON.stringify(filtered.getOrDefault([])));
// prints "value: [1, 2, 3, 4, 5, 6]"
`

Functor composition example:
`javascript
var Some = require("existence/some");
var None = require("existence/none");

var some = new Some(21);
var answer = some.map(function(n) {
return n * 2;
});
console.log("value: " + answer.getOrDefault("None"));
// prints "value: 42"

var none = new None();
var nada = none.map(function(n) {
return n * 2;
});
console.log("exists = " + nada.exists());
// prints "exists = false"
`

Applicative composition example:
`javascript
var Existence = require("existence");
var Some = require("existence/some");
var None = require("existence/none");
var curry = require("lodash").curry;

var someNumber = new Some(42);
var someString = new Some("beep");
var someBoolean = new Some(true);
var none = new None();

var lifted = Existence.of(curry(function(a, b, c) {
return a + " - " + b + " - " + c;
}));

var allThere = lifted.ap(someNumber).ap(someString).ap(someBoolean);
console.log("value: " + answer.getOrDefault("None"));
// prints "value: 42 - beep - true"

var missing = lifted.ap(someNumber).ap(none).ap(someBoolean);
console.log("value: " + answer.getOrDefault("None"));
// prints "value: None"

`

Monadic composition (flatMap / chain) example (flatMap is an alias for chain):
`javascript
var Some = require("existence/some");
var None = require("existence/none");

var value = new Some(42);
var filtered = value.flatMap(function(n) {
return (n % 1 == 0) ? new Some(n)
: new None()
});

console.log("value: " + filtered.getOrDefault("value was not even"));
// prints "value: 42"
``