dom/chrome-webidl/PromiseDebugging.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  */
   6
   7 /* This is a utility namespace for promise-debugging functionality */
   8
   9
  10 dictionary PromiseDebuggingStateHolder {
  11   PromiseDebuggingState state = "pending";
  12   any value;
  13   any reason;
  14 };
  15 enum PromiseDebuggingState { "pending", "fulfilled", "rejected" };
  16
  17 /**
  18  * An observer for Promise that _may_ be leaking uncaught rejections.
  19  *
  20  * It is generally a programming error to leave a Promise rejected and
  21  * not consume its rejection. The information exposed by this
  22  * interface is designed to allow clients to track down such Promise,
  23  * i.e. Promise that are currently
  24  * - in `rejected` state;
  25  * - last of their chain.
  26  *
  27  * Note, however, that a promise in such a state at the end of a tick
  28  * may eventually be consumed in some ulterior tick. Implementers of
  29  * this interface are responsible for presenting the information
  30  * in a meaningful manner.
  31  */
  32 [Exposed=Window]
  33 callback interface UncaughtRejectionObserver {
  34   /**
  35    * A Promise has been left in `rejected` state and is the
  36    * last in its chain. If this callback returns true, the rejection
  37    * will not be reported.
  38    *
  39    * @param p A currently uncaught Promise. If `p` is is eventually
  40    * caught, i.e. if its `then` callback is called, `onConsumed` will
  41    * be called.
  42    */
  43   boolean onLeftUncaught(object p);
  44
  45   /**
  46    * A Promise previously left uncaught is not the last in its
  47    * chain anymore.
  48    *
  49    * @param p A Promise that was previously left in uncaught state is
  50    * now caught, i.e. it is not the last in its chain anymore.
  51    */
  52   undefined onConsumed(object p);
  53 };
  54
  55 [ChromeOnly, Exposed=Window]
  56 namespace PromiseDebugging {
  57   /**
  58    * The various functions on this interface all expect to take promises but
  59    * don't want the WebIDL behavior of assimilating random passed-in objects
  60    * into promises.  They also want to treat Promise subclass instances as
  61    * promises instead of wrapping them in a vanilla Promise, which is what the
  62    * IDL spec says to do.  So we list all our arguments as "object" instead of
  63    * "Promise" and check for them being a Promise internally.
  64    */
  65
  66   /**
  67    * Get the current state of the given promise.
  68    */
  69   [Throws]
  70   PromiseDebuggingStateHolder getState(object p);
  71
  72   /**
  73    * Return an identifier for a promise. This identifier is guaranteed
  74    * to be unique to the current process.
  75    */
  76   [Throws]
  77   DOMString getPromiseID(object p);
  78
  79   /**
  80    * Return the stack to the promise's allocation point.  This can
  81    * return null if the promise was not created from script.
  82    */
  83   [Throws]
  84   object? getAllocationStack(object p);
  85
  86   /**
  87    * Return the stack to the promise's rejection point, if the
  88    * rejection happened from script.  This can return null if the
  89    * promise has not been rejected or was not rejected from script.
  90    */
  91   [Throws]
  92   object? getRejectionStack(object p);
  93
  94   /**
  95    * Return the stack to the promise's fulfillment point, if the
  96    * fulfillment happened from script.  This can return null if the
  97    * promise has not been fulfilled or was not fulfilled from script.
  98    */
  99   [Throws]
 100   object? getFullfillmentStack(object p);
 101
 102   /**
 103    * Watching uncaught rejections on the current thread.
 104    *
 105    * Adding an observer twice will cause it to be notified twice
 106    * of events.
 107    */
 108   undefined addUncaughtRejectionObserver(UncaughtRejectionObserver o);
 109   boolean removeUncaughtRejectionObserver(UncaughtRejectionObserver o);
 110 };