About

ctx-module.js implements a CommonJS-style module system for NodeJS which has a high degree of compatibility with the default module system, npm, etc -- but which exists in a separate vm context and not share an exports object graph, cache, etc, with the default module system.

Raison d'Etre

This library was created so that we could run unit tests of client-server architecture libraries which have namespace collisions and are intended to operate as singletons. Rather than making our tests rely on starting/stopping external daemons, we create the daemon in the test and connect to it from the same client. This also lets us deeply inspect the state of both components during a test, and step through both sides of a conversation with a single debugger.

This module system is sufficiently complete to load Distributive's dcp-client library, which has signficant dependencies and tinkers with module filename resolution.

Unsupported Features

• ESMs (undefined behaviour)

Supported Features

• CommonJS Modules/1.1.1
• return exports idiom
• module.exports re-assignment
• __filename, __dirname
• require.main
• require.extensions
• node_modules / package.json / index.js
• JSON modules (.json)
• NAPI modules (.node)
• MODULE_NOT_FOUND error code
• module module with a Module class with limited support for userland manipulation of _resolveFilename, _cache, etc.
• Monkey-patched vm module so that "this context" refers to CtxModule's contextLoad node modules into an alternate context

API

CtxModule(ctx, cnId, moduleCache, parent)

CtxModule constructor; creates a new module.

ctx

the context object in which the module will be created

cnId

optional string which is the canonical module id (usually filename) of the module. This parameter must be a filename for any module which wants to use require for relative-named modules.

moduleCache

optional per-ctx object which holds loaded modules, or strings which hold the filenames where the source code for the module is located. This parameter is necessary for any module which wants to use require. Properties of this object are either search-path or canonical module identifiers.

parent

optional object which is an instanceof CtxModule or a CtxModule-duck which at least has a require method.

makeNodeProgramContext

Factory function which creates a fresh context suitable for running NodeJS programs. Default modules such as fs, os, vm, path, process, tty, etc, are linked from the calling context.

contextName

optional string which specifies the name of the context

moreModules

optional object shaped like moduleCache which can inject modules from the outer context. Each property name is either the canonical module identifier (usually a rooted pathname) or a search-path module identifier (eg "path"). Each property must be either a string containing the module's filename, or an object containing the module's exports.

Example

const vm = require('vm');
const ctx = require('ctx-module').makeNodeProgramContext();

vm.runInContext('require("dcp-client").init()', ctx).then(console.log('initialized dcp-client'));

Author

Wes Garland, Distributive Corp.

LICENSE

Released under the terms of the MIT License; see LICENSE file.