Confirm
496
edits
Changes
[master 03795a6] Document safe getter value descriptors.
where <i>getter</i> and <i>setter</i> are grips on the property's getter and setter functions. These may be <tt>{ "type":"undefined" }</tt> if the property lacks the given accessor function.
A <b>safe getter value descriptor</b> provides a value that an inherited accessor returned when applied to an instance. (See [[#Finding_An_Object's_Prototype_And_Properties|Finding An Object's Prototype And Properties]] for an explanation of why and when such descriptors are used.) Such a descriptor has the form:
{ "getterValue": <i>value</i>, "getterPrototypeLevel": <i>level</i>,
"enumerable":<i>enumerable</i>, "writable":<i>writable</i> }
where <i>value</i> is a grip on the value the getter returned, <i>level</i> is the number of steps up the object's prototype chain one must take to find the object on which the getter appears as an own property. If the getter appears directly on the object, <i>level</i> is zero. The <i>writable</i> property is true if the inherited accessor has a setter, and false otherwise.
For example, if the JavaScript program being debugged evaluates the expression:
{ "from":<i>actor</i>, "prototype":{ "type":"object", "class":"Object", "actor":<i>objprotoActor</i> },
"ownProperties":{ "x":{ "enumerable":true, "configurable":true, "writeable":true, "value":10 },
}
}
Sending a [[#Finding_An_Object's_Prototype_And_Properties|"prototypeAndProperties"]] request to an object actor referring to a DOM mouse event might produce the following reply:
{ "from":<i>mouseEventActor</i>, "prototype":{ "type":"object", "class":"MouseEvent", "actor":<i>mouseEventProtoActor</i> },
"ownProperties":{ }
"safeGetterValues":{ "screenX": { "valueViaSafeGetter": 1000, "getterPrototypeLevel": 1,
"enumerable": true, "writable": false },
"screenY": { "valueViaSafeGetter": 1000, "getterPrototypeLevel": 1,
"enumerable": true, "writable": false },
"clientX": { "valueViaSafeGetter": 800, "getterPrototypeLevel": 1,
"enumerable": true, "writable": false },
"clientY": { "valueViaSafeGetter": 800, "getterPrototypeLevel": 1,
"enumerable": true, "writable": false },
<i>...</i>
}
}
with a <i>name</i>:<i>descriptor</i> pair for each of the object's own properties.
The web makes extensive use of inherited accessor properties; for example, the <code>clientX</code> and <code>clientY</code> properties of a mouse click event are actually accessor properties which the event object inherits from its prototype chain. It can be very valuable to display such properties' values directly on the object (taking care to distinguish them from true "own" properties), if the server can determine that the getters can be called without side effects.
To this end, when possible, the server may provide safe getter value descriptors for an object, as described in [[#Property_Descriptors|Property Descriptors]] above, reporting the values that getter functions found on the object's prototype chain return when applied to that object. If the server chooses to provide any, the reply includes a <code>"safeGetterValues"</code> property of the form:
{ <i>name</i>:<i>descriptor</i>, ... }
with a <i>name</i>:<i>descriptor</i> pair for each safe getter the object inherits from its prototype chain, or that appears directly on the object. Each <i>descriptor</i> here is a safe getter value descriptor.
<i>TODO: What about objects with many properties?</i>
