namespace webdriver.promise

<T> all(arr)code »

Given an array of promises, will return a promise that will be fulfilled with the fulfillment values of the input array's values. If any of the input array's promises are rejected, the returned promise will be rejected with the same reason.

asap(value, callback, opt_errback)code »

Invokes the appropriate callback function as soon as a promised value is resolved. This function is similar to webdriver.promise.when, except it does not return a new promise.

captureStackTrace(name, msg, topFn)code »

Generates an error to capture the current stack trace.

checkedNodeCall(fn, var_args)code »

Wraps a function that expects a node-style callback as its final argument. This callback expects two arguments: an error value (which will be null if the call succeeded), and the success value as the second argument. The callback will the resolve or reject the returned promise, based on its arguments.

consume(generatorFn, opt_self, var_args)code »

Consumes a GeneratorFunction. Each time the generator yields a promise, this function will wait for it to be fulfilled before feeding the fulfilled value back into next. Likewise, if a yielded promise is rejected, the rejection error will be passed to throw.

Example 1: the Fibonacci Sequence.

promise.consume(function* fibonacci() {
  var n1 = 1, n2 = 1;
  for (var i = 0; i < 4; ++i) {
    var tmp = yield n1 + n2;
    n1 = n2;
    n2 = tmp;
  }
  return n1 + n2;
}).then(function(result) {
  console.log(result);  // 13
});

Example 2: a generator that throws.

promise.consume(function* () {
  yield promise.delayed(250).then(function() {
    throw Error('boom');
  });
}).thenCatch(function(e) {
  console.log(e.toString());  // Error: boom
});

controlFlow()code »

createFlow(callback)code »

Creates a new control flow. The provided callback will be invoked as the first task within the new flow, with the flow as its sole argument. Returns a promise that resolves to the callback result.

<T> defer()code »

Creates a new deferred object.

delayed(ms)code »

Creates a promise that will be resolved at a set time in the future.

<TYPE, SELF> filter(arr, fn, opt_self)code »

Calls a function for each element in an array, and if the function returns true adds the element to a new array.

If the return value of the filter function is a promise, this function will wait for it to be fulfilled before determining whether to insert the element into the new array.

If the filter function throws or returns a rejected promise, the promise returned by this function will be rejected with the same reason. Only the first failure will be reported; all subsequent errors will be silently ignored.

<T> fulfilled(opt_value)code »

Creates a promise that has been resolved with the given value.

fullyResolved(value)code »

Returns a promise that will be resolved with the input value in a fully-resolved state. If the value is an array, each element will be fully resolved. Likewise, if the value is an object, all keys will be fully resolved. In both cases, all nested arrays and objects will also be fully resolved. All fields are resolved in place; the returned promise will resolve on value and not a copy.

Warning: This function makes no checks against objects that contain cyclical references:

var value = {};
value['self'] = value;
promise.fullyResolved(value);  // Stack overflow.

isGenerator(fn)code »

Tests is a function is a generator.

isPromise(value)code »

Determines whether a value should be treated as a promise. Any object whose "then" property is a function will be considered a promise.

<TYPE, SELF> map(arr, fn, opt_self)code »

Calls a function for each element in an array and inserts the result into a new array, which is used as the fulfillment value of the promise returned by this function.

If the return value of the mapping function is a promise, this function will wait for it to be fulfilled before inserting it into the new array.

If the mapping function throws or returns a rejected promise, the promise returned by this function will be rejected with the same reason. Only the first failure will be reported; all subsequent errors will be silently ignored.

<T> rejected(opt_reason)code »

Creates a promise that has been rejected with the given reason.

setDefaultFlow(flow)code »

Changes the default flow to use when no others are active.

when(value, opt_callback, opt_errback)code »

Registers an observer on a promised value, returning a new promise that will be resolved when the value is. If value is not a promise, then the return promise will be immediately resolved.