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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blac/core",
-  "version": "2.0.0-rc-10",
+  "version": "2.0.0-rc-13",
   "license": "MIT",
   "author": "Brendan Mullins <jsnanigans@gmail.com>",
   "main": "dist/index.cjs.js",

package/src/Blac.ts

@@ -1,10 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-// TODO: The 'any' types in this file are necessary for proper type inference in complex generic scenarios.
-// Specifically:
-// 1. BlocConstructor<any> in Maps - allows any bloc type to be stored while maintaining type safety in usage
-// 2. Type assertions for _disposalState - private property access across inheritance hierarchy
-// 3. Constructor argument types - enables flexible bloc instantiation patterns
-// These 'any' usages are carefully controlled and don't compromise runtime type safety.
 import { BlocBase, BlocInstanceId, BlocLifecycleState } from './BlocBase';
 import {
   BlocBaseAbstract,
@@ -13,6 +6,7 @@ import {
   BlocState,
   InferPropsFromGeneric,
 } from './types';
+import { SystemPluginRegistry } from './plugins/SystemPluginRegistry';
 
 /**
  * Configuration options for the Blac instance
@@ -20,6 +14,12 @@ import {
 export interface BlacConfig {
   /** Whether to expose the Blac instance globally */
   exposeBlacInstance?: boolean;
+  /**
+   * Whether to enable proxy dependency tracking for automatic re-render optimization.
+   * When false, state changes always cause re-renders unless dependencies are manually specified.
+   * Default: true
+   */
+  proxyDependencyTracking?: boolean;
 }
 
 export interface GetBlocOptions<B extends BlocBase<unknown>> {
@@ -108,6 +108,46 @@ export class Blac {
   static get getAllBlocs() {
     return Blac.instance.getAllBlocs;
   }
+
+  /** Private static configuration */
+  private static _config: BlacConfig = {
+    exposeBlacInstance: false,
+    proxyDependencyTracking: true,
+  };
+
+  /** Get current configuration */
+  static get config(): Readonly<BlacConfig> {
+    return { ...this._config };
+  }
+
+  /**
+   * Set or update Blac configuration
+   * @param config - Partial configuration to merge with existing config
+   * @throws Error if configuration is invalid
+   */
+  static setConfig(config: Partial<BlacConfig>): void {
+    // Validate config
+    if (config.proxyDependencyTracking !== undefined &&
+        typeof config.proxyDependencyTracking !== 'boolean') {
+      throw new Error('BlacConfig.proxyDependencyTracking must be a boolean');
+    }
+
+    if (config.exposeBlacInstance !== undefined &&
+        typeof config.exposeBlacInstance !== 'boolean') {
+      throw new Error('BlacConfig.exposeBlacInstance must be a boolean');
+    }
+
+    // Merge with existing config
+    this._config = {
+      ...this._config,
+      ...config,
+    };
+
+    // Log config update if logging is enabled
+    if (this.enableLog) {
+      this.instance.log('Blac config updated:', this._config);
+    }
+  }
   /** Map storing all registered bloc instances by their class name and ID */
   blocInstanceMap: Map<string, BlocBase<unknown>> = new Map();
   /** Map storing isolated bloc instances grouped by their constructor */
@@ -123,6 +163,8 @@ export class Blac {
   keepAliveBlocs: Set<BlocBase<unknown>> = new Set();
   /** Flag to control whether changes should be posted to document */
   postChangesToDocument = false;
+  /** System plugin registry */
+  readonly plugins = new SystemPluginRegistry();
 
   /**
    * Creates a new Blac instance.
@@ -134,6 +176,9 @@ export class Blac {
       return Blac.instance;
     }
     instanceManager.setInstance(this);
+
+    // Bootstrap plugins on creation
+    this.plugins.bootstrap();
   }
 
   /** Flag to enable/disable logging */
@@ -274,6 +319,9 @@ export class Blac {
     // First dispose the bloc to prevent further operations
     bloc._dispose();
 
+    // Notify plugins of bloc disposal
+    this.plugins.notifyBlocDisposed(bloc);
+
     // Then clean up from registries
     if (base.isolated) {
       this.unregisterIsolatedBlocInstance(bloc);
@@ -468,10 +516,16 @@ export class Blac {
 
     if (newBloc.isIsolated) {
       this.registerIsolatedBlocInstance(newBloc);
-      return newBloc;
+    } else {
+      this.registerBlocInstance(newBloc);
     }
 
-    this.registerBlocInstance(newBloc);
+    // Activate bloc plugins
+    newBloc._activatePlugins();
+
+    // Notify system plugins of bloc creation
+    this.plugins.notifyBlocCreated(newBloc);
+
     return newBloc;
   }
 
@@ -747,4 +801,35 @@ export class Blac {
   static get validateConsumers() {
     return Blac.instance.validateConsumers;
   }
+
+  /**
+   * Bootstrap the Blac instance and all plugins
+   */
+  bootstrap(): void {
+    this.plugins.bootstrap();
+  }
+
+  /**
+   * Shutdown the Blac instance and all plugins
+   */
+  shutdown(): void {
+    this.plugins.shutdown();
+
+    // Dispose all non-keepAlive blocs
+    for (const bloc of this.blocInstanceMap.values()) {
+      if (!bloc._keepAlive) {
+        this.disposeBloc(bloc);
+      }
+    }
+
+    for (const blocs of this.isolatedBlocMap.values()) {
+      for (const bloc of blocs) {
+        if (!bloc._keepAlive) {
+          this.disposeBloc(bloc);
+        }
+      }
+    }
+  }
+
+
 }

package/src/BlacObserver.ts

@@ -174,6 +174,9 @@ export class BlacObservable<S = unknown> {
         void observer.fn(newState, oldState, action);
       }
     });
+
+    // Notify system plugins of state change
+    Blac.instance.plugins.notifyStateChanged(this.bloc, oldState, newState);
   }
 
   /**

package/src/Bloc.ts

@@ -2,27 +2,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 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 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>
-  // The handler's event parameter will be correctly typed to the specific EventConstructor
-  // by the 'on' method's signature.
   readonly eventHandlers: Map<
-    // Key: Constructor of a specific event E (where E extends A)
-    // TODO: 'any[]' is required for constructor arguments to allow flexible event instantiation.
-    // Using specific parameter types would break type inference for events with different
-    // constructor signatures. The 'any[]' enables polymorphic event handling while
-    // maintaining type safety through the generic constraint 'E extends A'.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     new (...args: any[]) => A,
-    // Value: Handler function. 'event: A' is used here for the stored function type.
-    // The 'on' method ensures the specific handler (event: E) is correctly typed.
     (event: A, emit: (newState: S) => void) => void | Promise<void>
   > = new Map();
 
@@ -46,22 +32,14 @@ export abstract class Bloc<
    *                The 'event' parameter in the handler will be typed to the specific eventConstructor.
    */
   protected on<E extends A>(
-    // TODO: 'any[]' is required for constructor arguments (see explanation above).
-    // This allows events with different constructor signatures to be handled uniformly.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     eventConstructor: new (...args: any[]) => E,
     handler: (event: E, emit: (newState: S) => void) => void | Promise<void>,
   ): void {
     if (this.eventHandlers.has(eventConstructor)) {
-      // Using Blac.warn or a similar logging mechanism from BlocBase if available,
-      // otherwise console.warn. Assuming this._name and this._id are available from BlocBase.
       Blac.warn(
         `[Bloc ${this._name}:${String(this._id)}] Handler for event '${eventConstructor.name}' already registered. It will be overwritten.`,
       );
     }
-    // Cast the specific handler (event: E) to a more general (event: A) for storage.
-    // This is safe because E extends A. When the handler is called with an 'action' of type A,
-    // if it was originally registered for type E, 'action' must be an instance of E.
     this.eventHandlers.set(
       eventConstructor,
       handler as (
@@ -77,10 +55,32 @@ export abstract class Bloc<
    * @param action The action/event instance to be processed.
    */
   public add = async (action: A): Promise<void> => {
-    // Add event to queue
-    this._eventQueue.push(action);
+    // Transform event through plugins
+    let transformedAction: A | null = action;
+    try {
+      transformedAction = (this._plugins as any).transformEvent(action);
+    } catch (error) {
+      console.error('Error transforming event:', error);
+      // Continue with original event if transformation fails
+    }
+    
+    // If event was cancelled by plugin, don't process it
+    if (transformedAction === null) {
+      return;
+    }
+    
+    // Notify bloc plugins of event
+    try {
+      (this._plugins as any).notifyEvent(transformedAction);
+    } catch (error) {
+      console.error('Error notifying plugins of event:', error);
+    }
+    
+    // Notify system plugins of event
+    Blac.instance.plugins.notifyEventAdded(this as any, transformedAction);
+    
+    this._eventQueue.push(transformedAction);
 
-    // If not already processing, start processing the queue
     if (!this._isProcessingEvent) {
       await this._processEventQueue();
     }
@@ -91,7 +91,6 @@ export abstract class Bloc<
    * Processes events from the queue sequentially
    */
   private async _processEventQueue(): Promise<void> {
-    // Prevent concurrent processing
     if (this._isProcessingEvent) {
       return;
     }
@@ -113,34 +112,18 @@ export abstract class Bloc<
    * Processes a single event
    */
   private async _processEvent(action: A): Promise<void> {
-    // Using 'any[]' for constructor arguments for broader compatibility.
-    // TODO: Type assertion required to cast action.constructor to proper event constructor type.
-    // JavaScript's constructor property returns 'Function', but we need the specific event
-    // constructor type to look up handlers. This is safe because we validate the action
-    // extends the BlocEventConstraint interface.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const eventConstructor = action.constructor as new (...args: any[]) => A;
     const handler = this.eventHandlers.get(eventConstructor);
 
     if (handler) {
-      // Define the 'emit' function that handlers will use to update state.
-      // It captures the current state ('this.state') right before each emission
-      // to provide the correct 'previousState' to _pushState.
       const emit = (newState: S): void => {
         const previousState = this.state; // State just before this specific emission
-        // The 'action' passed to _pushState is the original action that triggered the handler,
-        // providing context for the state change (e.g., for logging or plugins).
         this._pushState(newState, previousState, action);
       };
 
       try {
-        // Await the handler in case it's an async function (e.g., performs API calls).
-        // The 'action' is passed to the handler, and due to the way 'on' is typed,
-        // the 'event' parameter within the handler function will be correctly
-        // typed to its specific class (e.g., LoadMyFeatureData).
         await handler(action, emit);
       } catch (error) {
-        // Enhanced error handling with better context
         const constructorName =
           (action.constructor as { name?: string }).name ||
           'UnnamedConstructor';
@@ -160,19 +143,30 @@ export abstract class Bloc<
           errorContext,
         );
 
-        // 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
+        // Notify plugins of the error
+        if (error instanceof Error) {
+          try {
+            this._plugins.notifyError(error, {
+              phase: 'event-processing',
+              operation: 'handler',
+              metadata: { event: action }
+            });
+            
+            Blac.instance.plugins.notifyError(error, this as any, {
+              phase: 'event-processing',
+              operation: 'handler',
+              metadata: { event: action }
+            });
+          } catch (pluginError) {
+            console.error('Error notifying plugins:', pluginError);
+          }
+        }
 
-        // Optional: Re-throw for critical errors (can be configured)
         if (error instanceof Error && error.name === 'CriticalError') {
           throw error;
         }
       }
     } else {
-      // Enhanced warning with more context
       const constructorName =
         (action.constructor as { name?: string }).name || 'UnnamedConstructor';
       Blac.warn(

package/src/BlocBase.ts

@@ -1,5 +1,7 @@
 import { BlacObservable } from './BlacObserver';
 import { generateUUID } from './utils/uuid';
+import { BlocPlugin, ErrorContext } from './plugins/types';
+import { BlocPluginRegistry } from './plugins/BlocPluginRegistry';
 
 export type BlocInstanceId = string | number | undefined;
 type DependencySelector<S> = (
@@ -32,6 +34,7 @@ export interface StateTransitionResult {
 interface BlocStaticProperties {
   isolated: boolean;
   keepAlive: boolean;
+  plugins?: BlocPlugin<any, any>[];
 }
 
 /**
@@ -158,6 +161,11 @@ export abstract class BlocBase<S, P = unknown> {
    */
   private _consumerRefs = new Map<string, WeakRef<object>>();
 
+  /**
+   * Plugin registry for this bloc instance
+   */
+  protected _plugins: BlocPluginRegistry<S, any>;
+
   /**
    * @internal
    * Validates that all consumer references are still alive
@@ -210,6 +218,16 @@ export abstract class BlocBase<S, P = unknown> {
         : false;
     this._isolated =
       typeof Constructor.isolated === 'boolean' ? Constructor.isolated : false;
+
+    // Initialize plugin registry
+    this._plugins = new BlocPluginRegistry<S, any>();
+
+    // Register static plugins
+    if (Constructor.plugins && Array.isArray(Constructor.plugins)) {
+      for (const plugin of Constructor.plugins) {
+        this.addPlugin(plugin);
+      }
+    }
   }
 
   /**
@@ -529,25 +547,55 @@ export abstract class BlocBase<S, P = unknown> {
       return;
     }
 
+    // Transform state through plugins
+    let transformedState: S = newState;
+    try {
+      const result = this._plugins.transformState(oldState, newState);
+      transformedState = result;
+    } catch (error) {
+      this._plugins.notifyError(error as Error, {
+        phase: 'state-change',
+        operation: 'transformState'
+      });
+      // Continue with original state if transformation fails
+    }
+
     if (this._batchingEnabled) {
       // When batching, just accumulate the updates
-      this._pendingUpdates.push({ newState, oldState, action });
+      this._pendingUpdates.push({ newState: transformedState, oldState, action });
 
       // Update internal state for consistency
       this._oldState = oldState;
-      this._state = newState;
+      this._state = transformedState;
       return;
     }
 
     // Normal state update flow
     this._oldState = oldState;
-    this._state = newState;
+    this._state = transformedState;
+
+    // Notify bloc plugins first
+    try {
+      this._plugins.notifyStateChange(oldState, transformedState);
+    } catch (error) {
+      console.error('Error notifying bloc plugins of state change:', error);
+    }
 
     // Notify observers of the state change
-    this._observer.notify(newState, oldState, action);
+    this._observer.notify(transformedState, oldState, action);
     this.lastUpdate = Date.now();
   };
 
+  /**
+   * Notify observers of a state change
+   * @internal Used by plugins for state hydration
+   * @param newState The new state
+   * @param oldState The old state
+   */
+  _notifyObservers(newState: S, oldState: S): void {
+    this._observer.notify(newState, oldState);
+  }
+
   /**
    * Enables batching for multiple state updates
    * @param batchFn Function to execute with batching enabled
@@ -586,4 +634,59 @@ export abstract class BlocBase<S, P = unknown> {
       this._pendingUpdates = [];
     }
   };
+
+  /**
+   * Add a plugin to this bloc instance
+   */
+  addPlugin(plugin: BlocPlugin<S, any>): void {
+    this._plugins.add(plugin);
+
+    // Attach if already active
+    if (this._disposalState === BlocLifecycleState.ACTIVE) {
+      try {
+        if (plugin.onAttach) {
+          plugin.onAttach(this);
+        }
+      } catch (error) {
+        console.error(`Failed to attach plugin '${plugin.name}':`, error);
+        this._plugins.remove(plugin.name);
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * Remove a plugin from this bloc instance
+   */
+  removePlugin(pluginName: string): boolean {
+    return this._plugins.remove(pluginName);
+  }
+
+  /**
+   * Get a plugin by name
+   */
+  getPlugin(pluginName: string): BlocPlugin<S, any> | undefined {
+    return this._plugins.get(pluginName);
+  }
+
+  /**
+   * Get all plugins
+   */
+  getPlugins(): ReadonlyArray<BlocPlugin<S, any>> {
+    return this._plugins.getAll();
+  }
+
+  /**
+   * @internal
+   * Activate plugins when bloc becomes active
+   */
+  _activatePlugins(): void {
+    if (this._disposalState === BlocLifecycleState.ACTIVE) {
+      try {
+        this._plugins.attach(this);
+      } catch (error) {
+        console.error(`Failed to activate plugins for ${this._name}:`, error);
+      }
+    }
+  }
 }

package/src/Cubit.ts

@@ -8,6 +8,20 @@ import { BlocBase } from './BlocBase';
  * @template P - The type of parameters (optional, defaults to null)
  */
 export abstract class Cubit<S, P = null> extends BlocBase<S, P> {
+  /**
+   * @internal
+   * Protected method for useBloc to call
+   */
+  protected _updateProps(props: P): void {
+    const oldProps = this.props;
+    this.props = props;
+    this.onPropsChanged?.(oldProps as P | undefined, props);
+  }
+  
+  /**
+   * Optional override for props handling
+   */
+  protected onPropsChanged?(oldProps: P | undefined, newProps: P): void;
   /**
    * Updates the current state and notifies all observers of the change.
    * If the new state is identical to the current state (using Object.is),

package/src/__tests__/Blac.config.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { Blac, BlacConfig } from '../index';
+
+describe('Blac.config', () => {
+  const originalConfig = { ...Blac.config };
+
+  beforeEach(() => {
+    // Reset to default config before each test
+    Blac.setConfig({
+      exposeBlacInstance: false,
+      proxyDependencyTracking: true,
+    });
+  });
+
+  afterEach(() => {
+    // Restore original config after tests
+    Blac.setConfig(originalConfig);
+  });
+
+  describe('setConfig', () => {
+    it('should have default configuration', () => {
+      expect(Blac.config).toEqual({
+        exposeBlacInstance: false,
+        proxyDependencyTracking: true,
+      });
+    });
+
+    it('should update configuration with partial config', () => {
+      Blac.setConfig({ proxyDependencyTracking: false });
+      
+      expect(Blac.config).toEqual({
+        exposeBlacInstance: false,
+        proxyDependencyTracking: false,
+      });
+    });
+
+    it('should merge configuration properly', () => {
+      Blac.setConfig({ exposeBlacInstance: true });
+      Blac.setConfig({ proxyDependencyTracking: false });
+      
+      expect(Blac.config).toEqual({
+        exposeBlacInstance: true,
+        proxyDependencyTracking: false,
+      });
+    });
+
+    it('should throw error for invalid proxyDependencyTracking type', () => {
+      expect(() => {
+        Blac.setConfig({ proxyDependencyTracking: 'true' as any });
+      }).toThrow('BlacConfig.proxyDependencyTracking must be a boolean');
+    });
+
+    it('should throw error for invalid exposeBlacInstance type', () => {
+      expect(() => {
+        Blac.setConfig({ exposeBlacInstance: 1 as any });
+      }).toThrow('BlacConfig.exposeBlacInstance must be a boolean');
+    });
+
+    it('should return a copy of config, not the original', () => {
+      const config1 = Blac.config;
+      const config2 = Blac.config;
+      
+      expect(config1).not.toBe(config2);
+      expect(config1).toEqual(config2);
+    });
+
+    it('should not allow direct modification of config', () => {
+      const config = Blac.config as any;
+      config.proxyDependencyTracking = false;
+      
+      // Original config should remain unchanged
+      expect(Blac.config.proxyDependencyTracking).toBe(true);
+    });
+  });
+
+  describe('config type exports', () => {
+    it('should allow typed config usage', () => {
+      const testConfig: Partial<BlacConfig> = {
+        proxyDependencyTracking: false,
+      };
+      
+      Blac.setConfig(testConfig);
+      expect(Blac.config.proxyDependencyTracking).toBe(false);
+    });
+  });
+});