@blac/core 2.0.0-rc-10 → 2.0.0-rn-12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blac/core",
-  "version": "2.0.0-rc-10",
+  "version": "2.0.0-rn-12",
   "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,
@@ -20,6 +13,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 +107,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 */

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,8 @@ 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);
 
-    // If not already processing, start processing the queue
     if (!this._isProcessingEvent) {
       await this._processEventQueue();
     }
@@ -91,7 +67,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 +88,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 +119,11 @@ 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
-
-        // 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/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);
+    });
+  });
+});

package/src/__tests__/props.test.ts

@@ -0,0 +1,256 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Bloc } from '../Bloc';
+import { Cubit } from '../Cubit';
+import { PropsUpdated } from '../events';
+import { BlacAdapter } from '../adapter/BlacAdapter';
+import { Blac } from '../Blac';
+
+// Test types
+interface TestProps {
+  query: string;
+  filters?: string[];
+}
+
+interface TestState {
+  data: string;
+  loading: boolean;
+}
+
+// Test Cubit with props
+class TestCubit extends Cubit<TestState, TestProps> {
+  onPropsChangedMock = vi.fn();
+
+  constructor() {
+    super({ data: '', loading: false });
+  }
+
+  protected onPropsChanged(oldProps: TestProps | undefined, newProps: TestProps): void {
+    this.onPropsChangedMock(oldProps, newProps);
+    if (oldProps?.query !== newProps.query) {
+      this.emit({ ...this.state, data: `Query: ${newProps.query}` });
+    }
+  }
+
+  loadData = () => {
+    const query = this.props?.query ?? 'default';
+    this.emit({ data: `Loaded: ${query}`, loading: false });
+  };
+}
+
+// Test Bloc with props
+class TestBloc extends Bloc<TestState, PropsUpdated<TestProps>> {
+  constructor() {
+    super({ data: '', loading: false });
+
+    this.on(PropsUpdated<TestProps>, (event, emit) => {
+      emit({ ...this.state, data: `Props: ${event.props.query}` });
+    });
+  }
+}
+
+describe('Props functionality', () => {
+  beforeEach(() => {
+    // Clear Blac instance between tests
+    Blac.resetInstance();
+  });
+
+  describe('PropsUpdated event', () => {
+    it('should create PropsUpdated event with correct props', () => {
+      const props = { query: 'test', filters: ['a', 'b'] };
+      const event = new PropsUpdated(props);
+      
+      expect(event.props).toEqual(props);
+      expect(event.props).toBe(props); // Should be the same reference
+    });
+  });
+
+  describe('Cubit props support', () => {
+    it('should support props getter', () => {
+      const cubit = new TestCubit();
+      expect(cubit.props).toBeNull();
+    });
+
+    it('should update props via _updateProps', () => {
+      const cubit = new TestCubit();
+      const props = { query: 'test' };
+      
+      (cubit as any)._updateProps(props);
+      
+      expect(cubit.props).toEqual(props);
+      expect(cubit.onPropsChangedMock).toHaveBeenCalledWith(null, props);
+    });
+
+    it('should emit state when props change', () => {
+      const cubit = new TestCubit();
+      const props1 = { query: 'test1' };
+      const props2 = { query: 'test2' };
+      
+      (cubit as any)._updateProps(props1);
+      expect(cubit.state.data).toBe('Query: test1');
+      
+      (cubit as any)._updateProps(props2);
+      expect(cubit.state.data).toBe('Query: test2');
+    });
+
+    it('should access props in methods', () => {
+      const cubit = new TestCubit();
+      
+      cubit.loadData();
+      expect(cubit.state.data).toBe('Loaded: default');
+      
+      (cubit as any)._updateProps({ query: 'custom' });
+      cubit.loadData();
+      expect(cubit.state.data).toBe('Loaded: custom');
+    });
+  });
+
+  describe('Bloc props support', () => {
+    it('should handle PropsUpdated events', async () => {
+      const bloc = new TestBloc();
+      const props = { query: 'search' };
+      
+      await bloc.add(new PropsUpdated(props));
+      
+      expect(bloc.state.data).toBe('Props: search');
+    });
+
+    it('should queue PropsUpdated events like any other event', async () => {
+      const bloc = new TestBloc();
+      
+      await bloc.add(new PropsUpdated({ query: 'first' }));
+      await bloc.add(new PropsUpdated({ query: 'second' }));
+      
+      expect(bloc.state.data).toBe('Props: second');
+    });
+  });
+
+  describe('BlacAdapter props ownership', () => {
+    it('should allow first adapter to own props', () => {
+      const Constructor = TestCubit as any;
+      const adapter1 = new BlacAdapter(
+        { componentRef: { current: {} }, blocConstructor: Constructor },
+        { props: { query: 'test1' } }
+      );
+      
+      expect(() => {
+        adapter1.updateProps({ query: 'test2' });
+      }).not.toThrow();
+    });
+
+    it('should prevent non-owner adapters from updating props', () => {
+      const warnSpy = vi.spyOn(Blac, 'warn').mockImplementation(() => {});
+      const Constructor = TestCubit as any;
+      
+      // First adapter becomes owner
+      const adapter1 = new BlacAdapter(
+        { componentRef: { current: {} }, blocConstructor: Constructor },
+        { props: { query: 'test1' } }
+      );
+      
+      // Second adapter tries to update props
+      const adapter2 = new BlacAdapter(
+        { componentRef: { current: {} }, blocConstructor: Constructor },
+        {}
+      );
+      
+      adapter2.updateProps({ query: 'hijack' });
+      
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('non-owner adapter')
+      );
+      
+      warnSpy.mockRestore();
+    });
+
+    it('should clear ownership on adapter unmount', () => {
+      const Constructor = TestCubit as any;
+      const adapter1 = new BlacAdapter(
+        { componentRef: { current: {} }, blocConstructor: Constructor },
+        { props: { query: 'test1' } }
+      );
+      
+      adapter1.mount();
+      adapter1.unmount();
+      
+      // New adapter should be able to take ownership
+      const adapter2 = new BlacAdapter(
+        { componentRef: { current: {} }, blocConstructor: Constructor },
+        { props: { query: 'test2' } }
+      );
+      
+      expect(() => {
+        adapter2.updateProps({ query: 'test3' });
+      }).not.toThrow();
+    });
+
+    it('should not update props if they are shallowly equal', () => {
+      const cubit = new TestCubit();
+      const Constructor = TestCubit as any;
+      const adapter = new BlacAdapter(
+        { componentRef: { current: {} }, blocConstructor: Constructor },
+        {}
+      );
+      
+      const props = { query: 'test' };
+      adapter.updateProps(props);
+      
+      // Reset mock
+      cubit.onPropsChangedMock.mockClear();
+      
+      // Update with same props
+      adapter.updateProps({ query: 'test' });
+      
+      // onPropsChanged should not have been called
+      expect(cubit.onPropsChangedMock).not.toHaveBeenCalled();
+    });
+
+    it('should ignore props updates during disposal', () => {
+      const Constructor = TestCubit as any;
+      const adapter = new BlacAdapter(
+        { componentRef: { current: {} }, blocConstructor: Constructor },
+        { props: { query: 'test1' } }
+      );
+      
+      // Force disposal state
+      (adapter.blocInstance as any)._disposalState = 'disposing';
+      
+      expect(() => {
+        adapter.updateProps({ query: 'test2' });
+      }).not.toThrow();
+      
+      // Props should not have been updated
+      expect((adapter.blocInstance as TestCubit).props?.query).toBe('test1');
+    });
+  });
+
+  describe('Props integration', () => {
+    it('should dispatch PropsUpdated for Bloc instances', async () => {
+      const Constructor = TestBloc as any;
+      const adapter = new BlacAdapter(
+        { componentRef: { current: {} }, blocConstructor: Constructor },
+        {}
+      );
+      
+      const bloc = adapter.blocInstance as TestBloc;
+      adapter.updateProps({ query: 'adapter-test' });
+      
+      // Wait for event processing
+      await new Promise(resolve => setTimeout(resolve, 50));
+      
+      expect(bloc.state.data).toBe('Props: adapter-test');
+    });
+
+    it('should call _updateProps for Cubit instances', () => {
+      const Constructor = TestCubit as any;
+      const adapter = new BlacAdapter(
+        { componentRef: { current: {} }, blocConstructor: Constructor },
+        {}
+      );
+      
+      adapter.updateProps({ query: 'adapter-test' });
+      
+      expect((adapter.blocInstance as TestCubit).props?.query).toBe('adapter-test');
+      expect((adapter.blocInstance as TestCubit).state.data).toBe('Query: adapter-test');
+    });
+  });
+});