src: add require transform pipeline

doc/api/globals.md

@@ -245,6 +245,55 @@ added: v0.3.0
 Use the internal `require()` machinery to look up the location of a module,
 but rather than loading the module, just return the resolved filename.
 
+### require.addTransform(transform)
+
+* `transform` {Function} A function to use to transform module text given the
+  content and full path to the file.
+
+Add a transform function to modify contents of a file loaded with `require()`
+before passing it to the parser. This enables pre-compile transformations such
+as transpiling code, replacing an interface with mock functions for testing or
+instrumenting code for purposes such as gathering code coverage metrics or
+tracing application behavior and measuring performance.
+
+The `transform` function accepts the content string and full file path as the
+first and second arguments. The function is expected to return a new content
+string as the result of the transformation.
+
+Multiple transforms may be added to the pipeline and will be applied in the
+order they are added.
+
+
+```js
+require.addTransform((content, filepath) => {
+  // Only apply the transform to a specific file
+  if (!/my\-module\.js$/.test(filename)) {
+    return content;
+  }
+  return `
+  ${content}
+  const originalFunction = exports.someFunction;
+  exports.someFunction = function myMockedFunction(first, second, callback) {
+    var start = process.hrtime();
+    function wrappedCallback() {
+      var end = process.hrtime(start);
+      console.log('execution time: %ds', end[0] + (end[1] / 1000000000));
+      return callback(this, arguments);
+    }
+    return someFunction.call(null, first, second, wrappedCallback);
+  }
+  `;
+});
+```
+
+### require.removeTransform(transform)
+
+* `transform` {Function} A function previously given to `require.addTransform()`
+  which will be removed from the transform pipeline.
+
+Removes a transform function from the transform pipeline so it will no longer
+be applied to the contents of files loaded in future `require()` calls.
+
 ## setImmediate(callback[, ...args])
 <!-- YAML
 added: v0.9.1

lib/internal/bootstrap_node.js

@@ -9,6 +9,8 @@
 
 (function(process) {
 
+  let internalModule;
+
   function startup() {
     const EventEmitter = NativeModule.require('events');
     process._eventsCount = 0;
@@ -34,6 +36,7 @@
     }
 
     const _process = NativeModule.require('internal/process');
+    internalModule = NativeModule.require('internal/module');
 
     _process.setup_hrtime();
     _process.setup_cpuUsage();
@@ -118,7 +121,6 @@
         // '--interactive'
         preloadModules();
 
-        const internalModule = NativeModule.require('internal/module');
         internalModule.addBuiltinLibsToObject(global);
         run(() => {
           evalScript('[eval]');
@@ -445,7 +447,6 @@
   function checkScriptSyntax(source, filename) {
     const Module = NativeModule.require('module');
     const vm = NativeModule.require('vm');
-    const internalModule = NativeModule.require('internal/module');
 
     // remove shebang and BOM
     source = internalModule.stripBOM(source.replace(/^#!.*/, ''));
@@ -544,6 +545,11 @@
 
   NativeModule.prototype.compile = function() {
     var source = NativeModule.getSource(this.id);
+    // NOTE: internalModule is loaded through NativeModule,
+    // so this step needs to be skipped until after that.
+    if (internalModule) {
+      source = internalModule.applyTransforms(source, this.filename);
+    }
     source = NativeModule.wrap(source);
 
     this.loading = true;

lib/internal/module.js

@@ -1,13 +1,39 @@
 'use strict';
 
+const assert = require('assert');
+
 exports = module.exports = {
   makeRequireFunction,
   stripBOM,
-  addBuiltinLibsToObject
+  addBuiltinLibsToObject,
+  applyTransforms
 };
 
 exports.requireDepth = 0;
 
+const transforms = [];
+
+function addTransform(transform) {
+  assert(typeof transform === 'function');
+  transforms.push(transform);
+}
+function removeTransform(transform) {
+  const index = transforms.indexOf(transform);
+  if (index >= 0) {
+    transforms.splice(index, 1);
+  }
+}
+
+function applyTransforms(content, filename) {
+  return transforms.reduce((content, transform) => {
+    const next = transform(content, filename);
+    if (typeof next !== 'string') {
+      throw new Error('Module transforms must return the modified content');
+    }
+    return next;
+  }, content);
+}
+
 // Invoke with makeRequireFunction(module) where |module| is the Module object
 // to use as the context for the require() function.
 function makeRequireFunction(mod) {
@@ -27,6 +53,8 @@ function makeRequireFunction(mod) {
   }
 
   require.resolve = resolve;
+  require.addTransform = addTransform;
+  require.removeTransform = removeTransform;
 
   require.main = process.mainModule;
 

lib/module.js

@@ -537,6 +537,8 @@ var resolvedArgv;
 // the file.
 // Returns exception, if any.
 Module.prototype._compile = function(content, filename) {
+  content = internalModule.applyTransforms(content, filename);
+
   // Remove shebang
   var contLen = content.length;
   if (contLen >= 2) {

test/parallel/test-require-transforms.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+
+// Juts so lint doesn't complain about unused common (which is required)
+common.refreshTmpDir();
+
+function fooTransform(content, filename) {
+  if (!/test-require-transforms\.js$/.test(filename)) {
+    return content;
+  }
+  return 'module.exports = "foo"';
+}
+function barTransform(content, filename) {
+  if (!/test-require-transforms\.js$/.test(filename)) {
+    return content;
+  }
+  return content.replace(/foo/, 'bar');
+}
+
+// Test one-step transform
+require.addTransform(fooTransform);
+delete require.cache[require.resolve('./test-require-transforms')];
+const oneStep = require('./test-require-transforms');
+assert.strictEqual(oneStep, 'foo');
+
+// Test two-step transform
+require.addTransform(barTransform);
+delete require.cache[require.resolve('./test-require-transforms')];
+const twoStep = require('./test-require-transforms');
+assert.strictEqual(twoStep, 'bar');
+
+// Test transform step removal
+require.removeTransform(barTransform);
+delete require.cache[require.resolve('./test-require-transforms')];
+const removal = require('./test-require-transforms');
+assert.strictEqual(removal, 'foo');