Skip to main content

PluginManager

Provides a lightweight plugin manager for Node / NPM with optional backbone-esnext-events 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.

It isn’t necessary to use an eventbus associated with the plugin manager though invocation then relies on invoking methods directly with the plugin manager instance.

When passing in an eventbus from backbone-esnext-events the plugin manager will register by default under these event categories:

plugins:add - add

plugins:add:all - addAll

plugins:async:add - addAsync

plugins:async:add:all - addAllAsync

plugins:async:destroy:manager - destroyAsync

plugins:async:invoke - invokeAsync

plugins:async:invoke:event - invokeAsyncEvent

plugins:async:remove - removeAsync

plugins:async:remove:all - removeAllAsync

plugins:create:event:proxy - createEventProxy

plugins:destroy:manager - destroy

plugins:get:all:plugin:data - getAllPluginData

plugins:get:extra:event:data - getExtraEventData

plugins:get:method:names - getMethodNames

plugins:get:options - getOptions

plugins:get:plugin:data - getPluginData

plugins:get:plugin:enabled - getPluginEnabled

plugins:get:plugin:event:names - getPluginEventNames

plugins:get:plugin:method:names - getPluginMethodNames

plugins:get:plugin:names - getPluginNames

plugins:get:plugin:options - getPluginOptions

plugins:get:plugins:enabled - getPluginsEnabled

plugins:get:plugins:by:event:name - getPluginsByEventName

plugins:get:plugins:event:names - getPluginsEventNames

plugins:has:method - hasMethod

plugins:has:plugin - hasPlugin

plugins:has:plugin:method - hasPluginMethod

plugins:invoke - invoke

plugins:is:valid:config - isValidConfig

plugins:remove - remove

plugins:remove:all - removeAll

plugins:set:extra:event:data - setExtraEventData

plugins:set:options - setOptions

plugins:set:plugin:enabled - setPluginEnabled

plugins:set:plugins:enabled - setPluginsEnabled

plugins:sync:invoke - invokeSync

plugins:sync:invoke:event - invokeSyncEvent

Automatically when a plugin is loaded and unloaded respective callbacks 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.

The plugin manager also supports asynchronous operation with the methods ending in Async along with event bindings that include async. For asynchronous variations of add, destroy, and remove 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 must complete before execution continues. One can use Promises to interact with the plugin manager asynchronously, but usage via async / await is recommended.

If eventbus functionality is enabled it is important especially if using a process / global level eventbus such as backbone-esnext-eventbus to call destroy to clean up all plugin eventbus resources and the plugin manager event bindings.

@see
@example

import Events from ‘backbone-esnext-events’; // Imports the TyphonEvents class for local usage. ::or alternatively:: import eventbus from ‘backbone-esnext-eventbus’; // Imports a global / process level eventbus.

import PluginManager from ‘typhonjs-plugin-manager’;

const pluginManager = new PluginManager({ eventbus });

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

// 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);

// One can also indirectly invoke any method of the plugin via: eventbus.triggerSync(‘plugins:invoke:sync:event’, ‘aCoolMethod’); // Any plugin with a method named aCoolMethod is invoked. eventbus.triggerSync(‘plugins:invoke:sync:event’, ‘aCoolMethod’, {}, {}, ‘an-npm-plugin-enabled-module’); // specific invocation.

// The 3rd parameter will make a copy of the hash and the 4th defines a pass through object hash sending a single // event / object hash to the invoked method.

// ———————–

// Given that backbone-esnext-eventbus defines a global / process level eventbus you can import it in an entirely // different file or even NPM module and invoke methods of loaded plugins like this:

import eventbus from ‘backbone-esnext-eventbus’;

eventbus.triggerSync(‘plugins:invoke’, ‘aCoolMethod’); // Any plugin with a method named aCoolMethod is invoked.

assert(eventbus.triggerSync(‘cool:event’) === true);

eventbus.trigger(‘plugins:remove’, ‘an-npm-plugin-enabled-module’); // Removes the plugin and unregisters events.

assert(eventbus.triggerSync(‘cool:event’) === true); // Will now fail!

// In this case though when using the global eventbus be mindful to always call pluginManager.destroy() in the main // thread of execution scope to remove all plugins and the plugin manager event bindings!

Index

Constructors

Methods

Constructors

constructor

  • new PluginManager(options?: { eventPrepend?: string; eventbus?: EventEmitter; throwNoMethod: boolean; throwNoPlugin: boolean }, extraEventData?: string): default

  • Instantiates PluginManager

    Parameters

    • options: { eventPrepend?: string; eventbus?: EventEmitter; throwNoMethod: boolean; throwNoPlugin: boolean } = ...

      Provides various configuration options:

      options.eventbus - An instance of ‘backbone-esnext-events’ used as the plugin eventbus.

      options.eventPrepend - A customized name to prepend PluginManager events on the eventbus.

      options.throwNoMethod - If true then when a method fails to be invoked by any plugin an exception will be thrown.

      options.throwNoPlugin- If true then when no plugin is matched to be invoked an exception will be thrown.

    • optionalextraEventData: string

      Provides additional optional data to attach to PluginEvent callbacks.

    Returns default

Methods

add

  • add(pluginConfig: PluginConfig, moduleData?: any): PluginData

  • Adds a plugin by the given configuration parameters. A plugin name is always required. If no other options are provided then the name doubles as the NPM module / local file to load. The loading first checks for an existing instance to use as the plugin. Then the target is chosen as the NPM module / local file to load. By passing in options this will be stored and accessible to the plugin during all callbacks.

    Parameters

    • pluginConfig: PluginConfig

      Defines the plugin to load.

    • optionalmoduleData: any

      Optional object hash to associate with plugin.

    Returns PluginData

addAll

  • addAll(pluginConfigs?: PluginConfig[], moduleData?: any): PluginData[]

  • Initializes multiple plugins in a single call.

    Parameters

    • pluginConfigs: PluginConfig[] = []

      An array of plugin config object hash entries.

    • optionalmoduleData: any

      Optional object hash to associate with all plugins.

    Returns PluginData[]

addAllAsync

  • addAllAsync(pluginConfigs?: PluginConfig[], moduleData?: any): Promise<PluginData[]>

  • Initializes multiple plugins in a single call.

    Parameters

    • pluginConfigs: PluginConfig[] = []

      An array of plugin config object hash entries.

    • optionalmoduleData: any

      Optional object hash to associate with all plugins.

    Returns Promise<PluginData[]>

addAsync

  • addAsync(pluginConfig: PluginConfig, moduleData?: any): Promise<PluginData>

  • Adds a plugin by the given configuration parameters. A plugin name is always required. If no other options are provided then the name doubles as the NPM module / local file to load. The loading first checks for an existing instance to use as the plugin. Then the target is chosen as the NPM module / local file to load. By passing in options this will be stored and accessible to the plugin during all callbacks.

    Parameters

    • pluginConfig: PluginConfig

      Defines the plugin to load.

    • optionalmoduleData: any

      Optional object hash to associate with plugin.

    Returns Promise<PluginData>

createEventProxy

  • createEventProxy(): EventEmitter

  • If an eventbus is assigned to this plugin manager then a new EventEmitter wrapping this eventbus is returned.

    Returns EventEmitter

destroy

  • destroy(): void

  • Destroys all managed plugins after unloading them.

    Returns void

destroyAsync

  • destroyAsync(): Promise<void>

  • Destroys all managed plugins after unloading them.

    Returns Promise<void>

getAllPluginData

  • getAllPluginData(enabled: boolean): PluginData[]

  • Returns all plugin data or if a boolean is passed in will return plugin data by current enabled state.

    Parameters

    • enabled: boolean

      If enabled is a boolean it will return plugins given their enabled state.

    Returns PluginData[]

getEventbus

  • getEventbus(): EventEmitter

  • Returns any associated eventbus.

    Returns EventEmitter

getExtraEventData

  • getExtraEventData(): any

  • Returns any extra event data associated with PluginEvents.

    Returns any

getMethodNames

  • getMethodNames(enabled: boolean, pluginName: string): string[]

  • Returns all method names or if a boolean is passed in will return method names for plugins by current enabled state.

    Parameters

    • enabled: boolean

      If enabled is a boolean it will return plugin methods names given their enabled state.

    • pluginName: string

      If a string then just this plugins methods names are returned.

    Returns string[]

getOptions

  • getOptions(): PluginManagerOptions

  • Returns a copy of the plugin manager options.

    Returns PluginManagerOptions

getPluginData

  • getPluginData(pluginName: string): PluginData

  • Gets the plugin data for a plugin by name.

    Parameters

    • pluginName: string

      A plugin name.

    Returns PluginData

getPluginEnabled

  • getPluginEnabled(pluginName: string): boolean

  • Returns the enabled state of a plugin.

    Parameters

    • pluginName: string

      Plugin name to set state.

    Returns boolean

getPluginEventNames

  • getPluginEventNames(pluginName: string): string[]

  • Returns the event binding names registered on any associated plugin EventProxy.

    Parameters

    • pluginName: string

      Plugin name to set state.

    Returns string[]

getPluginMethodNames

  • getPluginMethodNames(enabled: boolean): { method: string; plugin: string }[]

  • Returns all plugin names or if a boolean is passed in will return plugin names by current enabled state.

    Parameters

    • enabled: boolean

      If enabled is a boolean it will return plugins given their enabled state.

    Returns { method: string; plugin: string }[]

getPluginNames

  • getPluginNames(enabled: boolean): string[]

  • Returns all plugin names or if a boolean is passed in will return plugin names by current enabled state.

    Parameters

    • enabled: boolean

      If enabled is a boolean it will return plugins given their enabled state.

    Returns string[]

getPluginOptions

  • getPluginOptions(pluginName: string): any

  • Returns a copy of the given plugin options.

    Parameters

    • pluginName: string

      Plugin name to retrieve.

    Returns any

getPluginsByEventName

  • getPluginsByEventName(eventName: string): string[]

  • Returns the plugin names that registered the given event binding name.

    Parameters

    • eventName: string

      An event name that plugins may have registered.

    Returns string[]

getPluginsEnabled

  • getPluginsEnabled(pluginNames: string[]): { enabled: boolean; pluginName: string }[]

  • Returns the enabled state of a list of plugins.

    Parameters

    • pluginNames: string[]

      An array / iterable of plugin names.

    Returns { enabled: boolean; pluginName: string }[]

getPluginsEventNames

  • getPluginsEventNames(nameOrList?: string | string[]): { events: string[]; pluginName: string }[]

  • Returns the event binding names registered from each plugin.

    Parameters

    • optionalnameOrList: string | string[]

      An array / iterable of plugin names.

    Returns { events: string[]; pluginName: string }[]

hasMethod

  • hasMethod(methodName: string): boolean

  • Returns true if there is at least one plugin loaded with the given method name.

    Parameters

    • methodName: string

      Method name to test.

    Returns boolean

hasPlugin

  • hasPlugin(pluginName: string): boolean

  • Returns true if there is a plugin loaded with the given plugin name.

    Parameters

    • pluginName: string

      Plugin name to test.

    Returns boolean

hasPluginMethod

  • hasPluginMethod(pluginName: string, methodName: string): boolean

  • Returns true if there is a plugin loaded with the given plugin name that also has a method with the given method name.

    Parameters

    • pluginName: string

      Plugin name to test.

    • methodName: string

      Method name to test.

    Returns boolean

invoke

  • invoke(methodName: string, args?: any, nameOrList?: string | string[]): void

  • This dispatch method simply invokes any plugin targets for the given methodName..

    Parameters

    • methodName: string

      Method name to invoke.

    • optionalargs: any

      Optional arguments. An array will be spread as multiple arguments.

    • optionalnameOrList: string | string[]

      An optional plugin name or array / iterable of plugin names to invoke.

    Returns void

invokeAsync

  • invokeAsync(methodName: string, args?: any[], nameOrList?: string | string[]): Promise<any>

  • This dispatch method uses ES6 Promises and adds any returned results to an array which is added to a Promise.all construction which passes back a Promise which waits until all Promises complete. Any target invoked may return a Promise or any result. This is very useful to use for any asynchronous operations.

    Parameters

    • methodName: string

      Method name to invoke.

    • optionalargs: any[]

      Optional arguments. An array will be spread as multiple arguments.

    • optionalnameOrList: string | string[]

      An optional plugin name or array / iterable of plugin names to invoke.

    Returns Promise<any>

invokeAsyncEvent

  • invokeAsyncEvent(methodName: string, copyProps?: any, passthruProps?: any, nameOrList?: string | string[]): Promise<void | default>

  • This dispatch method synchronously passes to and returns from any invoked targets a PluginEvent.

    Parameters

    • methodName: string

      Method name to invoke.

    • optionalcopyProps: any

      plugin event object.

    • optionalpassthruProps: any

      if true, event has plugin option.

    • optionalnameOrList: string | string[]

      An optional plugin name or array / iterable of plugin names to invoke.

    Returns Promise<void | default>

invokeSync

  • invokeSync(methodName: string, args?: any, nameOrList?: string | string[]): any

  • This dispatch method synchronously passes back a single value or an array with all results returned by any invoked targets.

    Parameters

    • methodName: string

      Method name to invoke.

    • optionalargs: any

      Optional arguments. An array will be spread as multiple arguments.

    • optionalnameOrList: string | string[]

      An optional plugin name or array / iterable of plugin names to invoke.

    Returns any

invokeSyncEvent

  • invokeSyncEvent(methodName: string, copyProps?: any, passthruProps?: any, nameOrList?: string | string[]): default

  • This dispatch method synchronously passes to and returns from any invoked targets a PluginEvent.

    Parameters

    • methodName: string

      Method name to invoke.

    • optionalcopyProps: any

      plugin event object.

    • optionalpassthruProps: any
    • optionalnameOrList: string | string[]

      An optional plugin name or array / iterable of plugin names to invoke.

    Returns default

isValidConfig

  • isValidConfig(pluginConfig: PluginConfig): boolean

  • Performs validation of a PluginConfig.

    Parameters

    • pluginConfig: PluginConfig

      A PluginConfig to validate.

    Returns boolean

remove

  • remove(pluginName: string): boolean

  • Removes a plugin by name after unloading it and clearing any event bindings automatically.

    Parameters

    • pluginName: string

      The plugin name to remove.

    Returns boolean

removeAll

  • removeAll(): void

  • Removes all plugins after unloading them and clearing any event bindings automatically.

    Returns void

removeAllAsync

  • removeAllAsync(): Promise<any>

  • Removes all plugins after unloading them and clearing any event bindings automatically.

    Returns Promise<any>

removeAsync

  • removeAsync(pluginName: string): Promise<boolean>

  • Removes a plugin by name after unloading it and clearing any event bindings automatically.

    Parameters

    • pluginName: string

      The plugin name to remove.

    Returns Promise<boolean>

setEventbus

  • setEventbus(targetEventbus: EventEmitter, eventPrepend?: string): default

  • Sets the eventbus associated with this plugin manager. If any previous eventbus was associated all plugin manager events will be removed then added to the new eventbus. If there are any existing plugins being managed their events will be removed from the old eventbus and then onPluginLoad will be called with the new eventbus.

    Parameters

    • targetEventbus: EventEmitter

      The target eventbus to associate.

    • eventPrepend: string = "plugins"

      An optional string to prepend to all of the event binding targets.

    Returns default

setEventbusAsync

  • setEventbusAsync(targetEventbus: EventEmitter, eventPrepend?: string): Promise<default>

  • Sets the eventbus associated with this plugin manager. If any previous eventbus was associated all plugin manager events will be removed then added to the new eventbus. If there are any existing plugins being managed their events will be removed from the old eventbus and then onPluginLoad will be called with the new eventbus.

    Parameters

    • targetEventbus: EventEmitter

      The target eventbus to associate.

    • optionaleventPrepend: string

      An optional string to prepend to all of the event binding targets.

    Returns Promise<default>

setExtraEventData

  • setExtraEventData(extraEventData?: any): void

  • Sets any extra event data attached to PluginEvent extra field.

    Parameters

    • extraEventData: any = ...

      Adds extra data to PluginEvent extra field.

    Returns void

setOptions

  • setOptions(options?: PluginManagerOptions): void

  • Set optional parameters. All parameters are off by default.

    Parameters

    • optionaloptions: PluginManagerOptions

      Defines optional parameters to set.

    Returns void

setPluginEnabled

  • setPluginEnabled(pluginName: string, enabled: boolean): boolean

  • Enables or disables a single plugin.

    Parameters

    • pluginName: string

      Plugin name to set state.

    • enabled: boolean

      The new enabled state.

    Returns boolean

setPluginsEnabled

  • setPluginsEnabled(pluginNames: string[], enabled: boolean): boolean

  • Enables or disables a set of plugins given an array or iterabe of plugin names.

    Parameters

    • pluginNames: string[]

      An array / iterable of plugin names.

    • enabled: boolean

      The new enabled state.

    Returns boolean