Class PluginManager

Provides a lightweight plugin manager for Node / NPM & the browser with eventbus integration for plugins in a safe and protected manner across NPM modules, local files, and preloaded object instances. This pattern facilitates message passing between modules versus direct dependencies / method invocation.

A default eventbus will be created, but you may also pass in an eventbus from @typhonjs-plugin/eventbus and the plugin manager will register by default under these event categories:

plugins:async:add - PluginManager#add

plugins:async:add:all - PluginManager#addAll

plugins:async:destroy:manager - PluginManager#destroy

plugins:async:remove - PluginManager#remove

plugins:async:remove:all - PluginManager#removeAll

plugins:get:enabled - PluginManager#getEnabled

plugins:get:options - PluginManager#getOptions

plugins:get:plugin:by:event - PluginManager#getPluginByEvent

plugins:get:plugin:data - PluginManager#getPluginData

plugins:get:plugin:events - PluginManager#getPluginEvents

plugins:get:plugin:names - PluginManager#getPluginNames

plugins:has:plugin - PluginManager#hasPlugins

plugins:is:valid:config - PluginManager#isValidConfig

plugins:set:enabled - PluginManager#setEnabled

plugins:set:options - PluginManager#setOptions

Automatically when a plugin is loaded and unloaded respective functions onPluginLoad and onPluginUnload will be attempted to be invoked on the plugin. This is an opportunity for the plugin to receive any associated eventbus and wire itself into it. It should be noted that a protected proxy around the eventbus is passed to the plugins such that when the plugin is removed automatically all events registered on the eventbus are cleaned up without a plugin author needing to do this manually in the onPluginUnload callback. This solves any dangling event binding issues.

By supporting ES Modules / CommonJS in Node and ES Modules in the browser the plugin manager is by nature asynchronous for the core methods of adding / removing plugins and destroying the manager. The lifecycle methods onPluginLoad and onPluginUnload will be awaited on such that if a plugin returns a Promise or is an async method then it will complete before execution continues.

It is recommended to interact with the plugin manager eventbus through an eventbus proxy. The createEventbusProxy method will return a proxy to the default or currently set eventbus.

It should be noted that this module re-exports @typhonjs-plugin/eventbus which is available as named exports via the eventbus subpath export:

// Main Eventbus implementations:
import { Eventbus, EventbusProxy, EventbusSecure } from '#runtime/plugin/manager/eventbus';

// Consistent bus instances useful for testing and broad accessibility:
import { mainEventbus, pluginEventbus, testEventbus } from '#runtime/plugin/manager/eventbus/buses';
Copy

This reexport is for convenience as it provides one single distribution for Node & browser usage.

If external eventbus functionality is enabled by passing in an eventbus in the constructor of PluginManager it is important especially if using an existing process / global level eventbus instance from either this module or @typhonjs-plugin/eventbus to call PluginManager#destroy to clean up all plugin eventbus resources and the plugin manager event bindings; this is primarily a testing concern when running repeated tests over a reused eventbus.

For more information on Eventbus functionality please see:

import { PluginManager } from '@typhonjs-plugin/manager';

const pluginManager = new PluginManager();

await pluginManager.add({ name: 'an-npm-plugin-enabled-module' });
await pluginManager.add({ name: 'my-local-module', target: './myModule.js' });

const eventbus = pluginManager.createEventbusProxy();

// Let's say an-npm-plugin-enabled-module responds to 'cool:event' which returns 'true'.
// Let's say my-local-module responds to 'hot:event' which returns 'false'.
// Both of the plugin / modules will have 'onPluginLoaded' invoked with a proxy to the eventbus and any plugin
// options defined.

// One can then use the eventbus functionality to invoke associated module / plugin methods even retrieving results.
assert(eventbus.triggerSync('cool:event') === true);
assert(eventbus.triggerSync('hot:event') === false);
Copy