jsposed

A javascript patching library inspired by Xposed

Installing

npm install jsposed

pnpm add jsposed

yarn add jsposed

Usage

Basics

Import the Patcher class from jsposed:

import { Patcher } from "jsposed";

Create a new instance. The name is used for logging errors and optional (defaults to "JsPosed")

const patcher = new Patcher("MyPatcherName");

The patcher will catch all errors thrown by patch callbacks and by default print them with a lot of info. If you want to use your own logger or do more with the errors, you may pass your own error callback:

const patcher = new Patcher("MyPatcher", (kind, info, error, patch) => {
    console.error("Oh no :( Very bad thing happened while patching", info.methodName);
})

Patch types

There are three types of patches:

• before: Runs before the original method and optionally may skip calling the original method by setting context.result (more info below)
• instead: Runs instead of the original method. This will entirely skip the original method and requires you to return your own result if applicable
• after: Runs after the original method and thus has access to the result returned by it

You can either use the shortcut methods patcher.before, patcher.instead and patcher.after...:

patcher.before(window, "open", (context) => {
    console.log("before window.open", context.args[0]);
    context.args[0] = "https://www.youtube.com/watch?v=dQw4w9WgXcQ";
});

patcher.after(window, "open", (context) => {
    console.log("after window.open", context.result)
})

...or if you want to use both before and after more concisely, you may also create your own patch directly:

patcher.patch(window, "open", new Patch({
    before(context) { },
    after(context) { }
}))

The Patch callback

What all patches have in common is how their callback works:

• The first argument is a context that contains a lot of info about the invoked function and allows you to alter the arguments and result (see table below)
• For convenience and a nicer typescript experience, the arguments passed to the original function are also available as arg 2, 3, ..., n

PatchContext

| Field | Description | in before patches | in after patches | |-------|-------------|--------|-------| | thisObject | The this value of this function call | - | - | | args | The arguments passed in this function call | Changing this array will change the arguments passed to the original | - | | result | The result (return value) of this function call | Always unset. Setting it to anything (including undefined) will skip the original function | Always set. Changing it will change what's eventually returned | | error | The error thrown by the original function | Always unset. Setting it to a non-nullish value will skip the original function and throw that value | Might be set if the original function threw an error. Setting it to a non-nullish value will throw that value. Resetting it to a nullish value will prevent errors from being thrown | | resultOrError | Throws context.error if non-nullish, otherwise returns context.result | Always unset | Always set

Examples

For more examples on real functions, check tests/index.js

const { Patcher } = require("jsposed");

const patcher = new Patcher();

// Replace an argument before a method is called
const unpatch = patcher.before(someObject, "someMethod", (context, arg1) => {
    context.args[0] = "Replace some arg";
});

// Remove that patch again
unpatch.unpatch();

// Skip a method conditionally
patcher.before(someObject, "slap", (context, person) => {
    if (person.name === "Tom") {
        // Hey now, who in their right mind would slap poor Tom

        // Lets skip this method
        context.result = null; // Or some other value, this will be returned to the caller

        // Or maybe you would want to throw an error?
        context.error = new Error("DO NOT THE TOM!!");
    }
});

// Replace a method entirely
patcher.instead(someObject, "someMethod", (context) => {
    context.thisObject.doSomeOtherThing();
})

// Call the original method
// If you really really want to slap Tom, then I guess go ahead...
patcher.callOriginal(someObject.slap, someObject, "Tom");

// Now remove all patches again
patcher.unpatchAll();