README
Pluggers
A convenient plugin manager library.
pluggers is designed to make modular projects easier to create. recursive-install is recommended for making plugins truly independent.
Warning: there are many breaking changes for those who are upgrading from pre-v2 to v2.
Features & Plans
- Synchronous or Asynchronous plugin loading
- Flexible access between plugins
- Priority-based load order (explicit or automatic)
Installation
Use the package manager npm to install pluggers.
npm install --save pluggers
Usage
./plugin1.js
// ./plugin1.js
const Plugger = require("pluggers").default;
const plugin = new Plugger("plugin1");
plugin.pluginCallbacks.init = () => {
const test = "Hello World!";
return test;
};
module.exports = plugin;
./plugin2.js
// ./plugin2.js
const Plugger = require("pluggers").default;
// Error will be thrown if the plugin is using a used name ("plugin1") when loaded
const plugin = new Plugger("plugin2");
// Error will be thrown if a plugin named "plugin1" is not loaded
plugin.requirePlugin({ name: "plugin1" });
plugin.pluginCallbacks.init = (plugins) => {
const { plugin1 } = plugins;
console.log(plugin1);
};
module.exports = plugin;
./master.js
// ./master.js
const Plugger = require("pluggers").default;
// Create instance
const master = new Plugger("master");
// Add plugins
master.addPlugin(require("./plugin1"));
master.addPlugin(require("./plugin2"));
master.initAll().then(() => {
console.log("Complete!");
});
The above codes will print "Hello World!" and then "Complete!" if master.js
is executed.
API
Check out this documentation page.
How Priorities Work
There are 3 types of priorities that can be used, in order of the load order:
Positive priority, which is from
0
toInfinity
.
Plugins with positive number priorities will be initialized with the order from the lowest number (0
) to the highest number (Infinity
).Undefined priority
Plugins with undefined priorities will be initialized after plugins with positive number priorities with the order of which plugin gets loaded withaddPlugin()
first.Negative priority, which is from
-Infinity
to-1
.
Negative priorities work like how negative indexes work in Python (ex: a plugin with the priority of-1
will be initialized last,-2
will be initialized second last, etc). Plugins with negative priorities will be processed after plugins with positive number priorities and undefined priorities, with the order from the lowest number (-Infinity
) to the highest number (-1
), and will be initialized according to their respective priorities.
All types of priorities are stackable, for example:
...
loader.addPlugin(plugin1, { priority: 1 }); // this will be initialized first
loader.addPlugin(plugin2, { priority: 1 }); // this will be initialized after 'plugin1'. Note that its priority is the same as 'plugin1'
loader.initAll();
Because of their nature, plugins with negative priorities will be processed differently:
...
loader.addPlugin(plugin1, { priority: 1 }); // this will be initialized first
loader.addPlugin(plugin2, { priority: 1 });
loader.addPlugin(plugin3, { priority: -2 }) // this will be initialized after 'plugin1', before 'plugin2'
loader.addPlugin(plugin4, { priority: -1 }) // this will be initialized after 'plugin2'
loader.initAll(); // Load order: 'plugin1', 'plugin3', 'plugin2', 'plugin4'
Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.