@seal-sdk/plugin

Plugin registration and activation for the SEAL SDK.

@seal-sdk/plugin provides PluginEngine, which manages plugins and gives them access to an EngineRegistry during activation.

Applications composed with @seal-sdk/platform access the engine through platform.plugin.

Installation

For the recommended Platform composition:

npm install @seal-sdk/platform

For direct composition:

npm install @seal-sdk/plugin

Quick start

import {
  PlatformBuilder,
} from "@seal-sdk/platform";

const seal =
  new PlatformBuilder().build();

seal.plugin.register({
  id: "example-plugin",

  activate(registry) {
    // The registry is shared with the Platform host.
    void registry;
  },

  deactivate() {
    // Release synchronous plugin resources here.
  },
});

await seal.plugin.activate(
  "example-plugin",
);

console.log(
  seal.plugin.isActive(
    "example-plugin",
  ),
);

seal.plugin.deactivate(
  "example-plugin",
);

Plugin contract

A plugin has a required id and optional lifecycle hooks:

interface Plugin {
  readonly id: string;

  activate?: (
    registry: EngineRegistry,
  ) => void | Promise<void>;

  deactivate?: () => void;
}

Activation may be synchronous or asynchronous. Deactivation is currently synchronous.

PluginEngine

PluginEngine exposes:

• register(plugin)
• listPlugins()
• get(id)
• activate(id)
• deactivate(id)
• isActive(id)
• unregister(id)

register(plugin)

Registers a plugin by its id.

Registering the same id more than once is ignored. The original plugin remains registered.

listPlugins()

Returns a new array containing the registered plugins.

Changing the returned array does not change the engine's internal plugin list.

get(id)

Returns the registered plugin with the requested id.

The result is undefined when no matching plugin exists.

activate(id)

Activates a registered plugin.

Activation is idempotent:

• an active plugin is not activated again;
• a plugin with pending asynchronous activation is not activated again;
• an unknown plugin id is ignored.

A plugin without an activate hook is considered active immediately.

The activation hook receives the EngineRegistry owned by the Plugin Engine. When the engine comes from PlatformBuilder, this is the same registry used by the Platform host.

Asynchronous activation

When activate() returns a Promise, the plugin is considered active only after the Promise resolves.

While activation is pending, duplicate activation is prevented.

If activation rejects:

• the rejection is returned to the caller;
• the pending state is cleared;
• the plugin is not marked active;
• a later retry is allowed.

If a plugin is unregistered while activation is pending, completion of the Promise does not create orphaned active state.

deactivate(id)

Synchronously deactivates an active plugin.

Deactivation is idempotent:

• an inactive plugin is ignored;
• an unknown plugin id is ignored;
• an optional deactivate hook runs at most once for each active state.

After the hook runs, the plugin is no longer active.

isActive(id)

Returns whether the plugin has completed activation and is currently active.

Pending asynchronous activation does not count as active.

unregister(id)

Removes a registered plugin.

Unregistering:

• ignores unknown ids;
• removes active state;
• prevents a pending activation from producing orphaned active state.

unregister() does not call the plugin's deactivate hook automatically.

Direct composition

PluginEngine can receive an existing EngineRegistry:

import {
  PluginEngine,
} from "@seal-sdk/plugin";

import {
  EngineRegistry,
} from "@seal-sdk/registry";

const registry =
  new EngineRegistry();

const plugin =
  new PluginEngine(registry);

When no Registry is provided, the engine creates its own instance.

Most applications should use PlatformBuilder, which connects the Plugin Engine to the shared host Registry.

Public exports

The package exports:

• Plugin
• PluginEngine