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/decorate")
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