future v2.3.1

Future

Creates a Future (aka Promise, Deferred, Subscription, Callback) object.

Installation

Node.JS (Server):

npm install future

Ender.JS (Browser):

ender build future

Usage

var context = { "foo": "bar" }
  , Future = require('future')
  , future = Future(context)
  , err
  , message = "Hello World!"
  ;

future.whenever(function (error, data) {
  if (error) {
    throw err;
  }
  console.log(this.foo + " says: " + data);
});

future.setTimeout(100);
future.deliver(err, message);

Output:

"bar says: Hello World"
FutureTimeout: timeout 100ms
    at [object SomeObject]:x:y
    ...

API

Core

• Futures.future(globalContext=null) - creates a Future object and uses globalContext as the default this for callbacks

• deliver(err, data, ...) - Send a message (data) to all listeners (callbacks)

• fulfill([err, data, ...]) - Prevent the sending of any future messages. If arguments are passed they will be delivered.

• whenever(callback, [context]) - Listen to all messages, applying context if provided (passing null cancels globalContext)

• when(callback, [context]) - Listen one-time only, then removeCallback automatically

• setTimeout(ms) - will sends a FutureTimeout error if no activity occurs within ms

Accessory

• errback(err) - Useful for a peer-library requiring a method specifically for errbacks

  • i.e. jQuery's $.ajax

• callback(data [, ...]) - Useful for a peer-library requiring a method which does not pass err as the first parameter

  • i.e. jQuery's $.ajax

• removeCallback(callback, context=null) - This callback and associated context will no longer receive messages

• setAsap(on=true) - New listeners get existing data (if available) rather than waiting until the next delivery (default on)

• isFuture(obj) - a best-effort guess as to whether or not an object is a Future

• callbackCount(callback, context) - The number of listening callbacks

• deliveryCount(callback, context) - The number of deliveries made

• hasCallback(callback, context=null) - Returns true if the callback is listening