PromiseDebugging.webidl (3683B)
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 };