@blac/core 2.0.0-rc-16 → 2.0.0-rc.1

package/src/Bloc.ts

@@ -1,180 +0,0 @@
-import { Blac } from './Blac';
-import { BlocBase } from './BlocBase';
-import { BlocEventConstraint } from './types';
-
-export abstract class Bloc<
-  S, // State type
-  A extends BlocEventConstraint = BlocEventConstraint, // Base Action/Event type with proper constraints
-> extends BlocBase<S> {
-  readonly eventHandlers: Map<
-    new (...args: any[]) => A,
-    (event: A, emit: (newState: S) => void) => void | Promise<void>
-  > = new Map();
-
-  /**
-   * @internal
-   * Event queue to ensure sequential processing of async events
-   */
-  private _eventQueue: A[] = [];
-
-  /**
-   * @internal
-   * Flag indicating if an event is currently being processed
-   */
-  private _isProcessingEvent = false;
-
-  /**
-   * Registers an event handler for a specific event type.
-   * This method is typically called in the constructor of a derived Bloc class.
-   * @param eventConstructor The constructor of the event to handle (e.g., LoadDataEvent).
-   * @param handler A function that processes the event and can emit new states.
-   *                The 'event' parameter in the handler will be typed to the specific eventConstructor.
-   */
-  protected on<E extends A>(
-    eventConstructor: new (...args: any[]) => E,
-    handler: (event: E, emit: (newState: S) => void) => void | Promise<void>,
-  ): void {
-    if (this.eventHandlers.has(eventConstructor)) {
-      Blac.warn(
-        `[Bloc ${this._name}:${String(this._id)}] Handler for event '${eventConstructor.name}' already registered. It will be overwritten.`,
-      );
-    }
-    this.eventHandlers.set(
-      eventConstructor,
-      handler as (
-        event: A,
-        emit: (newState: S) => void,
-      ) => void | Promise<void>,
-    );
-  }
-
-  /**
-   * Dispatches an action/event to the Bloc.
-   * Events are queued and processed sequentially to prevent race conditions.
-   * @param action The action/event instance to be processed.
-   */
-  public add = async (action: A): Promise<void> => {
-    // 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 (!this._isProcessingEvent) {
-      await this._processEventQueue();
-    }
-  };
-
-  /**
-   * @internal
-   * Processes events from the queue sequentially
-   */
-  private async _processEventQueue(): Promise<void> {
-    if (this._isProcessingEvent) {
-      return;
-    }
-
-    this._isProcessingEvent = true;
-
-    try {
-      while (this._eventQueue.length > 0) {
-        const action = this._eventQueue.shift()!;
-        await this._processEvent(action);
-      }
-    } finally {
-      this._isProcessingEvent = false;
-    }
-  }
-
-  /**
-   * @internal
-   * Processes a single event
-   */
-  private async _processEvent(action: A): Promise<void> {
-    const eventConstructor = action.constructor as new (...args: any[]) => A;
-    const handler = this.eventHandlers.get(eventConstructor);
-
-    if (handler) {
-      const emit = (newState: S): void => {
-        const previousState = this.state; // State just before this specific emission
-        this._pushState(newState, previousState, action);
-      };
-
-      try {
-        await handler(action, emit);
-      } catch (error) {
-        const constructorName =
-          (action.constructor as { name?: string }).name ||
-          'UnnamedConstructor';
-        const errorContext = {
-          blocName: this._name,
-          blocId: String(this._id),
-          eventType: constructorName,
-          currentState: this.state,
-          action: action,
-          timestamp: new Date().toISOString(),
-        };
-
-        Blac.error(
-          `[Bloc ${this._name}:${String(this._id)}] Error in event handler for '${constructorName}':`,
-          error,
-          'Context:',
-          errorContext,
-        );
-
-        // 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);
-          }
-        }
-
-        if (error instanceof Error && error.name === 'CriticalError') {
-          throw error;
-        }
-      }
-    } else {
-      const constructorName =
-        (action.constructor as { name?: string }).name || 'UnnamedConstructor';
-      Blac.warn(
-        `[Bloc ${this._name}:${String(this._id)}] No handler registered for action type: '${constructorName}'.`,
-        'Registered handlers:',
-        Array.from(this.eventHandlers.keys()).map((k) => k.name),
-        'Action was:',
-        action,
-      );
-    }
-  }
-}

package/src/BlocBase.ts

@@ -1,398 +0,0 @@
-import { generateUUID } from './utils/uuid';
-import { BlocPlugin } from './plugins/types';
-import { BlocPluginRegistry } from './plugins/BlocPluginRegistry';
-import { SubscriptionManager } from './subscription/SubscriptionManager';
-import {
-  BlocLifecycleManager,
-  BlocLifecycleState,
-  StateTransitionResult,
-} from './lifecycle/BlocLifecycle';
-import { BatchingManager } from './utils/BatchingManager';
-import type { Blac } from './Blac';
-
-export type BlocInstanceId = string | number | undefined;
-
-interface BlocStaticProperties {
-  isolated: boolean;
-  keepAlive: boolean;
-  plugins?: BlocPlugin<any, any>[];
-}
-
-/**
- * Base class for both Blocs and Cubits using unified subscription model.
- */
-export abstract class BlocBase<S> {
-  public uid = generateUUID();
-  blacInstance?: Blac;
-
-  static isolated = false;
-  get isIsolated() {
-    return this._isolated;
-  }
-
-  static keepAlive = false;
-  get isKeepAlive() {
-    return this._keepAlive;
-  }
-
-  public _isolated = false;
-  public _id: BlocInstanceId;
-  public _instanceRef?: string;
-  public _name: string;
-
-  /**
-   * Unified subscription manager for all state notifications
-   */
-  public _subscriptionManager: SubscriptionManager<S>;
-
-  _state: S;
-  private _lifecycleManager = new BlocLifecycleManager();
-  private _batchingManager = new BatchingManager<S>();
-  _keepAlive = false;
-  public lastUpdate?: number;
-
-  _plugins = new BlocPluginRegistry<S, any>();
-
-  onDispose?: () => void;
-
-  /**
-   * Creates a new BlocBase instance with unified subscription management
-   */
-  constructor(initialState: S) {
-    this._state = initialState;
-    this._id = this.constructor.name;
-    this._name = this.constructor.name;
-
-    // Initialize unified subscription system
-    this._subscriptionManager = new SubscriptionManager(this as any);
-
-    // Access static properties
-    const Constructor = this.constructor as typeof BlocBase &
-      BlocStaticProperties;
-
-    this._keepAlive =
-      typeof Constructor.keepAlive === 'boolean'
-        ? Constructor.keepAlive
-        : 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._plugins.add(plugin);
-      }
-    }
-
-    // Attach all plugins
-    this._plugins.attach(this);
-  }
-
-  /**
-   * Returns the current state
-   */
-  get state(): S {
-    if (this._lifecycleManager.isDisposed) {
-      return this._state; // Return last known state for disposed blocs
-    }
-    return this._state;
-  }
-
-  /**
-   * Subscribe to all state changes
-   */
-  subscribe(callback: (state: S) => void): () => void {
-    return this._subscriptionManager.subscribe({
-      type: 'observer',
-      notify: (state) => callback(state as S),
-    });
-  }
-
-  /**
-   * Subscribe with a selector for optimized updates
-   */
-  subscribeWithSelector<T>(
-    selector: (state: S) => T,
-    callback: (value: T) => void,
-    equalityFn?: (a: T, b: T) => boolean,
-  ): () => void {
-    return this._subscriptionManager.subscribe({
-      type: 'consumer',
-      selector: selector as any,
-      equalityFn: equalityFn as any,
-      notify: (value) => callback(value as T),
-    });
-  }
-
-  /**
-   * Subscribe with React component reference for automatic cleanup
-   */
-  subscribeComponent(
-    componentRef: WeakRef<object>,
-    callback: () => void,
-  ): () => void {
-    return this._subscriptionManager.subscribe({
-      type: 'consumer',
-      weakRef: componentRef,
-      notify: callback,
-    });
-  }
-
-  /**
-   * Get current subscription count
-   */
-  get subscriptionCount(): number {
-    return this._subscriptionManager.size;
-  }
-
-  /**
-   * Track property access for a subscription
-   */
-  trackAccess(subscriptionId: string, path: string, value?: unknown): void {
-    this._subscriptionManager.trackAccess(subscriptionId, path, value);
-  }
-
-  /**
-   * Emit a new state
-   */
-  protected emit(newState: S, action?: unknown): void {
-    this._pushState(newState, this._state, action);
-  }
-
-  /**
-   * Internal state push method used by Bloc
-   */
-  _pushState(newState: S, oldState: S, action?: unknown): void {
-    // Validate state emission conditions
-    if (this._lifecycleManager.currentState !== BlocLifecycleState.ACTIVE) {
-      this.blacInstance?.error(
-        `[${this._name}:${this._id}] Attempted state update on ${this._lifecycleManager.currentState} bloc. Update ignored.`,
-      );
-      return;
-    }
-
-    if (newState === undefined) {
-      return; // Silent failure for undefined states
-    }
-
-    this._state = newState;
-
-    // Apply plugins
-    const transformedState = this._plugins.transformState(
-      oldState,
-      newState,
-    ) as S;
-    this._state = transformedState;
-
-    // Notify plugins of state change
-    this._plugins.notifyStateChange(oldState, transformedState);
-
-    // Notify system plugins of state change
-    this.blacInstance?.plugins.notifyStateChanged(
-      this as any,
-      oldState,
-      transformedState,
-    );
-
-    // Handle batching
-    if (this._batchingManager.isCurrentlyBatching) {
-      this._batchingManager.addUpdate({
-        newState: transformedState,
-        oldState,
-        action,
-      });
-      return;
-    }
-
-    // Notify all subscriptions
-    this._subscriptionManager.notify(transformedState, oldState, action);
-    this.lastUpdate = Date.now();
-  }
-
-  _batchUpdates(callback: () => void): void {
-    this._batchingManager.batchUpdates(callback, (finalUpdate) => {
-      this._subscriptionManager.notify(
-        finalUpdate.newState,
-        finalUpdate.oldState,
-        finalUpdate.action,
-      );
-    });
-  }
-
-  /**
-   * Add a plugin
-   */
-  addPlugin(plugin: BlocPlugin<S, any>): void {
-    this._plugins.add(plugin);
-
-    // If plugins are already attached (bloc is active), attach the new plugin
-    if ((this._plugins as any).attached && plugin.onAttach) {
-      try {
-        plugin.onAttach(this);
-      } catch (error) {
-        console.error(`Plugin '${plugin.name}' error in onAttach:`, error);
-      }
-    }
-  }
-
-  /**
-   * Remove a plugin
-   */
-  removePlugin(plugin: BlocPlugin<S, any>): void {
-    this._plugins.remove(plugin.name);
-  }
-
-  /**
-   * Get all plugins
-   */
-  get plugins(): ReadonlyArray<BlocPlugin<S, any>> {
-    return this._plugins.getAll();
-  }
-
-  /**
-   * Disposal management
-   */
-  get isDisposed(): boolean {
-    return this._lifecycleManager.isDisposed;
-  }
-
-  /**
-   * Atomic state transition for disposal
-   */
-  _atomicStateTransition(
-    expectedState: BlocLifecycleState,
-    newState: BlocLifecycleState,
-  ): StateTransitionResult {
-    return this._lifecycleManager.atomicStateTransition(
-      expectedState,
-      newState,
-    );
-  }
-
-  /**
-   * Dispose the bloc and clean up resources
-   */
-  async dispose(): Promise<void> {
-    const transitionResult = this._lifecycleManager.atomicStateTransition(
-      BlocLifecycleState.ACTIVE,
-      BlocLifecycleState.DISPOSING,
-    );
-
-    if (!transitionResult.success) {
-      if (
-        this._lifecycleManager.currentState ===
-        BlocLifecycleState.DISPOSAL_REQUESTED
-      ) {
-        this._lifecycleManager.atomicStateTransition(
-          BlocLifecycleState.DISPOSAL_REQUESTED,
-          BlocLifecycleState.DISPOSING,
-        );
-      } else {
-        return;
-      }
-    }
-
-    try {
-      // Clear subscriptions
-      this._subscriptionManager.clear();
-
-      // Call disposal hook
-      if (this.onDispose) {
-        this.onDispose();
-      }
-
-      // Notify plugins of disposal
-      for (const plugin of this._plugins.getAll()) {
-        try {
-          if ('onDispose' in plugin && typeof plugin.onDispose === 'function') {
-            plugin.onDispose(this as any);
-          }
-        } catch (error) {
-          console.error('Plugin disposal error:', error);
-        }
-      }
-
-      // Call disposal handler
-      const handler = this._lifecycleManager.getDisposalHandler();
-      if (handler) {
-        handler(this as any);
-      }
-    } finally {
-      this._lifecycleManager.atomicStateTransition(
-        BlocLifecycleState.DISPOSING,
-        BlocLifecycleState.DISPOSED,
-      );
-    }
-  }
-
-  /**
-   * Schedule disposal when no subscriptions remain
-   */
-  _scheduleDisposal(): void {
-    const shouldDispose =
-      this._subscriptionManager.size === 0 && !this._keepAlive;
-
-    if (!shouldDispose) {
-      return;
-    }
-
-    this._lifecycleManager.scheduleDisposal(
-      16,
-      () => this._subscriptionManager.size === 0 && !this._keepAlive,
-      () => this.dispose(),
-    );
-  }
-
-  /**
-   * Set disposal handler
-   */
-  setDisposalHandler(handler: (bloc: BlocBase<unknown>) => void): void {
-    this._lifecycleManager.setDisposalHandler(
-      handler as (bloc: unknown) => void,
-    );
-  }
-
-  /**
-   * Check if disposal should be scheduled (called by subscription manager)
-   */
-  checkDisposal(): void {
-    if (
-      this._subscriptionManager.size === 0 &&
-      !this._keepAlive &&
-      this._lifecycleManager.currentState === BlocLifecycleState.ACTIVE
-    ) {
-      this._scheduleDisposal();
-    }
-  }
-
-  /**
-   * Cancel disposal if bloc is in disposal_requested state
-   */
-  _cancelDisposalIfRequested(): void {
-    this.blacInstance?.log(
-      `[${this._name}:${this._id}] _cancelDisposalIfRequested called. Current state: ${this._lifecycleManager.currentState}`,
-    );
-
-    const success = this._lifecycleManager.cancelDisposal();
-
-    if (success) {
-      this.blacInstance?.log(
-        `[${this._name}:${this._id}] Disposal cancelled - new subscription added`,
-      );
-    } else if (
-      this._lifecycleManager.currentState ===
-      BlocLifecycleState.DISPOSAL_REQUESTED
-    ) {
-      this.blacInstance?.warn(
-        `[${this._name}:${this._id}] Failed to cancel disposal. Current state: ${this._lifecycleManager.currentState}`,
-      );
-    } else if (this._lifecycleManager.isDisposed) {
-      this.blacInstance?.error(
-        `[${this._name}:${this._id}] Cannot cancel disposal - bloc is already disposed`,
-      );
-    }
-  }
-}

package/src/Cubit.ts

@@ -1,68 +0,0 @@
-import { Blac } from './Blac';
-import { BlocBase } from './BlocBase';
-
-/**
- * A Cubit is a simpler version of a Bloc that doesn't handle events.
- * It manages state and provides methods to update it.
- * @template S - The type of state this Cubit manages
- */
-export abstract class Cubit<S> extends BlocBase<S> {
-  /**
-   * Updates the current state and notifies all observers of the change.
-   * If the new state is identical to the current state (using Object.is),
-   * no update will occur.
-   * @param state - The new state to set
-   */
-  emit(state: S): void {
-    if (Object.is(state, this.state)) {
-      return;
-    }
-
-    const oldState = this.state;
-    const newState = state;
-    this._pushState(newState, oldState);
-  }
-
-  /**
-   * Partially updates the current state by merging it with the provided state patch.
-   * This method is only applicable when the state is an object type.
-   *
-   * @param statePatch - A partial state object containing only the properties to update
-   * @param ignoreChangeCheck - If true, skips checking if the state has actually changed
-   * @throws {TypeError} If the state is not an object type
-   */
-  patch(
-    statePatch: S extends object ? Partial<S> : S,
-    ignoreChangeCheck = false,
-  ): void {
-    if (typeof this.state !== 'object' || this.state === null) {
-      Blac.warn(
-        'Cubit.patch: was called on a cubit where the state is not an object. This is a no-op.',
-      );
-      return;
-    }
-
-    let changes = false;
-    if (!ignoreChangeCheck) {
-      for (const key in statePatch) {
-        if (Object.prototype.hasOwnProperty.call(statePatch, key)) {
-          const s = this.state;
-          const current = s[key as keyof S];
-          if (!Object.is(statePatch[key as keyof S], current)) {
-            changes = true;
-            break;
-          }
-        }
-      }
-    } else {
-      changes = true;
-    }
-
-    if (changes) {
-      this.emit({
-        ...this.state,
-        ...(statePatch as Partial<S>),
-      } as S);
-    }
-  }
-}