data.either

    1.5.2 • Public • Published

    Data.Either

    Build Status NPM version Dependencies Status stable

    The Either(a, b) structure 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 structure 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

    // Returns the contents of the file at `path`, if it exists.
    //
    //  read : String -> Either(Error, String)
    function read(path) {
      return exists(path)?     Either.Right(fread(path))
      :      /* otherwise */   Either.Left("Non-existing file: " + path)
    }
     
    var intro = read('intro.txt')  // => Right(...)
    var outro = read('outro.txt')  // => Right(...)
    var nope  = read('nope.txt')   // => Left("Non-existing file: nope.txt")
     
    // We can concatenate things without knowing if they exist at all, and
    // failures are handled for us
    intro.chain(function(a) {
      return outro.map(function(b) {
        return a + b
      })
    }).orElse(logFailure)
    // => Right(...)
     
    intro.chain(function(a) {
      return nope.map(function(b) {
        return a + b
      })
    })
    // => Left("Non-existing file: nope.txt")

    Installing

    The easiest way is to grab it from NPM. If you're running in a Browser environment, you can use Browserify

    $ npm install data.either
    

    Using with CommonJS

    If you're not using NPM, Download the latest release, and require the data.either.umd.js file:

    var Either = require('data.either')

    Using with AMD

    Download the latest release, and require the data.either.umd.js file:

    require(['data.either'], function(Either) {
      ( ... )
    })

    Using without modules

    Download the latest release, and load the data.either.umd.js file. The properties are exposed in the global folktale.data.Either object:

    <script src="/path/to/data.either.umd.js"></script>

    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:

    $ git clone git://github.com/folktale/data.either.git
    $ cd data.either
    $ npm install
    $ make bundle
    

    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:

    $ git clone git://github.com/folktale/data.either.git
    $ cd data.either
    $ npm install
    $ make documentation
    

    Then open the file docs/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.

    Install

    npm i data.either

    DownloadsWeekly Downloads

    15,405

    Version

    1.5.2

    License

    MIT

    Unpacked Size

    34.7 kB

    Total Files

    15

    Last publish

    Collaborators

    • killdream
    • robotlolita