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

package/src/subscription/__tests__/SubscriptionManager.test.ts

@@ -0,0 +1,355 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SubscriptionManager } from '../SubscriptionManager';
+import { BlocBase } from '../../BlocBase';
+import { Cubit } from '../../Cubit';
+
+class TestCubit extends Cubit<{ count: number; nested: { value: string } }> {
+  increment = () => {
+    this.emit({ ...this.state, count: this.state.count + 1 });
+  };
+
+  updateNested = (value: string) => {
+    this.emit({ ...this.state, nested: { value } });
+  };
+}
+
+describe('SubscriptionManager', () => {
+  let cubit: TestCubit;
+  let manager: SubscriptionManager<{
+    count: number;
+    nested: { value: string };
+  }>;
+
+  beforeEach(() => {
+    cubit = new TestCubit({ count: 0, nested: { value: 'initial' } });
+    manager = new SubscriptionManager(cubit);
+  });
+
+  describe('subscribe', () => {
+    it('should create a subscription and return unsubscribe function', () => {
+      const notify = vi.fn();
+      const unsubscribe = manager.subscribe({
+        type: 'observer',
+        notify,
+      });
+
+      expect(manager.size).toBe(1);
+
+      unsubscribe();
+      expect(manager.size).toBe(0);
+    });
+
+    it('should initialize selector value on subscription', () => {
+      const notify = vi.fn();
+      const selector = vi.fn((state) => state.count);
+
+      manager.subscribe({
+        type: 'consumer',
+        selector,
+        notify,
+      });
+
+      expect(selector).toHaveBeenCalledWith(cubit.state, cubit);
+    });
+
+    it('should handle selector errors gracefully', () => {
+      const notify = vi.fn();
+      const selector = vi.fn(() => {
+        throw new Error('Selector error');
+      });
+
+      // Should not throw
+      expect(() => {
+        manager.subscribe({
+          type: 'observer',
+          selector,
+          notify,
+        });
+      }).not.toThrow();
+    });
+  });
+
+  describe('notify', () => {
+    it('should notify subscriptions without selectors', () => {
+      const notify = vi.fn();
+      manager.subscribe({
+        type: 'observer',
+        notify,
+      });
+
+      const oldState = { count: 0, nested: { value: 'old' } };
+      const newState = { count: 1, nested: { value: 'new' } };
+
+      manager.notify(newState, oldState);
+
+      expect(notify).toHaveBeenCalledWith(newState, oldState, undefined);
+    });
+
+    it('should use selector for change detection', () => {
+      const notify = vi.fn();
+      const selector = (state: any) => state.count;
+
+      manager.subscribe({
+        type: 'consumer',
+        selector,
+        notify,
+      });
+
+      // Same count, should not notify
+      manager.notify(
+        { count: 0, nested: { value: 'new' } },
+        { count: 0, nested: { value: 'old' } },
+      );
+      expect(notify).not.toHaveBeenCalled();
+
+      // Different count, should notify
+      manager.notify(
+        { count: 1, nested: { value: 'new' } },
+        { count: 0, nested: { value: 'old' } },
+      );
+      expect(notify).toHaveBeenCalledWith(1, 0, undefined);
+    });
+
+    it('should use custom equality function', () => {
+      const notify = vi.fn();
+      const selector = (state: any) => state.nested;
+      const equalityFn = (a: any, b: any) => a.value === b.value;
+
+      manager.subscribe({
+        type: 'observer',
+        selector,
+        equalityFn,
+        notify,
+      });
+
+      // First notification to establish baseline
+      manager.notify(
+        { count: 0, nested: { value: 'initial' } },
+        { count: 0, nested: { value: 'initial' } },
+      );
+      notify.mockClear();
+
+      // Same nested value, should not notify
+      manager.notify(
+        { count: 1, nested: { value: 'initial' } },
+        { count: 0, nested: { value: 'initial' } },
+      );
+      expect(notify).not.toHaveBeenCalled();
+
+      // Different nested value, should notify
+      manager.notify(
+        { count: 1, nested: { value: 'new' } },
+        { count: 0, nested: { value: 'initial' } },
+      );
+      expect(notify).toHaveBeenCalled();
+    });
+
+    it('should respect priority order', () => {
+      const callOrder: string[] = [];
+
+      manager.subscribe({
+        type: 'observer',
+        priority: 1,
+        notify: () => callOrder.push('low'),
+      });
+
+      manager.subscribe({
+        type: 'observer',
+        priority: 10,
+        notify: () => callOrder.push('high'),
+      });
+
+      manager.subscribe({
+        type: 'observer',
+        priority: 5,
+        notify: () => callOrder.push('medium'),
+      });
+
+      manager.notify(
+        { count: 1, nested: { value: 'new' } },
+        { count: 0, nested: { value: 'old' } },
+      );
+
+      expect(callOrder).toEqual(['high', 'medium', 'low']);
+    });
+
+    it('should handle notify errors gracefully', () => {
+      const goodNotify = vi.fn();
+      const badNotify = vi.fn(() => {
+        throw new Error('Notify error');
+      });
+
+      manager.subscribe({ type: 'observer', notify: badNotify });
+      manager.subscribe({ type: 'observer', notify: goodNotify });
+
+      // Should not throw and should call good notify
+      expect(() => {
+        manager.notify(
+          { count: 1, nested: { value: 'new' } },
+          { count: 0, nested: { value: 'old' } },
+        );
+      }).not.toThrow();
+
+      expect(goodNotify).toHaveBeenCalled();
+    });
+  });
+
+  describe('trackAccess', () => {
+    it('should track path dependencies', () => {
+      const notify = vi.fn();
+      const unsubscribe = manager.subscribe({
+        type: 'consumer',
+        notify,
+      });
+
+      // Get subscription ID (hacky but works for testing)
+      const subscriptionId = Array.from(
+        (manager as any).subscriptions.keys(),
+      )[0] as string;
+
+      manager.trackAccess(subscriptionId, 'count');
+      manager.trackAccess(subscriptionId, 'nested.value');
+
+      const subscription = manager.getSubscription(subscriptionId);
+      expect(subscription?.dependencies).toContain('count');
+      expect(subscription?.dependencies).toContain('nested.value');
+    });
+
+    it('should update metadata on access', () => {
+      const notify = vi.fn();
+      manager.subscribe({ type: 'consumer', notify });
+
+      const subscriptionId = Array.from(
+        (manager as any).subscriptions.keys(),
+      )[0] as string;
+
+      manager.trackAccess(subscriptionId, 'count');
+
+      const subscription = manager.getSubscription(subscriptionId);
+      expect(subscription?.metadata?.accessCount).toBe(1);
+      expect(subscription?.metadata?.lastAccessTime).toBeGreaterThan(0);
+    });
+  });
+
+  describe('shouldNotifyForPaths', () => {
+    it('should return true for direct path match', () => {
+      const notify = vi.fn();
+      manager.subscribe({ type: 'consumer', notify });
+
+      const subscriptionId = Array.from(
+        (manager as any).subscriptions.keys(),
+      )[0] as string;
+      manager.trackAccess(subscriptionId, 'count');
+
+      const changedPaths = new Set(['count']);
+      expect(manager.shouldNotifyForPaths(subscriptionId, changedPaths)).toBe(
+        true,
+      );
+    });
+
+    it('should return true for nested path changes', () => {
+      const notify = vi.fn();
+      manager.subscribe({ type: 'consumer', notify });
+
+      const subscriptionId = Array.from(
+        (manager as any).subscriptions.keys(),
+      )[0] as string;
+      manager.trackAccess(subscriptionId, 'nested');
+
+      const changedPaths = new Set(['nested.value']);
+      expect(manager.shouldNotifyForPaths(subscriptionId, changedPaths)).toBe(
+        true,
+      );
+    });
+
+    it('should return false for unrelated path changes', () => {
+      const notify = vi.fn();
+      manager.subscribe({ type: 'consumer', notify });
+
+      const subscriptionId = Array.from(
+        (manager as any).subscriptions.keys(),
+      )[0] as string;
+      manager.trackAccess(subscriptionId, 'count');
+
+      const changedPaths = new Set(['nested.value']);
+      expect(manager.shouldNotifyForPaths(subscriptionId, changedPaths)).toBe(
+        false,
+      );
+    });
+  });
+
+  describe('weak reference handling', () => {
+    it('should clean up subscriptions with dead weak references', async () => {
+      let obj: any = { id: 'test' };
+      const weakRef = new WeakRef(obj);
+      const notify = vi.fn();
+
+      manager.subscribe({
+        type: 'consumer',
+        weakRef,
+        notify,
+      });
+
+      expect(manager.size).toBe(1);
+
+      // Clear strong reference
+      obj = null;
+
+      // Force garbage collection (this is platform-specific and may not work in all environments)
+      if ((global as any).gc) {
+        (global as any).gc();
+      }
+
+      // Trigger notification which should clean up dead refs
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      manager.notify(
+        { count: 1, nested: { value: 'new' } },
+        { count: 0, nested: { value: 'old' } },
+      );
+
+      // Wait for microtask
+      await new Promise((resolve) => queueMicrotask(resolve));
+
+      // Note: This test may not reliably pass in all environments due to GC timing
+      // In production, the cleanup will happen eventually
+    });
+  });
+
+  describe('getStats', () => {
+    it('should return correct statistics', () => {
+      manager.subscribe({ type: 'consumer', notify: vi.fn() });
+      manager.subscribe({ type: 'observer', notify: vi.fn() });
+      manager.subscribe({ type: 'observer', notify: vi.fn() });
+
+      const stats = manager.getStats();
+
+      expect(stats.activeSubscriptions).toBe(3);
+      expect(stats.consumerCount).toBe(1);
+      expect(stats.observerCount).toBe(2);
+      expect(stats.totalNotifications).toBe(0);
+
+      // Trigger a notification
+      manager.notify(
+        { count: 1, nested: { value: 'new' } },
+        { count: 0, nested: { value: 'old' } },
+      );
+
+      const updatedStats = manager.getStats();
+      expect(updatedStats.totalNotifications).toBe(3); // All 3 subscriptions notified
+    });
+  });
+
+  describe('clear', () => {
+    it('should remove all subscriptions', () => {
+      manager.subscribe({ type: 'consumer', notify: vi.fn() });
+      manager.subscribe({ type: 'observer', notify: vi.fn() });
+
+      expect(manager.size).toBe(2);
+
+      manager.clear();
+
+      expect(manager.size).toBe(0);
+      expect(manager.hasSubscriptions).toBe(false);
+    });
+  });
+});

package/src/subscription/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './SubscriptionManager';

package/src/subscription/types.ts

@@ -0,0 +1,90 @@
+import { BlocBase } from '../BlocBase';
+
+/**
+ * Unified subscription interface that replaces the dual consumer/observer system
+ */
+export interface Subscription<S = unknown> {
+  /** Unique identifier for the subscription */
+  id: string;
+
+  /** Type of subscription for backward compatibility */
+  type: 'consumer' | 'observer';
+
+  /** Optional selector function to derive values from state */
+  selector?: (state: S, bloc?: BlocBase<S>) => unknown;
+
+  /** Custom equality function for selector results (defaults to Object.is) */
+  equalityFn?: (prev: unknown, next: unknown) => boolean;
+
+  /** Notification callback when state changes */
+  notify: (value: unknown, oldValue?: unknown, action?: unknown) => void;
+
+  /** Priority for notification order (higher = earlier) */
+  priority?: number;
+
+  /** WeakRef to the subscriber for automatic cleanup (React components) */
+  weakRef?: WeakRef<object>;
+
+  /** Last computed selector value for comparison */
+  lastValue?: unknown;
+
+  /** Tracked state path dependencies */
+  dependencies?: Set<string>;
+
+  /** Metadata for tracking and debugging */
+  metadata?: SubscriptionMetadata;
+}
+
+export interface SubscriptionMetadata {
+  /** Timestamp of last notification */
+  lastNotified?: number;
+
+  /** Whether the subscriber has rendered (React-specific) */
+  hasRendered?: boolean;
+
+  /** Number of times this subscription accessed state */
+  accessCount?: number;
+
+  /** First access timestamp */
+  firstAccessTime?: number;
+
+  /** Last access timestamp */
+  lastAccessTime?: number;
+}
+
+export interface SubscriptionOptions<S> {
+  /** Type of subscription */
+  type: 'consumer' | 'observer';
+
+  /** Optional selector function */
+  selector?: (state: S, bloc?: BlocBase<S>) => unknown;
+
+  /** Custom equality function */
+  equalityFn?: (prev: unknown, next: unknown) => boolean;
+
+  /** Notification callback */
+  notify: (value: unknown, oldValue?: unknown, action?: unknown) => void;
+
+  /** Priority for notifications */
+  priority?: number;
+
+  /** WeakRef to subscriber */
+  weakRef?: WeakRef<object>;
+}
+
+export interface SubscriptionManagerStats {
+  /** Total number of active subscriptions */
+  activeSubscriptions: number;
+
+  /** Number of consumer subscriptions */
+  consumerCount: number;
+
+  /** Number of observer subscriptions */
+  observerCount: number;
+
+  /** Total notifications sent */
+  totalNotifications: number;
+
+  /** Number of tracked dependencies */
+  trackedDependencies: number;
+}

package/src/testing.ts

@@ -57,15 +57,12 @@ export class BlocTest {
         );
       }, timeout);
 
-      const unsubscribe = bloc._observer.subscribe({
-        id: `test-waiter-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
-        fn: (newState: S) => {
-          if (predicate(newState)) {
-            clearTimeout(timeoutId);
-            unsubscribe();
-            resolve(newState);
-          }
-        },
+      const unsubscribe = bloc.subscribe((newState: S) => {
+        if (predicate(newState)) {
+          clearTimeout(timeoutId);
+          unsubscribe();
+          resolve(newState);
+        }
       });
 
       // Check current state immediately
@@ -97,36 +94,33 @@ export class BlocTest {
         );
       }, timeout);
 
-      const unsubscribe = bloc._observer.subscribe({
-        id: `test-expecter-${crypto.randomUUID()}`,
-        fn: (newState: S) => {
-          receivedStates.push(newState);
-
-          // Check if we have all expected states
-          if (receivedStates.length === expectedStates.length) {
-            clearTimeout(timeoutId);
-            unsubscribe();
-
-            // Verify all states match using deep equality
-            for (let i = 0; i < expectedStates.length; i++) {
-              const expected = expectedStates[i];
-              const received = receivedStates[i];
-
-              // Use JSON comparison for deep equality
-              if (JSON.stringify(expected) !== JSON.stringify(received)) {
-                reject(
-                  new Error(
-                    `State mismatch at index ${i}. Expected: ${JSON.stringify(expected)}, ` +
-                      `Received: ${JSON.stringify(received)}`,
-                  ),
-                );
-                return;
-              }
+      const unsubscribe = bloc.subscribe((newState: S) => {
+        receivedStates.push(newState);
+
+        // Check if we have all expected states
+        if (receivedStates.length === expectedStates.length) {
+          clearTimeout(timeoutId);
+          unsubscribe();
+
+          // Verify all states match using deep equality
+          for (let i = 0; i < expectedStates.length; i++) {
+            const expected = expectedStates[i];
+            const received = receivedStates[i];
+
+            // Use JSON comparison for deep equality
+            if (JSON.stringify(expected) !== JSON.stringify(received)) {
+              reject(
+                new Error(
+                  `State mismatch at index ${i}. Expected: ${JSON.stringify(expected)}, ` +
+                    `Received: ${JSON.stringify(received)}`,
+                ),
+              );
+              return;
             }
-
-            resolve();
           }
-        },
+
+          resolve();
+        }
       });
     });
   }

package/src/types.ts

@@ -12,9 +12,7 @@ export type BlocClassNoParams<B> = new (args: never[]) => B;
 /**
  * Represents the abstract base types for Bloc and Cubit
  */
-export type BlocBaseAbstract =
-  | typeof Bloc<any, any, any>
-  | typeof Cubit<any, any>;
+export type BlocBaseAbstract = typeof Bloc<any, any> | typeof Cubit<any>;
 
 /**
  * Represents a constructor type for a Bloc that can take any parameters
@@ -25,6 +23,9 @@ export type BlocConstructor<B> = (new (...args: any) => B) & {
   keepAlive?: boolean;
 };
 
+export type BlocConstructorParams<B extends BlocConstructor<BlocBase<any>>> =
+  ConstructorParameters<B>[0];
+
 /**
  * Extracts the state type from a BlocBase instance
  * @template B - The BlocBase type to extract the state from
@@ -38,24 +39,6 @@ export type ValueType<B extends BlocBase<any>> =
  */
 export type BlocState<T> = T extends BlocBase<infer S> ? S : never;
 
-/**
- * Extracts the props type from either a Bloc or Cubit
- * @template T - The Bloc or Cubit type to extract the props from
- */
-export type InferPropsFromGeneric<T> =
-  T extends Bloc<any, any, infer P>
-    ? P
-    : T extends Cubit<any, infer P>
-      ? P
-      : never;
-
-/**
- * Extracts the constructor parameters type from a BlocBase
- * @template B - The BlocBase type to extract the constructor parameters from
- */
-export type BlocConstructorParameters<B extends BlocBase<any>> =
-  BlocConstructor<B> extends new (...args: infer P) => B ? P : never;
-
 /**
  * Enhanced constraint for Bloc events - must be objects with proper constructor
  */

package/src/utils/BatchingManager.ts

@@ -0,0 +1,59 @@
+/**
+ * Manages batching of state updates to optimize performance
+ */
+export class BatchingManager<S> {
+  private pendingUpdates: Array<{
+    newState: S;
+    oldState: S;
+    action?: unknown;
+  }> = [];
+  private isBatching = false;
+
+  /**
+   * Execute a callback with batched updates
+   */
+  batchUpdates(
+    callback: () => void,
+    onFlush: (finalUpdate: {
+      newState: S;
+      oldState: S;
+      action?: unknown;
+    }) => void,
+  ): void {
+    if (this.isBatching) {
+      callback();
+      return;
+    }
+
+    this.isBatching = true;
+    this.pendingUpdates = [];
+
+    try {
+      callback();
+
+      if (this.pendingUpdates.length > 0) {
+        const finalUpdate = this.pendingUpdates[this.pendingUpdates.length - 1];
+        onFlush(finalUpdate);
+      }
+    } finally {
+      this.isBatching = false;
+      this.pendingUpdates = [];
+    }
+  }
+
+  /**
+   * Add an update to the batch
+   */
+  addUpdate(update: { newState: S; oldState: S; action?: unknown }): void {
+    if (this.isBatching) {
+      this.pendingUpdates.push(update);
+    }
+  }
+
+  /**
+   * Check if currently batching
+   */
+  get isCurrentlyBatching(): boolean {
+    return this.isBatching;
+  }
+}