monkeypatch-js

A very simple, easy to use monkey patching utility for JavaScript, with TypeScript support

Usage no npm install needed!

<script type="module">
  import monkeypatchJs from 'https://cdn.skypack.dev/monkeypatch-js';
</script>

README

monkeypatch-js

A very simple, easy to use monkey patching utility for JavaScript, with TypeScript support

Disclaimer

I do not encourage using monkey patching for fun. A developer should only ever use this technique if they have no other capable ways of accomplishing something. Things can, and WILL break upon misuse. It is completely up to the developer(s) to use this utility. I am not to be held responsible for any damage or harm caused by using monkeypatch-js.

Usage

monkeypatch-js provides 4 functions, "patch", "unpatch", "patchMultiple", "unpatchMultiple", these can all be used to patch given objects/classes/prototypes and their properties. A property can be of any type.

Upon patching, a __MONKEYPATCH object will be created on the host object which will store the original values of the properties patched. Patching the same property multiple times will unpatch it to it's original state before proceeding.

patch

patch(targetObject: object, targetProperty: string, replaceCallback: (original: any));

Patches a given property. "targetObject" is the object/class/prototype we are looking to patch on. "targetProperty" is the property we want to patch, given as a string. "replaceCallback" is a callback that gets supplied the original value. Inside of this callback you should return the new value.

unpatch

unpatch(targetObject: object, targetProperty: string);

Unpatches a given property. "targetObject" is the object/class/prototype we are looking to unpatch on. "targetProperty" is the property we want to unpatch, given as a string.

patchMultiple

patchMultiple(targets: Array<[object, string]>, replaceCallback: (original: any))

Patches multiple properties. "targets" is an array of tuples (sub-arrays) that define which object and property to patch. The first element in the tuple should always be the object, and the second element should always be the property. "replaceCallback" is a callback that gets supplied the original value. Inside of this callback you should return the new value. Every property will be patched according to your logic in this callback.

unpatchMultiple

unpatchMultiple(targets: Array<[object, string]>)

Unpatches multiple properties. "targets" is an array of tuples (sub-arrays) that define which object and property to unpatch. The first element in the tuple should always be the object, and the second element should always be the property.

Examples

Examples can be found in the repository, under the "example" folder. This contains examples for single, multiple, and instance-prototype patching.

Todo

  • Turn library into a class (?)
  • Create optional debug logs (?)
  • Optimize (!)
  • Review and finalize (!)