@blac/core 2.0.0-rc-8 → 2.0.0-rc-11

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');
+    });
+  });
+});

package/src/adapter/BlacAdapter.ts

@@ -0,0 +1,327 @@
+import { Blac } from '../Blac';
+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?: any;
+  onMount?: (bloc: B) => void;
+  onUnmount?: (bloc: B) => void;
+}
+
+/**
+ * BlacAdapter orchestrates the connection between Bloc instances and React components.
+ * It manages dependency tracking, lifecycle hooks, and proxy creation.
+ */
+export class BlacAdapter<B extends BlocConstructor<BlocBase<any>>> {
+  public readonly id = `consumer-${generateUUID()}`;
+  public readonly blocConstructor: B;
+  public readonly componentRef: { current: object } = { current: {} };
+  public blocInstance: InstanceType<B>;
+
+  // 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;
+
+  // Dependency tracking
+  private dependencyValues?: unknown[];
+  private isUsingDependencies: boolean = false;
+
+  // Lifecycle state
+  private hasMounted = false;
+  private mountCount = 0;
+
+  options?: AdapterOptions<InstanceType<B>>;
+
+  constructor(
+    instanceProps: { componentRef: { current: object }; blocConstructor: B },
+    options?: typeof this.options,
+  ) {
+    this.options = options;
+    this.blocConstructor = instanceProps.blocConstructor;
+    this.componentRef = instanceProps.componentRef;
+    this.isUsingDependencies = !!options?.dependencies;
+
+    // Initialize consumer tracker
+    this.consumerTracker = new ConsumerTracker();
+
+    // Initialize bloc instance and register consumer
+    this.blocInstance = this.updateBlocInstance();
+    this.consumerTracker.register(instanceProps.componentRef.current, this.id);
+
+    // Initialize dependency values if using dependencies
+    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(
+    consumerRef: object,
+    type: 'state' | 'class',
+    path: string,
+    value?: any,
+  ): void {
+    this.consumerTracker.trackAccess(consumerRef, type, path, value);
+  }
+
+  getConsumerDependencies(consumerRef: object): DependencyArray | null {
+    return this.consumerTracker.getDependencies(consumerRef);
+  }
+
+  shouldNotifyConsumer(
+    consumerRef: object,
+    changedPaths: Set<string>,
+  ): boolean {
+    const consumerInfo = this.consumerTracker.getConsumerInfo(consumerRef);
+    if (!consumerInfo) {
+      return true; // If consumer not registered yet, notify by default
+    }
+
+    // First render - always notify to establish baseline
+    if (!consumerInfo.hasRendered) {
+      return true;
+    }
+
+    // Use built-in method from ConsumerTracker
+    return this.consumerTracker.shouldNotifyConsumer(consumerRef, changedPaths);
+  }
+
+  updateLastNotified(consumerRef: object): void {
+    this.consumerTracker.updateLastNotified(consumerRef);
+    this.consumerTracker.setHasRendered(consumerRef, true);
+  }
+
+  resetConsumerTracking(): void {
+    this.consumerTracker.resetTracking(this.componentRef.current);
+  }
+
+  createStateProxy = <T extends object>(props: { target: T }): T => {
+    return ProxyFactory.createStateProxy({
+      target: props.target,
+      consumerRef: this.componentRef.current,
+      consumerTracker: this as any,
+    });
+  };
+
+  createClassProxy = <T extends object>(props: { target: T }): T => {
+    return ProxyFactory.createClassProxy({
+      target: props.target,
+      consumerRef: this.componentRef.current,
+      consumerTracker: this as any,
+    });
+  };
+
+  updateBlocInstance(): InstanceType<B> {
+    this.blocInstance = Blac.instance.getBloc<B>(this.blocConstructor, {
+      props: this.options?.props,
+      id: this.options?.id,
+      instanceRef: this.id,
+    });
+    return this.blocInstance;
+  }
+
+  createSubscription = (options: { onChange: () => void }) => {
+    const unsubscribe = this.blocInstance._observer.subscribe({
+      id: this.id,
+      fn: (
+        newState: BlocState<InstanceType<B>>,
+        oldState: BlocState<InstanceType<B>>,
+      ) => {
+        // Case 1: Manual dependencies provided
+        if (this.isUsingDependencies && this.options?.dependencies) {
+          const newValues = this.options.dependencies(this.blocInstance);
+          const hasChanged = this.hasDependencyValuesChanged(
+            this.dependencyValues,
+            newValues,
+          );
+
+          if (!hasChanged) {
+            return; // Don't trigger re-render
+          }
+
+          this.dependencyValues = newValues;
+        } 
+        // 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,
+          );
+          if (consumerInfo && consumerInfo.hasRendered) {
+            // Only check dependencies if component has rendered at least once
+            const hasChanged = this.consumerTracker.hasValuesChanged(
+              this.componentRef.current,
+              newState,
+              this.blocInstance,
+            );
+
+            if (!hasChanged) {
+              return; // Don't trigger re-render
+            }
+          }
+        }
+
+        options.onChange();
+      },
+    });
+
+    return unsubscribe;
+  };
+
+  mount = (): void => {
+    // Re-run dependencies on mount to ensure fresh values
+    if (this.isUsingDependencies && this.options?.dependencies) {
+      this.dependencyValues = this.options.dependencies(this.blocInstance);
+    }
+
+    // Lifecycle management
+    this.mountCount++;
+    this.blocInstance._addConsumer(this.id, this.componentRef.current);
+
+    // Call onMount callback if provided and not already called
+    if (!this.hasMounted) {
+      this.hasMounted = true;
+      this.mountTime = Date.now();
+
+      if (this.options?.onMount) {
+        try {
+          this.options.onMount(this.blocInstance);
+        } catch (error) {
+          throw error;
+        }
+      }
+    }
+  };
+
+  unmount = (): void => {
+    this.unmountTime = Date.now();
+    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 {
+        this.options.onUnmount(this.blocInstance);
+      } catch (error) {
+        // Don't re-throw on unmount to allow cleanup to continue
+      }
+    }
+  };
+
+  getProxyState = (
+    state: BlocState<InstanceType<B>>,
+  ): BlocState<InstanceType<B>> => {
+    // Return raw state if proxy tracking is disabled globally or using manual dependencies
+    if (this.isUsingDependencies || !Blac.config.proxyDependencyTracking) {
+      return state;
+    }
+
+    return ProxyFactory.getProxyState({
+      state,
+      consumerRef: this.componentRef.current,
+      consumerTracker: this as any,
+    });
+  };
+
+  getProxyBlocInstance = (): InstanceType<B> => {
+    // 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({
+      blocInstance: this.blocInstance,
+      consumerRef: this.componentRef.current,
+      consumerTracker: this as any,
+    });
+  };
+
+  // Expose calledOnMount for backward compatibility
+  get calledOnMount(): boolean {
+    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[],
+  ): boolean {
+    if (!prev) return true; // First run, always trigger
+    if (prev.length !== next.length) return true;
+
+    // Use Object.is for comparison (handles NaN, +0/-0 correctly)
+    for (let i = 0; i < prev.length; i++) {
+      if (!Object.is(prev[i], next[i])) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+}