shimmer

What is shimmer?

The shimmer npm package is a utility for wrapping and replacing object properties and methods, primarily used for monkey-patching - a technique to modify or extend the behavior of libraries or objects in a dynamic way. It allows developers to intercept and modify the behavior of functions in a non-intrusive manner, which is particularly useful for logging, monitoring, and testing purposes.

What are shimmer's main functionalities?

Wrapping a function

This code demonstrates how to use shimmer to wrap a function. It intercepts calls to the original function, allowing you to execute code before and after the original function is called.

const shimmer = require('shimmer');

function originalFunction() {
  console.log('Original function');
}

shimmer.wrap(originalFunction, function(original) {
  return function() {
    console.log('Before original function');
    original.apply(this, arguments);
    console.log('After original function');
  };
});

originalFunction();

Replacing a method of an object

This example shows how to use shimmer to replace a method of an object. It allows you to run custom code before and after the original method is executed, effectively modifying its behavior.

const shimmer = require('shimmer');

const myObject = {
  myMethod: function() {
    console.log('Original method');
  }
};

shimmer.wrap(myObject, 'myMethod', function(original) {
  return function() {
    console.log('Before original method');
    original.apply(this, arguments);
    console.log('After original method');
  };
});

myObject.myMethod();

Other packages similar to shimmer

hooker

Hooker is a package that provides similar functionality to shimmer, allowing for pre and post function interception. It differs in its API and the way it handles the context of the function calls, but serves a similar purpose in terms of enabling function wrapping and modification.

proxyquire

Proxyquire is designed for intercepting and mocking module dependencies during testing, which is a form of monkey-patching. While its primary use case is in testing scenarios to replace module dependencies, it shares the concept of intercepting and modifying behavior dynamically with shimmer.

README

Safer monkeypatching for Node.js

shimmer does a bunch of the work necessary to wrap other methods in a wrapper you provide:

var http = require('http');
var shimmer = require('shimmer');

shimmer.wrap(http, 'request', function (original) {
  return function () {
    console.log("Starting request!");
    var returned = original.apply(this, arguments)
    console.log("Done setting up request -- OH YEAH!");
    return returned;
  };
});

Mandatory disclaimer

There are times when it's necessary to monkeypatch default behavior in JavaScript and Node. However, changing the behavior of the runtime on the fly is rarely a good idea, and you should be using this module because you need to, not because it seems like fun.

API

All monkeypatched functions have an attribute, __wrapped, set to true on them.

shimmer(options)

If you pass in an options object containing a function labeled logger, shimmer will use it instead of the logger, which defaults to console.error. shimmer is built to be as unobtrusive as possible and has no need to run asynchronously, so it defaults to logging when things fail, instead of throwing.

shimmer.wrap(nodule, name, wrapper)

shimmer monkeypatches in place, so it expects to be passed an object. It accepts either instances, prototypes, or the results of calling require. name must be the string key for the field's name on the object.

wrapper is a function that takes a single parameter, which is the original function to be monkeypatched. shimmer assumes that you're adding behavior to the original method, and not replacing it outright. If you are replacing the original function, feel free to ignore the passed-in function.

If you aren't discarding the original, remember these tips:

• call the original with something like original.apply(this, arguments), unless your reason for monkeypatching is to transform the arguments.
• always capture and return the return value coming from the original function. Today's null-returning callback is tomorrow's error-code returning callback.
• Don't make an asynchronous function synchronous and vice versa.

shimmer.massWrap(nodules, names, wrapper)

Just like wrap, with the addition that you can wrap multiple methods on multiple modules. Note that this function expects the list of functions to be monkeypatched on all of the modules to be the same.

shimmer.unwrap(nodule, name)

A convenience function for restoring the function back the way it was before you started. Won't unwrap if somebody else has monkeypatched the function after you (but will log in that case). Won't throw if you try to double-unwrap a function (but will log).

shimmer.wrapEmitter(emitter, mark, prepare)

Wrap an EventEmitter's event listeners. Each listener will be passed to mark when it is registered with .addListener() or .on(), and then each listener is passed to prepare to be wrapped before it's called by the .emit() call. wrapListener deals with the single listener vs array of listeners logic, and also ensures that edge cases like .removeListener() being called from within an .emit() for the same event type is handled properly.

The wrapped EE can be restored to its pristine state by using emitter.__unwrap(), but this should only be used if you really know what you're doing.