Plugins

Plugin system for extending BlaC

← Back to @blac/core

Quick Reference

Class: PluginManager

Interfaces: BlacPlugin, BlacPluginWithInit, PluginConfig, PluginContext

Functions: createPluginManager, getPluginManager, hasInitHook

Classes

PluginManager

Manages plugin lifecycle for the BlaC state management system. Plugins receive notifications about state container lifecycle events.

export declare class PluginManager

Constructor:

constructor(registry: StateContainerRegistry);

Parameter	Type	Description
registry	StateContainerRegistry	The StateContainerRegistry to monitor for lifecycle events

Methods:

clear

Uninstall all plugins

clear(): void;

getAllPlugins

Get all installed plugins

getAllPlugins(): BlacPlugin[];

Returns: Array of all installed plugins

getPlugin

Get an installed plugin by name

getPlugin(pluginName: string): BlacPlugin | undefined;

Parameter	Type	Description
pluginName	string	The name of the plugin to retrieve

Returns: The plugin instance or undefined if not found

hasPlugin

Check if a plugin is installed

hasPlugin(pluginName: string): boolean;

Parameter	Type	Description
pluginName	string	The name of the plugin to check

Returns: true if the plugin is installed

install

Install a plugin with optional configuration

install(plugin: BlacPlugin, config?: PluginConfig): void;

Parameter	Type	Description
plugin	BlacPlugin	The plugin to install
config	PluginConfig	Optional plugin configuration

uninstall

Uninstall a plugin by name

uninstall(pluginName: string): void;

Parameter	Type	Description
pluginName	string	The name of the plugin to uninstall

Examples:

const manager = createPluginManager(registry);
manager.install(myPlugin, { environment: 'development' });

---

Interfaces

BlacPlugin

Interface for plugins that extend BlaC functionality

export interface BlacPlugin

Property	Type	Description
name	string	Unique plugin identifier
version	string	Plugin version identifier

Methods:

onEventAdded

Called when an event is added to a Vertex instance

onEventAdded?<E extends DiscriminatedEvent>(vertex: Vertex<any, E>, event: EventWithMetadata<E>, context: PluginContext): void;

onInstall

Called when the plugin is installed (optional)

onInstall?(context: PluginContext): void;

onInstanceCreated

Called when a state container instance is created

onInstanceCreated?(instance: StateContainer<any>, context: PluginContext): void;

onInstanceDisposed

Called when a state container instance is disposed

onInstanceDisposed?(instance: StateContainer<any>, context: PluginContext): void;

onStateChanged

Called when state changes in a container instance

onStateChanged?<S extends object = any>(instance: StateContainer<S>, previousState: S, currentState: S, callstack: string | undefined, context: PluginContext): void;

onUninstall

Called when the plugin is uninstalled

onUninstall?(): void;

---

BlacPluginWithInit

Plugin interface variant that requires mandatory onInstall hook

export interface BlacPluginWithInit extends BlacPlugin

Methods:

onInstall

Required initialization hook called when plugin is installed

onInstall(context: PluginContext): void;

---

PluginConfig

Configuration options for plugin installation

export interface PluginConfig

Property	Type	Description
enabled (optional)	boolean	Enable or disable the plugin
environment (optional)	'development' | 'production' | 'test' | 'all'	Environments where plugin runs

---

PluginContext

Safe context API provided to plugins for accessing registry data

export interface PluginContext

Methods:

getAllTypes

Get all registered state container types

getAllTypes(): Array<new (...args: any[]) => StateContainer<any>>;

getInstanceMetadata

Get metadata for a specific instance

getInstanceMetadata(instance: StateContainer<any>): InstanceMetadata;

getState

Get current state from a container

getState<S extends object = any>(instance: StateContainer<S>): S;

getStats

Get registry statistics

getStats(): {
        registeredTypes: number;
        totalInstances: number;
        typeBreakdown: Record<string, number>;
    };

queryInstances

Get all instances of a specific type

queryInstances<T extends StateContainer<any>>(typeClass: new (...args: any[]) => T): T[];

---

Functions

createPluginManager

Create a plugin manager instance

export declare function createPluginManager(registry: StateContainerRegistry): PluginManager;

Parameter	Type	Description
registry	StateContainerRegistry	The StateContainerRegistry to monitor for lifecycle events

Returns: A new PluginManager instance

---

getPluginManager

Get the global plugin manager

export declare function getPluginManager(): any;

---

hasInitHook

Type guard to check if a plugin has a required onInstall hook

export declare function hasInitHook(plugin: BlacPlugin): plugin is BlacPluginWithInit;

Parameter	Type	Description
plugin	BlacPlugin	The plugin to check

Returns: true if the plugin implements BlacPluginWithInit

---