summaryrefslogtreecommitdiffstats
path: root/js/src/doc/Debugger/Debugger.Object.md
diff options
context:
space:
mode:
Diffstat (limited to 'js/src/doc/Debugger/Debugger.Object.md')
-rw-r--r--js/src/doc/Debugger/Debugger.Object.md684
1 files changed, 684 insertions, 0 deletions
diff --git a/js/src/doc/Debugger/Debugger.Object.md b/js/src/doc/Debugger/Debugger.Object.md
new file mode 100644
index 0000000000..c6f8b90a49
--- /dev/null
+++ b/js/src/doc/Debugger/Debugger.Object.md
@@ -0,0 +1,684 @@
+# Debugger.Object
+
+A `Debugger.Object` instance represents an object in the debuggee,
+providing reflection-oriented methods to inspect and modify its referent.
+The referent's properties do not appear directly as properties of the
+`Debugger.Object` instance; the debugger can access them only through
+methods like `Debugger.Object.prototype.getOwnPropertyDescriptor` and
+`Debugger.Object.prototype.defineProperty`, ensuring that the debugger will
+not inadvertently invoke the referent's getters and setters.
+
+SpiderMonkey creates exactly one `Debugger.Object` instance for each
+debuggee object it presents to a given [`Debugger`][debugger-object]
+instance: if the debugger encounters the same object through two different
+routes (perhaps two functions are called on the same object), SpiderMonkey
+presents the same `Debugger.Object` instance to the debugger each time.
+This means that the debugger can use the `==` operator to recognize when
+two `Debugger.Object` instances refer to the same debuggee object, and
+place its own properties on a `Debugger.Object` instance to store metadata
+about particular debuggee objects.
+
+JavaScript code in different compartments can have different views of the
+same object. For example, in Firefox, code in privileged compartments sees
+content DOM element objects without redefinitions or extensions made to
+that object's properties by content code. (In Firefox terminology,
+privileged code sees the element through an "xray wrapper".) To ensure that
+debugger code sees each object just as the debuggee would, each
+`Debugger.Object` instance presents its referent as it would be seen from a
+particular compartment. This "viewing compartment" is chosen to match the
+way the debugger came across the referent. As a consequence, a single
+[`Debugger`][debugger-object] instance may actually have several
+`Debugger.Object` instances: one for each compartment from which the
+referent is viewed.
+
+If more than one [`Debugger`][debugger-object] instance is debugging the
+same code, each [`Debugger`][debugger-object] gets a separate
+`Debugger.Object` instance for a given object. This allows the code using
+each [`Debugger`][debugger-object] instance to place whatever properties it
+likes on its own `Debugger.Object` instances, without worrying about
+interfering with other debuggers.
+
+While most `Debugger.Object` instances are created by SpiderMonkey in the
+process of exposing debuggee's behavior and state to the debugger, the
+debugger can use `Debugger.Object.prototype.makeDebuggeeValue` to create
+`Debugger.Object` instances for given debuggee objects, or use
+`Debugger.Object.prototype.copy` and `Debugger.Object.prototype.create` to
+create new objects in debuggee compartments, allocated as if by particular
+debuggee globals.
+
+`Debugger.Object` instances protect their referents from the garbage
+collector; as long as the `Debugger.Object` instance is live, the referent
+remains live. This means that garbage collection has no visible effect on
+`Debugger.Object` instances.
+
+
+## Accessor Properties of the Debugger.Object prototype
+
+A `Debugger.Object` instance inherits the following accessor properties
+from its prototype:
+
+### `proto`
+The referent's prototype (as a new `Debugger.Object` instance), or `null` if
+it has no prototype. This accessor may throw if the referent is a scripted
+proxy or some other sort of exotic object (an opaque wrapper, for example).
+
+### `class`
+A string naming the ECMAScript `[[Class]]` of the referent.
+
+### `callable`
+`true` if the referent is a callable object (such as a function or a
+function proxy); false otherwise.
+
+### `name`
+The name of the referent, if it is a named function. If the referent is
+an anonymous function, or not a function at all, this is `undefined`.
+
+This accessor returns whatever name appeared after the `function`
+keyword in the source code, regardless of whether the function is the
+result of instantiating a function declaration (which binds the
+function to its name in the enclosing scope) or evaluating a function
+expression (which binds the function to its name only within the
+function's body).
+
+### `displayName`
+The referent's display name, if the referent is a function with a
+display name. If the referent is not a function, or if it has no display
+name, this is `undefined`.
+
+If a function has a given name, its display name is the same as its
+given name. In this case, the `displayName` and `name` properties are
+equal.
+
+If a function has no name, SpiderMonkey attempts to infer an appropriate
+name for it given its context. For example:
+
+```js
+function f() {} // display name: f (the given name)
+var g = function () {}; // display name: g
+o.p = function () {}; // display name: o.p
+var q = {
+ r: function () {} // display name: q.r
+};
+```
+
+Note that the display name may not be a proper JavaScript identifier,
+or even a proper expression: we attempt to find helpful names even when
+the function is not immediately assigned as the value of some variable
+or property. Thus, we use <code><i>a</i>/<i>b</i></code> to refer to
+the <i>b</i> defined within <i>a</i>, and <code><i>a</i>&lt;</code> to
+refer to a function that occurs somewhere within an expression that is
+assigned to <i>a</i>. For example:
+
+```js
+function h() {
+ var i = function() {}; // display name: h/i
+ f(function () {}); // display name: h/<
+}
+var s = f(function () {}); // display name: s<
+```
+
+### `parameterNames`
+If the referent is a debuggee function, the names of its parameters,
+as an array of strings. If the referent is not a debuggee function, or
+not a function at all, this is `undefined`.
+
+If the referent is a host function for which parameter names are not
+available, return an array with one element per parameter, each of which
+is `undefined`.
+
+If the referent is a function proxy, return an empty array.
+
+If the function uses destructuring parameters, the corresponding array elements
+are `undefined`. For example, if the referent is a function declared in this
+way:
+
+```js
+function f(a, [b, c], {d, e:f}) { ... }
+```
+
+then this `Debugger.Object` instance's `parameterNames` property would
+have the value:
+
+```js
+["a", undefined, undefined]
+```
+
+### `script`
+If the referent is a function that is debuggee code, this is that
+function's script, as a [`Debugger.Script`][script] instance. If the
+referent is a function proxy or not debuggee code, this is `undefined`.
+
+### `environment`
+If the referent is a function that is debuggee code, a
+[`Debugger.Environment`][environment] instance representing the lexical
+environment enclosing the function when it was created. If the referent
+is a function proxy or not debuggee code, this is `undefined`.
+
+### `isError`
+`true` if the referent is any potentially wrapped Error; `false` otherwise.
+
+### `errorMessageName`
+If the referent is an error created with an engine internal message template
+this is a string which is the name of the template; `undefined` otherwise.
+
+### `errorLineNumber`
+If the referent is an Error object, this is the 1-origin line number at which
+the referent was created; `undefined` otherwise.
+
+### `errorColumnNumber`
+If the referent is an Error object, this is the 1-origin column number in
+UTF-16 code units at which the referent was created; `undefined` otherwise.
+
+### `isBoundFunction`
+If the referent is a debuggee function, returns `true` if the referent is a
+bound function; `false` otherwise. If the referent is not a debuggee
+function, or not a function at all, returns `undefined` instead.
+
+### `isArrowFunction`
+If the referent is a debuggee function, returns `true` if the referent is an
+arrow function; `false` otherwise. If the referent is not a debuggee
+function, or not a function at all, returns `undefined` instead.
+
+### `isGeneratorFunction`
+If the referent is a debuggee function, returns `true` if the referent was
+created with a `function*` expression or statement, or false if it is some
+other sort of function. If the referent is not a debuggee function, or not a
+function at all, this is `undefined`. (This is always equal to
+`obj.script.isGeneratorFunction`, assuming `obj.script` is a
+`Debugger.Script`.)
+
+### `isAsyncFunction`
+If the referent is a debuggee function, returns `true` if the referent is an
+async function, defined with an `async function` expression or statement, or
+false if it is some other sort of function. If the referent is not a
+debuggee function, or not a function at all, this is `undefined`. (This is
+always equal to `obj.script.isAsyncFunction`, assuming `obj.script` is a
+`Debugger.Script`.)
+
+### `isClassConstructor`
+If the referent is a debuggee function, returns `true` if the referent is a class,
+or false if it is some other sort of function. If the referent is not a debuggee
+function, or not a function at all, this is `undefined`. (This is always equal to
+`obj.script.isClassConstructor`, assuming `obj.script` is a `Debugger.Script`.)
+
+### `isPromise`
+`true` if the referent is a Promise; `false` otherwise.
+
+### `boundTargetFunction`
+If the referent is a bound debuggee function, this is its target function—
+the function that was bound to a particular `this` object. If the referent
+is either not a bound function, not a debuggee function, or not a function
+at all, this is `undefined`.
+
+### `boundThis`
+If the referent is a bound debuggee function, this is the `this` value it
+was bound to. If the referent is either not a bound function, not a debuggee
+function, or not a function at all, this is `undefined`.
+
+### `boundArguments`
+If the referent is a bound debuggee function, this is an array (in the
+Debugger object's compartment) that contains the debuggee values of the
+`arguments` object it was bound to. If the referent is either not a bound
+function, not a debuggee function, or not a function at all, this is
+`undefined`.
+
+### `isProxy`
+If the referent is a (scripted) proxy, either revoked or not, return `true`.
+If the referent is not a (scripted) proxy, return `false`.
+
+### `proxyTarget`
+If the referent is a non-revoked (scripted) proxy, return a `Debugger.Object`
+instance referring to the ECMAScript `[[ProxyTarget]]` of the referent.
+If the referent is a revoked (scripted) proxy, return `null`.
+If the referent is not a (scripted) proxy, return `undefined`.
+
+### `proxyHandler`
+If the referent is a non-revoked (scripted) proxy, return a `Debugger.Object`
+instance referring to the ECMAScript `[[ProxyHandler]]` of the referent.
+If the referent is a revoked (scripted) proxy, return `null`.
+If the referent is not a (scripted) proxy, return `undefined`.
+
+### `promiseState`
+If the referent is a [`Promise`][promise], return a string indicating
+whether the [`Promise`][promise] is pending, or has been fulfilled or
+rejected. This string takes one of the following values:
+
+* `"pending"`, if the [`Promise`][promise] is pending.
+
+* `"fulfilled"`, if the [`Promise`][promise] has been fulfilled.
+
+* `"rejected"`, if the [`Promise`][promise] has been rejected.
+
+If the referent is not a [`Promise`][promise], throw a `TypeError`.
+
+### `promiseValue`
+Return a debuggee value representing the value the [`Promise`][promise] has
+been fulfilled with.
+
+If the referent is not a [`Promise`][promise], or the [`Promise`][promise]
+has not been fulfilled, throw a `TypeError`.
+
+### `promiseReason`
+Return a debuggee value representing the value the [`Promise`][promise] has
+been rejected with.
+
+If the referent is not a [`Promise`][promise], or the [`Promise`][promise]
+has not been rejected, throw a `TypeError`.
+
+### `promiseAllocationSite`
+If the referent is a [`Promise`][promise], this is the
+[JavaScript execution stack][saved-frame] captured at the time of the
+promise's allocation. This can return null if the promise was not
+created from script. If the referent is not a [`Promise`][promise], throw
+a `TypeError` exception.
+
+### `promiseResolutionSite`
+If the referent is a [`Promise`][promise], this is the
+[JavaScript execution stack][saved-frame] captured at the time of the
+promise's resolution. This can return null if the promise was not
+resolved by calling its `resolve` or `reject` resolving functions from
+script. If the referent is not a [`Promise`][promise], throw a `TypeError`
+exception.
+
+### `promiseID`
+If the referent is a [`Promise`][promise], this is a process-unique
+identifier for the [`Promise`][promise]. With e10s, the same id can
+potentially be assigned to multiple [`Promise`][promise] instances, if
+those instances were created in different processes. If the referent is
+not a [`Promise`][promise], throw a `TypeError` exception.
+
+### `promiseDependentPromises`
+If the referent is a [`Promise`][promise], this is an `Array` of
+`Debugger.Objects` referring to the promises directly depending on the
+referent [`Promise`][promise]. These are:
+
+1) Return values of `then()` calls on the promise.
+2) Return values of `Promise.all()` if the referent [`Promise`][promise]
+ was passed in as one of the arguments.
+3) Return values of `Promise.race()` if the referent [`Promise`][promise]
+ was passed in as one of the arguments.
+
+Once a [`Promise`][promise] is settled, it will generally notify its
+dependent promises and forget about them, so this is most useful on
+*pending* promises.
+
+Note that the `Array` only contains the promises that directly depend on
+the referent [`Promise`][promise]. It does not contain promises that depend
+on promises that depend on the referent [`Promise`][promise].
+
+If the referent is not a [`Promise`][promise], throw a `TypeError`
+exception.
+
+### `promiseLifetime`
+If the referent is a [`Promise`][promise], this is the number of
+milliseconds elapsed since the [`Promise`][promise] was created. If the
+referent is not a [`Promise`][promise], throw a `TypeError` exception.
+
+### `promiseTimeToResolution`
+If the referent is a [`Promise`][promise], this is the number of
+milliseconds elapsed between when the [`Promise`][promise] was created and
+when it was resolved. If the referent hasn't been resolved or is not a
+[`Promise`][promise], throw a `TypeError` exception.
+
+### `allocationSite`
+If [object allocation site tracking][tracking-allocs] was enabled when this
+`Debugger.Object`'s referent was allocated, return the
+[JavaScript execution stack][saved-frame] captured at the time of the
+allocation. Otherwise, return `null`.
+
+
+## Function Properties of the Debugger.Object prototype
+
+The functions described below may only be called with a `this` value
+referring to a `Debugger.Object` instance; they may not be used as methods
+of other kinds of objects. The descriptions use "referent" to mean "the
+referent of this `Debugger.Object` instance".
+
+Unless otherwise specified, these methods are not
+[invocation functions][inv fr]; if a call would cause debuggee code to run
+(say, because it gets or sets an accessor property whose handler is
+debuggee code, or because the referent is a proxy whose traps are debuggee
+code), the call throws a [`Debugger.DebuggeeWouldRun`][wouldrun] exception.
+
+These methods may throw if the referent is not a native object. Even simple
+accessors like `isExtensible` may throw if the referent is a proxy or some sort
+of exotic object like an opaque wrapper.
+
+### `getProperty(key, [receiver])`
+Return a [completion value][cv] with "return" being the value of the
+referent's property named <i>key</i>, or `undefined` if it has no such
+property. <i>key</i> must be a string or symbol; <i>receiver</i> must be
+a debuggee value. If the property is a getter, it will be evaluated with
+<i>receiver</i> as the receiver, defaulting to the `Debugger.Object`
+if omitted. All extant handler methods, breakpoints, and so on remain
+active during the call.
+
+### `setProperty(key, value<, [receiver])`
+Store <i>value</i> as the value of the referent's property named
+<i>key</i>, creating the property if it does not exist. <i>key</i>
+must be a string or symbol; <i>value</i> and <i>receiver</i> must be
+debuggee values. If the property is a setter, it will be evaluated with
+<i>receiver</i> as the receiver, defaulting to the `Debugger.Object`
+if omitted. Return a [completion value][cv] with "return" being a
+success/failure boolean, or else "throw" being the exception thrown
+during property assignment. All extant handler methods, breakpoints,
+and so on remain active during the call.
+
+### `getOwnPropertyDescriptor(key)`
+Return a property descriptor for the property named <i>key</i> of the
+referent. If the referent has no such property, return `undefined`.
+(This function behaves like the standard
+`Object.getOwnPropertyDescriptor` function, except that the object being
+inspected is implicit; the property descriptor returned is allocated as
+if by code scoped to the debugger's global object (and is thus in the
+debugger's compartment); and its `value`, `get`, and `set` properties,
+if present, are debuggee values.)
+
+### `getOwnPropertyNames()`
+Return an array of strings naming all the referent's own properties, as
+if <code>Object.getOwnPropertyNames(<i>referent</i>)</code> had been
+called in the debuggee, and the result copied in the scope of the
+debugger's global object.
+
+### `getOwnPropertyNamesLength()`
+Return the number of the referent's own properties.
+
+### `getOwnPropertySymbols()`
+Return an array of strings naming all the referent's own symbols, as
+if <code>Object.getOwnPropertySymbols(<i>referent</i>)</code> had been
+called in the debuggee, and the result copied in the scope of the
+debugger's global object.
+
+### `defineProperty(key, attributes)`
+Define a property on the referent named <i>key</i>, as described by
+the property descriptor <i>descriptor</i>. Any `value`, `get`, and
+`set` properties of <i>attributes</i> must be debuggee values. (This
+function behaves like `Object.defineProperty`, except that the target
+object is implicit, and in a different compartment from the function
+and descriptor.)
+
+### `defineProperties(properties)`
+Add the properties given by <i>properties</i> to the referent. (This
+function behaves like `Object.defineProperties`, except that the target
+object is implicit, and in a different compartment from the
+<i>properties</i> argument.)
+
+### `deleteProperty(key)`
+Remove the referent's property named <i>key</i>. Return true if the
+property was successfully removed, or if the referent has no such
+property. Return false if the property is non-configurable.
+
+### `seal()`
+Prevent properties from being added to or deleted from the referent.
+Return this `Debugger.Object` instance. (This function behaves like the
+standard `Object.seal` function, except that the object to be sealed is
+implicit and in a different compartment from the caller.)
+
+### `freeze()`
+Prevent properties from being added to or deleted from the referent, and
+mark each property as non-writable. Return this `Debugger.Object`
+instance. (This function behaves like the standard `Object.freeze`
+function, except that the object to be sealed is implicit and in a
+different compartment from the caller.)
+
+### `preventExtensions()`
+Prevent properties from being added to the referent. (This function
+behaves like the standard `Object.preventExtensions` function, except
+that the object to operate on is implicit and in a different compartment
+from the caller.)
+
+### `isSealed()`
+Return true if the referent is sealed—that is, if it is not extensible,
+and all its properties have been marked as non-configurable. (This
+function behaves like the standard `Object.isSealed` function, except
+that the object inspected is implicit and in a different compartment
+from the caller.)
+
+### `isFrozen()`
+Return true if the referent is frozen—that is, if it is not extensible,
+and all its properties have been marked as non-configurable and
+read-only. (This function behaves like the standard `Object.isFrozen`
+function, except that the object inspected is implicit and in a
+different compartment from the caller.)
+
+### `isExtensible()`
+Return true if the referent is extensible—that is, if it can have new
+properties defined on it. (This function behaves like the standard
+`Object.isExtensible` function, except that the object inspected is
+implicit and in a different compartment from the caller.)
+
+### `makeDebuggeeValue(value)`
+Return the debuggee value that represents <i>value</i> in the debuggee.
+If <i>value</i> is a primitive, we return it unchanged; if <i>value</i>
+is an object, we return the `Debugger.Object` instance representing
+that object, wrapped appropriately for use in this `Debugger.Object`'s
+referent's compartment.
+
+Note that, if <i>value</i> is an object, it need not be one allocated
+in a debuggee global, nor even a debuggee compartment; it can be any
+object the debugger wishes to use as a debuggee value.
+
+As described above, each `Debugger.Object` instance presents its
+referent as viewed from a particular compartment. Given a
+`Debugger.Object` instance <i>d</i> and an object <i>o</i>, the call
+<code><i>d</i>.makeDebuggeeValue(<i>o</i>)</code> returns a
+`Debugger.Object` instance that presents <i>o</i> as it would be seen
+by code in <i>d</i>'s compartment.
+
+### `isSameNative(value)`
+If <i>value</i> is a native function in the debugger's compartment, return
+whether the referent is a native function for the same C++ native.
+
+### `isNativeGetterWithJitInfo()`
+Return whether the referent is a native getter function with JSJitInfo.
+
+### `decompile([pretty])`
+If the referent is a function that is debuggee code, return the
+JavaScript source code for a function definition equivalent to the
+referent function in its effect and result, as a string. If
+<i>pretty</i> is present and `true`, produce indented code with line
+breaks. If the referent is not a function that is debuggee code, return
+`undefined`.
+
+### `call(this, argument, ...)`
+If the referent is callable, call it with the given <i>this</i> value
+and <i>argument</i> values, and return a [completion value][cv]
+describing how the call completed. <i>This</i> should be a debuggee
+value, or `{ asConstructor: true }` to invoke the referent as a
+constructor, in which case SpiderMonkey provides an appropriate `this`
+value itself. Each <i>argument</i> must be a debuggee value. All extant
+handler methods, breakpoints, and so on remain active
+during the call. If the referent is not callable, throw a `TypeError`.
+This function follows the [invocation function conventions][inv fr].
+
+Note: If this method is called on an object whose owner
+[Debugger object][debugger-object] has an onNativeCall handler, only hooks
+on objects associated with that debugger will be called during the evaluation.
+
+### `apply(this, arguments)`
+If the referent is callable, call it with the given <i>this</i> value
+and the argument values in <i>arguments</i>, and return a
+[completion value][cv] describing how the call completed. <i>This</i>
+should be a debuggee value, or `{ asConstructor: true }` to invoke
+<i>function</i> as a constructor, in which case SpiderMonkey provides
+an appropriate `this` value itself. <i>Arguments</i> must either be an
+array (in the debugger) of debuggee values, or `null` or `undefined`,
+which are treated as an empty array. All extant handler methods,
+breakpoints, and so on remain active during the call. If
+the referent is not callable, throw a `TypeError`. This function
+follows the [invocation function conventions][inv fr].
+
+Note: If this method is called on an object whose owner
+[Debugger object][debugger-object] has an onNativeCall handler, only hooks
+on objects associated with that debugger will be called during the evaluation.
+
+### `executeInGlobal(code, [options])`
+If the referent is a global object, evaluate <i>code</i> in that global
+environment, and return a [completion value][cv] describing how it completed.
+<i>Code</i> is a string. All extant handler methods, breakpoints,
+and so on remain active during the call (pending note below). This function
+follows the [invocation function conventions][inv fr].
+If the referent is not a global object, throw a `TypeError` exception.
+
+<i>Code</i> is interpreted as strict mode code when it contains a Use
+Strict Directive.
+
+This evaluation is semantically equivalent to executing statements at the
+global level, not an indirect eval. Regardless of <i>code</i> being strict
+mode code, variable declarations in <i>code</i> affect the referent global
+object.
+
+The <i>options</i> argument is as for [`Debugger.Frame.prototype.eval`][fr eval].
+
+Note: If this method is called on an object whose owner
+[Debugger object][debugger-object] has an onNativeCall handler, only hooks
+on objects associated with that debugger will be called during the evaluation.
+
+### `executeInGlobalWithBindings(code, bindings, [options])`
+Like `executeInGlobal`, but evaluate <i>code</i> using the referent as the
+variable object, but with a lexical environment extended with bindings
+from the object <i>bindings</i>.
+
+An extra environment is created with bindings specified by <i>bindings</i>.
+The environment contains bindings corresponding to each own enumerable property
+of <i>bindings</i>, where the property name <i>name</i> as binding name,
+and the property value <i>value</i> as binding's initial value.
+
+If `options.useInnerBindings` is not specified or is specified as `false`,
+it emulates where the bindings environment is placed outside of global,
+which means, if the binding conflicts with any global variable declared in
+the <i>code</i>, or any existing global variable, the binding is ignored.
+
+If `options.useInnerBindings` is speified as `true`, it directly performs as
+the bindings environment is placed inside the global, and the provided bindings
+shadow the global variables.
+
+Each <i>value</i> must be a debuggee value.
+
+This is not like a `with` statement: <i>code</i> may access, assign to, and
+delete the introduced bindings without having any effect on the passed
+<i>bindings</i> object, because the properties are copied to a new object for
+each invocation.
+
+This method allows debugger code to introduce temporary bindings that
+are visible to the given debuggee code and which refer to debugger-held
+debuggee values, and do so without mutating any existing debuggee
+environment.
+
+Note that, like `executeInGlobal`, any declarations it contains affect the
+referent global object, even as <i>code</i> is evaluated in an environment
+extended according to <i>bindings</i>. (In the terms used by the ECMAScript
+specification, the `VariableEnvironment` of the execution context for
+<i>code</i> is the referent, and the <i>bindings</i> appear in a new
+declarative environment, which is the eval code's `LexicalEnvironment`.)
+
+The <i>options</i> argument is as for [`Debugger.Frame.prototype.eval`][fr eval].
+
+Note: If this method is called on an object whose owner
+[Debugger object][debugger-object] has an onNativeCall handler, only hooks
+on objects associated with that debugger will be called during the evaluation.
+
+### `createSource(options)`
+If the referent is a global object, return a new JavaScript source in the
+global's realm which has its properties filled in according to the `options`
+object. If the referent is not a global object, throw a `TypeError`
+exception. The `options` object can have the following properties:
+ * `text`: String contents of the JavaScript in the source.
+ * `url`: URL the resulting source should be associated with.
+ * `startLine`: Starting line of the source.
+ * `startColumn`: Starting column of the source.
+ * `sourceMapURL`: Optional URL specifying the source's source map URL.
+ If not specified, the source map URL can be filled in if specified by
+ the source's text.
+ * `isScriptElement`: Optional boolean which will set the source's
+ `introductionType` to `"inlineScript"` if specified. Otherwise, the
+ source's `introductionType` will be `undefined`.
+
+### `asEnvironment()`
+If the referent is a global object, return the [`Debugger.Environment`][environment]
+instance representing the referent's global lexical scope. The global
+lexical scope's enclosing scope is the global object. If the referent is
+not a global object, throw a `TypeError`.
+
+### `unwrap()`
+If the referent is a wrapper that this `Debugger.Object`'s compartment
+is permitted to unwrap, return a `Debugger.Object` instance referring to
+the wrapped object. If we are not permitted to unwrap the referent,
+return `null`. If the referent is not a wrapper, return this
+`Debugger.Object` instance unchanged.
+
+### `unsafeDereference()`
+Return the referent of this `Debugger.Object` instance.
+
+If the referent is an inner object (say, an HTML5 `Window` object),
+return the corresponding outer object (say, the HTML5 `WindowProxy`
+object). This makes `unsafeDereference` more useful in producing values
+appropriate for direct use by debuggee code, without using [invocation functions][inv fr].
+
+This method pierces the membrane of `Debugger.Object` instances meant to
+protect debugger code from debuggee code, and allows debugger code to
+access debuggee objects through the standard cross-compartment wrappers,
+rather than via `Debugger.Object`'s reflection-oriented interfaces. This
+method makes it easier to gradually adapt large code bases to this
+Debugger API: adapted portions of the code can use `Debugger.Object`
+instances, but use this method to pass direct object references to code
+that has not yet been updated.
+
+### `forceLexicalInitializationByName(binding)`
+If <i>binding</i> is in an uninitialized state initialize it to undefined
+and return true, otherwise do nothing and return false.
+
+### `getPromiseReactions`
+
+If the referent is a [`Promise`][promise] or a cross-compartment wrapper of one,
+this returns an array of objects describing the reaction records added to the
+promise. There are several different sorts of reaction records:
+
+- The array entry for a reaction record added with `then` or `catch` has the
+ form `{ resolve: F, reject: F, result: P }`, where each `F` is a `Debugger.Object`
+ referring to a function object, and `P` is the promise that will be resolved
+ with the result of calling them.
+
+ The `resolve` and `reject` properties may be absent in some cases. A call to
+ `then` can omit the rejection handler, and a call to `catch` omits the
+ resolution handler. Furthermore, various promise facilities create records
+ like this as internal implementation details, creating handlers that are not
+ representable as JavaScript functions.
+
+- When a promise `P1` is resolved to another promise `P2` (such that resolving
+ `P2` resolves `P1` in the same way) that adds a reaction record to `P2`. The
+ array entry for that reaction record is simply the `Debugger.Object`
+ representing `P1`.
+
+ Note that, if `P1` and `P2` are in different compartments, resolving `P1` to
+ `P2` creates the same sort of reaction record as a call to `then` or
+ `catch`, with `P1` stored only in a private slot of the `resolve` and
+ `reject` functions, and not directly available from the reaction record.
+
+- An `await` expression calls `PromiseResolve` on its operand to obtain a
+ promise `P`, and then adds a reaction record to `P` that resumes the
+ suspended call appropriately. The array entry for that reaction record is a
+ `Debugger.Frame` representing the suspended call.
+
+ If the `await`'s operand `A` is a native promise with the standard
+ constructor, then `PromiseResolve` simply returns `A` unchanged, and the
+ reaction record for resuming the suspended call is added to `A`'s list. But
+ if `A` is some other sort of 'thenable', then `PromiseResolve` creates a new
+ promise and enqueues a job to call `A`'s `then` method; this may produce
+ more indirect chains from awaitees to awaiters.
+
+- `JS::AddPromiseReactions` and
+ `JS::AddPromiseReactionsIgnoringUnhandledRejection` create a reaction record
+ whose promise field is `null`.
+
+[debugger-object]: Debugger.md
+[script]: Debugger.Script.md
+[environment]: Debugger.Environment.md
+[promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
+[saved-frame]: ../SavedFrame/index
+
+[tracking-allocs]: Debugger.Memory.md#trackingallocationsites
+[inv fr]: Debugger.Frame.md#invocation-functions-and-debugger-frames
+[wouldrun]: Conventions.md#the-debugger-debuggeewouldrun-exception
+[cv]: Conventions.md#completion-values
+[fr eval]: Debugger.Frame.md#eval-code-options