# Namespace webdriver.promise

code »

## Interfaces

webdriver.promise.Thenable
  Thenable is a promise-like object with a `then` method which may be used to schedule callbacks on a promised value.

## Classes

webdriver.promise.CanceledTaskError_
  Special error used to signal when a task is canceled because a previous task in the same frame failed.
webdriver.promise.ControlFlow
  Handles the execution of scheduled tasks, each of which may be an asynchronous operation.
webdriver.promise.Deferred
  Represents a value that will be resolved at some point in the future.
webdriver.promise.Frame_
  An execution frame within a `webdriver.promise.ControlFlow`.
webdriver.promise.Node_
  A single node in an `webdriver.promise.ControlFlow`'s task tree.
webdriver.promise.Promise
  Represents the eventual value of a completed operation.
webdriver.promise.Task_
  A task to be executed by a `webdriver.promise.ControlFlow`.

Show:Public Protected Private

## Global Functions

code »`<T>` webdriver.promise.all ( arr ) ⇒ `!webdriver.promise.Promise`

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.

Parameters

arr: `!Array`
  An array of promises to wait on.

Returns

A promise that is fulfilled with an array containing the fulfilled values of the input array, or rejected with the same reason as the first rejected value.

code »webdriver.promise.asap ( value, callback, opt_errback )

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.

Parameters

value: `*`
  The value to observe.
callback: `Function`
  The function to call when the value is resolved successfully.
opt_errback: `Function=`
  The function to call when the value is rejected.

code »webdriver.promise.checkedNodeCall ( fn, var_args ) ⇒ `!webdriver.promise.Promise`

Wraps a function that is assumed to be a node-style callback as its final argument. This callback takes two arguments: an error value (which will be null if the call succeeded), and the success value as the second argument. If the call fails, the returned promise will be rejected, otherwise it will be resolved with the result.

Parameters

fn: `!Function`
  The function to wrap.
var_args: `...?`
  The arguments to apply to the function, excluding the final callback.

Returns

A promise that will be resolved with the result of the provided function's callback.

code »webdriver.promise.consume ( generatorFn, opt_self, var_args ) ⇒ `!webdriver.promise.Promise`

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.

     webdriver.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.

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

Parameters

generatorFn: `!Function`
  The generator function to execute.
opt_self: `Object=`
  The object to use as "this" when invoking the initial generator.
var_args: `...*`
  Any arguments to pass to the initial generator.

Returns

A promise that will resolve to the generator's final result.

Throws

`TypeError`
  If the given function is not a generator.

code »webdriver.promise.controlFlow ( ) ⇒ `!webdriver.promise.ControlFlow`

Returns

The currently active control flow.

code »webdriver.promise.createFlow ( callback ) ⇒ `!webdriver.promise.Promise`

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.

Parameters

callback: `function(!webdriver.promise.ControlFlow)`
  The entry point to the newly created flow.

Returns

A promise that resolves to the callback result.

code »`<T>` webdriver.promise.defer ( opt_canceller ) ⇒ `!webdriver.promise.Deferred.<T>`

Creates a new deferred object.

Parameters

opt_canceller: `Function=`
  Function to call when cancelling the computation of this instance's value.

Returns

The new deferred object.

code »webdriver.promise.delayed ( ms ) ⇒ `!webdriver.promise.Promise`

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

Parameters

ms: `number`
  The amount of time, in milliseconds, to wait before resolving the promise.

Returns

The promise.

code »`<TYPE, SELF>` webdriver.promise.filter ( arr, fn, opt_self )

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.

Parameters

arr: `!(Array.<TYPE>|webdriver.promise.Promise)`
  The array to iterator over, or a promise that will resolve to said array.
fn: `function(this: SELF, TYPE, number, !Array.<TYPE>): (boolean|webdriver.promise.Promise.<boolean>)`
  The function to call for each element in the array.
opt_self: `SELF=`
  The object to be used as the value of 'this' within `fn`.

code »`<T>` webdriver.promise.fulfilled ( opt_value ) ⇒ `!webdriver.promise.Promise.<T>`

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

Parameters

opt_value: `T=`
  The resolved value.

Returns

The resolved promise.

code »webdriver.promise.fullyResolveKeys_ ( obj ) ⇒ `!webdriver.promise.Promise`

Parameters

obj: `!(Array|Object)`
  the object to resolve.

Returns

A promise that will be resolved with the input object once all of its values have been fully resolved.

code »webdriver.promise.fullyResolveValue_ ( value ) ⇒ `!webdriver.promise.Promise`

Parameters

value: `*`
  The value to fully resolve. If a promise, assumed to already be resolved.

Returns

A promise for a fully resolved version of the input value.

code »webdriver.promise.fullyResolved ( value ) ⇒ `!webdriver.promise.Promise`

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;
       webdriver.promise.fullyResolved(value);  // Stack overflow.

Parameters

value: `*`
  The value to fully resolve.

Returns

A promise for a fully resolved version of the input value.

code »webdriver.promise.isError_ ( value ) ⇒ `boolean`

Tests if a value is an Error-like object. This is more than an straight instanceof check since the value may originate from another context.

Parameters

value: `*`
  The value to test.

Returns

Whether the value is an error.

code »webdriver.promise.isGenerator ( fn ) ⇒ `boolean`

Tests is a function is a generator.

Parameters

fn: `!Function`
  The function to test.

Returns

Whether the function is a generator.

code »webdriver.promise.isPromise ( value ) ⇒ `boolean`

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

Parameters

value: `*`
  The value to test.

Returns

Whether the value is a promise.

code »`<TYPE, SELF>` webdriver.promise.map ( arr, fn, opt_self )

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.

Parameters

arr: `!(Array.<TYPE>|webdriver.promise.Promise)`
  The array to iterator over, or a promise that will resolve to said array.
fn: `function(this: SELF, TYPE, number, !Array.<TYPE>): ?`
  The function to call for each element in the array. This function should expect three arguments (the element, the index, and the array itself.
opt_self: `SELF=`
  The object to be used as the value of 'this' within `fn`.

code »webdriver.promise.popFlow_ ( )
code »webdriver.promise.pushFlow_ ( flow )

Parameters

flow: `!webdriver.promise.ControlFlow`
  The new flow.

code »`<T>` webdriver.promise.rejected ( opt_reason ) ⇒ `!webdriver.promise.Promise.<T>`

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

Parameters

opt_reason: `*=`
  The rejection reason; may be any value, but is usually an Error or a string.

Returns

The rejected promise.

code »webdriver.promise.setDefaultFlow ( flow )

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

Parameters

flow: `!webdriver.promise.ControlFlow`
  The new default flow.

Throws

`Error`
  If the default flow is not currently active.

code »webdriver.promise.when ( value, opt_callback, opt_errback ) ⇒ `!webdriver.promise.Promise`

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.

Parameters

value: `*`
  The value to observe.
opt_callback: `Function=`
  The function to call when the value is resolved successfully.
opt_errback: `Function=`
  The function to call when the value is rejected.

Returns

A new promise.

## Global Properties

code »webdriver.promise.activeFlows_ : `!Array`

A stack of active control flows, with the top of the stack used to schedule commands. When there are multiple flows on the stack, the flow at index N represents a callback triggered within a task owned by the flow at index N-1.

code »webdriver.promise.defaultFlow_ : `!webdriver.promise.ControlFlow`

The default flow to use if no others are active.