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

package/src/__tests__/plugins.test.ts

@@ -0,0 +1,454 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Blac } from '../Blac';
+import { Cubit } from '../Cubit';
+import { Bloc } from '../Bloc';
+import { BlacPlugin, BlocPlugin, PluginCapabilities, ErrorContext } from '../plugins';
+import { BlocBase } from '../BlocBase';
+
+// Test Cubit
+class CounterCubit extends Cubit<number> {
+  constructor() {
+    super(0);
+  }
+  
+  increment = () => this.emit(this.state + 1);
+  decrement = () => this.emit(this.state - 1);
+  setValue = (value: number) => this.emit(value);
+}
+
+// Test Bloc
+abstract class CounterEvent {}
+class Increment extends CounterEvent {}
+class Decrement extends CounterEvent {}
+class SetValue extends CounterEvent {
+  constructor(public value: number) {
+    super();
+  }
+}
+
+class CounterBloc extends Bloc<number, CounterEvent> {
+  constructor() {
+    super(0);
+    
+    this.on(Increment, (event, emit) => emit(this.state + 1));
+    this.on(Decrement, (event, emit) => emit(this.state - 1));
+    this.on(SetValue, (event, emit) => emit(event.value));
+  }
+}
+
+// Test implementations of plugins
+class TestLoggingPlugin implements BlacPlugin {
+  readonly name = 'logging';
+  readonly version = '1.0.0';
+  private logLevel: 'debug' | 'info' | 'warn' | 'error';
+  
+  constructor(options: { logLevel?: 'debug' | 'info' | 'warn' | 'error' } = {}) {
+    this.logLevel = options.logLevel || 'info';
+  }
+  
+  onBlocCreated(bloc: BlocBase<any>): void {
+    this.log('debug', `Bloc created: ${bloc._name}:${bloc._id}`);
+  }
+  
+  onStateChanged(bloc: BlocBase<any>, previousState: any, currentState: any): void {
+    this.log('debug', `State changed in ${bloc._name}:${bloc._id}`, {
+      previousState,
+      currentState
+    });
+  }
+  
+  private log(level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: any): void {
+    const levels = ['debug', 'info', 'warn', 'error'];
+    const currentLevelIndex = levels.indexOf(this.logLevel);
+    const messageLevelIndex = levels.indexOf(level);
+    
+    if (messageLevelIndex >= currentLevelIndex) {
+      const timestamp = new Date().toISOString();
+      const logMessage = `[BlaC] [${timestamp}] ${message}`;
+      
+      switch (level) {
+        case 'debug':
+          console.debug(logMessage, data);
+          break;
+        case 'info':
+          console.log(logMessage, data);
+          break;
+        case 'warn':
+          console.warn(logMessage, data);
+          break;
+        case 'error':
+          console.error(logMessage, data);
+          break;
+      }
+    }
+  }
+}
+
+interface StorageAdapter {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+class TestPersistencePlugin<TState> implements BlocPlugin<TState> {
+  readonly name = 'persistence';
+  readonly version = '1.0.0';
+  readonly capabilities: PluginCapabilities = {
+    readState: true,
+    transformState: true,
+    interceptEvents: false,
+    persistData: true,
+    accessMetadata: false
+  };
+  
+  private storage: StorageAdapter;
+  private key: string;
+  private saveDebounceMs: number;
+  private saveTimer?: any;
+  
+  constructor(options: {
+    key: string;
+    storage?: StorageAdapter;
+    saveDebounceMs?: number;
+  }) {
+    this.key = options.key;
+    this.storage = options.storage || new MockStorage();
+    this.saveDebounceMs = options.saveDebounceMs ?? 100;
+  }
+  
+  onAttach(bloc: BlocBase<TState, any>): void {
+    const savedData = this.storage.getItem(this.key);
+    if (savedData) {
+      const restoredState = JSON.parse(savedData);
+      (bloc as any)._state = restoredState;
+    }
+  }
+  
+  onStateChange(previousState: TState, currentState: TState): void {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+    }
+    
+    if (this.saveDebounceMs > 0) {
+      this.saveTimer = setTimeout(() => {
+        this.storage.setItem(this.key, JSON.stringify(currentState));
+      }, this.saveDebounceMs);
+    } else {
+      this.storage.setItem(this.key, JSON.stringify(currentState));
+    }
+  }
+}
+
+class TestValidationPlugin<T> implements BlocPlugin<T> {
+  readonly name = 'validation';
+  readonly version = '1.0.0';
+  readonly capabilities: PluginCapabilities = {
+    readState: true,
+    transformState: true,
+    interceptEvents: false,
+    persistData: false,
+    accessMetadata: false
+  };
+  
+  constructor(private validator: (state: T) => boolean | string) {}
+  
+  transformState(previousState: T, nextState: T): T {
+    const result = this.validator(nextState);
+    
+    if (result === true) {
+      return nextState;
+    } else if (result === false) {
+      console.warn('State change rejected by validation plugin');
+      return previousState;
+    } else {
+      console.error(`State validation failed: ${result}`);
+      return previousState;
+    }
+  }
+}
+
+// Mock storage
+class MockStorage implements StorageAdapter {
+  private store = new Map<string, string>();
+  
+  getItem(key: string): string | null {
+    return this.store.get(key) || null;
+  }
+  
+  setItem(key: string, value: string): void {
+    this.store.set(key, value);
+  }
+  
+  removeItem(key: string): void {
+    this.store.delete(key);
+  }
+}
+
+describe('New Plugin System', () => {
+  beforeEach(() => {
+    Blac.resetInstance();
+  });
+  
+  describe('System Plugins (BlacPlugin)', () => {
+    it('should register and execute system plugins', () => {
+      const onBlocCreated = vi.fn();
+      const onStateChanged = vi.fn();
+      
+      const plugin: BlacPlugin = {
+        name: 'test-system-plugin',
+        version: '1.0.0',
+        onBlocCreated,
+        onStateChanged
+      };
+      
+      Blac.instance.plugins.add(plugin);
+      
+      const cubit = Blac.getBloc(CounterCubit);
+      expect(onBlocCreated).toHaveBeenCalledWith(cubit);
+      
+      cubit.increment();
+      expect(onStateChanged).toHaveBeenCalledWith(cubit, 0, 1);
+    });
+    
+    it('should handle plugin errors gracefully', () => {
+      const errorPlugin: BlacPlugin = {
+        name: 'error-plugin',
+        version: '1.0.0',
+        onBlocCreated: () => {
+          throw new Error('Plugin error');
+        }
+      };
+      
+      Blac.instance.plugins.add(errorPlugin);
+      
+      // Should not throw when creating bloc
+      expect(() => Blac.getBloc(CounterCubit)).not.toThrow();
+    });
+    
+    it('should execute bootstrap hooks', () => {
+      const beforeBootstrap = vi.fn();
+      const afterBootstrap = vi.fn();
+      
+      const plugin: BlacPlugin = {
+        name: 'bootstrap-plugin',
+        version: '1.0.0',
+        beforeBootstrap,
+        afterBootstrap
+      };
+      
+      Blac.resetInstance();
+      Blac.instance.plugins.add(plugin);
+      Blac.instance.bootstrap();
+      
+      expect(beforeBootstrap).toHaveBeenCalled();
+      expect(afterBootstrap).toHaveBeenCalled();
+    });
+    
+    it('should track metrics', () => {
+      const plugin: BlacPlugin = {
+        name: 'metrics-plugin',
+        version: '1.0.0',
+        onBlocCreated: () => {
+          // Do something
+        }
+      };
+      
+      Blac.instance.plugins.add(plugin);
+      Blac.getBloc(CounterCubit);
+      
+      const metrics = Blac.instance.plugins.getMetrics('metrics-plugin');
+      expect(metrics).toBeDefined();
+      expect(metrics?.get('onBlocCreated')).toBeDefined();
+      expect(metrics?.get('onBlocCreated')?.executionCount).toBe(1);
+    });
+  });
+  
+  describe('Bloc Plugins (BlocPlugin)', () => {
+    it('should attach plugins to specific blocs', () => {
+      const onAttach = vi.fn();
+      const onStateChange = vi.fn();
+      
+      const plugin: BlocPlugin<number> = {
+        name: 'test-bloc-plugin',
+        version: '1.0.0',
+        onAttach,
+        onStateChange
+      };
+      
+      const cubit = new CounterCubit();
+      cubit.addPlugin(plugin);
+      
+      // Activate the bloc
+      Blac.activateBloc(cubit as any);
+      
+      expect(onAttach).toHaveBeenCalledWith(cubit);
+      
+      cubit.increment();
+      expect(onStateChange).toHaveBeenCalledWith(0, 1);
+    });
+    
+    it('should transform state through plugins', () => {
+      const transformPlugin: BlocPlugin<number> = {
+        name: 'double-plugin',
+        version: '1.0.0',
+        transformState: (prev, next) => next * 2
+      };
+      
+      const cubit = new CounterCubit();
+      cubit.addPlugin(transformPlugin);
+      Blac.activateBloc(cubit as any);
+      
+      cubit.setValue(5);
+      expect(cubit.state).toBe(10); // 5 * 2
+    });
+    
+    it('should transform events through plugins', () => {
+      const transformPlugin: BlocPlugin<number, CounterEvent> = {
+        name: 'event-doubler',
+        version: '1.0.0',
+        transformEvent: (event) => {
+          if (event instanceof SetValue) {
+            return new SetValue(event.value * 2);
+          }
+          return event;
+        }
+      };
+      
+      const bloc = new CounterBloc();
+      bloc.addPlugin(transformPlugin);
+      Blac.activateBloc(bloc as any);
+      
+      bloc.add(new SetValue(5));
+      
+      // Wait for event processing
+      setTimeout(() => {
+        expect(bloc.state).toBe(10); // 5 * 2
+      }, 10);
+    });
+    
+    it('should respect plugin capabilities', () => {
+      const readOnlyPlugin: BlocPlugin<number> = {
+        name: 'read-only',
+        version: '1.0.0',
+        capabilities: {
+          readState: true,
+          transformState: false,
+          interceptEvents: false,
+          persistData: false,
+          accessMetadata: false
+        },
+        transformState: () => {
+          throw new Error('Should not be called');
+        },
+        onStateChange: vi.fn()
+      };
+      
+      const cubit = new CounterCubit();
+      cubit.addPlugin(readOnlyPlugin);
+      Blac.activateBloc(cubit as any);
+      
+      cubit.increment();
+      expect(cubit.state).toBe(1); // Transform not applied
+      expect(readOnlyPlugin.onStateChange).toHaveBeenCalled();
+    });
+  });
+  
+  describe('Example Plugins', () => {
+    it('should log with TestLoggingPlugin', () => {
+      const consoleSpy = vi.spyOn(console, 'debug');
+      
+      const plugin = new TestLoggingPlugin({ logLevel: 'debug' });
+      Blac.instance.plugins.add(plugin);
+      
+      const cubit = Blac.getBloc(CounterCubit);
+      cubit.increment();
+      
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Bloc created'),
+        undefined
+      );
+      
+      consoleSpy.mockRestore();
+    });
+    
+    it('should persist state with TestPersistencePlugin', () => {
+      const storage = new MockStorage();
+      storage.setItem('counter', '42');
+      
+      const plugin = new TestPersistencePlugin<number>({
+        key: 'counter',
+        storage,
+        saveDebounceMs: 0
+      });
+      
+      const cubit = new CounterCubit();
+      cubit.addPlugin(plugin);
+      Blac.activateBloc(cubit as any);
+      
+      // Should restore from storage
+      expect(cubit.state).toBe(42);
+      
+      // Should save new state
+      cubit.setValue(100);
+      
+      // Wait for debounced save
+      setTimeout(() => {
+        expect(storage.getItem('counter')).toBe('100');
+      }, 10);
+    });
+    
+    it('should validate state with TestValidationPlugin', () => {
+      const validator = (state: number) => {
+        if (state < 0) return 'Value must be non-negative';
+        if (state > 100) return 'Value must not exceed 100';
+        return true;
+      };
+      
+      const plugin = new TestValidationPlugin(validator);
+      
+      const cubit = new CounterCubit();
+      cubit.addPlugin(plugin);
+      Blac.activateBloc(cubit as any);
+      
+      cubit.setValue(-5);
+      expect(cubit.state).toBe(0); // Rejected
+      
+      cubit.setValue(50);
+      expect(cubit.state).toBe(50); // Accepted
+      
+      cubit.setValue(150);
+      expect(cubit.state).toBe(50); // Rejected
+    });
+  });
+  
+  describe('Plugin Composition', () => {
+    it('should compose multiple bloc plugins', () => {
+      const storage = new MockStorage();
+      
+      const persistencePlugin = new TestPersistencePlugin<number>({
+        key: 'validated-counter',
+        storage,
+        saveDebounceMs: 0
+      });
+      
+      const validationPlugin = new TestValidationPlugin<number>(
+        (state) => state >= 0 && state <= 10
+      );
+      
+      const cubit = new CounterCubit();
+      cubit.addPlugin(validationPlugin);
+      cubit.addPlugin(persistencePlugin);
+      Blac.activateBloc(cubit as any);
+      
+      cubit.setValue(5);
+      expect(cubit.state).toBe(5);
+      
+      cubit.setValue(15);
+      expect(cubit.state).toBe(5); // Validation rejected
+      
+      setTimeout(() => {
+        expect(storage.getItem('validated-counter')).toBe('5');
+      }, 10);
+    });
+  });
+});

package/src/index.ts

@@ -15,3 +15,6 @@ export * from './testing';
 
 // Adapter
 export * from './adapter';
+
+// Plugins
+export * from './plugins';

package/src/plugins/BlocPluginRegistry.ts

@@ -0,0 +1,220 @@
+import { BlocPlugin, PluginRegistry, ErrorContext } from '../core/types';
+
+/**
+ * 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) {
+      try {
+        plugin.onDetach();
+      } catch (error) {
+        console.error(`Plugin '${pluginName}' error in onDetach:`, error);
+      }
+    }
+    
+    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) {
+          try {
+            plugin.onDetach();
+          } catch (error) {
+            console.error(`Plugin '${plugin.name}' error in onDetach:`, error);
+          }
+        }
+      }
+    }
+    
+    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;
+  }
+}