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

package/src/lifecycle/BlocLifecycle.ts

@@ -0,0 +1,156 @@
+/**
+ * Enum representing the lifecycle states of a Bloc instance
+ */
+export enum BlocLifecycleState {
+  ACTIVE = 'active',
+  DISPOSAL_REQUESTED = 'disposal_requested',
+  DISPOSING = 'disposing',
+  DISPOSED = 'disposed',
+}
+
+export interface StateTransitionResult {
+  success: boolean;
+  currentState: BlocLifecycleState;
+  previousState: BlocLifecycleState;
+}
+
+/**
+ * Manages the lifecycle state transitions for Bloc instances.
+ * Ensures atomic state transitions to prevent race conditions during disposal.
+ */
+export class BlocLifecycleManager {
+  private disposalState = BlocLifecycleState.ACTIVE;
+  private disposalLock = false;
+  private disposalTimer?: NodeJS.Timeout | number;
+  private disposalHandler?: (bloc: unknown) => void;
+
+  get currentState(): BlocLifecycleState {
+    return this.disposalState;
+  }
+
+  get isDisposed(): boolean {
+    return this.disposalState === BlocLifecycleState.DISPOSED;
+  }
+
+  /**
+   * Atomic state transition for disposal
+   */
+  atomicStateTransition(
+    expectedState: BlocLifecycleState,
+    newState: BlocLifecycleState,
+  ): StateTransitionResult {
+    if (this.disposalLock) {
+      return {
+        success: false,
+        currentState: this.disposalState,
+        previousState: this.disposalState,
+      };
+    }
+
+    this.disposalLock = true;
+    try {
+      if (this.disposalState !== expectedState) {
+        return {
+          success: false,
+          currentState: this.disposalState,
+          previousState: this.disposalState,
+        };
+      }
+
+      const previousState = this.disposalState;
+      this.disposalState = newState;
+
+      return {
+        success: true,
+        currentState: newState,
+        previousState,
+      };
+    } finally {
+      this.disposalLock = false;
+    }
+  }
+
+  /**
+   * Schedule disposal after a delay
+   */
+  scheduleDisposal(
+    delay: number,
+    canDispose: () => boolean,
+    onDispose: () => void,
+  ): void {
+    // Cancel any existing disposal timer
+    if (this.disposalTimer) {
+      clearTimeout(this.disposalTimer as NodeJS.Timeout);
+      this.disposalTimer = undefined;
+    }
+
+    const transitionResult = this.atomicStateTransition(
+      BlocLifecycleState.ACTIVE,
+      BlocLifecycleState.DISPOSAL_REQUESTED,
+    );
+
+    if (!transitionResult.success) {
+      return;
+    }
+
+    this.disposalTimer = setTimeout(() => {
+      if (
+        canDispose() &&
+        this.disposalState === BlocLifecycleState.DISPOSAL_REQUESTED
+      ) {
+        onDispose();
+      } else {
+        this.atomicStateTransition(
+          BlocLifecycleState.DISPOSAL_REQUESTED,
+          BlocLifecycleState.ACTIVE,
+        );
+      }
+    }, delay);
+  }
+
+  /**
+   * Cancel disposal if in disposal requested state
+   */
+  cancelDisposal(): boolean {
+    if (this.disposalState === BlocLifecycleState.DISPOSAL_REQUESTED) {
+      // Cancel disposal timer
+      if (this.disposalTimer) {
+        clearTimeout(this.disposalTimer as NodeJS.Timeout);
+        this.disposalTimer = undefined;
+      }
+
+      // Transition back to active state
+      const result = this.atomicStateTransition(
+        BlocLifecycleState.DISPOSAL_REQUESTED,
+        BlocLifecycleState.ACTIVE,
+      );
+
+      return result.success;
+    }
+    return false;
+  }
+
+  /**
+   * Set disposal handler
+   */
+  setDisposalHandler(handler: (bloc: unknown) => void): void {
+    this.disposalHandler = handler;
+  }
+
+  /**
+   * Get disposal handler
+   */
+  getDisposalHandler(): ((bloc: unknown) => void) | undefined {
+    return this.disposalHandler;
+  }
+
+  /**
+   * Clear disposal timer
+   */
+  clearDisposalTimer(): void {
+    if (this.disposalTimer) {
+      clearTimeout(this.disposalTimer as NodeJS.Timeout);
+      this.disposalTimer = undefined;
+    }
+  }
+}

package/src/lifecycle/index.ts

@@ -0,0 +1 @@
+export * from './BlocLifecycle';

package/src/plugins/BlocPluginRegistry.ts

@@ -0,0 +1,240 @@
+import { BlocPlugin, PluginRegistry, ErrorContext } from './types';
+import { handleError } from '../errors/handleError';
+import { ErrorCategory } from '../errors/BlacError';
+
+/**
+ * Registry for bloc-specific plugins
+ */
+export class BlocPluginRegistry<TState, TEvent = never>
+  implements PluginRegistry<BlocPlugin<TState, TEvent>>
+{
+  private plugins = new Map<string, BlocPlugin<TState, TEvent>>();
+  private executionOrder: string[] = [];
+  private attached = false;
+
+  /**
+   * Add a bloc plugin
+   */
+  add(plugin: BlocPlugin<TState, TEvent>): void {
+    if (this.plugins.has(plugin.name)) {
+      throw new Error(`Plugin '${plugin.name}' is already registered`);
+    }
+
+    // Validate capabilities
+    if (plugin.capabilities) {
+      this.validateCapabilities(plugin);
+    }
+
+    this.plugins.set(plugin.name, plugin);
+    this.executionOrder.push(plugin.name);
+  }
+
+  /**
+   * Remove a bloc plugin
+   */
+  remove(pluginName: string): boolean {
+    const plugin = this.plugins.get(pluginName);
+    if (!plugin) return false;
+
+    // Call onDetach if attached
+    if (this.attached && plugin.onDetach) {
+      handleError.wrap(() => plugin.onDetach!(), ErrorCategory.PLUGIN, {
+        pluginName,
+        operation: 'onDetach',
+      });
+    }
+
+    this.plugins.delete(pluginName);
+    this.executionOrder = this.executionOrder.filter(
+      (name) => name !== pluginName,
+    );
+
+    return true;
+  }
+
+  /**
+   * Get a plugin by name
+   */
+  get(pluginName: string): BlocPlugin<TState, TEvent> | undefined {
+    return this.plugins.get(pluginName);
+  }
+
+  /**
+   * Get all plugins in execution order
+   */
+  getAll(): ReadonlyArray<BlocPlugin<TState, TEvent>> {
+    return this.executionOrder.map((name) => this.plugins.get(name)!);
+  }
+
+  /**
+   * Clear all plugins
+   */
+  clear(): void {
+    // Detach all plugins first
+    if (this.attached) {
+      for (const plugin of this.getAll()) {
+        if (plugin.onDetach) {
+          handleError.wrap(() => plugin.onDetach!(), ErrorCategory.PLUGIN, {
+            pluginName: plugin.name,
+            operation: 'onDetach',
+          });
+        }
+      }
+    }
+
+    this.plugins.clear();
+    this.executionOrder = [];
+    this.attached = false;
+  }
+
+  /**
+   * Attach all plugins to a bloc
+   */
+  attach(bloc: any): void {
+    if (this.attached) {
+      throw new Error('Plugins are already attached');
+    }
+
+    for (const plugin of this.getAll()) {
+      if (plugin.onAttach) {
+        try {
+          plugin.onAttach(bloc);
+        } catch (error) {
+          console.error(`Plugin '${plugin.name}' error in onAttach:`, error);
+          // Remove failing plugin
+          this.remove(plugin.name);
+        }
+      }
+    }
+
+    this.attached = true;
+  }
+
+  /**
+   * Transform state through all plugins
+   */
+  transformState(previousState: TState, nextState: TState): TState {
+    let transformedState = nextState;
+
+    for (const plugin of this.getAll()) {
+      if (plugin.transformState && this.canTransformState(plugin)) {
+        try {
+          transformedState = plugin.transformState(
+            previousState,
+            transformedState,
+          );
+        } catch (error) {
+          console.error(
+            `Plugin '${plugin.name}' error in transformState:`,
+            error,
+          );
+          // Continue with untransformed state
+        }
+      }
+    }
+
+    return transformedState;
+  }
+
+  /**
+   * Transform event through all plugins
+   */
+  transformEvent(event: TEvent): TEvent | null {
+    let transformedEvent: TEvent | null = event;
+
+    for (const plugin of this.getAll()) {
+      if (transformedEvent === null) break;
+
+      if (plugin.transformEvent && this.canInterceptEvents(plugin)) {
+        try {
+          transformedEvent = plugin.transformEvent(transformedEvent);
+        } catch (error) {
+          console.error(
+            `Plugin '${plugin.name}' error in transformEvent:`,
+            error,
+          );
+          // Continue with untransformed event
+        }
+      }
+    }
+
+    return transformedEvent;
+  }
+
+  /**
+   * Notify plugins of state change
+   */
+  notifyStateChange(previousState: TState, currentState: TState): void {
+    for (const plugin of this.getAll()) {
+      if (plugin.onStateChange && this.canReadState(plugin)) {
+        try {
+          plugin.onStateChange(previousState, currentState);
+        } catch (error) {
+          console.error(
+            `Plugin '${plugin.name}' error in onStateChange:`,
+            error,
+          );
+        }
+      }
+    }
+  }
+
+  /**
+   * Notify plugins of event
+   */
+  notifyEvent(event: TEvent): void {
+    for (const plugin of this.getAll()) {
+      if (plugin.onEvent && this.canReadState(plugin)) {
+        try {
+          plugin.onEvent(event);
+        } catch (error) {
+          console.error(`Plugin '${plugin.name}' error in onEvent:`, error);
+        }
+      }
+    }
+  }
+
+  /**
+   * Notify plugins of error
+   */
+  notifyError(error: Error, context: ErrorContext): void {
+    for (const plugin of this.getAll()) {
+      if (plugin.onError) {
+        try {
+          plugin.onError(error, context);
+        } catch (hookError) {
+          console.error(`Plugin '${plugin.name}' error in onError:`, hookError);
+        }
+      }
+    }
+  }
+
+  private validateCapabilities(plugin: BlocPlugin<TState, TEvent>): void {
+    const caps = plugin.capabilities!;
+
+    // Validate logical constraints
+    if (caps.transformState && !caps.readState) {
+      throw new Error(
+        `Plugin '${plugin.name}': transformState requires readState capability`,
+      );
+    }
+
+    if (caps.interceptEvents && !caps.readState) {
+      throw new Error(
+        `Plugin '${plugin.name}': interceptEvents requires readState capability`,
+      );
+    }
+  }
+
+  private canReadState(plugin: BlocPlugin<TState, TEvent>): boolean {
+    return !plugin.capabilities || plugin.capabilities.readState !== false;
+  }
+
+  private canTransformState(plugin: BlocPlugin<TState, TEvent>): boolean {
+    return !plugin.capabilities || plugin.capabilities.transformState === true;
+  }
+
+  private canInterceptEvents(plugin: BlocPlugin<TState, TEvent>): boolean {
+    return !plugin.capabilities || plugin.capabilities.interceptEvents === true;
+  }
+}

package/src/plugins/SystemPluginRegistry.ts

@@ -0,0 +1,242 @@
+import {
+  BlacPlugin,
+  PluginRegistry,
+  PluginMetrics,
+  ErrorContext,
+  AdapterMetadata,
+} from './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);
+    });
+  }
+
+  /**
+   * Notify plugins of adapter lifecycle events
+   */
+  notifyAdapterCreated(adapter: any, metadata: AdapterMetadata): void {
+    this.executeHook('onAdapterCreated', [adapter, metadata]);
+  }
+
+  notifyAdapterMount(adapter: any, metadata: AdapterMetadata): void {
+    this.executeHook('onAdapterMount', [adapter, metadata]);
+  }
+
+  notifyAdapterUnmount(adapter: any, metadata: AdapterMetadata): void {
+    this.executeHook('onAdapterUnmount', [adapter, metadata]);
+  }
+
+  notifyAdapterRender(adapter: any, metadata: AdapterMetadata): void {
+    this.executeHook('onAdapterRender', [adapter, metadata]);
+  }
+
+  notifyAdapterDisposed(adapter: any, metadata: AdapterMetadata): void {
+    this.executeHook('onAdapterDisposed', [adapter, metadata]);
+  }
+
+  /**
+   * 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,
+    });
+  }
+}