; Date: Sat Apr 07 2018

Tags: Node.JS

Suppose you've found a Node.js module that almost does what you want, but it needs another feature or two, or some other tweak? How to modify the package, and perhaps temporarily modify it at runtime? Technically, monkey patching is not simply maintaining a local modification to someone elses code, but to dynamically modify that code at runtime. Some say this is evil, but it is a practice that is required at times. Let's see how to do this.

First - npm does not support maintaining a local modification to a module. If you've edited files inside the node_modules directory, those modifications will be overwritten the next time you npm update or npm install over the top of that package.

I can imagine a possible addition to npm so the dependencies section supports an entry like:

{
    ...
    "dependencies": {
        ...
        "module-to-patch": {
            "dependency": "module@version-or-tag",
            "patch": "/path/to/file-containing-diff-u-patch-to-apply"
        }
        ...
    }
    ...
}

This is different from the normal dependency declaration in that it references a file that is used to patch the module after it is installed. Er... the patch would have to be run before any compilation step is performed, so that native code could be patched as well as JavaScript code.

But, npm doesn't have such a feature.

What one can do is implement a module that modifies the module object. That module can be checked into a repository, and then used as a regular dependency. An example is the excellent fs-extra module which implements the fs module functions with new functions that return Promise objects.

Consider the normal encapsulation of a Node.js module. Node.js modules act as if they were written as:

(function() {
    ... contents of module
})();

In other words the content of the module is inside an anonymous private context that cannot be modified from outside that context.

The exception is that anything inside the module assigned to the module.exports object is then available as the object returned from require('that-module').

There is nothing much special about the object returned by require(). It is simply the object created as module.exports inside the module. We're talking about traditional CommonJS-style Node.js modules here. The newfangled ES6 modules are a little different.

Making a local patch to a module

To make a local patch to a module, write a new module ... let's call it modified-module to extend/change that-module. In pseudo-code it would be implemented as so:

const thatModule = require('that-module');

// First, copy over all the fields from the original module
for (let fieldName in thatModule) {
    module.exports[fieldName] = thatModule[fieldName];
}

// Then write new implementations of any function you want to change
module.exports.function1 = function(arg, arg2, arg3) {
    // new function implementation
    // To call the original function do:
    thatModule.function1();
}

Then, simply add a dependency to modified-module in your package.json, and in your code require('modified-module') instead of require('that-module'). You'll be able to rely on the documentation for that-module and to only document your modifications to the module.

Wait - how do you actually Monkey Patch a Node.js module?

Right .. that wasn't monkey patching. So .. try this:

const thatModule = require('that-module');
const origThatModule = thatModule;

if (process.env.PATCH_THAT_MODULE === 'yes') {
    thatModule.function1 = function(arg, arg2, arg3) {
        // new function implementation
        // To call the original function do:
        origThatModule.function1();
    }
}

Or, more concretely:

MacBook-Pro-4:mp david$ cat main.js
const fs = require('fs');

fs.hello = function() { console.log('Hello World'); }

require('./check-patch');

MacBook-Pro-4:mp david$ cat check-patch.js 
const fs = require('fs');

fs.hello();

MacBook-Pro-4:mp david$ node main.js 
Hello World
MacBook-Pro-4:mp david$ 

That is - in main.js a change is made to the fs module. Requiring the module into another module see's the same modification.

Summary

Both of these approaches can be part of your application, and will not be overwritten when the source module is installed or updated. Using this technique, your modifications to another module are in your source code, and stored in your own repository.

It's still best to send any modifications to the upstream module owner so you do not have to maintain the modification.