RingoJS

Module ringo/promise

Allows to work with deferred values that will be resolved in the future.

Class Deferred

Instance Methods

Instance Properties

Class Promise

Instance Methods

Class PromiseList


Deferred ()

Creates an object representing a deferred value. The deferred object has two properties: a promise object and a resolve() function.

The promise object can be used to register a callback to be invoked when the promise is eventually resolved.

The resolve function is used to resolve the promise as either fulfilled or failed.

Example

// --- sample output ---
// getDeferredValue() ...
// getDeferredValue() finished after 396 ms
// Resolved promise, got foo
// Total time:  2400 ms

const getDeferredValue = function () {
  const deferred = new Deferred();
  setTimeout(function() {
    deferred.resolve("foo");
  }, 2000);

  return deferred;
};

const start = Date.now();
console.log("getDeferredValue() ... ");

const def = getDeferredValue();
console.log("getDeferredValue() finished after",
  Date.now() - start, "ms");

def.promise.then(function(value) {
  console.log("Resolved promise, got", value);
  console.log("Total time: ", Date.now() - start, "ms");
});

Deferred.prototype. promise

The promise object can be used to register a callback to be invoked when the promise is eventually resolved.


Deferred.prototype. resolve (result, isError)

Resolve the promise.

Parameters

Object result

the result or error value

Boolean isError

if true the promise is resolved as failed


Promise

A promise object. This class is not exported, create a deferred object to create a promise.


Promise.prototype. then (callback, errback)

Register callback and errback functions to be invoked when the promise is resolved.

Parameters

Function callback

called if the promise is resolved as fulfilled

Function errback

called if the promise is resolved as failed

Returns

Object

a new promise that resolves to the return value of the callback or errback when it is called.


Promise.prototype. wait (timeout)

Wait for the promise to be resolved.

Parameters

Number timeout

optional time in milliseconds to wait for. If timeout is undefined wait() blocks forever.

Returns

Object

the value if the promise is resolved as fulfilled

Throws

Object the error value if the promise is resolved as failed

PromiseList (promise...)

The PromiseList class allows to combine several promises into one. It represents itself a promise that resolves to an array of objects, each containing a value or error property with the value or error of the corresponding promise argument.

A PromiseList resolves successfully even if some or all of the partial promises resolve to an error. It is the responsibility of the handler function to check each individual promise result.

Example

// --- sample output ---
// Done!
// { value: 'i am ok' }
// { value: 1 }
// { error: 'some error' }

let d1 = Deferred(), d2 = Deferred(), d3 = Deferred();

// PromiseList accepts a promise or deferred object
let list = PromiseList(d1.promise, d2, d3);

list.then(function(results) {
  console.log("Done!");
  results.forEach(function(result) {
    console.dir(result);
  });
}, function(error) {
   console.error("Error :-(");
});

d2.resolve(1);
d3.resolve("some error", true);
d1.resolve("i am ok");

Parameters

Promise... promise...

any number of promise arguments.