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

package/src/adapter/BlacAdapter.ts

@@ -1,14 +1,16 @@
 import { Blac } from '../Blac';
-import { BlocBase } from '../BlocBase';
+import { BlocBase, BlocLifecycleState } from '../BlocBase';
 import { BlocConstructor, BlocState, InferPropsFromGeneric } from '../types';
+import { PropsUpdated } from '../events';
 import { generateUUID } from '../utils/uuid';
+import { shallowEqual } from '../utils/shallowEqual';
 import { ConsumerTracker, DependencyArray } from './ConsumerTracker';
 import { ProxyFactory } from './ProxyFactory';
 
 export interface AdapterOptions<B extends BlocBase<any>> {
   id?: string;
   dependencies?: (bloc: B) => unknown[];
-  props?: InferPropsFromGeneric<B>;
+  props?: any;
   onMount?: (bloc: B) => void;
   onUnmount?: (bloc: B) => void;
 }
@@ -26,6 +28,10 @@ export class BlacAdapter<B extends BlocConstructor<BlocBase<any>>> {
   // Core components
   private consumerTracker: ConsumerTracker;
 
+  // Props ownership tracking
+  private static propsOwners = new WeakMap<BlocBase<any>, string>();
+  private lastProps?: any;
+
   unmountTime: number = 0;
   mountTime: number = 0;
 
@@ -59,6 +65,11 @@ export class BlacAdapter<B extends BlocConstructor<BlocBase<any>>> {
     if (this.isUsingDependencies && options?.dependencies) {
       this.dependencyValues = options.dependencies(this.blocInstance);
     }
+
+    // Handle initial props if provided
+    if (options?.props !== undefined) {
+      this.updateProps(options.props);
+    }
   }
 
   trackAccess(
@@ -133,7 +144,7 @@ export class BlacAdapter<B extends BlocConstructor<BlocBase<any>>> {
         newState: BlocState<InstanceType<B>>,
         oldState: BlocState<InstanceType<B>>,
       ) => {
-        // Handle dependency-based change detection
+        // Case 1: Manual dependencies provided
         if (this.isUsingDependencies && this.options?.dependencies) {
           const newValues = this.options.dependencies(this.blocInstance);
           const hasChanged = this.hasDependencyValuesChanged(
@@ -146,7 +157,15 @@ export class BlacAdapter<B extends BlocConstructor<BlocBase<any>>> {
           }
 
           this.dependencyValues = newValues;
-        } else {
+        } 
+        // Case 2: Proxy tracking disabled globally (and no manual dependencies)
+        else if (!Blac.config.proxyDependencyTracking) {
+          // Always trigger re-render when proxy tracking is disabled
+          options.onChange();
+          return;
+        } 
+        // Case 3: Proxy tracking enabled (default behavior)
+        else {
           // Check if any tracked values have changed (proxy-based tracking)
           const consumerInfo = this.consumerTracker.getConsumerInfo(
             this.componentRef.current,
@@ -202,6 +221,11 @@ export class BlacAdapter<B extends BlocConstructor<BlocBase<any>>> {
     this.consumerTracker.unregister(this.componentRef.current);
     this.blocInstance._removeConsumer(this.id);
 
+    // Clear ownership if we own this bloc
+    if (BlacAdapter.propsOwners.get(this.blocInstance) === this.id) {
+      BlacAdapter.propsOwners.delete(this.blocInstance);
+    }
+
     // Call onUnmount callback
     if (this.options?.onUnmount) {
       try {
@@ -215,8 +239,9 @@ export class BlacAdapter<B extends BlocConstructor<BlocBase<any>>> {
   getProxyState = (
     state: BlocState<InstanceType<B>>,
   ): BlocState<InstanceType<B>> => {
-    if (this.isUsingDependencies) {
-      return state; // Return raw state when using dependencies
+    // Return raw state if proxy tracking is disabled globally or using manual dependencies
+    if (this.isUsingDependencies || !Blac.config.proxyDependencyTracking) {
+      return state;
     }
 
     return ProxyFactory.getProxyState({
@@ -227,8 +252,9 @@ export class BlacAdapter<B extends BlocConstructor<BlocBase<any>>> {
   };
 
   getProxyBlocInstance = (): InstanceType<B> => {
-    if (this.isUsingDependencies) {
-      return this.blocInstance; // Return raw instance when using dependencies
+    // Return raw instance if proxy tracking is disabled globally or using manual dependencies
+    if (this.isUsingDependencies || !Blac.config.proxyDependencyTracking) {
+      return this.blocInstance;
     }
 
     return ProxyFactory.getProxyBlocInstance({
@@ -243,6 +269,45 @@ export class BlacAdapter<B extends BlocConstructor<BlocBase<any>>> {
     return this.hasMounted;
   }
 
+  updateProps(props: any): void {
+    const bloc = this.blocInstance;
+    
+    // Check ownership
+    if (!BlacAdapter.propsOwners.has(bloc)) {
+      // First adapter with props becomes the owner
+      BlacAdapter.propsOwners.set(bloc, this.id);
+    }
+    
+    if (BlacAdapter.propsOwners.get(bloc) !== this.id) {
+      Blac.warn(
+        `[BlacAdapter] Attempted to set props on ${bloc.constructor.name} from non-owner adapter`
+      );
+      return;
+    }
+    
+    // Disposal safety
+    if ((bloc as any)._disposalState === BlocLifecycleState.DISPOSED ||
+        (bloc as any)._disposalState === BlocLifecycleState.DISPOSING) {
+      return;
+    }
+    
+    // Check if props have changed
+    if (shallowEqual(this.lastProps, props)) {
+      return;
+    }
+    
+    // Update props based on bloc type
+    if ('add' in bloc && typeof bloc.add === 'function') {
+      // Bloc: dispatch PropsUpdated event
+      (bloc as any).add(new PropsUpdated(props));
+    } else if ('_updateProps' in bloc && typeof (bloc as any)._updateProps === 'function') {
+      // Cubit: direct props update
+      (bloc as any)._updateProps(props);
+    }
+    
+    this.lastProps = props;
+  }
+
   private hasDependencyValuesChanged(
     prev: unknown[] | undefined,
     next: unknown[],

package/src/events.ts

@@ -0,0 +1,3 @@
+export class PropsUpdated<P = any> {
+  constructor(public readonly props: P) {}
+}

package/src/index.ts

@@ -4,12 +4,17 @@ export * from './Bloc';
 export * from './BlocBase';
 export * from './Cubit';
 export * from './types';
+export * from './events';
 
 // Utilities
 export * from './utils/uuid';
+export * from './utils/shallowEqual';
 
 // Test utilities
 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;
+  }
+}

package/src/plugins/SystemPluginRegistry.ts

@@ -0,0 +1,192 @@
+import { BlacPlugin, PluginRegistry, PluginMetrics, ErrorContext } from '../core/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);
+    });
+  }
+
+  /**
+   * 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
+    });
+  }
+}

package/src/plugins/index.ts

@@ -0,0 +1,8 @@
+// Core types
+export * from './types';
+
+// System plugins
+export { SystemPluginRegistry } from './SystemPluginRegistry';
+
+// Bloc plugins
+export { BlocPluginRegistry } from './BlocPluginRegistry';

package/src/plugins/types.ts

@@ -0,0 +1,100 @@
+import { BlocBase } from '../BlocBase';
+import { Bloc } from '../Bloc';
+
+/**
+ * Error context provided to error handlers
+ */
+export interface ErrorContext {
+  readonly phase: 'initialization' | 'state-change' | 'event-processing' | 'disposal';
+  readonly operation: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+/**
+ * Plugin capabilities for security model
+ */
+export interface PluginCapabilities {
+  readonly readState: boolean;
+  readonly transformState: boolean;
+  readonly interceptEvents: boolean;
+  readonly persistData: boolean;
+  readonly accessMetadata: boolean;
+}
+
+/**
+ * Base interface for all plugins
+ */
+export interface Plugin {
+  readonly name: string;
+  readonly version: string;
+  readonly capabilities?: PluginCapabilities;
+}
+
+/**
+ * System-wide plugin that observes all blocs
+ */
+export interface BlacPlugin extends Plugin {
+  // Lifecycle hooks - all synchronous
+  beforeBootstrap?(): void;
+  afterBootstrap?(): void;
+  beforeShutdown?(): void;
+  afterShutdown?(): void;
+
+  // System-wide observations
+  onBlocCreated?(bloc: BlocBase<any>): void;
+  onBlocDisposed?(bloc: BlocBase<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;
+}
+
+/**
+ * Bloc-specific plugin that can transform behavior
+ */
+export interface BlocPlugin<TState = any, TEvent = never> extends Plugin {
+  // Transform hooks - can modify data
+  transformState?(previousState: TState, nextState: TState): TState;
+  transformEvent?(event: TEvent): TEvent | null;
+
+  // Lifecycle hooks
+  onAttach?(bloc: BlocBase<TState, any>): void;
+  onDetach?(): void;
+
+  // Observation hooks
+  onStateChange?(previousState: TState, currentState: TState): void;
+  onEvent?(event: TEvent): void;
+  onError?(error: Error, context: ErrorContext): void;
+}
+
+/**
+ * Plugin execution context for performance monitoring
+ */
+export interface PluginExecutionContext {
+  readonly pluginName: string;
+  readonly hookName: string;
+  readonly startTime: number;
+  readonly blocName?: string;
+  readonly blocId?: string;
+}
+
+/**
+ * Plugin metrics for monitoring
+ */
+export interface PluginMetrics {
+  readonly executionTime: number;
+  readonly executionCount: number;
+  readonly errorCount: number;
+  readonly lastError?: Error;
+  readonly lastExecutionTime?: number;
+}
+
+/**
+ * Plugin registry interface
+ */
+export interface PluginRegistry<T extends Plugin> {
+  add(plugin: T): void;
+  remove(pluginName: string): boolean;
+  get(pluginName: string): T | undefined;
+  getAll(): ReadonlyArray<T>;
+  clear(): void;
+}