@blac/core 2.0.0-rc-5 → 2.0.0-rc-6

package/src/Bloc.ts

@@ -1,12 +1,13 @@
 import { Blac } from './Blac';
 import { BlocBase } from './BlocBase';
+import { BlocEventConstraint } from './types';
 
-// A should be the base type for all events this Bloc handles and must be an object type
-// to access action.constructor. Events are typically class instances.
+// A should be the base type for all events this Bloc handles and must extend BlocEventConstraint
+// to access action.constructor and ensure proper event structure.
 // P is for props, changed from any to unknown.
 export abstract class Bloc<
     S, // State type
-    A extends object, // Base Action/Event type, constrained to object
+    A extends BlocEventConstraint = BlocEventConstraint, // Base Action/Event type with proper constraints
     P = unknown // Props type
 > extends BlocBase<S, P> {
     // Stores handlers: Map<EventConstructor (subtype of A), HandlerFunction>
@@ -22,6 +23,18 @@ export abstract class Bloc<
         (event: A, emit: (newState: S) => void) => void | Promise<void>
     > = new Map();
 
+    /**
+     * @internal
+     * Event queue to ensure sequential processing of async events
+     */
+    private _eventQueue: A[] = [];
+    
+    /**
+     * @internal
+     * Flag indicating if an event is currently being processed
+     */
+    private _isProcessingEvent = false;
+
     /**
      * Registers an event handler for a specific event type.
      * This method is typically called in the constructor of a derived Bloc class.
@@ -53,11 +66,46 @@ export abstract class Bloc<
 
     /**
      * Dispatches an action/event to the Bloc.
-     * If a handler is registered for this specific event type (via 'on'), it will be invoked.
-     * Asynchronous handlers are awaited.
+     * Events are queued and processed sequentially to prevent race conditions.
      * @param action The action/event instance to be processed.
      */
     public add = async (action: A): Promise<void> => {
+        // Add event to queue
+        this._eventQueue.push(action);
+        
+        // If not already processing, start processing the queue
+        if (!this._isProcessingEvent) {
+            await this._processEventQueue();
+        }
+    };
+
+    /**
+     * @internal
+     * Processes events from the queue sequentially
+     */
+    private async _processEventQueue(): Promise<void> {
+        // Prevent concurrent processing
+        if (this._isProcessingEvent) {
+            return;
+        }
+        
+        this._isProcessingEvent = true;
+        
+        try {
+            while (this._eventQueue.length > 0) {
+                const action = this._eventQueue.shift()!;
+                await this._processEvent(action);
+            }
+        } finally {
+            this._isProcessingEvent = false;
+        }
+    }
+
+    /**
+     * @internal
+     * Processes a single event
+     */
+    private async _processEvent(action: A): Promise<void> {
         // Using 'any[]' for constructor arguments for broader compatibility.
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const eventConstructor = action.constructor as new (...args: any[]) => A;
@@ -81,29 +129,42 @@ export abstract class Bloc<
                 // typed to its specific class (e.g., LoadMyFeatureData).
                 await handler(action, emit);
             } catch (error) {
-                // It's good practice to handle errors occurring within event handlers.
+                // Enhanced error handling with better context
+                const constructorName = (action.constructor as { name?: string }).name || 'UnnamedConstructor';
+                const errorContext = {
+                    blocName: this._name,
+                    blocId: String(this._id),
+                    eventType: constructorName,
+                    currentState: this.state,
+                    action: action,
+                    timestamp: new Date().toISOString()
+                };
+                
                 Blac.error(
-                    `[Bloc ${this._name}:${String(this._id)}] Error in event handler for '${eventConstructor.name}':`,
+                    `[Bloc ${this._name}:${String(this._id)}] Error in event handler for '${constructorName}':`,
                     error,
-                    "Action:", action
+                    "Context:", errorContext
                 );
-                // Depending on the desired error handling strategy, you might:
-                // 1. Emit a specific error state: this.emit(new MyErrorState(error));
-                // 2. Re-throw the error: throw error;
-                // 3. Log and ignore (as done here by default).
-                // This should be decided based on application requirements.
+                
+                // TODO: Consider implementing error boundary pattern
+                // For now, we log and continue, but applications may want to:
+                // 1. Emit an error state
+                // 2. Re-throw the error  
+                // 3. Call an error handler callback
+                
+                // Optional: Re-throw for critical errors (can be configured)
+                if (error instanceof Error && error.name === 'CriticalError') {
+                    throw error;
+                }
             }
         } else {
-            // action.constructor.name should be safe due to 'A extends object' and common JS practice for constructors.
-            // If linting still complains, it might be overly strict for this common pattern.
+            // Enhanced warning with more context
             const constructorName = (action.constructor as { name?: string }).name || 'UnnamedConstructor';
             Blac.warn(
-                `[Bloc ${this._name}:${String(this._id)}] No handler registered for action type: '${constructorName}'. Action was:`,
-                action
+                `[Bloc ${this._name}:${String(this._id)}] No handler registered for action type: '${constructorName}'.`,
+                "Registered handlers:", Array.from(this.eventHandlers.keys()).map(k => k.name),
+                "Action was:", action
             );
-            // If no handler is found, the action is effectively ignored.
-            // Consider if this is the desired behavior or if an error should be thrown
-            // or a default handler should be invoked.
         }
-    };
+    }
 }

package/src/BlocBase.ts

@@ -1,5 +1,5 @@
 import { BlacObservable } from './BlacObserver';
-import { BlocConstructor } from './types';
+import { generateUUID } from './utils/uuid';
 
 export type BlocInstanceId = string | number | undefined;
 type DependencySelector<S> = (newState: S) => unknown[][];
@@ -22,7 +22,7 @@ export abstract class BlocBase<
   S,
   P = unknown
 > {
-  public uid = crypto.randomUUID();
+  public uid = generateUUID();
   /**
    * When true, every consumer will receive its own unique instance of this Bloc.
    * Use this when state should not be shared between components.
@@ -85,6 +85,12 @@ export abstract class BlocBase<
    */
   public readonly _createdAt = Date.now();
 
+  /**
+   * @internal
+   * Disposal state to prevent race conditions
+   */
+  private _disposalState: 'active' | 'disposing' | 'disposed' = 'active';
+
   /**
    * @internal
    * The current state of the Bloc.
@@ -103,6 +109,50 @@ export abstract class BlocBase<
    */
   public props: P | null = null;
 
+  /**
+   * @internal
+   * Flag to prevent batching race conditions
+   */
+  private _batchingLock = false;
+
+  /**
+   * @internal
+   * Pending batched updates
+   */
+  private _pendingUpdates: Array<{newState: S, oldState: S, action?: unknown}> = [];
+
+  /**
+   * @internal
+   * Map of consumer IDs to their WeakRef objects for proper cleanup
+   */
+  private _consumerRefs = new Map<string, WeakRef<object>>();
+
+  /**
+   * @internal
+   * Validates that all consumer references are still alive
+   * Removes dead consumers automatically
+   */
+  _validateConsumers = (): void => {
+    const deadConsumers: string[] = [];
+    
+    for (const [consumerId, weakRef] of this._consumerRefs) {
+      if (weakRef.deref() === undefined) {
+        deadConsumers.push(consumerId);
+      }
+    }
+    
+    // Clean up dead consumers
+    for (const consumerId of deadConsumers) {
+      this._consumers.delete(consumerId);
+      this._consumerRefs.delete(consumerId);
+    }
+    
+    // Schedule disposal if no live consumers remain
+    if (this._consumers.size === 0 && !this._keepAlive && this._disposalState === 'active') {
+      this._scheduleDisposal();
+    }
+  };
+
   /**
    * Creates a new BlocBase instance with the given initial state.
    * Sets up the observer, registers with the Blac manager, and initializes addons.
@@ -157,8 +207,15 @@ export abstract class BlocBase<
    * Notifies the Blac manager and clears all observers.
    */
   _dispose() {
-    // Clear all consumers
+    // Prevent re-entrant disposal using atomic state change
+    if (this._disposalState !== 'active') {
+      return;
+    }
+    this._disposalState = 'disposing';
+    
+    // Clear all consumers and their references
     this._consumers.clear();
+    this._consumerRefs.clear();
     
     // Clear observer subscriptions
     this._observer.clear();
@@ -166,6 +223,9 @@ export abstract class BlocBase<
     // Call user-defined disposal hook
     this.onDispose?.();
     
+    // Mark as fully disposed
+    this._disposalState = 'disposed';
+    
     // The Blac manager will handle removal from registry
     // This method is called by Blac.disposeBloc, so we don't need to call it again
   }
@@ -182,12 +242,6 @@ export abstract class BlocBase<
    */
   _consumers = new Set<string>();
 
-  /**
-   * @internal
-   * WeakSet to track consumer references for cleanup validation
-   */
-  private _consumerRefs = new WeakSet<object>();
-
   /**
    * @internal
    * Registers a new consumer to this Bloc instance.
@@ -197,11 +251,17 @@ export abstract class BlocBase<
    * @param consumerRef Optional reference to the consumer object for cleanup validation
    */
   _addConsumer = (consumerId: string, consumerRef?: object) => {
+    // Prevent adding consumers to disposed blocs
+    if (this._disposalState !== 'active') {
+      return;
+    }
+    
     if (this._consumers.has(consumerId)) return;
     this._consumers.add(consumerId);
     
+    // Store WeakRef for proper memory management
     if (consumerRef) {
-      this._consumerRefs.add(consumerRef);
+      this._consumerRefs.set(consumerId, new WeakRef(consumerRef));
     }
     
     // this._blac.dispatchEvent(BlacLifecycleEvent.BLOC_CONSUMER_ADDED, this, { consumerId });
@@ -216,11 +276,13 @@ export abstract class BlocBase<
    */
   _removeConsumer = (consumerId: string) => {
     if (!this._consumers.has(consumerId)) return;
+    
     this._consumers.delete(consumerId);
+    this._consumerRefs.delete(consumerId);
     // this._blac.dispatchEvent(BlacLifecycleEvent.BLOC_CONSUMER_REMOVED, this, { consumerId });
     
     // If no consumers remain and not keep-alive, schedule disposal
-    if (this._consumers.size === 0 && !this._keepAlive) {
+    if (this._consumers.size === 0 && !this._keepAlive && this._disposalState === 'active') {
       this._scheduleDisposal();
     }
   };
@@ -244,16 +306,19 @@ export abstract class BlocBase<
    * Schedules disposal of this bloc instance if it has no consumers
    */
   private _scheduleDisposal() {
-    // Use setTimeout to avoid disposal during render cycles
-    setTimeout(() => {
-      if (this._consumers.size === 0 && !this._keepAlive) {
-        if (this._disposalHandler) {
-          this._disposalHandler(this as any);
-        } else {
-          this._dispose();
-        }
+    // Prevent multiple disposal attempts
+    if (this._disposalState !== 'active') {
+      return;
+    }
+    
+    // Double-check conditions before disposal
+    if (this._consumers.size === 0 && !this._keepAlive) {
+      if (this._disposalHandler) {
+        this._disposalHandler(this as any);
+      } else {
+        this._dispose();
       }
-    }, 0);
+    }
   }
 
   lastUpdate = Date.now();
@@ -264,12 +329,6 @@ export abstract class BlocBase<
    */
   private _batchingEnabled = false;
 
-  /**
-   * @internal
-   * Pending state updates when batching is enabled
-   */
-  private _pendingUpdates: Array<{newState: S, oldState: S, action?: unknown}> = [];
-
   /**
    * @internal
    * Updates the state and notifies all observers of the change.
@@ -279,28 +338,33 @@ export abstract class BlocBase<
    * @param action Optional metadata about what caused the state change
    */
   _pushState = (newState: S, oldState: S, action?: unknown): void => {
-    // Runtime validation for state changes
+    // Validate newState
     if (newState === undefined) {
       console.warn('BlocBase._pushState: newState is undefined', this);
       return;
     }
-    
+
     // Validate action type if provided
-    if (action !== undefined && action !== null) {
-      const actionType = typeof action;
-      if (!(['string', 'object', 'number'].includes(actionType))) {
-        console.warn('BlocBase._pushState: Invalid action type', this, action);
-      }
+    if (action !== undefined && typeof action !== 'object' && typeof action !== 'function') {
+      console.warn('BlocBase._pushState: Invalid action type', this, action);
+      return;
     }
 
-    // If batching is enabled, queue the update
     if (this._batchingEnabled) {
+      // When batching, just accumulate the updates
       this._pendingUpdates.push({ newState, oldState, action });
+      
+      // Update internal state for consistency
+      this._oldState = oldState;
+      this._state = newState;
       return;
     }
-    
+
+    // Normal state update flow
     this._oldState = oldState;
     this._state = newState;
+    
+    // Notify observers of the state change
     this._observer.notify(newState, oldState, action);
     this.lastUpdate = Date.now();
   };
@@ -310,28 +374,32 @@ export abstract class BlocBase<
    * @param batchFn Function to execute with batching enabled
    */
   batch = <T>(batchFn: () => T): T => {
-    const wasBatching = this._batchingEnabled;
-    this._batchingEnabled = true;
+    // Prevent batching race conditions
+    if (this._batchingLock) {
+      // If already batching, just execute the function without nesting batches
+      return batchFn();
+    }
     
+    this._batchingLock = true;
+    this._batchingEnabled = true;
+    this._pendingUpdates = [];
+
     try {
       const result = batchFn();
       
-      // Process all pending updates
+      // Process all batched updates
       if (this._pendingUpdates.length > 0) {
-        const lastUpdate = this._pendingUpdates[this._pendingUpdates.length - 1];
-        this._oldState = this._pendingUpdates[0].oldState;
-        this._state = lastUpdate.newState;
-        
-        // Notify with the final state
-        this._observer.notify(lastUpdate.newState, this._oldState, lastUpdate.action);
+        // Only notify once with the final state
+        const finalUpdate = this._pendingUpdates[this._pendingUpdates.length - 1];
+        this._observer.notify(finalUpdate.newState, finalUpdate.oldState, finalUpdate.action);
         this.lastUpdate = Date.now();
-        
-        this._pendingUpdates = [];
       }
       
       return result;
     } finally {
-      this._batchingEnabled = wasBatching;
+      this._batchingEnabled = false;
+      this._batchingLock = false;
+      this._pendingUpdates = [];
     }
   };
 }

package/src/index.ts

@@ -1,7 +1,14 @@
 export * from './Blac';
+export * from './BlacEvent';
 export * from './BlacObserver';
 export * from './Bloc';
 export * from './BlocBase';
 export * from './Cubit';
 export * from './types';
 
+// Utilities
+export * from './utils/uuid';
+
+// Test utilities
+export * from './testing';
+

package/src/testing.ts

@@ -0,0 +1,239 @@
+import { Blac } from './Blac';
+import { Bloc } from './Bloc';
+import { BlocBase } from './BlocBase';
+import { Cubit } from './Cubit';
+import { BlocEventConstraint } from './types';
+
+/**
+ * Test utilities for Blac state management
+ */
+export class BlocTest {
+  private static originalInstance: Blac;
+  
+  /**
+   * Sets up a clean test environment
+   */
+  static setUp(): void {
+    this.originalInstance = Blac.instance;
+    Blac.resetInstance();
+    Blac.enableLog = false; // Disable logging in tests by default
+  }
+  
+  /**
+   * Tears down the test environment and restores original state
+   */
+  static tearDown(): void {
+    Blac.resetInstance();
+    // Note: Cannot restore original instance due to singleton pattern
+    // Tests should use setUp/tearDown properly to manage state
+  }
+  
+  /**
+   * Creates a test bloc with automatic cleanup
+   */
+  static createBloc<T extends BlocBase<any>>(
+    BlocClass: new (...args: any[]) => T,
+    ...args: any[]
+  ): T {
+    const bloc = new BlocClass(...args);
+    Blac.activateBloc(bloc);
+    return bloc;
+  }
+  
+  /**
+   * Waits for a bloc to emit a specific state
+   */
+  static async waitForState<T extends BlocBase<S>, S>(
+    bloc: T,
+    predicate: (state: S) => boolean,
+    timeout = 5000
+  ): Promise<S> {
+    return new Promise<S>((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        reject(new Error(`Timeout waiting for state matching predicate after ${timeout}ms`));
+      }, timeout);
+      
+      const unsubscribe = bloc._observer.subscribe({
+        id: `test-waiter-${crypto.randomUUID()}`,
+        fn: (newState: S) => {
+          if (predicate(newState)) {
+            clearTimeout(timeoutId);
+            unsubscribe();
+            resolve(newState);
+          }
+        }
+      });
+      
+      // Check current state immediately
+      if (predicate(bloc.state)) {
+        clearTimeout(timeoutId);
+        unsubscribe();
+        resolve(bloc.state);
+      }
+    });
+  }
+  
+  /**
+   * Expects a bloc to emit specific states in order
+   */
+  static async expectStates<T extends BlocBase<S>, S>(
+    bloc: T,
+    expectedStates: S[],
+    timeout = 5000
+  ): Promise<void> {
+    const receivedStates: S[] = [];
+    
+    return new Promise<void>((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        reject(new Error(
+          `Timeout waiting for states. Expected: ${JSON.stringify(expectedStates)}, ` +
+          `Received: ${JSON.stringify(receivedStates)}`
+        ));
+      }, timeout);
+      
+      const unsubscribe = bloc._observer.subscribe({
+        id: `test-expecter-${crypto.randomUUID()}`,
+        fn: (newState: S) => {
+          receivedStates.push(newState);
+          
+          // Check if we have all expected states
+          if (receivedStates.length === expectedStates.length) {
+            clearTimeout(timeoutId);
+            unsubscribe();
+            
+            // Verify all states match using deep equality
+            for (let i = 0; i < expectedStates.length; i++) {
+              const expected = expectedStates[i];
+              const received = receivedStates[i];
+              
+              // Use JSON comparison for deep equality
+              if (JSON.stringify(expected) !== JSON.stringify(received)) {
+                reject(new Error(
+                  `State mismatch at index ${i}. Expected: ${JSON.stringify(expected)}, ` +
+                  `Received: ${JSON.stringify(received)}`
+                ));
+                return;
+              }
+            }
+            
+            resolve();
+          }
+        }
+      });
+    });
+  }
+}
+
+/**
+ * Mock Bloc for testing
+ */
+export class MockBloc<S, A extends BlocEventConstraint = BlocEventConstraint> extends Bloc<S, A> {
+  private mockHandlers = new Map<string, (event: A, emit: (newState: S) => void) => void | Promise<void>>();
+  
+  constructor(initialState: S) {
+    super(initialState);
+  }
+  
+  /**
+   * Mock an event handler for testing
+   */
+  mockEventHandler<E extends A>(
+    eventConstructor: new (...args: any[]) => E,
+    handler: (event: E, emit: (newState: S) => void) => void | Promise<void>
+  ): void {
+    // Use the on method to register the mock handler
+    this.on(eventConstructor, handler);
+  }
+  
+  /**
+   * Get the number of registered handlers
+   */
+  getHandlerCount(): number {
+    return this.eventHandlers.size;
+  }
+  
+  /**
+   * Check if a handler is registered for an event type
+   */
+  hasHandler(eventConstructor: new (...args: any[]) => A): boolean {
+    return this.eventHandlers.has(eventConstructor);
+  }
+}
+
+/**
+ * Mock Cubit for testing
+ */
+export class MockCubit<S> extends Cubit<S> {
+  private stateHistory: S[] = [];
+  
+  constructor(initialState: S) {
+    super(initialState);
+    this.stateHistory.push(initialState);
+  }
+  
+  /**
+   * Override emit to track state history
+   */
+  emit(newState: S): void {
+    this.stateHistory.push(newState);
+    super.emit(newState);
+  }
+  
+  /**
+   * Get the history of all states
+   */
+  getStateHistory(): S[] {
+    return [...this.stateHistory];
+  }
+  
+  /**
+   * Clear state history
+   */
+  clearStateHistory(): void {
+    this.stateHistory = [this.state];
+  }
+}
+
+/**
+ * Memory leak detector for tests
+ */
+export class MemoryLeakDetector {
+  private initialStats: ReturnType<typeof Blac.getMemoryStats>;
+  
+  constructor() {
+    this.initialStats = Blac.getMemoryStats();
+  }
+  
+  /**
+   * Check for memory leaks and return a report
+   */
+  checkForLeaks(): {
+    hasLeaks: boolean;
+    report: string;
+    stats: ReturnType<typeof Blac.getMemoryStats>;
+  } {
+    const currentStats = Blac.getMemoryStats();
+    const hasLeaks = (
+      currentStats.registeredBlocs > this.initialStats.registeredBlocs ||
+      currentStats.isolatedBlocs > this.initialStats.isolatedBlocs ||
+      currentStats.keepAliveBlocs > this.initialStats.keepAliveBlocs
+    );
+    
+    const report = `
+Memory Leak Detection Report:
+- Initial registered blocs: ${this.initialStats.registeredBlocs}
+- Current registered blocs: ${currentStats.registeredBlocs}
+- Initial isolated blocs: ${this.initialStats.isolatedBlocs}  
+- Current isolated blocs: ${currentStats.isolatedBlocs}
+- Initial keep-alive blocs: ${this.initialStats.keepAliveBlocs}
+- Current keep-alive blocs: ${currentStats.keepAliveBlocs}
+- Potential leaks detected: ${hasLeaks ? 'YES' : 'NO'}
+    `.trim();
+    
+    return {
+      hasLeaks,
+      report,
+      stats: currentStats
+    };
+  }
+}