vm-shim v0.0.6

vm-shim

This began as a wan attempt to reproduce/polyfill/infill the Node.JS vm#runIn<Some?>Context() methods in browsers. It has transformed into the present tan muscular self-assured and smiling project before you.

I'd wanted to show that shimming vm in the browser really could be done directly, partly to avoid iframes (which vm-browserify uses) to create and clone globals and contexts, and partly to side-step Node.js's contra-normative implementations of runInContext methods.

It's actually a "why didn't I think of that?" solution to problems such as -

• why don't vm methods accept functions as arguments, not just strings?
• why don't eval() and Function() accept functions as arguments?
• why do eval() and Function() leak un-var'd symbols to the global scope, in browser & node.js environments?
• how can we inspect items defined in closures?
• how can we override (or mock) them?

methods provided (so far)

• vm#runInContext(code, context)
• vm#runInNewContext(code, context)
• vm#runInThisContext(code)

not provided (yet)

• vm#.createContext
• vm#.createScript
• script.runInThisContext()
• script.runInNewContext([sandbox])

install

npm install vm-shim

git clone https://github.com/dfkaye/vm-shim.git    
 

implementation

Starting with vm.runInContext(code, context), the Function() constructor is at the core. The code param may be either a string or a function. The context param is a simple object with key-value mappings. For any key on the context, a new var for that key is prefixed to the code. The code is passed in to Function() so that the keynames can't leak outside the new function's scope.

Refactored 8 Nov 2013: a lot of little things involved - biggest is that runInThisContext now uses eval() internally, and the other two use with() inside of Function(). Who says you can't use with()?

10 Nov Having discovered that eval() leaks globals (!?!) if symbols are not var'd, all methods rely on a helper method to scrape EVERY global added by its internal eval() (or Function()) call.

10 Dec: removed use of with.

example tests

The unit tests demonstrate how runInContext and runInNewContext methods work by passing a context param containing a reference to the test's expectation object or function.

Example runInContext test passes the expect function via context argument:

it("overrides external scope vars with context attrs", function() {

  var attr = "shouldn't see this";
  
  var context = {
    attr: 'ok', 
    expect: expect  // <-- pass expect here
  };
  
  vm.runInContext(function(){
    expect(attr).toBe('ok');
    expect(attr).not.toBe('should not see this');
  }, context); 
  
});

Example runInNewContext test to verify context is returned:

it('should return context object', function () {
  var context = { name: 'test' };
  
  var result = vm.runInNewContext('', context);
  
  expect(result).toBe(context);
  expect(result.name).toBe('test');
});

Example runInThisContext test to verify accidental is not placed on global scope:

it("should not leak accidental (un-var'd) globals", function() {

  vm.runInThisContext(function(){
    accidental = 'defined';
  });
  
  expect(global.accidental).not.toBeDefined();
});

node tests

Using Misko Hevery's jasmine-node to run command line tests on node (even though this project initially aimed at a browser shim).

The package.json file defines three test script commands to run the tests via jasmine-node without the browsers:

npm test 
# => jasmine-node --verbose ./test/suite.spec.js

npm run test-vm 
# => jasmine-node --verbose ./test/vm-shim.spec.js

browser tests

Using @pivotallabs' jasmine-2.0.0 for the browser suite.

The jasmine2 browser test page is viewable on rawgit.

Using Toby Ho's MAGNIFICENT testemjs to drive tests in multiple browsers for jasmine-2.0.0 (see how to hack testem for jasmine 2), as well as jasmine-node. The testem.json file uses the standalone test page above, and also uses a custom launcher for jasmine-node (v 1.3.1).

View both test types at the console by running:

testem -l j

history

Just noting for the record:

• Original idea emerged late at night 17 SEPT 2013
• First implemented with rawgit approach 18 SEPT,
• Full success including objects as properties of the context argument 19 SEPT.
• Breaking the usual TDD procedure:
  • Started with console statements and prayer ~ removed both for real unit tests
  • Tape tests added 20 SEPT.
  • Jasmine tests/page added 20 SEPT.
• Error, and leakage tests added 21 SEPT.
• runInNewContext, runInThisContext methods added; runInContext refactored 4 OCT 2013
• CoffeeScript test with jasmine-node added 6 OCT
• tape test written in CoffeeScript test added 7 OCT
• scope injection tests started 21 OCT
• scope injection: spec started, tests updated, testem.json added 6 NOV 2013
• massive refactoring 8 NOV 2013
  • certain cases were just wrong (needed 'eval()' for 'runInThisContext()', e.g.)
  • new/completed bdd specs for both vm-shim and scope mocking (temp name is 'mockScope')
• last global leakage fixed 10 NOV
• deleted CoffeeScript and tape tests (fun but extra work for now) 11 NOV
• rawgit-viewable test page that also works with testem 12 NOV
• moved mock scope stuff to metafunction project 18 NOV