f29adc772c07947d16d84a4df351a5d4cdaf3fdb
[WebKit-https.git] / Source / JavaScriptCore / inspector / protocol / Runtime.json
1 {
2     "domain": "Runtime",
3     "description": "Runtime domain exposes JavaScript runtime by means of remote evaluation and mirror objects. Evaluation results are returned as mirror object that expose object type, string representation and unique identifier that can be used for further object reference. Original objects are maintained in memory unless they are either explicitly released or are released along with the other objects in their object group.",
4     "types": [
5         {
6             "id": "RemoteObjectId",
7             "type": "string",
8             "description": "Unique object identifier."
9         },
10         {
11             "id": "RemoteObject",
12             "type": "object",
13             "description": "Mirror object referencing original JavaScript object.",
14             "properties": [
15                 { "name": "type", "type": "string", "enum": ["object", "function", "undefined", "string", "number", "boolean", "symbol"], "description": "Object type." },
16                 { "name": "subtype", "type": "string", "optional": true, "enum": ["array", "null", "node", "regexp", "date", "error", "map", "set", "weakmap", "iterator"], "description": "Object subtype hint. Specified for <code>object</code> type values only." },
17                 { "name": "className", "type": "string", "optional": true, "description": "Object class (constructor) name. Specified for <code>object</code> type values only." },
18                 { "name": "value", "type": "any", "optional": true, "description": "Remote object value (in case of primitive values or JSON values if it was requested)." },
19                 { "name": "description", "type": "string", "optional": true, "description": "String representation of the object." },
20                 { "name": "objectId", "$ref": "RemoteObjectId", "optional": true, "description": "Unique object identifier (for non-primitive values)." },
21                 { "name": "size", "type": "integer", "optional": true, "description": "Size of the array/collection. Specified for array/map/set/weakmap object type values only." },
22                 { "name": "preview", "$ref": "ObjectPreview", "optional": true, "description": "Preview containing abbreviated property values. Specified for <code>object</code> type values only." }
23             ]
24         },
25         {
26             "id": "ObjectPreview",
27             "type": "object",
28             "description": "Object containing abbreviated remote object value.",
29             "properties": [
30                 { "name": "type", "type": "string", "enum": ["object", "function", "undefined", "string", "number", "boolean", "symbol"], "description": "Object type." },
31                 { "name": "subtype", "type": "string", "optional": true, "enum": ["array", "null", "node", "regexp", "date", "error", "map", "set", "weakmap", "iterator"], "description": "Object subtype hint. Specified for <code>object</code> type values only." },
32                 { "name": "description", "type": "string", "optional": true, "description": "String representation of the object." },
33                 { "name": "lossless", "type": "boolean", "description": "Determines whether preview is lossless (contains all information of the original object)." },
34                 { "name": "overflow", "type": "boolean", "optional": true, "description": "True iff some of the properties of the original did not fit." },
35                 { "name": "properties", "type": "array", "items": { "$ref": "PropertyPreview" }, "optional": true, "description": "List of the properties." },
36                 { "name": "entries", "type": "array", "items": { "$ref": "EntryPreview" }, "optional": true, "description": "List of the entries. Specified for <code>map</code> and <code>set</code> subtype values only." },
37                 { "name": "size", "type": "integer", "optional": true, "description": "Size of the array/collection. Specified for array/map/set/weakmap object type values only." }
38             ]
39         },
40         {
41             "id": "PropertyPreview",
42             "type": "object",
43             "properties": [
44                 { "name": "name", "type": "string", "description": "Property name." },
45                 { "name": "type", "type": "string", "enum": ["object", "function", "undefined", "string", "number", "boolean", "symbol", "accessor"], "description": "Object type." },
46                 { "name": "subtype", "type": "string", "optional": true, "enum": ["array", "null", "node", "regexp", "date", "error", "map", "set", "weakmap", "iterator"], "description": "Object subtype hint. Specified for <code>object</code> type values only." },
47                 { "name": "value", "type": "string", "optional": true, "description": "User-friendly property value string." },
48                 { "name": "valuePreview", "$ref": "ObjectPreview", "optional": true, "description": "Nested value preview." },
49                 { "name": "internal", "type": "boolean", "optional": true, "description": "True if this is an internal property." }
50             ]
51         },
52         {
53             "id": "EntryPreview",
54             "type": "object",
55             "properties": [
56                 { "name": "key", "$ref": "ObjectPreview", "optional": true, "description": "Entry key. Specified for map-like collection entries." },
57                 { "name": "value", "$ref": "ObjectPreview", "description": "Entry value." }
58             ]
59         },
60         {
61             "id": "CollectionEntry",
62             "type": "object",
63             "properties": [
64                 { "name": "key", "$ref": "Runtime.RemoteObject", "optional": true, "description": "Entry key of a map-like collection, otherwise not provided." },
65                 { "name": "value", "$ref": "Runtime.RemoteObject", "description": "Entry value." }
66             ]
67         },
68         {
69             "id": "PropertyDescriptor",
70             "type": "object",
71             "description": "Object property descriptor.",
72             "properties": [
73                 { "name": "name", "type": "string", "description": "Property name." },
74                 { "name": "value", "$ref": "RemoteObject", "optional": true, "description": "The value associated with the property." },
75                 { "name": "writable", "type": "boolean", "optional": true, "description": "True if the value associated with the property may be changed (data descriptors only)." },
76                 { "name": "get", "$ref": "RemoteObject", "optional": true, "description": "A function which serves as a getter for the property, or <code>undefined</code> if there is no getter (accessor descriptors only)." },
77                 { "name": "set", "$ref": "RemoteObject", "optional": true, "description": "A function which serves as a setter for the property, or <code>undefined</code> if there is no setter (accessor descriptors only)." },
78                 { "name": "configurable", "type": "boolean", "description": "True if the type of this property descriptor may be changed and if the property may be deleted from the corresponding object." },
79                 { "name": "enumerable", "type": "boolean", "description": "True if this property shows up during enumeration of the properties on the corresponding object." },
80                 { "name": "wasThrown", "type": "boolean", "optional": true, "description": "True if the result was thrown during the evaluation." },
81                 { "name": "isOwn", "optional": true, "type": "boolean", "description": "True if the property is owned for the object." },
82                 { "name": "nativeGetter", "optional": true, "type": "boolean", "description": "True if the property value came from a native getter." }
83             ]
84         },
85         {
86             "id": "InternalPropertyDescriptor",
87             "type": "object",
88             "description": "Object internal property descriptor. This property isn't normally visible in JavaScript code.",
89             "properties": [
90                 { "name": "name", "type": "string", "description": "Conventional property name." },
91                 { "name": "value", "$ref": "RemoteObject", "optional": true, "description": "The value associated with the property." }
92             ]
93         },
94         {
95             "id": "CallArgument",
96             "type": "object",
97             "description": "Represents function call argument. Either remote object id <code>objectId</code> or primitive <code>value</code> or neither of (for undefined) them should be specified.",
98             "properties": [
99                 { "name": "value", "type": "any", "optional": true, "description": "Primitive value." },
100                 { "name": "objectId", "$ref": "RemoteObjectId", "optional": true, "description": "Remote object handle." }
101             ]
102         },
103         {
104             "id": "ExecutionContextId",
105             "type": "integer",
106             "description": "Id of an execution context."
107         },
108         {
109             "id": "ExecutionContextDescription",
110             "type": "object",
111             "description": "Description of an isolated world.",
112             "properties": [
113                 { "name": "id", "$ref": "ExecutionContextId", "description": "Unique id of the execution context. It can be used to specify in which execution context script evaluation should be performed." },
114                 { "name": "isPageContext", "type": "boolean", "description": "True if this is a context where inpspected web page scripts run. False if it is a content script isolated context." },
115                 { "name": "name", "type": "string", "description": "Human readable name describing given context."},
116                 { "name": "frameId", "$ref": "Network.FrameId", "description": "Id of the owning frame." }
117             ]
118         },
119         {
120             "id": "SyntaxErrorType",
121             "type": "string",
122             "enum": ["none", "irrecoverable", "unterminated-literal", "recoverable"],
123             "description": "Syntax error type: \"none\" for no error, \"irrecoverable\" for unrecoverable errors, \"unterminated-literal\" for when there is an unterminated literal, \"recoverable\" for when the expression is unfinished but valid so far."
124         },
125         {
126             "id": "ErrorRange",
127             "type": "object",
128             "description": "Range of an error in source code.",
129             "properties": [
130                 { "name": "startOffset", "type": "integer", "description": "Start offset of range (inclusive)." },
131                 { "name": "endOffset", "type": "integer", "description": "End offset of range (exclusive)." }
132             ]
133         },
134         {
135             "id": "StructureDescription",
136             "type": "object",
137             "properties": [
138                 { "name": "fields", "type": "array",  "items": { "type": "string" }, "optional": true, "description": "Array of strings, where the strings represent object properties." },
139                 { "name": "optionalFields", "type": "array",  "items": { "type": "string" }, "optional": true, "description": "Array of strings, where the strings represent optional object properties." },
140                 { "name": "constructorName", "type": "string", "optional": true, "description": "Name of the constructor." },
141                 { "name": "prototypeStructure", "$ref": "StructureDescription", "optional": true, "description": "Pointer to the StructureRepresentation of the protoype if one exists." },
142                 { "name": "isImprecise", "type": "boolean", "optional": true, "description": "If true, it indicates that the fields in this StructureDescription may be inaccurate. I.e, there might have been fields that have been deleted before it was profiled or it has fields we haven't profiled." }
143             ]
144         },
145         {
146             "id": "TypeSet",
147             "type": "object",
148             "properties": [
149                 { "name": "isFunction", "type": "boolean", "description": "Indicates if this type description has been type Function." },
150                 { "name": "isUndefined", "type": "boolean", "description": "Indicates if this type description has been type Undefined." },
151                 { "name": "isNull", "type": "boolean", "description": "Indicates if this type description has been type Null." },
152                 { "name": "isBoolean", "type": "boolean", "description": "Indicates if this type description has been type Boolean." },
153                 { "name": "isInteger", "type": "boolean", "description": "Indicates if this type description has been type Integer." },
154                 { "name": "isNumber", "type": "boolean", "description": "Indicates if this type description has been type Number." },
155                 { "name": "isString", "type": "boolean", "description": "Indicates if this type description has been type String." },
156                 { "name": "isObject", "type": "boolean", "description": "Indicates if this type description has been type Object." }
157             ]
158         },
159         {
160             "id": "TypeDescription",
161             "type": "object",
162             "description": "Container for type information that has been gathered.",
163             "properties": [
164                 { "name": "isValid", "type": "boolean", "description": "If true, we were able to correlate the offset successfuly with a program location. If false, the offset may be bogus or the offset may be from a CodeBlock that hasn't executed." },
165                 { "name": "leastCommonAncestor", "type": "string", "optional": true, "description": "Least common ancestor of all Constructors if the TypeDescription has seen any structures. This string is the display name of the shared constructor function." },
166                 { "name": "typeSet", "$ref": "TypeSet", "optional": true, "description": "Set of booleans for determining the aggregate type of this type description." },
167                 { "name": "structures", "type": "array", "items": { "$ref": "StructureDescription" }, "optional": true, "description": "Array of descriptions for all structures seen for this variable." },
168                 { "name": "isTruncated", "type": "boolean", "optional": true, "description": "If true, this indicates that no more structures are being profiled because some maximum threshold has been reached and profiling has stopped because of memory pressure." }
169             ]
170         },
171         {
172             "id": "TypeLocation",
173             "type": "object",
174             "description": "Describes the location of an expression we want type information for.",
175             "properties": [
176                 { "name": "typeInformationDescriptor", "type": "integer", "description": "What kind of type information do we want (normal, function return values, 'this' statement)." },
177                 { "name": "sourceID", "type": "string", "description": "sourceID uniquely identifying a script" },
178                 { "name": "divot", "type": "integer", "description": "character offset for assignment range" }
179             ]
180         },
181         {
182             "id": "BasicBlock",
183             "type": "object",
184             "description": "From Wikipedia: a basic block is a portion of the code within a program with only one entry point and only one exit point. This type gives the location of a basic block and if that basic block has executed.",
185             "properties": [
186                 { "name": "startOffset", "type": "integer", "description": "Start offset of the basic block." },
187                 { "name": "endOffset", "type": "integer", "description": "End offset of the basic block." },
188                 { "name": "hasExecuted", "type": "boolean", "description": "Indicates if the basic block has executed before." }
189             ]
190         }
191     ],
192     "commands": [
193         {
194             "name": "parse",
195             "parameters": [
196                 { "name": "source", "type": "string", "description": "Source code to parse." }
197             ],
198             "returns": [
199                 { "name": "result", "$ref": "SyntaxErrorType", "description": "Parse result." },
200                 { "name": "message", "type": "string", "optional": true, "description": "Parse error message." },
201                 { "name": "range", "$ref": "ErrorRange", "optional": true, "description": "Range in the source where the error occurred." }
202             ],
203             "description": "Parses JavaScript source code for errors."
204         },
205         {
206             "name": "evaluate",
207             "parameters": [
208                 { "name": "expression", "type": "string", "description": "Expression to evaluate." },
209                 { "name": "objectGroup", "type": "string", "optional": true, "description": "Symbolic group name that can be used to release multiple objects." },
210                 { "name": "includeCommandLineAPI", "type": "boolean", "optional": true, "description": "Determines whether Command Line API should be available during the evaluation." },
211                 { "name": "doNotPauseOnExceptionsAndMuteConsole", "type": "boolean", "optional": true, "description": "Specifies whether evaluation should stop on exceptions and mute console. Overrides setPauseOnException state." },
212                 { "name": "contextId", "$ref": "Runtime.ExecutionContextId", "optional": true, "description": "Specifies in which isolated context to perform evaluation. Each content script lives in an isolated context and this parameter may be used to specify one of those contexts. If the parameter is omitted or 0 the evaluation will be performed in the context of the inspected page." },
213                 { "name": "returnByValue", "type": "boolean", "optional": true, "description": "Whether the result is expected to be a JSON object that should be sent by value." },
214                 { "name": "generatePreview", "type": "boolean", "optional": true, "description": "Whether preview should be generated for the result." },
215                 { "name": "saveResult", "type": "boolean", "optional": true, "description": "Whether the resulting value should be considered for saving in the $n history." }
216             ],
217             "returns": [
218                 { "name": "result", "$ref": "RemoteObject", "description": "Evaluation result." },
219                 { "name": "wasThrown", "type": "boolean", "optional": true, "description": "True if the result was thrown during the evaluation." },
220                 { "name": "savedResultIndex", "type": "integer", "optional": true, "description": "If the result was saved, this is the $n index that can be used to access the value." }
221             ],
222             "description": "Evaluates expression on global object."
223         },
224         {
225             "name": "callFunctionOn",
226             "parameters": [
227                 { "name": "objectId", "$ref": "RemoteObjectId", "description": "Identifier of the object to call function on." },
228                 { "name": "functionDeclaration", "type": "string", "description": "Declaration of the function to call." },
229                 { "name": "arguments", "type": "array", "items": { "$ref": "CallArgument", "description": "Call argument." }, "optional": true, "description": "Call arguments. All call arguments must belong to the same JavaScript world as the target object." },
230                 { "name": "doNotPauseOnExceptionsAndMuteConsole", "type": "boolean", "optional": true, "description": "Specifies whether function call should stop on exceptions and mute console. Overrides setPauseOnException state." },
231                 { "name": "returnByValue", "type": "boolean", "optional": true, "description": "Whether the result is expected to be a JSON object which should be sent by value." },
232                 { "name": "generatePreview", "type": "boolean", "optional": true, "description": "Whether preview should be generated for the result." }
233             ],
234             "returns": [
235                 { "name": "result", "$ref": "RemoteObject", "description": "Call result." },
236                 { "name": "wasThrown", "type": "boolean", "optional": true, "description": "True if the result was thrown during the evaluation." }
237             ],
238             "description": "Calls function with given declaration on the given object. Object group of the result is inherited from the target object."
239         },
240         {
241             "name": "getProperties",
242             "parameters": [
243                 { "name": "objectId", "$ref": "RemoteObjectId", "description": "Identifier of the object to return properties for." },
244                 { "name": "ownProperties", "optional": true, "type": "boolean", "description": "If true, returns properties belonging only to the object itself, not to its prototype chain." },
245                 { "name": "generatePreview", "type": "boolean", "optional": true, "description": "Whether preview should be generated for property values." }
246             ],
247             "returns": [
248                 { "name": "result", "type": "array", "items": { "$ref": "PropertyDescriptor"}, "description": "Object properties." },
249                 { "name": "internalProperties", "optional": true, "type": "array", "items": { "$ref": "InternalPropertyDescriptor"}, "description": "Internal object properties." }
250             ],
251             "description": "Returns properties of a given object. Object group of the result is inherited from the target object."
252         },
253         {
254             "name": "getDisplayableProperties",
255             "parameters": [
256                 { "name": "objectId", "$ref": "RemoteObjectId", "description": "Identifier of the object to return properties for." },
257                 { "name": "generatePreview", "type": "boolean", "optional": true, "description": "Whether preview should be generated for property values." }
258             ],
259             "returns": [
260                 { "name": "properties", "type": "array", "items": { "$ref": "PropertyDescriptor"}, "description": "Object properties." },
261                 { "name": "internalProperties", "optional": true, "type": "array", "items": { "$ref": "InternalPropertyDescriptor"}, "description": "Internal object properties." }
262             ],
263             "description": "Returns displayable properties of a given object. Object group of the result is inherited from the target object. Displayable properties are own properties, internal properties, and native getters in the prototype chain (assumed to be bindings and treated like own properties for the frontend)."
264         },
265         {
266             "name": "getCollectionEntries",
267             "description": "Returns entries of given Map / Set collection.",
268             "parameters": [
269                 { "name": "objectId", "$ref": "Runtime.RemoteObjectId", "description": "Id of the collection to get entries for." },
270                 { "name": "objectGroup", "optional": true, "type": "string", "description": "Symbolic group name that can be used to release multiple. If not provided, it will be the same objectGroup as the RemoteObject determined from <code>objectId</code>. This is useful for WeakMap to release the collection entries." },
271                 { "name": "startIndex", "optional": true, "type": "integer", "description": "If provided skip to this index before collecting values. Otherwise, 0." },
272                 { "name": "numberToFetch", "optional": true, "type": "integer", "description": "If provided only return <code>numberToFetch</code> values. Otherwise, return values all the way to the end." }
273             ],
274             "returns": [
275                 { "name": "entries", "type": "array", "items": { "$ref": "CollectionEntry" }, "description": "Array of collection entries." }
276             ]
277         },
278         {
279             "name": "saveResult",
280             "parameters": [
281                 { "name": "value", "$ref": "CallArgument", "description": "Id or value of the object to save." },
282                 { "name": "contextId", "optional": true, "$ref": "ExecutionContextId", "description": "Unique id of the execution context. To specify in which execution context script evaluation should be performed. If not provided, determine from the CallArgument's objectId." }
283             ],
284             "returns": [
285                 { "name": "savedResultIndex", "type": "integer", "optional": true, "description": "If the value was saved, this is the $n index that can be used to access the value." }
286             ],
287             "description": "Assign a saved result index to this value."
288         },
289         {
290             "name": "releaseObject",
291             "parameters": [
292                 { "name": "objectId", "$ref": "RemoteObjectId", "description": "Identifier of the object to release." }
293             ],
294             "description": "Releases remote object with given id."
295         },
296         {
297             "name": "releaseObjectGroup",
298             "parameters": [
299                 { "name": "objectGroup", "type": "string", "description": "Symbolic object group name." }
300             ],
301             "description": "Releases all remote objects that belong to a given group."
302         },
303         {
304             "name": "run",
305             "description": "Tells inspected instance(worker or page) that it can run in case it was started paused."
306         },
307         {
308             "name": "enable",
309             "description": "Enables reporting of execution contexts creation by means of <code>executionContextCreated</code> event. When the reporting gets enabled the event will be sent immediately for each existing execution context."
310         },
311         {
312             "name": "disable",
313             "description": "Disables reporting of execution contexts creation."
314         },
315         {
316             "name": "getRuntimeTypesForVariablesAtOffsets",
317             "parameters": [
318                 { "name": "locations", "type": "array", "items": { "$ref": "TypeLocation" }, "description": "An array of type locations we're requesting information for. Results are expected in the same order they're sent in."}
319             ],
320             "returns": [
321                 { "name": "types", "type": "array", "items": { "$ref": "TypeDescription", "description": "Types for requested variable." } }
322             ],
323             "description": "Returns detailed informtation on given function."
324         },
325         {
326             "name": "enableTypeProfiler",
327             "description": "Enables type profiling on the VM."
328         },
329         {
330             "name": "disableTypeProfiler",
331             "description": "Disables type profiling on the VM."
332         },
333         {
334             "name": "getBasicBlocks",
335             "parameters": [
336                 { "name": "sourceID", "type": "string", "description": "Indicates which sourceID information is requested for." }
337             ],
338             "returns": [
339                 { "name": "basicBlocks", "type": "array", "items": { "$ref": "BasicBlock", "description": "Array of basic blocks." } }
340             ],
341             "description": "Returns a list of basic blocks for the given sourceID with information about their text ranges and whether or not they have executed."
342         }
343     ],
344     "events": [
345         {
346             "name": "executionContextCreated",
347             "parameters": [
348                 { "name": "context", "$ref": "ExecutionContextDescription", "description": "A newly created execution contex." }
349             ],
350             "description": "Issued when new execution context is created."
351         }
352     ]
353 }