ServerPluginManager

ServerPluginManager

The PluginManager allows to register and retrieve soundworks plugins.

Plugins should always be registered both client-side and server-side, and before Client#start or Server#start to be properly initialized.

In some sitautions, you might want to register the same plugin factory several times using different ids (e.g. for watching several parts of the file system, etc.).

Refer to the plugins' documentation for more precise examples, and the specific API they expose. See https://soundworks.dev/guide/ecosystem for more informations on the available plugins.

// client-side
import { Client } from '@soundworks/core/client.js';
import syncPlugin from '@soundworks/plugin-sync/client.js';

const client = new Client(config);
// register the plugin before `client.start()`
client.pluginManager.register('sync', syncPlugin);

await client.start();

const sync = await client.pluginManager.get('sync');

setInterval(() => {
  // log the estimated global synced clock alongside the local clock.
  console.log(sync.getSyncTime(), sync.getLocalTime());
}, 1000);

// server-side
import { Server } from '@soundworks/core/server.js';
import syncPlugin from '@soundworks/plugin-sync/server.js';

const server = new Server(config);
// register the plugin before `server.start()`
server.pluginManager.register('sync', syncPlugin);

await server.start();

const sync = await server.pluginManager.get('sync');

setInterval(() => {
  // log the estimated global synced clock alongside the local clock.
  console.log(sync.getSyncTime(), sync.getLocalTime());
}, 1000);

Extends

Members

[undefined]

Description:

  • #private

Source:
Overrides:

#private

status :'idle'|'inited'|'started'|'errored'

Description:

  • Status of the plugin manager

Source:
Overrides:

Status of the plugin manager

Type:
  • 'idle' | 'inited' | 'started' | 'errored'

Methods

addDependency()

Description:

  • Manually add a dependency to a given plugin.

    Usefull to require a plugin within a plugin

Source:
Overrides:

(async) get(id) → {ServerPlugin}

Description:

  • Retrieve a fully started instance of a registered plugin.

    Be aware that the get method resolves only when the plugin is fully 'started', which is what we want 99.99% of the time. As such, and to prevent the application to be stuck in some kind of Promise dead lock, this method will throw if used before server.init() (or server.start()).

    To handle the remaining 0.01% cases and access plugin instances during their initialization (e.g. to display initialization screen, etc.), you should rely on the onStateChange method.

    Note: the async API is designed to enable the dynamic creation of plugins (hopefully without brealing changes) in a future release.

Source:
Parameters:
Name Type Description
id ServerPlugin#id

Id of the plugin as defined when registered.
Returns:
Type
ServerPlugin

getRegisteredPlugins() → {Array.<string>}

Description:

  • Returns the list of the registered plugins ids

Source:
Overrides:
Returns:
Type
Array.<string>

(async) getUnsafe()

Description:

  • Retrieve an fully started instance of a registered plugin without checking that the pluginManager is started.

    This method is required for starting the plugin manager itself and to require a plugin from within another plugin.

    Warning: Unless you are developing your own plugins, you should not have to use this method

Source:
Overrides:

onStateChange(callback) → {pluginManagerDeleteOnStateChangeCallback}

Description:

  • Propagate a notification each time a plugin is updated (status or inner state). The callback will receive the list of all plugins as first parameter, and the plugin instance that initiated the state change event as second parameter.

    In most cases, you should not have to rely on this method.

Source:
Overrides:
Example
const unsubscribe = client.pluginManager.onStateChange(pluginList, initiator => {
  // log the current status of all plugins
  for (let name in pluginList) {
    console.log(name, pluginList[name].status);
  }
  // if the change was initiated by a plugin, log its status and state
  if (initiator !== null) {
.    console.log(initiator.name, initiator.status, initiator.state);
  }
});
// stop listening for updates later
unsubscribe();
Parameters:
Name Type Description
callback pluginManagerOnStateChangeCallback

Callback to execute on state change
Returns:
  • Clear the subscription when executed
Type
pluginManagerDeleteOnStateChangeCallback

register(id, factory, optionsopt, depsopt)

Description:

  • Register a plugin into the manager.

    A plugin must always be registered both on client-side and on server-side

    Refer to the plugin documentation to check its options and proper way of registering it.

Source:
Overrides:
See:
Example
// client-side
client.pluginManager.register('user-defined-id', pluginFactory);
// server-side
server.pluginManager.register('user-defined-id', pluginFactory);
Parameters:
Name Type Attributes Default Description
id string

Unique id of the plugin. Enables the registration of the same plugin factory under different ids.
factory function null

Factory function that returns the Plugin class.
options object <optional>
 {}

Options to configure the plugin.
deps array <optional>
 []

List of plugins' names the plugin depends on, i.e. the plugin initialization will start only after the plugins it depends on are fully started themselves.