# Class webdriver.promise.Deferred.`<T>`

code »

    webdriver.promise.Promise.<(T|null)>
      └ webdriver.promise.Deferred

Represents a value that will be resolved at some point in the future. This class represents the protected "producer" half of a Promise - each Deferred has a `promise` property that may be returned to consumers for registering callbacks, reserving the ability to resolve the deferred to the producer.

If this Deferred is rejected and there are no listeners registered before the next turn of the event loop, the rejection will be passed to the `webdriver.promise.ControlFlow` as an unhandled failure.

If this Deferred is cancelled, the cancellation reason will be forward to the Deferred's canceller function (if provided). The canceller may return a truth-y value to override the reason provided for rejection.

## Constructor

webdriver.promise.Deferred ( opt_canceller, opt_flow )

Parameters

opt_canceller: `Function=`
  Function to call when cancelling the computation of this instance's value.
opt_flow: `webdriver.promise.ControlFlow=`
  The control flow this instance was created under. This should only be provided during unit tests.

## Enumerations

webdriver.promise.Deferred.State_
  The three states a `webdriver.promise.Deferred` object may be in.

Show:PublicProtectedPrivate

## Type Definitions

code »webdriver.promise.Deferred.Listener_ : `{callback: (Function|undefined), errback: (Function|undefined), fulfill: function(*), reject: function(*)}`
Type definition for a listener registered on a Deferred object.

## Instance Methods

### Defined in `webdriver.promise.Deferred`

code » errback ( opt_error )

Rejects this promise. If the error is itself a promise, this instance will be chained to it and be rejected with the error's resolved value.

Parameters

opt_error: `*=`
  The rejection reason, typically either a `Error` or a `string`.

code » fulfill ( opt_value )

Resolves this promise with the given value. If the value is itself a promise and not a reference to this deferred, this instance will wait for it before resolving.

Parameters

opt_value: `T=`
  The fulfilled value.

code » reject ( opt_error )

Rejects this promise. If the error is itself a promise, this instance will be chained to it and be rejected with the error's resolved value.

Parameters

opt_error: `*=`
  The rejection reason, typically either a `Error` or a `string`.

code » removeAll ( )

Removes all of the listeners previously registered on this deferred.

Throws

`Error`
  If this deferred has already been resolved.

### Defined in `webdriver.promise.Promise.<(T|null)>`

code » cancel ( reason )

Cancels the computation of this promise's value, rejecting the promise in the process.

Parameters

reason: `*`
  The reason this promise is being cancelled. If not an `Error`, one will be created using the value's string representation.

code » isPending ( ) ⇒ `boolean`

Returns

Whether this promise's value is still being computed.

code » `<R>` then ( opt_callback, opt_errback ) ⇒ `!webdriver.promise.Promise.<R>`

Registers listeners for when this instance is resolved. This function most overridden by subtypes.

Parameters

opt_callback: `?(function(T): (R|webdriver.promise.Promise.<R>))=`
  The function to call if this promise is successfully resolved. The function should expect a single argument: the promise's resolved value.
opt_errback: `?(function(*): (R|webdriver.promise.Promise.<R>))=`
  The function to call if this promise is rejected. The function should expect a single argument: the rejection reason.

Returns

A new promise which will be resolved with the result of the invoked callback.

code » `<R>` thenCatch ( errback ) ⇒ `!webdriver.promise.Promise.<R>`

Registers a listener for when this promise is rejected. This is synonymous with the `catch` clause in a synchronous API:

       // Synchronous API:
       try {
         doSynchronousWork();
       } catch (ex) {
         console.error(ex);
       }

       // Asynchronous promise API:
       doAsynchronousWork().thenCatch(function(ex) {
         console.error(ex);
       });

Parameters

errback: `function(*): (R|webdriver.promise.Promise.<R>)`
  The function to call if this promise is rejected. The function should expect a single argument: the rejection reason.

Returns

A new promise which will be resolved with the result of the invoked callback.

code » `<R>` thenFinally ( callback ) ⇒ `!webdriver.promise.Promise.<R>`

Registers a listener to invoke when this promise is resolved, regardless of whether the promise's value was successfully computed. This function is synonymous with the `finally` clause in a synchronous API:

       // Synchronous API:
       try {
         doSynchronousWork();
       } finally {
         cleanUp();
       }

       // Asynchronous promise API:
       doAsynchronousWork().thenFinally(cleanUp);

Note: similar to the `finally` clause, if the registered callback returns a rejected promise or throws an error, it will silently replace the rejection error (if any) from this promise:

       try {
         throw Error('one');
       } finally {
         throw Error('two');  // Hides Error: one
       }

       webdriver.promise.rejected(Error('one'))
           .thenFinally(function() {
             throw Error('two');  // Hides Error: one
           });

Parameters

callback: `function(): (R|webdriver.promise.Promise.<R>)`
  The function to call when this promise is resolved.

Returns

A promise that will be fulfilled with the callback result.

## Instance Properties

### Defined in `webdriver.promise.Deferred`

code » webdriver.promise.Deferred.prototype.promise : `webdriver.promise.Promise.<T>`

Represents the eventual value of a completed operation. Each promise may be in one of three states: pending, resolved, or rejected. Each promise starts in the pending state and may make a single transition to either a fulfilled or failed state.

This class is based on the Promise/A proposal from CommonJS. Additional functions are provided for API compatibility with Dojo Deferred objects.

## Static Properties

code » webdriver.promise.Deferred.superClass_ : `webdriver.promise.Promise.prototype`