Skip to content
This repository
Browse code

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.
  • Loading branch information...
commit 1eb9fc5f336aa1f797aad4b3374bd5acbd31f19d 1 parent 34f05a3
K. Gadd kg authored bnoordhuis committed

Showing 1 changed file with 39 additions and 1 deletion. Show diff stats Hide diff stats

  1. +39 1 doc/api/vm.markdown
40 doc/api/vm.markdown
Source Rendered
... ... @@ -1,6 +1,6 @@
1 1 # Executing JavaScript
2 2
3   - Stability: 3 - Stable
  3 + Stability: 2 - Unstable. See Caveats, below.
4 4
5 5 <!--name=vm-->
6 6
@@ -10,6 +10,44 @@ You can access this module with:
10 10
11 11 JavaScript code can be compiled and run immediately or compiled, saved, and run later.
12 12
  13 +## Caveats
  14 +
  15 +The `vm` module has many known issues and edge cases. If you run into
  16 +issues or unexpected behavior, please consult
  17 +[the open issues on GitHub](https://github.com/joyent/node/issues/search?q=vm).
  18 +Some of the biggest problems are described below.
  19 +
  20 +### Sandboxes
  21 +
  22 +The `sandbox` argument to `vm.runInNewContext` and `vm.createContext`,
  23 +along with the `initSandbox` argument to `vm.createContext`, do not
  24 +behave as one might normally expect and their behavior varies
  25 +between different versions of Node.
  26 +
  27 +The key issue to be aware of is that V8 provides no way to directly
  28 +control the global object used within a context. As a result, while
  29 +properties of your `sandbox` object will be available in the context,
  30 +any properties from the `prototype`s of the `sandbox` may not be
  31 +available. Furthermore, the `this` expression within the global scope
  32 +of the context evaluates to the empty object (`{}`) instead of to
  33 +your sandbox.
  34 +
  35 +Your sandbox's properties are also not shared directly with the script.
  36 +Instead, the properties of the sandbox are copied into the context at
  37 +the beginning of execution, and then after execution, the properties
  38 +are copied back out in an attempt to propagate any changes.
  39 +
  40 +### Globals
  41 +
  42 +Properties of the global object, like `Array` and `String`, have
  43 +different values inside of a context. This means that common
  44 +expressions like `[] instanceof Array` or
  45 +`Object.getPrototypeOf([]) === Array.prototype` may not produce
  46 +expected results when used inside of scripts evaluated via the `vm` module.
  47 +
  48 +Some of these problems have known workarounds listed in the issues for
  49 +`vm` on GitHub. for example, `Array.isArray` works around
  50 +the example problem with `Array`.
13 51
14 52 ## vm.runInThisContext(code, [filename])
15 53

0 comments on commit 1eb9fc5

Please sign in to comment.
Something went wrong with that request. Please try again.