Plugged In

Plugin system for Node Js.

Installation

  npm install plugged-in

Usage

Let's imagine that you want to create an application where it can be extended via plugin modules. To accomplish this you need to have your application class extend the PluginManager class.

Application.js

  export default class Application extends PluginManager {
    constructor(config) {
      super(config);
    }
  }

Also, add the plugged-in configuration to your package.json and set your application context.

package.json

  "plugged-in": {
    "context": "plugged-in-test"
  },

That's it. You're now ready to have your plugin modules get plugged-in.

Now, for your plugins. Your plugin modules need to export and advertise their supported functionality.

package.json

  "plugged-in": {
    "context": "plugged-in-test",
    "provides": {
      "getTitle": "getTitle",
      "getBody": [
        "getBody",
        "removeLinks"
      ]
    }
  },

In this example, the plugin tells the PluginManager that it provides the getTitle and getBody features in the plugged-in-test context.

Only plugins that match the PluginManager context will be plugged in.

For getTitle it provides one event callback, the getTitle(event) callback and for get body, it provides two, getBody(event) and removeLinks(event).

These callbacks will be called in the order they are defined.

Once your application has extended PluginManager and defined the application context. You need to call the init() method to generate the .plugged-in.json config and load the plugins.

If the config file already exists, it will not be regenerated. The application will load the configured plugins.

  const app = new Application();
  await app.init();
  app. ...

Invoke Plugin Functionality

To invoke the plugin's functions, you need to dispatch an event from the PluginManager (or your Application).

  const context = { body: 'current body' };
  await this.dispatch('getBody', context);
  const body = context.body; // resulting value

To get a return value from an event execution, set the desired data on the context property of the event. This is what get's returned from the dispatch call.

More on Usage

See the examples directory for usage example. The examples show the manager project and one plugin project.

NOTE:

If you have plugins installed globally, you need to run the link command to make them available to the plugin manager. Running init() will find both local and global modules, but only local modules can be used during execution.

  npm link plugged-in-plugin

Add additional Plugins on init

When initialising the PluginManager, you can optionally pass your own handlers to the manager. If it matches an existing function name already registered it will replace it. This allows you to locally override plugin functionality. On the other hand, if you want to allow duplicated function names, pass override = false to the constructor in the options.

  const addInitialisedAt = (event) => {
    event.context.initialisedAt = new Date();
  };

  await app.init({
    postInit: addInitialisedAt,
  });

API

Actual api docs generated by esdoc and available at https://rawphp.github.io/plugged-in.