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.CancellationError
Error used when the computation of a promise is cancelled.
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.Promise
Represents the eventual value of a completed operation.
webdriver.promise.Task_
A task to be executed by a webdriver.promise.ControlFlow.
Show:

Global Functions

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.

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.
Returns
The currently active control flow.

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.

Creates a new deferred object.

Returns
The new deferred object.

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.

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

Parameters
opt_value: T=
The resolved value.
Returns
The resolved 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.
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.

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.

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.

Tests is a function is a generator.

Parameters
fn: !Function
The function to test.
Returns
Whether the function is a generator.

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.

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.

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

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.

The default flow to use if no others are active.