Registry / testing / shimmer

shimmer

JSON →
library1.8.0jsnpmunverified

The `shimmer` package (version 1.2.1) is a JavaScript utility designed for safe monkeypatching of functions, primarily within Node.js CommonJS environments. It provides a set of tools, including `wrap`, `massWrap`, `unwrap`, and `massUnwrap`, to intercept and augment the behavior of existing functions on objects or entire modules. The library's core philosophy is to add behavior around an original function, rather than replacing it, and includes important guidelines for maintaining function integrity (e.g., preserving return values, not altering async/sync nature). Released approximately seven years ago, its current status suggests it is in maintenance mode rather than active development. It differentiates itself by providing explicit safety mechanisms and logging for potential issues during monkeypatching, defaulting to `console.error` for non-throwing error reporting. This makes it suitable for extending or observing existing Node.js module functionality with reduced risk compared to direct function reassignment.

testingobservability
npm install shimmer
github ↗package ↗
INSTALL
IMPORT
SIG · SHIMMER
S
shimmer
testingjavascriptv1.8.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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
✓ const shimmer = require('shimmer'); shimmer.wrap(targetModule, 'methodName', function (original) { /* ... */ });
✗ import { wrap } from 'shimmer'; // Not directly exported as named export
`wrap` is a method on the default `shimmer` export. Ensure you import the main `shimmer` object first.
shimmer.unwrap
✓ const shimmer = require('shimmer'); shimmer.unwrap(targetModule, 'methodName');
✗ import { unwrap } from 'shimmer'; // Not directly exported as named export
`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)
✓ const shimmer = require('shimmer'); const customShimmer = shimmer({ logger: myCustomLogger });
✗ import shimmer from 'shimmer'; shimmer({ logger: myCustomLogger }); // ESM import might not initialize the configurable instance correctly without CJS interop
This allows configuring the logger used by shimmer. It returns a new shimmer instance with the provided options. The default logger is `console.error`.

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');
Debug
Known issues
breakingThis 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.
affects: <=1.2.1
gotchaMonkeypatching 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.
affects: >=0.1.0
gotchaWhen 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.
affects: >=0.1.0
gotchaAlways 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;`
affects: >=0.1.0
gotchaDo 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).
affects: >=0.1.0
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.
affects: >=0.1.0
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.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: original.apply is not a function
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'
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
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.
Upgrade
Version history
1.8.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
16 hits · last 30 days
node
12
OpenAI (training)
2
Resources
githubhttps://github.com/othiym23/shimmer ↗
packagehttps://www.npmjs.com/package/shimmer ↗
shimmer — npm install shimmer · libregistry