node package manager


Abstraction for eventual values


Build Status

This library defines abstraction for eventual values & data type implementing this abstraction. This abstraction is identical to promises in their intent and could be even called promises. Although API and behavior has subtle differences from popular Promises/A specification there for different name was chosen.

Main intent of the eventual abstraction is to represent eventual values, ones that functions need to compute asynchronously and there for can not be returned. Returning from functions is important, this enables us to form programs units in form of black boxes defining data transformation flow between input and output.


when module exports polymorphic function that is implemented by eventual data type. It maybe used to track pending eventual's realization. It also comes with default implementation that calls onRealize handler with a value it's called with, unless it's type of error. For Error values when is defined differently, error values are treated as rejections and onError handler is called. This is one of the key differences from the typical promise API. Another difference is that if value passed to when is not pending, return of onRealize called with values realization is returned, instead of eventual.

var when = require("eventual/when")
when(1)                                         // => 1 
when(2, function(x) { return x + 1 })           // => 3 
when(Error("boom"), console.log, console.error) // => error: boom 


defer module exports function that may be used to make pending eventual value that later can be delivered.

var defer = require("eventual/defer")
var deliver = require("pending/deliver")
var foo = defer()
deliver(foo, 3)
when(foo)   // => 3 
var bar = defer()
var baz = defer()
deliver(bar, baz)
deliver(baz, 2)
when(bar)  // => 2 


apply module exports function that can be used with eventual values, it treats each of it's arguments as eventual value and returns a fresh one in return. Once all of the arguments are realized first one is invoked with rest ones and return value is delivered to the resulting eventual. If everything happens synchronously actual value is returned.

var apply = require("eventual/apply")
var defer = require("eventual/defer")
var deliver = require("pending/deliver")
function sum(x y) { return x + y }
var x = defer()
var y = apply(sum, x, 3)
deliver(x, 2)
when(y)       // => 5 


decorate module exports function that can be used to compose functions which take eventual values as arguments, and returns eventual realized with result of applying realization values of eventuals to a decorated f. If result is delivered in sync realization value is returned instead.

var eventual = require("eventual/apply")
var defer = require("eventual/defer")
var deliver = require("pending/deliver")
var sum = eventual(function(x y) { return x + y })
var x = defer()
var y = defer()
var xy = sum(x, y)
deliver(x, 2)
deliver(y, 3)
when(xy)       // => 5 
sum(2, 2)      // => 4 
sum(x, 1)      // => 3 


recover module exports function that allows one to recover from an error if eventual value happen to be rejected. It renturns an eventual that is either equivalent of given one or is realized to return value of the recovery function, invoked with a rejection error.

var recover = require("eventual/recover")
var defer = require("eventual/defer")
var deliver = require("pending/deliver")
var when = require("eventual/when")
var p1 = defer()
deliver(p1, Error("boom"))
var p2 = recover(p1, function() { return "np" })
when(p2)    // => np 
var v1 = defer()
deliver(v1, "bye")
var v2 = recover(v1, function() { return "np" })
when(v2)    // => bye 


group module exports function that takes array of eventual values and return single eventual value that is relized to an array of delivery values for those eventuals. If any of the eventuals is rejeceted with error, result is rejected with it too.

var group = require("eventual/group")
var a = defer()
var b = defer()
var c = defer()
var abc = group([ a, b, c ])
deliver(a, 1)
deliver(b, 2)
deliver(c, 3)
when(abc)  // => [ 1, 2, 3 ] 


type module exports function representing data type of eventual values. Type implements watchables, pending and eventual abstractions, where first two are defined in an external libraries.


npm install eventual