toolkit/modules/Promise.jsm

   1 /* -*- indent-tabs-mode: nil; js-indent-level: 2 -*- */
   2 /* vim: set ts=2 et sw=2 tw=80 filetype=javascript: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 "use strict";
   8
   9 var EXPORTED_SYMBOLS = ["Promise"];
  10
  11 /**
  12  * This module implements the "promise" construct, according to the
  13  * "Promises/A+" proposal as known in April 2013, documented here:
  14  *
  15  * <http://promises-aplus.github.com/promises-spec/>
  16  *
  17  * A promise is an object representing a value that may not be available yet.
  18  * Internally, a promise can be in one of three states:
  19  *
  20  * - Pending, when the final value is not available yet.  This is the only state
  21  *   that may transition to one of the other two states.
  22  *
  23  * - Resolved, when and if the final value becomes available.  A resolution
  24  *   value becomes permanently associated with the promise.  This may be any
  25  *   value, including "undefined".
  26  *
  27  * - Rejected, if an error prevented the final value from being determined.  A
  28  *   rejection reason becomes permanently associated with the promise.  This may
  29  *   be any value, including "undefined", though it is generally an Error
  30  *   object, like in exception handling.
  31  *
  32  * A reference to an existing promise may be received by different means, for
  33  * example as the return value of a call into an asynchronous API.  In this
  34  * case, the state of the promise can be observed but not directly controlled.
  35  *
  36  * To observe the state of a promise, its "then" method must be used.  This
  37  * method registers callback functions that are called as soon as the promise is
  38  * either resolved or rejected.  The method returns a new promise, that in turn
  39  * is resolved or rejected depending on the state of the original promise and on
  40  * the behavior of the callbacks.  For example, unhandled exceptions in the
  41  * callbacks cause the new promise to be rejected, even if the original promise
  42  * is resolved.  See the documentation of the "then" method for details.
  43  *
  44  * Promises may also be created using the "Promise.defer" function, the main
  45  * entry point of this module.  The function, along with the new promise,
  46  * returns separate methods to change its state to be resolved or rejected.
  47  * See the documentation of the "Deferred" prototype for details.
  48  *
  49  * -----------------------------------------------------------------------------
  50  *
  51  * Cu.import("resource://gre/modules/Promise.jsm");
  52  *
  53  * // This function creates and returns a new promise.
  54  * function promiseValueAfterTimeout(aValue, aTimeout)
  55  * {
  56  *   let deferred = Promise.defer();
  57  *
  58  *   try {
  59  *     // An asynchronous operation will trigger the resolution of the promise.
  60  *     // In this example, we don't have a callback that triggers a rejection.
  61  *     do_timeout(aTimeout, function () {
  62  *       deferred.resolve(aValue);
  63  *     });
  64  *   } catch (ex) {
  65  *     // Generally, functions returning promises propagate exceptions through
  66  *     // the returned promise, though they may also choose to fail early.
  67  *     deferred.reject(ex);
  68  *   }
  69  *
  70  *   // We don't return the deferred to the caller, but only the contained
  71  *   // promise, so that the caller cannot accidentally change its state.
  72  *   return deferred.promise;
  73  * }
  74  *
  75  * // This code uses the promise returned be the function above.
  76  * let promise = promiseValueAfterTimeout("Value", 1000);
  77  *
  78  * let newPromise = promise.then(function onResolve(aValue) {
  79  *   do_print("Resolved with this value: " + aValue);
  80  * }, function onReject(aReason) {
  81  *   do_print("Rejected with this reason: " + aReason);
  82  * });
  83  *
  84  * // Unexpected errors should always be reported at the end of a promise chain.
  85  * newPromise.then(null, Components.utils.reportError);
  86  *
  87  * -----------------------------------------------------------------------------
  88  */
  89
  90 // eslint-disable-next-line mozilla/use-services
  91 Cc["@mozilla.org/moz/jssubscript-loader;1"]
  92   .getService(Ci.mozIJSSubScriptLoader)
  93   .loadSubScript("resource://gre/modules/Promise-backend.js", this);