existence v1.1.0

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:

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:

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:

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):

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"