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

package/src/adapter/__tests__/BlacAdapter.test.ts

@@ -74,10 +74,10 @@ describe('BlacAdapter', () => {
     it('should create adapter with proper initialization', () => {
       const adapter = new BlacAdapter(
         { componentRef, blocConstructor: CounterCubit },
-        { id: 'test-counter' },
+        { instanceId: 'test-counter' },
       );
 
-      expect(adapter.id).toMatch(/^consumer-/);
+      expect(adapter.id).toMatch(/^adapter-/);
       expect(adapter.blocConstructor).toBe(CounterCubit);
       expect(adapter.componentRef).toBe(componentRef);
       expect(adapter.blocInstance).toBeInstanceOf(CounterCubit);
@@ -87,36 +87,39 @@ describe('BlacAdapter', () => {
       // Create first adapter
       const adapter1 = new BlacAdapter(
         { componentRef, blocConstructor: CounterCubit },
-        { id: 'shared-counter' },
+        { instanceId: 'shared-counter' },
       );
 
       // Create second adapter with same id
       const componentRef2 = { current: {} };
       const adapter2 = new BlacAdapter(
         { componentRef: componentRef2, blocConstructor: CounterCubit },
-        { id: 'shared-counter' },
+        { instanceId: 'shared-counter' },
       );
 
       // Should share the same bloc instance
       expect(adapter1.blocInstance).toBe(adapter2.blocInstance);
     });
 
-    it('should pass props to bloc constructor', () => {
-      class PropsCubit extends Cubit<string, { initialValue: string }> {
-        constructor(
-          public override props: { initialValue: string } | null = null,
-        ) {
+    it('should pass staticProps to bloc constructor', () => {
+      class PropsCubit extends Cubit<string> {
+        props?: { initialValue: string };
+
+        constructor(props?: { initialValue: string }) {
           super(props?.initialValue || 'default');
+          this.props = props;
         }
       }
 
       const adapter = new BlacAdapter(
         { componentRef, blocConstructor: PropsCubit as any },
-        { props: { initialValue: 'custom' } },
+        { staticProps: { initialValue: 'custom' } },
       );
 
       expect(adapter.blocInstance.state).toBe('custom');
-      expect(adapter.blocInstance.props).toEqual({ initialValue: 'custom' });
+      expect((adapter.blocInstance as PropsCubit).props).toEqual({
+        initialValue: 'custom',
+      });
     });
   });
 
@@ -199,16 +202,13 @@ describe('BlacAdapter', () => {
       });
 
       // Access state through proxy
-      const proxyState = adapter.getProxyState(adapter.blocInstance.state);
+      const proxyState = adapter.getStateProxy();
       const name = proxyState.name;
       const email = proxyState.profile.email;
 
-      // Check tracked dependencies
-      const dependencies = adapter.getConsumerDependencies(
-        componentRef.current,
-      );
-      expect(dependencies?.statePaths).toContain('name');
-      expect(dependencies?.statePaths).toContain('profile.email');
+      // Verify proxy state works correctly
+      expect(name).toBe('John');
+      expect(email).toBe('john@example.com');
     });
 
     it('should track class property access through proxy', () => {
@@ -232,16 +232,13 @@ describe('BlacAdapter', () => {
       });
 
       // Access getters through proxy
-      const proxyBloc = adapter.getProxyBlocInstance();
+      const proxyBloc = adapter.getBlocProxy();
       const doubled = proxyBloc.doubled;
       const isPositive = proxyBloc.isPositive;
 
-      // Check tracked dependencies
-      const dependencies = adapter.getConsumerDependencies(
-        componentRef.current,
-      );
-      expect(dependencies?.classPaths).toContain('doubled');
-      expect(dependencies?.classPaths).toContain('isPositive');
+      // Verify proxy getters work correctly
+      expect(doubled).toBe(0);
+      expect(isPositive).toBe(false);
     });
 
     it('should only notify when tracked values change', () => {
@@ -251,21 +248,25 @@ describe('BlacAdapter', () => {
         blocConstructor: UserCubit,
       });
 
-      // Track specific property access
-      adapter.resetConsumerTracking();
-      const proxyState = adapter.getProxyState(adapter.blocInstance.state);
-      const name = proxyState.name; // Only track name
-
-      // Mark as rendered to enable dependency checking
-      adapter.updateLastNotified(componentRef.current);
+      // Mount the adapter first
+      adapter.mount();
 
+      // Create subscription with automatic tracking
       const unsubscribe = adapter.createSubscription({ onChange });
 
+      // Access specific property through proxy to track it
+      const proxyState = adapter.getStateProxy();
+      const name = proxyState.name; // Track name property
+
+      // Clear onChange calls from initial subscription
+      onChange.mockClear();
+
       // Change tracked property - should notify
       adapter.blocInstance.updateName('Jane');
       expect(onChange).toHaveBeenCalledTimes(1);
 
-      // Change untracked property - should NOT notify
+      // For automatic tracking, only tracked properties trigger notifications
+      // Since we only accessed 'name', changing 'theme' should not notify
       onChange.mockClear();
       adapter.blocInstance.updateTheme('dark');
       expect(onChange).not.toHaveBeenCalled();
@@ -280,14 +281,15 @@ describe('BlacAdapter', () => {
       });
 
       // Access nested property
-      const proxyState = adapter.getProxyState(adapter.blocInstance.state);
+      const proxyState = adapter.getStateProxy();
       const theme = proxyState.profile.preferences.theme;
 
-      // Check tracked path
-      const dependencies = adapter.getConsumerDependencies(
-        componentRef.current,
-      );
-      expect(dependencies?.statePaths).toContain('profile.preferences.theme');
+      // Verify nested property access works
+      expect(theme).toBe('light');
+
+      // Verify nested proxy returns correct values
+      expect(proxyState.profile.email).toBe('john@example.com');
+      expect(proxyState.profile.preferences).toEqual({ theme: 'light' });
     });
   });
 
@@ -304,17 +306,16 @@ describe('BlacAdapter', () => {
       // Mount
       adapter.mount();
       expect(onMount).toHaveBeenCalledWith(adapter.blocInstance);
-      expect(adapter.calledOnMount).toBe(true);
-      expect(adapter.blocInstance._consumers.has(adapter.id)).toBe(true);
+      expect(adapter.mountTime).toBeGreaterThan(0);
 
-      // Mount again - should not call onMount twice
+      // Mount again - onMount is called each time
       adapter.mount();
-      expect(onMount).toHaveBeenCalledTimes(1);
+      expect(onMount).toHaveBeenCalledTimes(2);
 
       // Unmount
       adapter.unmount();
       expect(onUnmount).toHaveBeenCalledWith(adapter.blocInstance);
-      expect(adapter.blocInstance._consumers.has(adapter.id)).toBe(false);
+      expect(adapter.unmountTime).toBeGreaterThan(0);
     });
 
     it('should handle onMount errors', () => {
@@ -371,7 +372,7 @@ describe('BlacAdapter', () => {
       const onChange = vi.fn();
       const unsubscribe = adapter.createSubscription({ onChange });
 
-      expect(adapter.blocInstance._observer.size).toBe(1);
+      expect(adapter.blocInstance.subscriptionCount).toBe(1);
 
       // Trigger state change
       adapter.blocInstance.increment();
@@ -379,7 +380,7 @@ describe('BlacAdapter', () => {
 
       // Cleanup
       unsubscribe();
-      expect(adapter.blocInstance._observer.size).toBe(0);
+      expect(adapter.blocInstance.subscriptionCount).toBe(0);
     });
 
     it('should handle first render without dependencies check', () => {
@@ -407,7 +408,7 @@ describe('BlacAdapter', () => {
         { dependencies: (bloc) => [bloc.state.name] },
       );
 
-      const state = adapter.getProxyState(adapter.blocInstance.state);
+      const state = adapter.getStateProxy();
 
       // Should be raw state, not proxy
       expect(state).toBe(adapter.blocInstance.state);
@@ -419,7 +420,7 @@ describe('BlacAdapter', () => {
         { dependencies: (bloc) => [bloc.state] },
       );
 
-      const blocInstance = adapter.getProxyBlocInstance();
+      const blocInstance = adapter.getBlocProxy();
 
       // Should be raw instance, not proxy
       expect(blocInstance).toBe(adapter.blocInstance);
@@ -431,8 +432,8 @@ describe('BlacAdapter', () => {
         blocConstructor: UserCubit,
       });
 
-      const proxyState = adapter.getProxyState(adapter.blocInstance.state);
-      const proxyBloc = adapter.getProxyBlocInstance();
+      const proxyState = adapter.getStateProxy();
+      const proxyBloc = adapter.getBlocProxy();
 
       // Should be proxies
       expect(proxyState).not.toBe(adapter.blocInstance.state);
@@ -441,7 +442,7 @@ describe('BlacAdapter', () => {
   });
 
   describe('Consumer Tracking Integration', () => {
-    it('should properly track and validate consumers', () => {
+    it('should properly handle subscription lifecycle', () => {
       const adapter = new BlacAdapter({
         componentRef,
         blocConstructor: CounterCubit,
@@ -449,42 +450,35 @@ describe('BlacAdapter', () => {
 
       adapter.mount();
 
-      // Consumer should be tracked
-      const hasConsumer = adapter.shouldNotifyConsumer(
-        componentRef.current,
-        new Set(['state']),
-      );
-      expect(hasConsumer).toBe(true); // First render always notifies
+      const onChange = vi.fn();
+      const unsubscribe = adapter.createSubscription({ onChange });
 
-      // Update tracking info
-      adapter.updateLastNotified(componentRef.current);
+      // State change should notify
+      adapter.blocInstance.increment();
+      expect(onChange).toHaveBeenCalledTimes(1);
 
-      // Now should use dependency tracking
-      const shouldNotify = adapter.shouldNotifyConsumer(
-        componentRef.current,
-        new Set(['untracked']),
-      );
-      expect(shouldNotify).toBe(false);
+      // After unsubscribe, no more notifications
+      unsubscribe();
+      adapter.blocInstance.increment();
+      expect(onChange).toHaveBeenCalledTimes(1);
     });
 
-    it('should reset consumer tracking', () => {
+    it('should reset tracking state properly', () => {
       const adapter = new BlacAdapter({
         componentRef,
         blocConstructor: UserCubit,
       });
 
-      // Track some accesses
-      adapter.trackAccess(componentRef.current, 'state', 'name', 'John');
-      adapter.trackAccess(componentRef.current, 'state', 'age', 30);
-
-      const depsBefore = adapter.getConsumerDependencies(componentRef.current);
-      expect(depsBefore?.statePaths.length).toBe(2);
+      // Access state to potentially track
+      const proxyState = adapter.getStateProxy();
+      const name = proxyState.name;
 
-      // Reset tracking
-      adapter.resetConsumerTracking();
+      // Reset tracking clears internal state
+      adapter.resetTracking();
 
-      const depsAfter = adapter.getConsumerDependencies(componentRef.current);
-      expect(depsAfter?.statePaths.length).toBe(0);
+      // Verify adapter is still functional after reset
+      const theme = proxyState.profile.preferences.theme;
+      expect(theme).toBe('light');
     });
   });
 
@@ -534,7 +528,7 @@ describe('BlacAdapter', () => {
         adapter.unmount();
       }
 
-      expect(adapter.blocInstance._consumers.size).toBe(0);
+      expect(adapter.blocInstance.subscriptionCount).toBe(0);
     });
 
     it('should handle value changes with Object.is semantics', () => {

package/src/adapter/__tests__/ProxyFactory.test.ts

@@ -191,7 +191,7 @@ describe('ProxyFactory', () => {
       expect(userName).toBe('Jane');
 
       // Array methods should work
-      const mapped = proxy.items.map((x) => x * 2);
+      const mapped = proxy.items.map((x: number) => x * 2);
       expect(mapped).toEqual([2, 4, 6]);
     });
 

package/src/adapter/index.ts

@@ -1,3 +1,2 @@
 export * from './BlacAdapter';
-export * from './ConsumerTracker';
 export * from './ProxyFactory';

package/src/errors/BlacError.ts

@@ -0,0 +1,69 @@
+export enum ErrorCategory {
+  LIFECYCLE = 'LIFECYCLE',
+  STATE = 'STATE',
+  PLUGIN = 'PLUGIN',
+  VALIDATION = 'VALIDATION',
+  DISPOSAL = 'DISPOSAL',
+  CONSUMER = 'CONSUMER',
+}
+
+export enum ErrorSeverity {
+  FATAL = 'FATAL', // System cannot continue
+  ERROR = 'ERROR', // Operation failed but system continues
+  WARNING = 'WARNING', // Potential issue but operation succeeded
+  INFO = 'INFO', // Informational, not an error
+}
+
+export type BlacErrorContext = {
+  blocName?: string;
+  blocId?: string;
+  consumerId?: string;
+  pluginName?: string;
+  operation?: string;
+  metadata?: Record<string, unknown>;
+};
+
+export class BlacError extends Error {
+  constructor(
+    message: string,
+    public readonly category: ErrorCategory,
+    public readonly severity: ErrorSeverity,
+    public readonly context?: BlacErrorContext,
+    public readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = 'BlacError';
+
+    // Ensure proper prototype chain
+    Object.setPrototypeOf(this, BlacError.prototype);
+  }
+
+  toString(): string {
+    const contextStr = this.context
+      ? ` [${Object.entries(this.context)
+          .filter(([_, v]) => v !== undefined)
+          .map(([k, v]) => `${k}: ${v}`)
+          .join(', ')}]`
+      : '';
+
+    return `${this.name} [${this.severity}/${this.category}]: ${this.message}${contextStr}`;
+  }
+}
+
+export type ErrorHandler = (error: BlacError) => void;
+
+export type ErrorHandlingStrategy = {
+  shouldPropagate: (error: BlacError) => boolean;
+  shouldLog: (error: BlacError) => boolean;
+  handle: (error: BlacError) => void;
+};
+
+export const DefaultErrorStrategy: ErrorHandlingStrategy = {
+  shouldPropagate: (error) => error.severity === ErrorSeverity.FATAL,
+  shouldLog: (error) => error.severity !== ErrorSeverity.INFO,
+  handle: (error) => {
+    if (DefaultErrorStrategy.shouldLog(error)) {
+      console.error(error.toString(), error.cause);
+    }
+  },
+};

package/src/errors/ErrorManager.ts

@@ -0,0 +1,101 @@
+import {
+  BlacError,
+  ErrorHandler,
+  ErrorHandlingStrategy,
+  DefaultErrorStrategy,
+} from './BlacError';
+
+/**
+ * Centralized error management system for BlaC framework.
+ * Handles error processing, logging, and propagation strategies.
+ */
+export class ErrorManager {
+  private static instance: ErrorManager;
+  private handlers: Set<ErrorHandler> = new Set();
+  private strategy: ErrorHandlingStrategy = DefaultErrorStrategy;
+
+  /**
+   * Get the singleton instance of ErrorManager
+   */
+  static getInstance(): ErrorManager {
+    if (!ErrorManager.instance) {
+      ErrorManager.instance = new ErrorManager();
+    }
+    return ErrorManager.instance;
+  }
+
+  /**
+   * Set a custom error handling strategy
+   */
+  setStrategy(strategy: ErrorHandlingStrategy): void {
+    this.strategy = strategy;
+  }
+
+  /**
+   * Add a custom error handler that will be called for all errors
+   */
+  addHandler(handler: ErrorHandler): void {
+    this.handlers.add(handler);
+  }
+
+  /**
+   * Remove a previously added error handler
+   */
+  removeHandler(handler: ErrorHandler): void {
+    this.handlers.delete(handler);
+  }
+
+  /**
+   * Process an error through all handlers and apply the configured strategy
+   */
+  handle(error: BlacError): void {
+    // Always notify handlers first
+    this.handlers.forEach((handler) => {
+      try {
+        handler(error);
+      } catch (handlerError) {
+        // Prevent handler errors from breaking error handling
+        console.error('Error in error handler:', handlerError);
+      }
+    });
+
+    // Apply strategy
+    this.strategy.handle(error);
+
+    // Propagate if needed
+    if (this.strategy.shouldPropagate(error)) {
+      throw error;
+    }
+  }
+
+  /**
+   * Convenience method for wrapping operations with error handling
+   */
+  wrap<T>(operation: () => T, errorFactory: (error: unknown) => BlacError): T {
+    try {
+      return operation();
+    } catch (error) {
+      const blacError = errorFactory(error);
+      this.handle(blacError);
+      // Will only reach here if strategy says not to propagate
+      return undefined as T;
+    }
+  }
+
+  /**
+   * Async version of wrap
+   */
+  async wrapAsync<T>(
+    operation: () => Promise<T>,
+    errorFactory: (error: unknown) => BlacError,
+  ): Promise<T> {
+    try {
+      return await operation();
+    } catch (error) {
+      const blacError = errorFactory(error);
+      this.handle(blacError);
+      // Will only reach here if strategy says not to propagate
+      return undefined as T;
+    }
+  }
+}

package/src/errors/handleError.ts

@@ -0,0 +1,114 @@
+import {
+  BlacError,
+  ErrorCategory,
+  ErrorSeverity,
+  BlacErrorContext,
+} from './BlacError';
+import { ErrorManager } from './ErrorManager';
+
+/**
+ * Standard error handling helper for BlaC
+ *
+ * Usage:
+ * - For fatal errors that should propagate: handleError.fatal(...)
+ * - For recoverable errors: handleError.error(...)
+ * - For warnings: handleError.warn(...)
+ */
+export const handleError = {
+  fatal: (
+    message: string,
+    category: ErrorCategory,
+    context?: BlacErrorContext,
+    cause?: unknown,
+  ): never => {
+    const error = new BlacError(
+      message,
+      category,
+      ErrorSeverity.FATAL,
+      context,
+      cause,
+    );
+    ErrorManager.getInstance().handle(error);
+    // This will always throw due to FATAL severity
+    throw error;
+  },
+
+  error: (
+    message: string,
+    category: ErrorCategory,
+    context?: BlacErrorContext,
+    cause?: unknown,
+  ): void => {
+    const error = new BlacError(
+      message,
+      category,
+      ErrorSeverity.ERROR,
+      context,
+      cause,
+    );
+    ErrorManager.getInstance().handle(error);
+  },
+
+  warn: (
+    message: string,
+    category: ErrorCategory,
+    context?: BlacErrorContext,
+    cause?: unknown,
+  ): void => {
+    const error = new BlacError(
+      message,
+      category,
+      ErrorSeverity.WARNING,
+      context,
+      cause,
+    );
+    ErrorManager.getInstance().handle(error);
+  },
+
+  info: (
+    message: string,
+    category: ErrorCategory,
+    context?: BlacErrorContext,
+  ): void => {
+    const error = new BlacError(message, category, ErrorSeverity.INFO, context);
+    ErrorManager.getInstance().handle(error);
+  },
+
+  /**
+   * Wraps a function to catch and handle errors
+   */
+  wrap: <T>(
+    fn: () => T,
+    category: ErrorCategory,
+    context?: BlacErrorContext,
+    severity: ErrorSeverity = ErrorSeverity.ERROR,
+  ): T | undefined => {
+    try {
+      return fn();
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : String(cause);
+      const error = new BlacError(message, category, severity, context, cause);
+      ErrorManager.getInstance().handle(error);
+      return undefined;
+    }
+  },
+
+  /**
+   * Wraps an async function to catch and handle errors
+   */
+  wrapAsync: async <T>(
+    fn: () => Promise<T>,
+    category: ErrorCategory,
+    context?: BlacErrorContext,
+    severity: ErrorSeverity = ErrorSeverity.ERROR,
+  ): Promise<T | undefined> => {
+    try {
+      return await fn();
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : String(cause);
+      const error = new BlacError(message, category, severity, context, cause);
+      ErrorManager.getInstance().handle(error);
+      return undefined;
+    }
+  },
+};

package/src/errors/index.ts

@@ -0,0 +1,13 @@
+export {
+  BlacError,
+  ErrorCategory,
+  ErrorSeverity,
+  DefaultErrorStrategy,
+} from './BlacError';
+export type {
+  BlacErrorContext,
+  ErrorHandler,
+  ErrorHandlingStrategy,
+} from './BlacError';
+export { ErrorManager } from './ErrorManager';
+export { handleError } from './handleError';

package/src/events.ts

@@ -1,3 +1,9 @@
+/**
+ * Event fired when props are updated on a Bloc or Cubit instance.
+ * This is primarily used internally by the framework to notify
+ * about prop changes in React components.
+ * @template P - The type of props being updated
+ */
 export class PropsUpdated<P = any> {
   constructor(public readonly props: P) {}
-}
+}

package/src/index.ts

@@ -1,14 +1,17 @@
 export * from './Blac';
-export * from './BlacObserver';
 export * from './Bloc';
 export * from './BlocBase';
 export * from './Cubit';
 export * from './types';
 export * from './events';
+export * from './subscription';
+export * from './lifecycle';
 
 // Utilities
 export * from './utils/uuid';
 export * from './utils/shallowEqual';
+export * from './utils/generateInstanceId';
+export * from './utils/RerenderLogger';
 
 // Test utilities
 export * from './testing';
@@ -18,3 +21,6 @@ export * from './adapter';
 
 // Plugins
 export * from './plugins';
+
+// Error handling
+export * from './errors';