Promise Extends
Promises provide a result that may be resolved asynchronously. A Promise may be resolved by being fulfilled or rejected with a value, which will be known as the fulfillment value or the rejection reason. Whether fulfilled or rejected, the Promise result is immutable once it is set. Promises may represent results of any type, including undefined. Rejection reasons are typically Errors, but may also be of any type. Closure Promises allow for optional type annotations that enforce that fulfillment values are of the appropriate types at compile time. The result of a Promise is accessible by calling then and registering onFulfilled and onRejected callbacks. Once the Promise resolves, the relevant callbacks are invoked with the fulfillment value or rejection reason as argument. Callbacks are always invoked in the order they were registered, even when additional then calls are made from inside another callback. A callback is always run asynchronously sometime after the scope containing the registering then invocation has returned. If a Promise is resolved with another Promise, the first Promise will block until the second is resolved, and then assumes the same result as the second Promise. This allows Promises to depend on the results of other Promises, linking together multiple asynchronous operations. This implementation is compatible with the Promises/A+ specification and passes that specification's conformance test suite. A Closure Promise may be resolved with a Promise instance (or sufficiently compatible Promise-like object) created by other Promise implementations. From the specification, Promise-like objects are known as "Thenables".

Inheritance

Constructor

goog.Promise(resolveropt_context)

Parameters

resolver : function( this:RESOLVER_CONTEXT, function((TYPE | IThenable.<TYPE> | Thenable)=), function(*)): void
Initialization function that is invoked immediately with resolve and reject functions as arguments. The Promise is resolved or rejected with the first argument passed to either function.
opt_context : RESOLVER_CONTEXT=
An optional context for executing the resolver function. If unspecified, the resolver function will be executed in the default scope.

Instance Methods

Public Protected Private
Defined in goog.Promise
addCallbackEntry_(callbackEntry)
Adds a callback entry to the current Promise, and schedules callback execution if the Promise has already been resolved.
Arguments:
callbackEntry : goog.Promise.CallbackEntry_
Record containing onFulfilled and onRejected callbacks to execute after the Promise is resolved.
code »
addChildPromise_(onFulfilledonRejectedopt_context) !goog.Promise
Creates a child Promise and adds it to the callback entry list. The result of the child Promise is determined by the state of the parent Promise and the result of the onFulfilled or onRejected callbacks as specified in the Promise resolution procedure.
Arguments:
onFulfilled : ?function(this:THIS, TYPE): (RESULT | goog.Promise.<RESULT> | Thenable)
A callback that will be invoked if the Promise is fullfilled, or null.
onRejected : ?function(this:THIS, *): *
A callback that will be invoked if the Promise is rejected, or null.
opt_context : THIS=
An optional execution context for the callbacks. in the default calling context.
Returns: !goog.Promise  The child Promise.
code »
addStackTrace_(err)
Records a stack trace entry for functions that call then or the Promise constructor. May be disabled by unsetting LONG_STACK_TRACES.
Arguments:
err : !Error
An Error object created by the calling function for providing a stack trace.
code »
appendLongStack_(err)
Adds extra stack trace information to an exception for the list of asynchronous then calls that have been run for this Promise. Stack trace information is recorded in , and appended to rethrown errors when LONG_STACK_TRACES is enabled.
Arguments:
err : *
An unhandled exception captured during callback execution.
code »
cancel(opt_message)
Cancels the Promise if it is still pending by rejecting it with a cancel Error. No action is performed if the Promise is already resolved. All child Promises of the canceled Promise will be rejected with the same cancel error, as with normal Promise rejection. If the Promise to be canceled is the only child of a pending Promise, the parent Promise will also be canceled. Cancellation may propagate upward through multiple generations.
Arguments:
opt_message : string=
An optional debugging message for describing the cancellation reason.
code »
cancelChild_(childPromiseerr)
Cancels a child Promise from the list of callback entries. If the Promise has not already been resolved, reject it with a cancel error. If there are no other children in the list of callback entries, propagate the cancellation by canceling this Promise as well.
Arguments:
childPromise : !goog.Promise
The Promise to cancel.
err : !Error
The cancel error to use for rejecting the Promise.
code »
cancelInternal_(err)
Cancels this Promise with the given error.
Arguments:
err : !Error
The cancellation error.
code »
executeCallback_(callbackEntrystateresult)
Executes a pending callback for this Promise. Invokes an onFulfilled or onRejected callback based on the resolved state of the Promise.
Arguments:
callbackEntry : !goog.Promise.CallbackEntry_
An entry containing the onFulfilled and/or onRejected callbacks for this step.
state : goog.Promise.State_
The resolution status of the Promise, either FULFILLED or REJECTED.
result : *
The resolved result of the Promise.
code »
executeCallbacks_()
Executes all pending callbacks for this Promise.
code »
removeUnhandledRejection_()
Marks this rejected Promise as having being handled. Also marks any parent Promises in the rejected state as handled. The rejection handler will no longer be invoked for this Promise (if it has not been called already).
code »
resolve_(statex)
Attempts to resolve a Promise with a given resolution state and value. This is a no-op if the given Promise has already been resolved. If the given result is a Thenable (such as another Promise), the Promise will be resolved with the same state and result as the Thenable once it is itself resolved. If the given result is not a Thenable, the Promise will be fulfilled or rejected with that result based on the given state.
Arguments:
state : goog.Promise.State_
No description.
x : *
The result to apply to the Promise.
code »
scheduleCallbacks_()
Executes the pending callbacks of a resolved Promise after a timeout. Section 2.2.4 of the Promises/A+ specification requires that Promise callbacks must only be invoked from a call stack that only contains Promise implementation code, which we accomplish by invoking callback execution after a timeout. If startExecution_ is called multiple times for the same Promise, the callback chain will be evaluated only once. Additional callbacks may be added during the evaluation phase, and will be executed in the same event loop. All Promises added to the waiting list during the same browser event loop will be executed in one batch to avoid using a separate timeout per Promise.
code »
then()
Adds callbacks that will operate on the result of the Promise, returning a new child Promise. If the Promise is fulfilled, the onFulfilled callback will be invoked with the fulfillment value as argument, and the child Promise will be fulfilled with the return value of the callback. If the callback throws an exception, the child Promise will be rejected with the thrown value instead. If the Promise is rejected, the onRejected callback will be invoked with the rejection reason as argument, and the child Promise will be resolved with the return value or rejected with the thrown value of the callback.
code »
thenAlways(onResolvedopt_context) !goog.Promise.<TYPE>
Adds a callback that will be invoked whether the Promise is fulfilled or rejected. The callback receives no argument, and no new child Promise is created. This is useful for ensuring that cleanup takes place after certain asynchronous operations. Callbacks added with thenAlways will be executed in the same order with other calls to then, thenAlways, or thenCatch. Since it does not produce a new child Promise, cancellation propagation is not prevented by adding callbacks with thenAlways. A Promise that has a cleanup handler added with thenAlways will be canceled if all of its children created by then (or thenCatch) are canceled.
Arguments:
onResolved : function(this:THIS): void
A function that will be invoked when the Promise is resolved.
opt_context : THIS=
An optional context object that will be the execution context for the callbacks. By default, functions are executed in the global scope.
Returns: !goog.Promise.<TYPE>  This Promise, for chaining additional calls.
code »
thenCatch(onRejectedopt_context) !goog.Promise
Adds a callback that will be invoked only if the Promise is rejected. This is equivalent to then(null, onRejected).
Arguments:
onRejected : !function(this:THIS, *): *
A function that will be invoked with the rejection reason if the Promise is rejected.
opt_context : THIS=
An optional context object that will be the execution context for the callbacks. By default, functions are executed in the global scope.
Returns: !goog.Promise  A new Promise that will receive the result of the callback.
code »
tryThen_(thenablethen)
Attempts to call the then method on an object in the hopes that it is a Promise-compatible instance. This allows interoperation between different Promise implementations, however a non-compliant object may cause a Promise to hang indefinitely. If the then method throws an exception, the dependent Promise will be rejected with the thrown value.
Arguments:
thenable : Thenable
An object with a then method that may be compatible with the Promise/A+ specification.
then : !Function
The then method of the Thenable object.
code »
unblockAndFulfill_(value)
Unblocks the Promise and fulfills it with the given value.
Arguments:
value : TYPE
No description.
code »
unblockAndReject_(reason)
Unblocks the Promise and rejects it with the given rejection reason.
Arguments:
reason : *
No description.
code »

Instance Properties

Defined in goog.Promise
callbackEntries_ :
The list of onFulfilled and onRejected callbacks added to this Promise by calls to then().
Code »
currentStep_ :
Index of the most recently executed stack frame entry.
Code »
executing_ :
Whether the Promise is in the queue of Promises to execute.
Code »
hadUnhandledRejection_ :
When the UNHANDLED_REJECTION_DELAY is set to 0 milliseconds, a boolean that is set if the Promise is rejected, and reset to false if an onRejected callback is invoked for the Promise (or one of its descendants). If the rejection is not handled before the next timestep, the rejection reason is passed to the unhandled rejection handler.
Code »
parent_ : goog.Promise
For Promises created by calling then(), the originating parent.
Code »
result_ :
The resolved result of the Promise. Immutable once set with either a fulfillment value or rejection reason.
Code »
stack_ :
A list of stack trace frames pointing to the locations where this Promise was created or had callbacks added to it. Saved to add additional context to stack traces when an exception is thrown.
Code »
state_ :
The internal state of this Promise. Either PENDING, FULFILLED, REJECTED, or BLOCKED.
Code »
unhandledRejectionId_ :
A timeout ID used when the UNHANDLED_REJECTION_DELAY is greater than 0 milliseconds. The ID is set when the Promise is rejected, and cleared only if an onRejected callback is invoked for the Promise (or one of its descendants) before the delay is exceeded. If the rejection is not handled before the timeout completes, the rejection reason is passed to the unhandled rejection handler.
Code »

Static Methods

goog.Promise.addUnhandledRejection_(promisereason)
Marks this rejected Promise as unhandled. If no onRejected callback is called for this Promise before the UNHANDLED_REJECTION_DELAY expires, the reason will be passed to the unhandled rejection handler. The handler typically rethrows the rejection reason so that it becomes visible in the developer console.
Arguments:
promise : !goog.Promise
The rejected Promise.
reason : *
The Promise rejection reason.
code »
goog.Promise.all(promises) !goog.Promise.<!Array.<TYPE>>
No description.
Arguments:
promises : !Array.<!(goog.Thenable.<TYPE> | Thenable)>
No description.
Returns: !goog.Promise.<!Array.<TYPE>>  A Promise that receives a list of every fulfilled value once every input Promise (or Promise-like) is successfully fulfilled, or is rejected by the first rejection result.
code »
goog.Promise.firstFulfilled(promises) !goog.Promise.<TYPE>
No description.
Arguments:
promises : !Array.<!(goog.Thenable.<TYPE> | Thenable)>
No description.
Returns: !goog.Promise.<TYPE>  A Promise that receives the value of the first input to be fulfilled, or is rejected with a list of every rejection reason if all inputs are rejected.
code »
goog.Promise.handleRejection_()
A method that is invoked with the rejection reasons for Promises that are rejected but have no onRejected callbacks registered yet.
code »
goog.Promise.race(promises) !goog.Promise.<TYPE>
No description.
Arguments:
promises : !Array.<!(goog.Thenable.<TYPE> | Thenable)>
No description.
Returns: !goog.Promise.<TYPE>  A Promise that receives the result of the first Promise (or Promise-like) input to complete.
code »
goog.Promise.reject(opt_reason) !goog.Promise
No description.
Arguments:
opt_reason : *=
No description.
Returns: !goog.Promise  A new Promise that is immediately rejected with the given reason.
code »
goog.Promise.resolve(opt_value) !goog.Promise.<TYPE>
No description.
Arguments:
opt_value : (TYPE | goog.Thenable.<TYPE> | Thenable)=
No description.
Returns: !goog.Promise.<TYPE>  A new Promise that is immediately resolved with the given value.
code »
goog.Promise.setUnhandledRejectionHandler(handler)
Sets a handler that will be called with reasons from unhandled rejected Promises. If the rejected Promise (or one of its descendants) has an onRejected callback registered, the rejection will be considered handled, and the rejection handler will not be called. By default, unhandled rejections are rethrown so that the error may be captured by the developer console or a window.onerror handler.
Arguments:
handler : function(*)
A function that will be called with reasons from rejected Promises. Defaults to goog.async.throwException.
code »
goog.Promise.withResolver() !goog.promise.Resolver.<TYPE>
No description.
Returns: !goog.promise.Resolver.<TYPE>  Resolver wrapping the promise and its resolve / reject functions. Resolving or rejecting the resolver resolves or rejects the promise.
code »

Static Properties

goog.Promise.CallbackEntry_ :
Typedef for entries in the callback chain. Each call to then, thenCatch, or thenAlways creates an entry containing the functions that may be invoked once the Promise is resolved.
Code »
goog.Promise.LONG_STACK_TRACES :
No description.
Code »
goog.Promise.UNHANDLED_REJECTION_DELAY :
No description.
Code »

Enumerations

goog.Promise.State_ :
The possible internal states for a Promise. These states are not directly observable to external callers.
Constants:
BLOCKED
No description.
FULFILLED
No description.
PENDING
No description.
REJECTED
No description.
Code »

Package Promise

Package Reference