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

package/src/plugins/__tests__/SystemPluginRegistry.test.ts

@@ -0,0 +1,404 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SystemPluginRegistry } from '../SystemPluginRegistry';
+import { BlacPlugin } from '../types';
+import { BlocBase } from '../../BlocBase';
+import { Bloc } from '../../Bloc';
+
+// Mock bloc for testing
+class MockBloc extends BlocBase<number> {
+  constructor(initialState = 0) {
+    super(initialState);
+  }
+}
+
+// Mock event bloc
+class MockEventBloc extends Bloc<number, { type: string }> {
+  constructor() {
+    super(0);
+  }
+}
+
+// Helper to create test plugins
+const createTestPlugin = (
+  name: string,
+  hooks?: Partial<BlacPlugin>,
+): BlacPlugin => ({
+  name,
+  version: '1.0.0',
+  ...hooks,
+});
+
+describe('SystemPluginRegistry', () => {
+  let registry: SystemPluginRegistry;
+
+  beforeEach(() => {
+    registry = new SystemPluginRegistry();
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  describe('Plugin Management', () => {
+    it('should add plugins successfully', () => {
+      const plugin = createTestPlugin('test-plugin');
+
+      registry.add(plugin);
+
+      expect(registry.get('test-plugin')).toBe(plugin);
+      expect(registry.getAll()).toContain(plugin);
+    });
+
+    it('should throw error when adding duplicate plugin', () => {
+      const plugin = createTestPlugin('test-plugin');
+
+      registry.add(plugin);
+
+      expect(() => registry.add(plugin)).toThrow(
+        "Plugin 'test-plugin' is already registered",
+      );
+    });
+
+    it('should maintain execution order', () => {
+      const plugin1 = createTestPlugin('plugin-1');
+      const plugin2 = createTestPlugin('plugin-2');
+      const plugin3 = createTestPlugin('plugin-3');
+
+      registry.add(plugin1);
+      registry.add(plugin2);
+      registry.add(plugin3);
+
+      const all = registry.getAll();
+      expect(all[0]).toBe(plugin1);
+      expect(all[1]).toBe(plugin2);
+      expect(all[2]).toBe(plugin3);
+    });
+
+    it('should remove plugins and clean up metrics', () => {
+      const plugin = createTestPlugin('test-plugin');
+
+      registry.add(plugin);
+      expect(registry.get('test-plugin')).toBe(plugin);
+      expect(registry.getMetrics('test-plugin')).toBeDefined();
+
+      const removed = registry.remove('test-plugin');
+      expect(removed).toBe(true);
+      expect(registry.get('test-plugin')).toBeUndefined();
+      expect(registry.getAll()).not.toContain(plugin);
+      expect(registry.getMetrics('test-plugin')).toBeUndefined();
+    });
+
+    it('should return false when removing non-existent plugin', () => {
+      const removed = registry.remove('non-existent');
+      expect(removed).toBe(false);
+    });
+
+    it('should clear all plugins and metrics', () => {
+      registry.add(createTestPlugin('plugin-1'));
+      registry.add(createTestPlugin('plugin-2'));
+      registry.add(createTestPlugin('plugin-3'));
+
+      expect(registry.getAll().length).toBe(3);
+
+      registry.clear();
+
+      expect(registry.getAll().length).toBe(0);
+      expect(registry.getMetrics('plugin-1')).toBeUndefined();
+    });
+  });
+
+  describe('Hook Execution', () => {
+    it('should execute hooks on all plugins', () => {
+      const hook1 = vi.fn();
+      const hook2 = vi.fn();
+      const hook3 = vi.fn();
+
+      registry.add(createTestPlugin('plugin-1', { onBlocCreated: hook1 }));
+      registry.add(createTestPlugin('plugin-2', { onBlocCreated: hook2 }));
+      registry.add(createTestPlugin('plugin-3', { onBlocCreated: hook3 }));
+
+      const bloc = new MockBloc();
+      registry.executeHook('onBlocCreated', [bloc]);
+
+      expect(hook1).toHaveBeenCalledWith(bloc);
+      expect(hook2).toHaveBeenCalledWith(bloc);
+      expect(hook3).toHaveBeenCalledWith(bloc);
+    });
+
+    it('should skip plugins without the specified hook', () => {
+      const hook1 = vi.fn();
+      const hook3 = vi.fn();
+
+      registry.add(createTestPlugin('plugin-1', { onBlocCreated: hook1 }));
+      registry.add(createTestPlugin('plugin-2')); // No hook
+      registry.add(createTestPlugin('plugin-3', { onBlocCreated: hook3 }));
+
+      const bloc = new MockBloc();
+      registry.executeHook('onBlocCreated', [bloc]);
+
+      expect(hook1).toHaveBeenCalledWith(bloc);
+      expect(hook3).toHaveBeenCalledWith(bloc);
+    });
+
+    it('should handle hook errors and continue execution', () => {
+      const hook1 = vi.fn(() => {
+        throw new Error('Hook 1 error');
+      });
+      const hook2 = vi.fn();
+      const hook3 = vi.fn();
+
+      registry.add(createTestPlugin('plugin-1', { onBlocCreated: hook1 }));
+      registry.add(createTestPlugin('plugin-2', { onBlocCreated: hook2 }));
+      registry.add(createTestPlugin('plugin-3', { onBlocCreated: hook3 }));
+
+      const bloc = new MockBloc();
+      registry.executeHook('onBlocCreated', [bloc]);
+
+      expect(hook1).toHaveBeenCalled();
+      expect(hook2).toHaveBeenCalled();
+      expect(hook3).toHaveBeenCalled();
+      expect(console.error).toHaveBeenCalledWith(
+        expect.stringContaining(
+          "Plugin 'plugin-1' error in hook 'onBlocCreated'",
+        ),
+        expect.any(Error),
+      );
+    });
+
+    it('should use custom error handler if provided', () => {
+      const errorHandler = vi.fn();
+      const failingHook = vi.fn(() => {
+        throw new Error('Test error');
+      });
+
+      const plugin = createTestPlugin('failing-plugin', {
+        onBlocCreated: failingHook,
+      });
+      registry.add(plugin);
+
+      const bloc = new MockBloc();
+      registry.executeHook('onBlocCreated', [bloc], errorHandler);
+
+      expect(errorHandler).toHaveBeenCalledWith(expect.any(Error), plugin);
+      expect(console.error).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Lifecycle Hooks', () => {
+    it('should execute bootstrap hooks', () => {
+      const beforeBootstrap1 = vi.fn();
+      const beforeBootstrap2 = vi.fn();
+      const afterBootstrap1 = vi.fn();
+      const afterBootstrap2 = vi.fn();
+
+      registry.add(
+        createTestPlugin('plugin-1', {
+          beforeBootstrap: beforeBootstrap1,
+          afterBootstrap: afterBootstrap1,
+        }),
+      );
+      registry.add(
+        createTestPlugin('plugin-2', {
+          beforeBootstrap: beforeBootstrap2,
+          afterBootstrap: afterBootstrap2,
+        }),
+      );
+
+      registry.bootstrap();
+
+      expect(beforeBootstrap1).toHaveBeenCalled();
+      expect(beforeBootstrap2).toHaveBeenCalled();
+      expect(afterBootstrap1).toHaveBeenCalled();
+      expect(afterBootstrap2).toHaveBeenCalled();
+    });
+
+    it('should execute shutdown hooks', () => {
+      const beforeShutdown = vi.fn();
+      const afterShutdown = vi.fn();
+
+      registry.add(
+        createTestPlugin('plugin-1', {
+          beforeShutdown,
+          afterShutdown,
+        }),
+      );
+
+      registry.shutdown();
+
+      expect(beforeShutdown).toHaveBeenCalled();
+      expect(afterShutdown).toHaveBeenCalled();
+    });
+  });
+
+  describe('Bloc Lifecycle Notifications', () => {
+    it('should notify plugins of bloc creation', () => {
+      const onBlocCreated = vi.fn();
+
+      registry.add(createTestPlugin('plugin-1', { onBlocCreated }));
+
+      const bloc = new MockBloc();
+      registry.notifyBlocCreated(bloc);
+
+      expect(onBlocCreated).toHaveBeenCalledWith(bloc);
+    });
+
+    it('should notify plugins of bloc disposal', () => {
+      const onBlocDisposed = vi.fn();
+
+      registry.add(createTestPlugin('plugin-1', { onBlocDisposed }));
+
+      const bloc = new MockBloc();
+      registry.notifyBlocDisposed(bloc);
+
+      expect(onBlocDisposed).toHaveBeenCalledWith(bloc);
+    });
+
+    it('should notify plugins of state changes', () => {
+      const onStateChanged = vi.fn();
+
+      registry.add(createTestPlugin('plugin-1', { onStateChanged }));
+
+      const bloc = new MockBloc();
+      const prevState = 0;
+      const currState = 1;
+
+      registry.notifyStateChanged(bloc, prevState, currState);
+
+      expect(onStateChanged).toHaveBeenCalledWith(bloc, prevState, currState);
+    });
+
+    it('should notify plugins of event additions', () => {
+      const onEventAdded = vi.fn();
+
+      registry.add(createTestPlugin('plugin-1', { onEventAdded }));
+
+      const bloc = new MockEventBloc();
+      const event = 'test-event';
+
+      registry.notifyEventAdded(bloc, event);
+
+      expect(onEventAdded).toHaveBeenCalledWith(bloc, event);
+    });
+
+    it('should notify plugins of errors with double fault protection', () => {
+      const onError1 = vi.fn();
+      const onError2 = vi.fn(() => {
+        throw new Error('Error handler failed');
+      });
+
+      registry.add(createTestPlugin('plugin-1', { onError: onError1 }));
+      registry.add(createTestPlugin('plugin-2', { onError: onError2 }));
+
+      const error = new Error('Test error');
+      const bloc = new MockBloc();
+      const context = {
+        phase: 'state-change' as const,
+        operation: 'test-operation',
+      };
+
+      registry.notifyError(error, bloc as any, context);
+
+      expect(onError1).toHaveBeenCalledWith(error, bloc, context);
+      expect(onError2).toHaveBeenCalledWith(error, bloc, context);
+      expect(console.error).toHaveBeenCalledWith(
+        expect.stringContaining("Plugin 'plugin-2' error handler failed:"),
+        expect.any(Error),
+      );
+    });
+  });
+
+  describe('Metrics Tracking', () => {
+    it('should initialize metrics for new plugins', () => {
+      registry.add(createTestPlugin('test-plugin'));
+
+      const metrics = registry.getMetrics('test-plugin');
+      expect(metrics).toBeDefined();
+      expect(metrics).toBeInstanceOf(Map);
+    });
+
+    it('should record successful hook executions', () => {
+      const hook = vi.fn();
+      registry.add(createTestPlugin('test-plugin', { onBlocCreated: hook }));
+
+      const bloc = new MockBloc();
+      registry.notifyBlocCreated(bloc);
+
+      const metrics = registry.getMetrics('test-plugin');
+      const hookMetrics = metrics?.get('onBlocCreated');
+
+      expect(hookMetrics).toBeDefined();
+      expect(hookMetrics?.executionCount).toBe(1);
+      expect(hookMetrics?.errorCount).toBe(0);
+      expect(hookMetrics?.executionTime).toBeGreaterThan(0);
+      expect(hookMetrics?.lastExecutionTime).toBeGreaterThan(0);
+    });
+
+    it('should record hook errors', () => {
+      const error = new Error('Hook error');
+      const hook = vi.fn(() => {
+        throw error;
+      });
+
+      registry.add(createTestPlugin('test-plugin', { onBlocCreated: hook }));
+
+      const bloc = new MockBloc();
+      registry.notifyBlocCreated(bloc);
+
+      const metrics = registry.getMetrics('test-plugin');
+      const hookMetrics = metrics?.get('onBlocCreated');
+
+      expect(hookMetrics).toBeDefined();
+      expect(hookMetrics?.errorCount).toBe(1);
+      expect(hookMetrics?.lastError).toBe(error);
+    });
+
+    it('should accumulate metrics over multiple executions', () => {
+      const hook = vi.fn();
+      registry.add(createTestPlugin('test-plugin', { onBlocCreated: hook }));
+
+      const bloc = new MockBloc();
+
+      // Execute multiple times
+      for (let i = 0; i < 5; i++) {
+        registry.notifyBlocCreated(bloc);
+      }
+
+      const metrics = registry.getMetrics('test-plugin');
+      const hookMetrics = metrics?.get('onBlocCreated');
+
+      expect(hookMetrics?.executionCount).toBe(5);
+      expect(hookMetrics?.executionTime).toBeGreaterThan(0);
+    });
+
+    it('should return undefined metrics for non-existent plugin', () => {
+      const metrics = registry.getMetrics('non-existent');
+      expect(metrics).toBeUndefined();
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle plugins with context binding correctly', () => {
+      let capturedThis: any;
+      const plugin = createTestPlugin('test-plugin', {
+        onBlocCreated: function (this: any) {
+          capturedThis = this;
+        },
+      });
+
+      registry.add(plugin);
+      registry.notifyBlocCreated(new MockBloc());
+
+      expect(capturedThis).toBe(plugin);
+    });
+
+    it('should handle multiple rapid hook executions', () => {
+      const hook = vi.fn();
+      registry.add(createTestPlugin('test-plugin', { onBlocCreated: hook }));
+
+      const bloc = new MockBloc();
+
+      for (let i = 0; i < 100; i++) {
+        registry.notifyBlocCreated(bloc);
+      }
+
+      expect(hook).toHaveBeenCalledTimes(100);
+    });
+  });
+});

package/src/plugins/types.ts

@@ -5,7 +5,11 @@ import { Bloc } from '../Bloc';
  * Error context provided to error handlers
  */
 export interface ErrorContext {
-  readonly phase: 'initialization' | 'state-change' | 'event-processing' | 'disposal';
+  readonly phase:
+    | 'initialization'
+    | 'state-change'
+    | 'event-processing'
+    | 'disposal';
   readonly operation: string;
   readonly metadata?: Record<string, unknown>;
 }
@@ -30,6 +34,20 @@ export interface Plugin {
   readonly capabilities?: PluginCapabilities;
 }
 
+/**
+ * Adapter metadata provided to plugins
+ */
+export interface AdapterMetadata {
+  componentName?: string;
+  blocInstance: BlocBase<any>;
+  renderCount: number;
+  trackedPaths?: string[];
+  isUsingDependencies?: boolean;
+  lastState?: any;
+  lastDependencyValues?: any[];
+  currentDependencyValues?: any[];
+}
+
 /**
  * System-wide plugin that observes all blocs
  */
@@ -43,9 +61,20 @@ export interface BlacPlugin extends Plugin {
   // System-wide observations
   onBlocCreated?(bloc: BlocBase<any>): void;
   onBlocDisposed?(bloc: BlocBase<any>): void;
-  onStateChanged?(bloc: BlocBase<any>, previousState: any, currentState: 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;
+
+  // Adapter lifecycle hooks
+  onAdapterCreated?(adapter: any, metadata: AdapterMetadata): void;
+  onAdapterMount?(adapter: any, metadata: AdapterMetadata): void;
+  onAdapterUnmount?(adapter: any, metadata: AdapterMetadata): void;
+  onAdapterRender?(adapter: any, metadata: AdapterMetadata): void;
+  onAdapterDisposed?(adapter: any, metadata: AdapterMetadata): void;
 }
 
 /**
@@ -57,7 +86,7 @@ export interface BlocPlugin<TState = any, TEvent = never> extends Plugin {
   transformEvent?(event: TEvent): TEvent | null;
 
   // Lifecycle hooks
-  onAttach?(bloc: BlocBase<TState, any>): void;
+  onAttach?(bloc: BlocBase<TState>): void;
   onDetach?(): void;
 
   // Observation hooks

package/src/subscription/README.md

@@ -0,0 +1,132 @@
+# Unified Subscription Model
+
+## Overview
+
+The unified subscription model replaces the dual consumer/observer system in BlaC with a single, consistent subscription mechanism. This reduces complexity, improves performance, and provides a cleaner API for state management.
+
+## Architecture
+
+### Core Components
+
+1. **Subscription Interface** (`types.ts`)
+   - Single interface for all subscription types
+   - Supports selectors, custom equality functions, and priorities
+   - Tracks dependencies and metadata
+
+2. **SubscriptionManager** (`SubscriptionManager.ts`)
+   - Manages all subscriptions with a single Map
+   - Handles notification dispatch with priority ordering
+   - Automatic weak reference cleanup
+   - Path-based dependency tracking
+
+3. **Backward Compatibility Adapters**
+   - `ConsumerTrackerAdapter`: Maintains ConsumerTracker API
+   - `BlacObservableAdapter`: Maintains BlacObservable API
+   - Zero breaking changes for existing code
+
+## Benefits
+
+### 1. Simplified Mental Model
+
+- Single subscription concept instead of two overlapping systems
+- Consistent API across React and non-React usage
+- Easier to understand and debug
+
+### 2. Better Performance
+
+- Single notification pass instead of dual system
+- Reduced memory overhead
+- O(1) subscription lookups
+- Automatic dead reference cleanup
+
+### 3. Enhanced Features
+
+- Priority-based notification ordering
+- Unified dependency tracking
+- Consistent selector/equality function support
+- Better TypeScript support
+
+### 4. Reduced Complexity
+
+- ~50% less code to maintain
+- Single source of truth for subscriptions
+- Eliminated circular dependencies
+- Cleaner separation of concerns
+
+## Migration Path
+
+### Phase 1: Infrastructure (COMPLETE)
+
+✅ Implement core subscription types and manager
+✅ Create backward compatibility adapters
+✅ Comprehensive test coverage
+
+### Phase 2: Integration (IN PROGRESS)
+
+⏳ Update BlocBase to use SubscriptionManager
+⏳ Maintain existing APIs through adapters
+⏳ Ensure all tests pass
+
+### Phase 3: React Adapter
+
+- Update useBloc to create unified subscriptions
+- Optimize re-render logic with unified system
+- Maintain backward compatibility
+
+### Phase 4: Deprecation
+
+- Mark old APIs as deprecated
+- Provide migration guide
+- Remove in next major version
+
+## Usage Examples
+
+### React-style Subscription
+
+```typescript
+// Subscribe to specific state slice
+const unsubscribe = bloc.subscribeWithSelector(
+  (state) => state.count,
+  (newCount) => console.log('Count changed:', newCount),
+);
+```
+
+### Observer-style Subscription
+
+```typescript
+// Subscribe with dependency array
+const unsubscribe = bloc.observe(
+  (newState, oldState) => console.log('State changed'),
+  (state) => [state.user.id, state.settings.theme], // Only notify when these change
+);
+```
+
+### Direct Subscription Manager Usage
+
+```typescript
+const subscription = subscriptionManager.subscribe({
+  type: 'consumer',
+  selector: (state) => state.items.length,
+  equalityFn: (a, b) => a === b,
+  notify: (length) => updateItemCount(length),
+  priority: 10, // Higher priority = earlier notification
+});
+```
+
+## Performance Considerations
+
+1. **Selector Optimization**: Use memoized selectors for expensive computations
+2. **Equality Functions**: Provide custom equality for complex objects
+3. **Priority Usage**: Use priorities sparingly, only when order matters
+4. **Weak References**: Automatic cleanup reduces memory leaks
+
+## Future Enhancements
+
+1. **Batched Notifications**: Group updates for better performance
+2. **Async Selectors**: Support for async data derivation
+3. **DevTools Integration**: Enhanced debugging capabilities
+4. **Subscription Composition**: Combine multiple subscriptions
+
+## Conclusion
+
+The unified subscription model simplifies BlaC's architecture while maintaining full backward compatibility. It provides a solid foundation for future enhancements and makes the library easier to use and maintain.