Safe Monkeypatching for JavaScript

Common errors

• TypeError: original.apply is not a function

  cause The `wrapper` function did not correctly receive or invoke the `original` function, or the `name` provided to `shimmer.wrap` referred to a non-function property.
  fix Ensure your `wrapper` function signature is `function (original) { return function () { /* ... */ original.apply(this, arguments); } }` and that `name` points to an actual function on the `nodule`.

• Error: Cannot find module 'shimmer'

  cause The `shimmer` package is not installed or the Node.js runtime cannot locate it.
  fix Run `npm install shimmer` or `yarn add shimmer` to install the package.

• ReferenceError: shimmer is not defined

  cause The `shimmer` module was not imported or required correctly before use.
  fix Add `const shimmer = require('shimmer');` at the top of your file to import the module in CommonJS environments.

Warnings

• breaking This library is an older package (last updated ~7 years ago) and is not actively maintained. Compatibility with very recent Node.js versions or complex ESM setups may not be guaranteed without specific workarounds.
  Fix: For new projects, consider alternatives or carefully test `shimmer` in your specific environment. Evaluate if monkeypatching is truly necessary, as it can lead to fragile code.
• gotcha Monkeypatching is inherently risky. The library includes a 'mandatory disclaimer' that modifying runtime behavior on the fly is rarely a good idea and should only be done out of necessity, not for fun.
  Fix: Ensure you fully understand the implications of modifying core module behavior. Use it only when no other extension point (e.g., events, dependency injection) is available.
• gotcha When providing a `wrapper` function, you *must* call the `original.apply(this, arguments)` unless you are intentionally transforming arguments or replacing the function's logic.
  Fix: Always include `original.apply(this, arguments)` in your wrapper to ensure the original functionality is executed, capturing and returning its result. Forgetting this will likely break the patched function.
• gotcha Always capture and return the return value from the `original` function within your `wrapper`. Ignoring it can lead to unexpected behavior later, especially with callbacks or promise-based APIs.
  Fix: Ensure your wrapper returns `original.apply(this, arguments)` or the result of processing its return value. Example: `const result = original.apply(this, arguments); return result;`
• gotcha Do not change an asynchronous function to be synchronous or vice versa within your `wrapper`. This fundamentally alters the contract of the original function and can cause significant issues in consuming code.
  Fix: Maintain the original function's synchronous or asynchronous nature. If it was async, your wrapper should also handle its asynchronous return (e.g., promises, callbacks).
• gotcha `shimmer` defaults to logging failures via `console.error` rather than throwing exceptions, making it unobtrusive but potentially masking immediate errors.
  Fix: Configure a custom logger via `shimmer({ logger: myCustomLogger })` for more controlled error handling or to integrate with your application's logging infrastructure. Regularly check logs for `shimmer`-related messages.
• gotcha `shimmer.unwrap` will not unwrap a function if it has been monkeypatched by another library *after* your `shimmer` patch, and it will only log this event.
  Fix: Be aware of the order of monkeypatching in your application. If multiple libraries patch the same function, the last one to patch will be the active one, and `shimmer.unwrap` may not fully restore the original behavior if it's not the last layer.

Install

• npm install shimmer npm
• yarn add shimmer yarn
• pnpm add shimmer pnpm

Imports

• shimmer

  const shimmer = require('shimmer');

  Primarily designed for CommonJS. While `import shimmer from 'shimmer'` might work with bundlers or specific Node.js configurations, it's not the intended or officially supported import style for this older library version.
• shimmer.wrap
  wrong:

  import { wrap } from 'shimmer'; // Not directly exported as named export

  correct:

  const shimmer = require('shimmer');
  shimmer.wrap(targetModule, 'methodName', function (original) { /* ... */ });

  `wrap` is a method on the default `shimmer` export. Ensure you import the main `shimmer` object first.
• shimmer.unwrap
  wrong:

  import { unwrap } from 'shimmer'; // Not directly exported as named export

  correct:

  const shimmer = require('shimmer');
  shimmer.unwrap(targetModule, 'methodName');

  `unwrap` is a method on the default `shimmer` export. It restores the function to its state before `shimmer` patched it, logging if another patch is present or if double-unwrapping occurs.
• shimmer(options)
  wrong:

  import shimmer from 'shimmer'; shimmer({ logger: myCustomLogger }); // ESM import might not initialize the configurable instance correctly without CJS interop

  correct:

  const shimmer = require('shimmer');
  const customShimmer = shimmer({ logger: myCustomLogger });

  This allows configuring the logger used by shimmer. It returns a new shimmer instance with the provided options. The default logger is `console.error`.

Quickstart

This example demonstrates how to use `shimmer.wrap` to intercept and log details of `http.request` calls in Node.js, and then `shimmer.unwrap` to restore the original function.

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

console.log('Original http.request is:', http.request.__wrapped ? 'wrapped' : 'not wrapped');

shimmer.wrap(http, 'request', function (original) {
  return function () {
    console.log('>>> Intercepting http.request: Starting request!');
    const args = Array.from(arguments);
    const options = typeof args[0] === 'string' ? new URL(args[0]) : args[0];
    console.log('    Request options:', options);
    const returned = original.apply(this, arguments);
    console.log('<<< Intercepting http.request: Done setting up request.');
    return returned;
  };
});

console.log('Patched http.request is:', http.request.__wrapped ? 'wrapped' : 'not wrapped');

// Example usage to trigger the wrapped function
const req = http.request('http://www.google.com', (res) => {
  console.log(`STATUS: ${res.statusCode}`);
  res.setEncoding('utf8');
  res.on('data', (chunk) => {
    // console.log(`BODY: ${chunk}`);
  });
  res.on('end', () => {
    console.log('No more data in response.');
  });
});

req.on('error', (e) => {
  console.error(`problem with request: ${e.message}`);
});

req.end();

// Clean up
shimmer.unwrap(http, 'request');
console.log('Unwrapped http.request is:', http.request.__wrapped ? 'wrapped' : 'not wrapped');