# Module: pluginBroker

Contains all of the lower level plugin processing functions, and also acts as an interface for loading, unloading, reloading, registering, unregistering plugins and plugin metaData.

Author:
  - Seth Hollingsead
Copyright:
  - Copyright © 2022-… by Seth Hollingsead. All rights reserved
Source:
  - brokers/pluginBroker.js, line 1

### Requires

- module:ruleBroker
- module:loggers
- module:data
- @haystacks/constants
- url
- path

### Methods

#### (inner) countPluginsInRegistry() → {integer}

Scans the plugin registry data hive and determines how many plugins are registered there.

Author:
  - Seth Hollingsead
Source:
  - brokers/pluginBroker.js, line 144

##### Returns:

The count of the number of plugins listed in the plugin registry data hive.

Type
  integer

#### (inner) countPluginsInRegistryPath() → {integer}

Counts the number of sub-folders located at the path specified in the plugin registry data hive.

Author:
  - Seth Hollingsead
Source:
  - brokers/pluginBroker.js, line 162

##### Returns:

The count of the number of plugin sub-folders in the plugins path listed in the plugin registry data hive.

Type
  integer

#### (inner) extractAndProcessPluginEntryPointURI(pluginMetaData, pluginPath) → {string}

Extracts the entry point path and file name for a plugin from the package.json data object. Processes the entry point path with a path.join to form a fully qualified path. Converts the resulting fully qualified path into a path URI string for importing later.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pluginMetaData` | object | The meta data for the given plugin loaded for the corrosponding package.json.
`pluginPath` | string | The path to the plugin, used to form a fully-qualified path.

Author:
  - Seth Hollingsead
Source:
  - brokers/pluginBroker.js, line 422

##### Returns:

The path entry point to the plugin as a URI file path.

Type
  string

#### (inner) listPluginsInRegistry() → {array.<string>}

Builds a list array of the names of the plugins in the plugin registry.

Author:
  - Seth Hollingsead
Source:
  - brokers/pluginBroker.js, line 85

##### Returns:

A list array of the names of the plugins in the plugin registry.

Type
  array.<string>

#### (inner) listPluginsInRegistryPath() → {array.<string>}

In the plugin registry there should be an entry for the path of the plugins on the local system. This function will load that path and return a list of the sub-folders located at that path.

Author:
  - Seth Hollingsead
Source:
  - brokers/pluginBroker.js, line 125

##### Returns:

A list array of the names of the plugins located at the specified path on the local system from the plugins registry data hive.

Type
  array.<string>

#### (inner) listPluginsPathsInRegistry() → {array.<string>}

Builds a list array of the paths of the plugins in the plugin registry.

Author:
  - Seth Hollingsead
Source:
  - brokers/pluginBroker.js, line 105

##### Returns:

A list array of the paths of the plugins in the plugin registry.

Type
  array.<string>

#### (inner) loadPlugin(pluginExecutionPath) → {object}

Uses a combination of promises and a function call to import the specified plugin file at the specified URI path.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pluginExecutionPath` | string | The entry point for the plugin that should be loaded.

Author:
  - Seth Hollingsead
Source:
  - brokers/pluginBroker.js, line 461

##### Returns:

The data that was returned and loaded from the plugin.

Type
  object

#### (inner) loadPluginMetaData(pluginPath) → {object}

Loads the plugin meta data for the plugin at the specified path by looking for a package.json at the specified path and loading that file, and returning it as a JSON object.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pluginPath` | string | The path to a plugin where a package.json should be expected to be found for that plugin.

Author:
  - Seth Hollingsead
Source:
  - brokers/pluginBroker.js, line 398

##### Returns:

The JSON data object loaded from the plugin package.json file, specified by the input parameter.

Type
  object

#### (inner) loadPluginRegistry(pluginRegistryPath) → {object}

Loads the plugin registry file, which specified the data with the paths were plugins should be loaded from.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pluginRegistryPath` | string | Teh path to the plugin registry for the app that loaded the haystacks framework.

Author:
  - Seth Hollingsead
Source:
  - brokers/pluginBroker.js, line 33

##### Returns:

The JSON data object loaded from the specified plugin registry path by the input parameter.

Type
  object

#### (inner) registerPlugin(pluginName, pluginPath) → {boolean}

Manually registers a plugin with the plugin registry data hive. Allows for special case where plugins can be registered from a different path, then the path specified by the plugin registry. Caution should be emphasised when loading plugins from a custom path location, this should be used primarily for debugging and triage use cases.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pluginName` | string | The name of the plugin that should be registered.
`pluginPath` | string | The path to the plugin, to be added to the plugin registry. This should be the path to the plugin/package.json file, but not including the package.json as part of the path URI.

Author:
  - Seth Hollingsead
Source:
  - brokers/pluginBroker.js, line 180

##### Returns:

True or False to indicate if the plugin was added to the plugin registry successfully or not.

Type
  boolean

#### (inner) savePluginRegistry() → {boolean}

Exports the plugin registry data hive JSON object and saves it out to disk, over-writing any existing plugin registry JSON file at the location specified by the application.

Author:
  - Seth Hollingsead
Source:
  - brokers/pluginBroker.js, line 366

##### Returns:

True or False to indicate if the export to file was completed successfully or not.

Type
  boolean

#### (inner) storePluginRegistryInDataStructure(pluginRegistryData) → {boolean}

Pushes the input plugin registry data to the D-data structure so it can be used by the rest of the framework.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pluginRegistryData` | object | The plugin registry data that should be stored in the D-data structure.

Author:
  - Seth Hollingsead
Source:
  - brokers/pluginBroker.js, line 56

##### Returns:

A True or False value to indicate if the data was successfully stored in the D-data structure or not.

Type
  boolean

#### (inner) syncPluginRegistryWithPluginRegistryPath() → {boolean}

performs a synchronization procedure on the plugin registry to ensure that the contents and plugins registered in the plugin registry match with the list of plugin folders located at the path specified in the plugin registry as the default plugin path. The updates are made to the plugin registry data hive.

Author:
  - Seth Hollingsead
Source:
  - brokers/pluginBroker.js, line 259

##### Returns:

True or False to indicate if the synchronization was performed successfully.

Type
  boolean

#### (inner) unregisterAllPlugins() → {boolean}

Removes all plugins from the list of registered plugins in the plugin registry. This removes all plugins in the plugins registry data hive.

Author:
  - Seth Hollingsead
Source:
  - brokers/pluginBroker.js, line 339

##### Returns:

True or False to indicate if the plugin registry data hive was cleared successfully or not.

Type
  boolean

#### (inner) unregisterPlugin(pluginName) → {boolean}

Manually removes a plugin from the plugin registry data hive.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pluginName` | string | The name of the plugin that should be removed from the plugin registry.

Author:
  - Seth Hollingsead
Source:
  - brokers/pluginBroker.js, line 218

##### Returns:

True or False to indicate if the plugin was removed from the plugin registry successfully or not.

Type
  boolean