The Either(a, b) monad represents the logical disjunction between a and
b. In other words, Either may contain either a value of type a or a value
of type b, at any given time. This particular implementation is biased on the
right value (b), thus projections will take the right value over the left
one.
A common use of this monad is to represent computations that may fail, when you
want to provide additional information on the failure. This can force failures
and their handling to be explicit, and avoid the problems associated with
throwing exceptions — non locality, abnormal exits, etc.
Furthermore, being a monad, Either(a, b) can be composed in manners similar
to other monads, by using the generic sequencing and composition operations
provided for the common interface in Fantasy Land.
Example
var Either = require('data.either')
// + type: String -> Either(Error, String)
function read(path) {
return exists(path)? Either.Right(readFile(path))
: /* otherwise */ Either.Left(new Error(path + ' does not exist.'))
}
var intro = read('intro.json')
var outro = read('outro.json')
intro.map(function(a) {
outro.map(function(b) {
console.log(intro + outro)
}).orElse(logFailure)
}).orElse(logFailure)
Installing
The easiest way is to grab it from NPM. If you're running in a Browser
environment, you can use Browserify
The Either Monad
The
Either(a, b)
monad represents the logical disjunction betweena
andb
. In other words,Either
may contain either a value of typea
or a value of typeb
, at any given time. This particular implementation is biased on the right value (b
), thus projections will take the right value over the left one.A common use of this monad is to represent computations that may fail, when you want to provide additional information on the failure. This can force failures and their handling to be explicit, and avoid the problems associated with throwing exceptions — non locality, abnormal exits, etc.
Furthermore, being a monad,
Either(a, b)
can be composed in manners similar to other monads, by using the generic sequencing and composition operations provided for the common interface in Fantasy Land.Example
Installing
The easiest way is to grab it from NPM. If you're running in a Browser environment, you can use Browserify
Using with CommonJS
If you're not using NPM, Download the latest release, and require the
data.either.umd.js
file:Using with AMD
Download the latest release, and require the
data.either.umd.js
file:Using without modules
Download the latest release, and load the
data.either.umd.js
file. The properties are exposed in the globalfolktale.data.Either
object:Compiling from source
If you want to compile this library from the source, you'll need Git, Make, Node.js, and run the following commands:
This will generate the
dist/data.either.umd.js
file, which you can load in any JavaScript environment.Documentation
You can read the documentation online or build it yourself:
Then open the file
docs/literate/index.html
in your browser.Platform support
This library assumes an ES5 environment, but can be easily supported in ES3 platforms by the use of shims. Just include es5-shim :)
Licence
Copyright (c) 2013 Quildreen Motta.
Released under the MIT licence.