+
lively.vm
+
+
lively.vm provides the ability to evaluate JavaScript code in an evaluation context. Normally the JavaScript eval() function uses the local scope of the function it was called in (however, there are some additional weird rules ). It offers no further options about scope and bindings.
+
+
lively.vm has a range of options that control what bindings are available inside the executed code and also how top-level assignments inside the evaluated code are captured. The latter is helpful when you want to access intermediate results and assignments caused by the evaluation, e.g. to allow incremental development.
+
+
Example
+
+
When you press the eval button below the content of the text area is passed to lively.vm.runEval(source, options) and the result printed.
+
+
+
+
+
+
+
+
+
+
Usage
+
+
+ In it's simplest form, use lively.vm.syncEval(code, options). The return value is a result object whose value is the return value of the last statement in the evaluated code;
+
+lively.vm.syncEval("3 + 4");
+=> {
+ value: 7,
+ isError: false,
+ isPromise: false,
+ warnings: []
+}
+
+
+
+
bindings
+
+
+ To capture the bindings of top-level variables inside the evaluated code, use the topLevelVarRecorder option. Note that this will not pollute the global namespace.
+
+var bindings = {};
+lively.vm.syncEval(
+ "var x = 3; var y = 4; x + y;",
+ {topLevelVarRecorder: bindings});
+=> {value: 7}
+bindings.x
+=> 3
+bindings.y
+=> 4
+
+
+
+
+ Similarly, you can make pass bindings into the evaluation:
+
+var bindings = {x: 99};
+lively.vm.syncEval("x = x + 2;", {topLevelVarRecorder: bindings});
+=> {value: 101}
+bindings.x
+=> 101
+
+
+
+
callbacks and asynchronous evaluation, custom transpilers
+
+ lively.vm.runEval supports evaluation processes that are asynchronous. runEval itself will return a Promise that resolves to the eval result object. You can also specify an onEndEval handler to be notified when the evaluation is done. The following example also uses the transpileroption to allow top-level await (your JavaScript VM needs to support that, alternatively use a transpiler like babeljs in the transpiler function you pass to lively.vm).
+
+
+await lively.vm.runEval(
+ "await new Promise((resolve, reject) => setTimeout(() => resolve(42), 1000));", {
+ topLevelVarRecorder: {},
+ wrapInStartEndCall: true,
+ transpiler: source => "(async function() {" + source + "})()",
+ onEndEval: (err, value) => console.log("evaluation done", value)
+});
+=> will print "42" after 1 sec.
+
+
+
Using it with lively.modules
+
+ lively.modules is a module system that supports interactive runtime changes of source code. When lively.modules is loaded and SystemJS are loaded, you can pass a targetModule option to lively.vm that will run the evaluation in the context of the module, having access to all top-level module bindings (and being able to change those).
+
+
Assuming we have a module "test.js" with the following code:
+
+var x = 3;
+export var y = x + 4;
+
+
+
lively.vm can be used to access as well as modify exports and module internal state:
+
+await lively.vm.runEval("x", {targetModule: "test.js"});
+=> {value: 3}
+await lively.vm.runEval("y = 10", {targetModule: "test.js"});
+(await System.import("test.js")).y
+=> 10
+
+
+
+
dynamic code completions
+
+To inspect objects from an editor or repl and get auto completions of properties and methods you can use lively.vm.completions.getCompletions. The result of the getCompletions call is a nested list, providing the prototype hierarchy of the completion target and their respective attributes/methods.
+
+var someObject = {
+ aProperty: 23,
+ anotherProperty: "hello world",
+ xProperty: 99
+}, bindings = {topLevelVarRecorder: {someObject}}
+
+let result = await lively.vm.completions.getCompletions(
+ source => lively.vm.syncEval(source, bindings),
+ "someObject.a");
+
+=> {
+ code: "someObject",
+ startLetters: "a",
+ completions: [
+ ["[object Object]",
+ ["aProperty",
+ "anotherProperty",
+ "xProperty"]
+ ],
+ ["Object",
+ ["__defineGetter__()",
+ "__defineSetter__()",
+ "__lookupGetter__()",
+ "__lookupSetter__()",
+ "constructor()",
+ "hasOwnProperty()",
+ "isPrototypeOf()",
+ "propertyIsEnumerable()",
+ "toLocaleString()",
+ "toString()",...]
+ ]],
+}
+
+
+
+
+
notifications
+
+
There are two types of system-wide notifications:
+
+{type: "lively.vm/doitrequest", code, targetModule, waitForPromise}
+{type: "lively.vm/doitresult", code, targetModule, waitForPromise, result}
+
+
These notifications are all emitted with lively.notifications.
+
+
+
License
+
MIT
+
