vm-jumpstart v0.0.0

vm-jumpstart

Easily initialize a JavaScript VM with a set of (asynchronously read) js files in addition to the initSandbox.

Dependencies/Libraries

Node.js - server-side JS platform (vers. >= 0.10.x should work fine)

bluebird - JavaScript Promises library

Why?

Node's javascript VMs probably need to be loaded up with js from a bunch of files on disk often enough.

Some might find dealing with the asynchronous parts of reading multiple files from disk and loading them into a VM via vm.runInContext(code, context, [filename]) after running vm.createContext([initSandbox]) slightly tedious. Since synchronous filereads are evil (block the entire application while they're happening), this small library streamlines doing it asynchronously.

Caveats

This library's functionality is asynchronous. That's a good thing, but it means you'll need to receive the generated VM in a callback function.

Installation and Usage

Enter your existing node project's directory.

Install the node module as a dependency (and save the dependency to package.json):

npm install vm-jumpstart --save

In your code, you'll need to require vm-jumpstart. You'll want create a config object that meets your needs. You'll also want some callback to access to vmContext you're generating.

var jumpstartVM = require('vm-jumpstart').jumpstart;

var vmConfig = {
        initSandbox: { //optional - defaults to {}
            // setup your vm sandbox
            // http://nodejs.org/api/vm.html#vm_vm_createcontext_initsandbox
        },
        srcFilepaths: [
            // insert absolute filepaths for your code, in the order in which they should be loaded into the vm
            // e.g. "/home/usr/blah/blah/bah/srcfileA.js",
            //      "/home/usr/blah/blah/bah/srcfileB.js"
        ],
        stacktraceFileNamer: function(filepath) { //optional - defaults to showing just the filename and extension
          // function to detemine how each filepath for loaded code is formatted in any errors in the vm
          return filepath; //e.g. show full filepath
    	}
    }
};

jumpstartVM(vmConfig, function callback(err, vmObj) {
	// if there were no errors:
	//   vmObj.vmConfig should contain the vmConfig that was passed to jumpstart (with some normalization)
	//   vmObj.vmContext should contain the vm context that was generated -- which you probably want to interract with

	// you're on your own with what you want to do with the vm
});

Testing

There's not a lot happening in the tests, but they can serve as a mini-demo, if nothing else. You can run them by going to the node_module directory for vm_jumpstart and running:

npm test

License

MIT