@blac/core 2.0.0-rc-11 → 2.0.0-rc-13

package/src/plugins/SystemPluginRegistry.ts

@@ -0,0 +1,192 @@
+import { BlacPlugin, PluginRegistry, PluginMetrics, ErrorContext } from '../core/types';
+import { BlocBase } from '../BlocBase';
+import { Bloc } from '../Bloc';
+
+/**
+ * Registry for system-wide plugins
+ */
+export class SystemPluginRegistry implements PluginRegistry<BlacPlugin> {
+  private plugins = new Map<string, BlacPlugin>();
+  private metrics = new Map<string, Map<string, PluginMetrics>>();
+  private executionOrder: string[] = [];
+
+  /**
+   * Add a system plugin
+   */
+  add(plugin: BlacPlugin): void {
+    if (this.plugins.has(plugin.name)) {
+      throw new Error(`Plugin '${plugin.name}' is already registered`);
+    }
+
+    this.plugins.set(plugin.name, plugin);
+    this.executionOrder.push(plugin.name);
+    this.initializeMetrics(plugin.name);
+  }
+
+  /**
+   * Remove a system plugin
+   */
+  remove(pluginName: string): boolean {
+    const plugin = this.plugins.get(pluginName);
+    if (!plugin) return false;
+
+    this.plugins.delete(pluginName);
+    this.metrics.delete(pluginName);
+    this.executionOrder = this.executionOrder.filter(name => name !== pluginName);
+
+    return true;
+  }
+
+  /**
+   * Get a plugin by name
+   */
+  get(pluginName: string): BlacPlugin | undefined {
+    return this.plugins.get(pluginName);
+  }
+
+  /**
+   * Get all plugins in execution order
+   */
+  getAll(): ReadonlyArray<BlacPlugin> {
+    return this.executionOrder.map(name => this.plugins.get(name)!);
+  }
+
+  /**
+   * Clear all plugins
+   */
+  clear(): void {
+    this.plugins.clear();
+    this.metrics.clear();
+    this.executionOrder = [];
+  }
+
+  /**
+   * Execute a hook on all plugins
+   */
+  executeHook(
+    hookName: keyof BlacPlugin,
+    args: unknown[],
+    errorHandler?: (error: Error, plugin: BlacPlugin) => void
+  ): void {
+    for (const pluginName of this.executionOrder) {
+      const plugin = this.plugins.get(pluginName)!;
+      const hook = plugin[hookName] as Function | undefined;
+
+      if (typeof hook !== 'function') continue;
+
+      const startTime = performance.now();
+
+      try {
+        hook.apply(plugin, args);
+        this.recordSuccess(pluginName, hookName as string, startTime);
+      } catch (error) {
+        this.recordError(pluginName, hookName as string, error as Error);
+
+        if (errorHandler) {
+          errorHandler(error as Error, plugin);
+        } else {
+          // Default: log and continue
+          console.error(`Plugin '${pluginName}' error in hook '${hookName as string}':`, error);
+        }
+      }
+    }
+  }
+
+  /**
+   * Bootstrap all plugins
+   */
+  bootstrap(): void {
+    this.executeHook('beforeBootstrap', []);
+    this.executeHook('afterBootstrap', []);
+  }
+
+  /**
+   * Shutdown all plugins
+   */
+  shutdown(): void {
+    this.executeHook('beforeShutdown', []);
+    this.executeHook('afterShutdown', []);
+  }
+
+  /**
+   * Notify plugins of bloc creation
+   */
+  notifyBlocCreated(bloc: BlocBase<any>): void {
+    this.executeHook('onBlocCreated', [bloc]);
+  }
+
+  /**
+   * Notify plugins of bloc disposal
+   */
+  notifyBlocDisposed(bloc: BlocBase<any>): void {
+    this.executeHook('onBlocDisposed', [bloc]);
+  }
+
+  /**
+   * Notify plugins of state change
+   */
+  notifyStateChanged(bloc: BlocBase<any>, previousState: any, currentState: any): void {
+    this.executeHook('onStateChanged', [bloc, previousState, currentState]);
+  }
+
+  /**
+   * Notify plugins of event addition
+   */
+  notifyEventAdded(bloc: Bloc<any, any>, event: any): void {
+    this.executeHook('onEventAdded', [bloc, event]);
+  }
+
+  /**
+   * Notify plugins of errors
+   */
+  notifyError(error: Error, bloc: BlocBase<unknown>, context: ErrorContext): void {
+    this.executeHook('onError', [error, bloc, context], (hookError, plugin) => {
+      // Double fault protection - if error handler fails, just log
+      console.error(`Plugin '${plugin.name}' error handler failed:`, hookError);
+    });
+  }
+
+  /**
+   * Get metrics for a plugin
+   */
+  getMetrics(pluginName: string): Map<string, PluginMetrics> | undefined {
+    return this.metrics.get(pluginName);
+  }
+
+  private initializeMetrics(pluginName: string): void {
+    this.metrics.set(pluginName, new Map());
+  }
+
+  private recordSuccess(pluginName: string, hookName: string, startTime: number): void {
+    const pluginMetrics = this.metrics.get(pluginName)!;
+    const hookMetrics = pluginMetrics.get(hookName) || {
+      executionTime: 0,
+      executionCount: 0,
+      errorCount: 0
+    };
+
+    const executionTime = performance.now() - startTime;
+
+    pluginMetrics.set(hookName, {
+      ...hookMetrics,
+      executionTime: hookMetrics.executionTime + executionTime,
+      executionCount: hookMetrics.executionCount + 1,
+      lastExecutionTime: executionTime
+    });
+  }
+
+  private recordError(pluginName: string, hookName: string, error: Error): void {
+    const pluginMetrics = this.metrics.get(pluginName)!;
+    const hookMetrics = pluginMetrics.get(hookName) || {
+      executionTime: 0,
+      executionCount: 0,
+      errorCount: 0
+    };
+
+    pluginMetrics.set(hookName, {
+      ...hookMetrics,
+      errorCount: hookMetrics.errorCount + 1,
+      lastError: error
+    });
+  }
+}

package/src/plugins/index.ts

@@ -0,0 +1,8 @@
+// Core types
+export * from './types';
+
+// System plugins
+export { SystemPluginRegistry } from './SystemPluginRegistry';
+
+// Bloc plugins
+export { BlocPluginRegistry } from './BlocPluginRegistry';

package/src/plugins/types.ts

@@ -0,0 +1,100 @@
+import { BlocBase } from '../BlocBase';
+import { Bloc } from '../Bloc';
+
+/**
+ * Error context provided to error handlers
+ */
+export interface ErrorContext {
+  readonly phase: 'initialization' | 'state-change' | 'event-processing' | 'disposal';
+  readonly operation: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+/**
+ * Plugin capabilities for security model
+ */
+export interface PluginCapabilities {
+  readonly readState: boolean;
+  readonly transformState: boolean;
+  readonly interceptEvents: boolean;
+  readonly persistData: boolean;
+  readonly accessMetadata: boolean;
+}
+
+/**
+ * Base interface for all plugins
+ */
+export interface Plugin {
+  readonly name: string;
+  readonly version: string;
+  readonly capabilities?: PluginCapabilities;
+}
+
+/**
+ * System-wide plugin that observes all blocs
+ */
+export interface BlacPlugin extends Plugin {
+  // Lifecycle hooks - all synchronous
+  beforeBootstrap?(): void;
+  afterBootstrap?(): void;
+  beforeShutdown?(): void;
+  afterShutdown?(): void;
+
+  // System-wide observations
+  onBlocCreated?(bloc: BlocBase<any>): void;
+  onBlocDisposed?(bloc: BlocBase<any>): void;
+  onStateChanged?(bloc: BlocBase<any>, previousState: any, currentState: any): void;
+  onEventAdded?(bloc: Bloc<any, any>, event: any): void;
+  onError?(error: Error, bloc: BlocBase<unknown>, context: ErrorContext): void;
+}
+
+/**
+ * Bloc-specific plugin that can transform behavior
+ */
+export interface BlocPlugin<TState = any, TEvent = never> extends Plugin {
+  // Transform hooks - can modify data
+  transformState?(previousState: TState, nextState: TState): TState;
+  transformEvent?(event: TEvent): TEvent | null;
+
+  // Lifecycle hooks
+  onAttach?(bloc: BlocBase<TState, any>): void;
+  onDetach?(): void;
+
+  // Observation hooks
+  onStateChange?(previousState: TState, currentState: TState): void;
+  onEvent?(event: TEvent): void;
+  onError?(error: Error, context: ErrorContext): void;
+}
+
+/**
+ * Plugin execution context for performance monitoring
+ */
+export interface PluginExecutionContext {
+  readonly pluginName: string;
+  readonly hookName: string;
+  readonly startTime: number;
+  readonly blocName?: string;
+  readonly blocId?: string;
+}
+
+/**
+ * Plugin metrics for monitoring
+ */
+export interface PluginMetrics {
+  readonly executionTime: number;
+  readonly executionCount: number;
+  readonly errorCount: number;
+  readonly lastError?: Error;
+  readonly lastExecutionTime?: number;
+}
+
+/**
+ * Plugin registry interface
+ */
+export interface PluginRegistry<T extends Plugin> {
+  add(plugin: T): void;
+  remove(pluginName: string): boolean;
+  get(pluginName: string): T | undefined;
+  getAll(): ReadonlyArray<T>;
+  clear(): void;
+}