From f0b9f4243e7308451173cea16ec0234dddb017ad Mon Sep 17 00:00:00 2001
From: Stephen Belanger <admin@stephenbelanger.com>
Date: Tue, 11 Apr 2017 16:30:08 -0700
Subject: [PATCH 1/3] src: let preloaded modules set source transformer

This feature simply passes the content and filename through
a transformer function which could be used for things like
applying AST transforms to the source before it is run.
---
 lib/internal/bootstrap_node.js       |  8 ++++++++
 lib/module.js                        |  4 ++++
 test/fixtures/process-module-wrap.js |  4 ++++
 test/parallel/test-preload.js        | 10 ++++++++++
 4 files changed, 26 insertions(+)
 create mode 100644 test/fixtures/process-module-wrap.js

diff --git a/lib/internal/bootstrap_node.js b/lib/internal/bootstrap_node.js
index b4ed16573e1e07..1df92bfe1dcf8b 100644
--- a/lib/internal/bootstrap_node.js
+++ b/lib/internal/bootstrap_node.js
@@ -412,6 +412,10 @@
   function preloadModules() {
     if (process._preload_modules) {
       NativeModule.require('module')._preloadModules(process._preload_modules);
+      if (process.moduleWrap) {
+        NativeModule.preloadModuleWrap = process.moduleWrap;
+        delete process.moduleWrap;
+      }
     }
   }
 
@@ -474,6 +478,7 @@
   }
 
   NativeModule._source = process.binding('natives');
+  NativeModule.preloadModuleWrap = null;
   NativeModule._cache = {};
 
   NativeModule.require = function(id) {
@@ -544,6 +549,9 @@
 
   NativeModule.prototype.compile = function() {
     var source = NativeModule.getSource(this.id);
+    if (NativeModule.preloadModuleWrap !== null) {
+      source = NativeModule.preloadModuleWrap(source, this.filename);
+    }
     source = NativeModule.wrap(source);
 
     this.loading = true;
diff --git a/lib/module.js b/lib/module.js
index fe83cd0ecb8a26..e71640d438cb59 100644
--- a/lib/module.js
+++ b/lib/module.js
@@ -537,6 +537,10 @@ var resolvedArgv;
 // the file.
 // Returns exception, if any.
 Module.prototype._compile = function(content, filename) {
+  if (NativeModule.preloadModuleWrap !== null) {
+    content = NativeModule.preloadModuleWrap(content, filename);
+  }
+  
   // Remove shebang
   var contLen = content.length;
   if (contLen >= 2) {
diff --git a/test/fixtures/process-module-wrap.js b/test/fixtures/process-module-wrap.js
new file mode 100644
index 00000000000000..ab041c34b0ca82
--- /dev/null
+++ b/test/fixtures/process-module-wrap.js
@@ -0,0 +1,4 @@
+process.moduleWrap = function(content, filename) {
+  if (filename !== 'http.js') return content
+  return content + '\nmodule.exports.hello = "hi";'
+}
diff --git a/test/parallel/test-preload.js b/test/parallel/test-preload.js
index 8dc64cc6c60168..ccfb195ef7480a 100644
--- a/test/parallel/test-preload.js
+++ b/test/parallel/test-preload.js
@@ -29,6 +29,7 @@ const fixtureA = fixture('printA.js');
 const fixtureB = fixture('printB.js');
 const fixtureC = fixture('printC.js');
 const fixtureD = fixture('define-global.js');
+const fixtureE = fixture('process-module-wrap.js');
 const fixtureThrows = fixture('throws_error4.js');
 
 // test preloading a single module works
@@ -146,3 +147,12 @@ childProcess.exec(
     assert.ok(/worker terminated with code 43/.test(stdout));
   }
 );
+
+// test that preload can be used with --eval
+childProcess.exec(
+  nodeBinary + ' ' + preloadOption([fixtureE]) + '-p "require(\'http\').hello"',
+  function(err, stdout, stderr) {
+    assert.ifError(err);
+    assert.strictEqual(stdout, 'hi\n');
+  }
+);

From 6b6ca10558c126d44cf2dcba72c0325eaeb7b698 Mon Sep 17 00:00:00 2001
From: Stephen Belanger <admin@stephenbelanger.com>
Date: Thu, 13 Apr 2017 10:44:35 -0700
Subject: [PATCH 2/3] doc: Document `process.moduleWrap()`

---
 doc/api/process.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/doc/api/process.md b/doc/api/process.md
index 306f555e4fcfce..fd975e4432745b 100644
--- a/doc/api/process.md
+++ b/doc/api/process.md
@@ -1187,6 +1187,45 @@ Will generate:
 `external` refers to the memory usage of C++ objects bound to JavaScript
 objects managed by V8.
 
+## process.moduleWrap(content, filepath)
+
+* `content` {String} The file contents
+* `filepath` {String} The full path of the file
+* Returns: {String} The replacement content
+
+The `process.moduleWrap()` method, which only exists while preloading modules
+with the `--require` flag, will receive the text content of any file to be
+loaded with `require()` and will replace it with the return value. This method
+may be set to apply 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 the flow of
+an application.
+
+This is an example of replacing a function with one which has been instrumented
+to log execution time:
+
+```js
+process.moduleWrap = function(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)
+  }
+  `
+}
+```
+
 ## process.nextTick(callback[, ...args])
 <!-- YAML
 added: v0.1.26

From 7f3a29a1861df980a19b13a1e8405a1ca33e42e0 Mon Sep 17 00:00:00 2001
From: Stephen Belanger <admin@stephenbelanger.com>
Date: Thu, 13 Apr 2017 15:13:24 -0700
Subject: [PATCH 3/3] src: add require transform pipeline

This is a simple pipeline to enable applying transform
functions to loaded JavaScript files for various purposes
such as transpiling, creating test mocks, recording code
coverage or applying custom instrumentation.
---
 doc/api/globals.md                       | 49 ++++++++++++++++++++++++
 doc/api/process.md                       | 39 -------------------
 lib/internal/bootstrap_node.js           | 16 ++++----
 lib/internal/module.js                   | 30 ++++++++++++++-
 lib/module.js                            |  6 +--
 test/fixtures/process-module-wrap.js     |  4 --
 test/parallel/test-preload.js            | 10 -----
 test/parallel/test-require-transforms.js | 38 ++++++++++++++++++
 8 files changed, 125 insertions(+), 67 deletions(-)
 delete mode 100644 test/fixtures/process-module-wrap.js
 create mode 100644 test/parallel/test-require-transforms.js

diff --git a/doc/api/globals.md b/doc/api/globals.md
index 4e727a917ac31c..33a0b30563357f 100644
--- a/doc/api/globals.md
+++ b/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
diff --git a/doc/api/process.md b/doc/api/process.md
index fd975e4432745b..306f555e4fcfce 100644
--- a/doc/api/process.md
+++ b/doc/api/process.md
@@ -1187,45 +1187,6 @@ Will generate:
 `external` refers to the memory usage of C++ objects bound to JavaScript
 objects managed by V8.
 
-## process.moduleWrap(content, filepath)
-
-* `content` {String} The file contents
-* `filepath` {String} The full path of the file
-* Returns: {String} The replacement content
-
-The `process.moduleWrap()` method, which only exists while preloading modules
-with the `--require` flag, will receive the text content of any file to be
-loaded with `require()` and will replace it with the return value. This method
-may be set to apply 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 the flow of
-an application.
-
-This is an example of replacing a function with one which has been instrumented
-to log execution time:
-
-```js
-process.moduleWrap = function(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)
-  }
-  `
-}
-```
-
 ## process.nextTick(callback[, ...args])
 <!-- YAML
 added: v0.1.26
diff --git a/lib/internal/bootstrap_node.js b/lib/internal/bootstrap_node.js
index 1df92bfe1dcf8b..f07cdfce1020a2 100644
--- a/lib/internal/bootstrap_node.js
+++ b/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]');
@@ -412,10 +414,6 @@
   function preloadModules() {
     if (process._preload_modules) {
       NativeModule.require('module')._preloadModules(process._preload_modules);
-      if (process.moduleWrap) {
-        NativeModule.preloadModuleWrap = process.moduleWrap;
-        delete process.moduleWrap;
-      }
     }
   }
 
@@ -449,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(/^#!.*/, ''));
@@ -478,7 +475,6 @@
   }
 
   NativeModule._source = process.binding('natives');
-  NativeModule.preloadModuleWrap = null;
   NativeModule._cache = {};
 
   NativeModule.require = function(id) {
@@ -549,8 +545,10 @@
 
   NativeModule.prototype.compile = function() {
     var source = NativeModule.getSource(this.id);
-    if (NativeModule.preloadModuleWrap !== null) {
-      source = NativeModule.preloadModuleWrap(source, this.filename);
+    // 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);
 
diff --git a/lib/internal/module.js b/lib/internal/module.js
index 8fc8dfbf327e61..8f9521ed4e56d6 100644
--- a/lib/internal/module.js
+++ b/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;
 
diff --git a/lib/module.js b/lib/module.js
index e71640d438cb59..c6f352c7d89d39 100644
--- a/lib/module.js
+++ b/lib/module.js
@@ -537,10 +537,8 @@ var resolvedArgv;
 // the file.
 // Returns exception, if any.
 Module.prototype._compile = function(content, filename) {
-  if (NativeModule.preloadModuleWrap !== null) {
-    content = NativeModule.preloadModuleWrap(content, filename);
-  }
-  
+  content = internalModule.applyTransforms(content, filename);
+
   // Remove shebang
   var contLen = content.length;
   if (contLen >= 2) {
diff --git a/test/fixtures/process-module-wrap.js b/test/fixtures/process-module-wrap.js
deleted file mode 100644
index ab041c34b0ca82..00000000000000
--- a/test/fixtures/process-module-wrap.js
+++ /dev/null
@@ -1,4 +0,0 @@
-process.moduleWrap = function(content, filename) {
-  if (filename !== 'http.js') return content
-  return content + '\nmodule.exports.hello = "hi";'
-}
diff --git a/test/parallel/test-preload.js b/test/parallel/test-preload.js
index ccfb195ef7480a..8dc64cc6c60168 100644
--- a/test/parallel/test-preload.js
+++ b/test/parallel/test-preload.js
@@ -29,7 +29,6 @@ const fixtureA = fixture('printA.js');
 const fixtureB = fixture('printB.js');
 const fixtureC = fixture('printC.js');
 const fixtureD = fixture('define-global.js');
-const fixtureE = fixture('process-module-wrap.js');
 const fixtureThrows = fixture('throws_error4.js');
 
 // test preloading a single module works
@@ -147,12 +146,3 @@ childProcess.exec(
     assert.ok(/worker terminated with code 43/.test(stdout));
   }
 );
-
-// test that preload can be used with --eval
-childProcess.exec(
-  nodeBinary + ' ' + preloadOption([fixtureE]) + '-p "require(\'http\').hello"',
-  function(err, stdout, stderr) {
-    assert.ifError(err);
-    assert.strictEqual(stdout, 'hi\n');
-  }
-);
diff --git a/test/parallel/test-require-transforms.js b/test/parallel/test-require-transforms.js
new file mode 100644
index 00000000000000..dca1ae853afb5d
--- /dev/null
+++ b/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');