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

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

@@ -1,13 +1,17 @@
-import { BlocPlugin, PluginRegistry, ErrorContext } from '../core/types';
+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>> {
+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
    */
@@ -15,52 +19,53 @@ export class BlocPluginRegistry<TState, TEvent = never> implements PluginRegistr
     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) {
-      try {
-        plugin.onDetach();
-      } catch (error) {
-        console.error(`Plugin '${pluginName}' error in onDetach:`, error);
-      }
+      handleError.wrap(() => plugin.onDetach!(), ErrorCategory.PLUGIN, {
+        pluginName,
+        operation: 'onDetach',
+      });
     }
-    
+
     this.plugins.delete(pluginName);
-    this.executionOrder = this.executionOrder.filter(name => name !== 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)!);
+    return this.executionOrder.map((name) => this.plugins.get(name)!);
   }
-  
+
   /**
    * Clear all plugins
    */
@@ -69,20 +74,19 @@ export class BlocPluginRegistry<TState, TEvent = never> implements PluginRegistr
     if (this.attached) {
       for (const plugin of this.getAll()) {
         if (plugin.onDetach) {
-          try {
-            plugin.onDetach();
-          } catch (error) {
-            console.error(`Plugin '${plugin.name}' error in onDetach:`, error);
-          }
+          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
    */
@@ -90,7 +94,7 @@ export class BlocPluginRegistry<TState, TEvent = never> implements PluginRegistr
     if (this.attached) {
       throw new Error('Plugins are already attached');
     }
-    
+
     for (const plugin of this.getAll()) {
       if (plugin.onAttach) {
         try {
@@ -102,52 +106,61 @@ export class BlocPluginRegistry<TState, TEvent = never> implements PluginRegistr
         }
       }
     }
-    
+
     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);
+          transformedState = plugin.transformState(
+            previousState,
+            transformedState,
+          );
         } catch (error) {
-          console.error(`Plugin '${plugin.name}' error in transformState:`, 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);
+          console.error(
+            `Plugin '${plugin.name}' error in transformEvent:`,
+            error,
+          );
           // Continue with untransformed event
         }
       }
     }
-    
+
     return transformedEvent;
   }
-  
+
   /**
    * Notify plugins of state change
    */
@@ -157,12 +170,15 @@ export class BlocPluginRegistry<TState, TEvent = never> implements PluginRegistr
         try {
           plugin.onStateChange(previousState, currentState);
         } catch (error) {
-          console.error(`Plugin '${plugin.name}' error in onStateChange:`, error);
+          console.error(
+            `Plugin '${plugin.name}' error in onStateChange:`,
+            error,
+          );
         }
       }
     }
   }
-  
+
   /**
    * Notify plugins of event
    */
@@ -177,7 +193,7 @@ export class BlocPluginRegistry<TState, TEvent = never> implements PluginRegistr
       }
     }
   }
-  
+
   /**
    * Notify plugins of error
    */
@@ -192,29 +208,33 @@ export class BlocPluginRegistry<TState, TEvent = never> implements PluginRegistr
       }
     }
   }
-  
+
   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`);
+      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`);
+      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

@@ -1,4 +1,10 @@
-import { BlacPlugin, PluginRegistry, PluginMetrics, ErrorContext } from '../core/types';
+import {
+  BlacPlugin,
+  PluginRegistry,
+  PluginMetrics,
+  ErrorContext,
+  AdapterMetadata,
+} from './types';
 import { BlocBase } from '../BlocBase';
 import { Bloc } from '../Bloc';
 
@@ -32,7 +38,9 @@ export class SystemPluginRegistry implements PluginRegistry<BlacPlugin> {
 
     this.plugins.delete(pluginName);
     this.metrics.delete(pluginName);
-    this.executionOrder = this.executionOrder.filter(name => name !== pluginName);
+    this.executionOrder = this.executionOrder.filter(
+      (name) => name !== pluginName,
+    );
 
     return true;
   }
@@ -48,7 +56,7 @@ export class SystemPluginRegistry implements PluginRegistry<BlacPlugin> {
    * Get all plugins in execution order
    */
   getAll(): ReadonlyArray<BlacPlugin> {
-    return this.executionOrder.map(name => this.plugins.get(name)!);
+    return this.executionOrder.map((name) => this.plugins.get(name)!);
   }
 
   /**
@@ -66,7 +74,7 @@ export class SystemPluginRegistry implements PluginRegistry<BlacPlugin> {
   executeHook(
     hookName: keyof BlacPlugin,
     args: unknown[],
-    errorHandler?: (error: Error, plugin: BlacPlugin) => void
+    errorHandler?: (error: Error, plugin: BlacPlugin) => void,
   ): void {
     for (const pluginName of this.executionOrder) {
       const plugin = this.plugins.get(pluginName)!;
@@ -86,7 +94,10 @@ export class SystemPluginRegistry implements PluginRegistry<BlacPlugin> {
           errorHandler(error as Error, plugin);
         } else {
           // Default: log and continue
-          console.error(`Plugin '${pluginName}' error in hook '${hookName as string}':`, error);
+          console.error(
+            `Plugin '${pluginName}' error in hook '${hookName as string}':`,
+            error,
+          );
         }
       }
     }
@@ -125,7 +136,11 @@ export class SystemPluginRegistry implements PluginRegistry<BlacPlugin> {
   /**
    * Notify plugins of state change
    */
-  notifyStateChanged(bloc: BlocBase<any>, previousState: any, currentState: any): void {
+  notifyStateChanged(
+    bloc: BlocBase<any>,
+    previousState: any,
+    currentState: any,
+  ): void {
     this.executeHook('onStateChanged', [bloc, previousState, currentState]);
   }
 
@@ -139,13 +154,40 @@ export class SystemPluginRegistry implements PluginRegistry<BlacPlugin> {
   /**
    * Notify plugins of errors
    */
-  notifyError(error: Error, bloc: BlocBase<unknown>, context: ErrorContext): void {
+  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
    */
@@ -157,12 +199,16 @@ export class SystemPluginRegistry implements PluginRegistry<BlacPlugin> {
     this.metrics.set(pluginName, new Map());
   }
 
-  private recordSuccess(pluginName: string, hookName: string, startTime: number): void {
+  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
+      errorCount: 0,
     };
 
     const executionTime = performance.now() - startTime;
@@ -171,22 +217,26 @@ export class SystemPluginRegistry implements PluginRegistry<BlacPlugin> {
       ...hookMetrics,
       executionTime: hookMetrics.executionTime + executionTime,
       executionCount: hookMetrics.executionCount + 1,
-      lastExecutionTime: executionTime
+      lastExecutionTime: executionTime,
     });
   }
 
-  private recordError(pluginName: string, hookName: string, error: Error): void {
+  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
+      errorCount: 0,
     };
 
     pluginMetrics.set(hookName, {
       ...hookMetrics,
       errorCount: hookMetrics.errorCount + 1,
-      lastError: error
+      lastError: error,
     });
   }
 }