From 1eb9fc5f336aa1f797aad4b3374bd5acbd31f19d Mon Sep 17 00:00:00 2001 From: Kevin Gadd Date: Wed, 25 Apr 2012 00:11:06 -0700 Subject: [PATCH] docs: add warning to vm module docs Add a clear warning about known issues with the module and a pointer to the GitHub issues list for the module. Describe some of the biggest known issues with the module. --- doc/api/vm.markdown | 40 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/doc/api/vm.markdown b/doc/api/vm.markdown index 895329553b..49df036f2f 100644 --- a/doc/api/vm.markdown +++ b/doc/api/vm.markdown @@ -1,6 +1,6 @@ # Executing JavaScript - Stability: 3 - Stable + Stability: 2 - Unstable. See Caveats, below. @@ -10,6 +10,44 @@ You can access this module with: JavaScript code can be compiled and run immediately or compiled, saved, and run later. +## Caveats + +The `vm` module has many known issues and edge cases. If you run into +issues or unexpected behavior, please consult +[the open issues on GitHub](https://github.com/joyent/node/issues/search?q=vm). +Some of the biggest problems are described below. + +### Sandboxes + +The `sandbox` argument to `vm.runInNewContext` and `vm.createContext`, +along with the `initSandbox` argument to `vm.createContext`, do not +behave as one might normally expect and their behavior varies +between different versions of Node. + +The key issue to be aware of is that V8 provides no way to directly +control the global object used within a context. As a result, while +properties of your `sandbox` object will be available in the context, +any properties from the `prototype`s of the `sandbox` may not be +available. Furthermore, the `this` expression within the global scope +of the context evaluates to the empty object (`{}`) instead of to +your sandbox. + +Your sandbox's properties are also not shared directly with the script. +Instead, the properties of the sandbox are copied into the context at +the beginning of execution, and then after execution, the properties +are copied back out in an attempt to propagate any changes. + +### Globals + +Properties of the global object, like `Array` and `String`, have +different values inside of a context. This means that common +expressions like `[] instanceof Array` or +`Object.getPrototypeOf([]) === Array.prototype` may not produce +expected results when used inside of scripts evaluated via the `vm` module. + +Some of these problems have known workarounds listed in the issues for +`vm` on GitHub. for example, `Array.isArray` works around +the example problem with `Array`. ## vm.runInThisContext(code, [filename])