@blac/core 2.0.0-rc-14 → 2.0.0-rc.0

package/src/errors/ErrorManager.ts

@@ -1,101 +0,0 @@
-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

@@ -1,114 +0,0 @@
-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

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

package/src/index.ts

@@ -1,26 +0,0 @@
-export * from './Blac';
-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';
-
-// Adapter
-export * from './adapter';
-
-// Plugins
-export * from './plugins';
-
-// Error handling
-export * from './errors';

package/src/lifecycle/BlocLifecycle.ts

@@ -1,156 +0,0 @@
-/**
- * Enum representing the lifecycle states of a Bloc instance
- */
-export enum BlocLifecycleState {
-  ACTIVE = 'active',
-  DISPOSAL_REQUESTED = 'disposal_requested',
-  DISPOSING = 'disposing',
-  DISPOSED = 'disposed',
-}
-
-export interface StateTransitionResult {
-  success: boolean;
-  currentState: BlocLifecycleState;
-  previousState: BlocLifecycleState;
-}
-
-/**
- * Manages the lifecycle state transitions for Bloc instances.
- * Ensures atomic state transitions to prevent race conditions during disposal.
- */
-export class BlocLifecycleManager {
-  private disposalState = BlocLifecycleState.ACTIVE;
-  private disposalLock = false;
-  private disposalTimer?: NodeJS.Timeout | number;
-  private disposalHandler?: (bloc: unknown) => void;
-
-  get currentState(): BlocLifecycleState {
-    return this.disposalState;
-  }
-
-  get isDisposed(): boolean {
-    return this.disposalState === BlocLifecycleState.DISPOSED;
-  }
-
-  /**
-   * Atomic state transition for disposal
-   */
-  atomicStateTransition(
-    expectedState: BlocLifecycleState,
-    newState: BlocLifecycleState,
-  ): StateTransitionResult {
-    if (this.disposalLock) {
-      return {
-        success: false,
-        currentState: this.disposalState,
-        previousState: this.disposalState,
-      };
-    }
-
-    this.disposalLock = true;
-    try {
-      if (this.disposalState !== expectedState) {
-        return {
-          success: false,
-          currentState: this.disposalState,
-          previousState: this.disposalState,
-        };
-      }
-
-      const previousState = this.disposalState;
-      this.disposalState = newState;
-
-      return {
-        success: true,
-        currentState: newState,
-        previousState,
-      };
-    } finally {
-      this.disposalLock = false;
-    }
-  }
-
-  /**
-   * Schedule disposal after a delay
-   */
-  scheduleDisposal(
-    delay: number,
-    canDispose: () => boolean,
-    onDispose: () => void,
-  ): void {
-    // Cancel any existing disposal timer
-    if (this.disposalTimer) {
-      clearTimeout(this.disposalTimer as NodeJS.Timeout);
-      this.disposalTimer = undefined;
-    }
-
-    const transitionResult = this.atomicStateTransition(
-      BlocLifecycleState.ACTIVE,
-      BlocLifecycleState.DISPOSAL_REQUESTED,
-    );
-
-    if (!transitionResult.success) {
-      return;
-    }
-
-    this.disposalTimer = setTimeout(() => {
-      if (
-        canDispose() &&
-        this.disposalState === BlocLifecycleState.DISPOSAL_REQUESTED
-      ) {
-        onDispose();
-      } else {
-        this.atomicStateTransition(
-          BlocLifecycleState.DISPOSAL_REQUESTED,
-          BlocLifecycleState.ACTIVE,
-        );
-      }
-    }, delay);
-  }
-
-  /**
-   * Cancel disposal if in disposal requested state
-   */
-  cancelDisposal(): boolean {
-    if (this.disposalState === BlocLifecycleState.DISPOSAL_REQUESTED) {
-      // Cancel disposal timer
-      if (this.disposalTimer) {
-        clearTimeout(this.disposalTimer as NodeJS.Timeout);
-        this.disposalTimer = undefined;
-      }
-
-      // Transition back to active state
-      const result = this.atomicStateTransition(
-        BlocLifecycleState.DISPOSAL_REQUESTED,
-        BlocLifecycleState.ACTIVE,
-      );
-
-      return result.success;
-    }
-    return false;
-  }
-
-  /**
-   * Set disposal handler
-   */
-  setDisposalHandler(handler: (bloc: unknown) => void): void {
-    this.disposalHandler = handler;
-  }
-
-  /**
-   * Get disposal handler
-   */
-  getDisposalHandler(): ((bloc: unknown) => void) | undefined {
-    return this.disposalHandler;
-  }
-
-  /**
-   * Clear disposal timer
-   */
-  clearDisposalTimer(): void {
-    if (this.disposalTimer) {
-      clearTimeout(this.disposalTimer as NodeJS.Timeout);
-      this.disposalTimer = undefined;
-    }
-  }
-}

package/src/lifecycle/index.ts

@@ -1 +0,0 @@
-export * from './BlocLifecycle';

package/src/plugins/BlocPluginRegistry.ts

@@ -1,240 +0,0 @@
-import { BlocPlugin, PluginRegistry, ErrorContext } from './types';
-import { handleError } from '../errors/handleError';
-import { ErrorCategory } from '../errors/BlacError';
-
-/**
- * Registry for bloc-specific plugins
- */
-export class BlocPluginRegistry<TState, TEvent = never>
-  implements PluginRegistry<BlocPlugin<TState, TEvent>>
-{
-  private plugins = new Map<string, BlocPlugin<TState, TEvent>>();
-  private executionOrder: string[] = [];
-  private attached = false;
-
-  /**
-   * Add a bloc plugin
-   */
-  add(plugin: BlocPlugin<TState, TEvent>): void {
-    if (this.plugins.has(plugin.name)) {
-      throw new Error(`Plugin '${plugin.name}' is already registered`);
-    }
-
-    // Validate capabilities
-    if (plugin.capabilities) {
-      this.validateCapabilities(plugin);
-    }
-
-    this.plugins.set(plugin.name, plugin);
-    this.executionOrder.push(plugin.name);
-  }
-
-  /**
-   * Remove a bloc plugin
-   */
-  remove(pluginName: string): boolean {
-    const plugin = this.plugins.get(pluginName);
-    if (!plugin) return false;
-
-    // Call onDetach if attached
-    if (this.attached && plugin.onDetach) {
-      handleError.wrap(() => plugin.onDetach!(), ErrorCategory.PLUGIN, {
-        pluginName,
-        operation: 'onDetach',
-      });
-    }
-
-    this.plugins.delete(pluginName);
-    this.executionOrder = this.executionOrder.filter(
-      (name) => name !== pluginName,
-    );
-
-    return true;
-  }
-
-  /**
-   * Get a plugin by name
-   */
-  get(pluginName: string): BlocPlugin<TState, TEvent> | undefined {
-    return this.plugins.get(pluginName);
-  }
-
-  /**
-   * Get all plugins in execution order
-   */
-  getAll(): ReadonlyArray<BlocPlugin<TState, TEvent>> {
-    return this.executionOrder.map((name) => this.plugins.get(name)!);
-  }
-
-  /**
-   * Clear all plugins
-   */
-  clear(): void {
-    // Detach all plugins first
-    if (this.attached) {
-      for (const plugin of this.getAll()) {
-        if (plugin.onDetach) {
-          handleError.wrap(() => plugin.onDetach!(), ErrorCategory.PLUGIN, {
-            pluginName: plugin.name,
-            operation: 'onDetach',
-          });
-        }
-      }
-    }
-
-    this.plugins.clear();
-    this.executionOrder = [];
-    this.attached = false;
-  }
-
-  /**
-   * Attach all plugins to a bloc
-   */
-  attach(bloc: any): void {
-    if (this.attached) {
-      throw new Error('Plugins are already attached');
-    }
-
-    for (const plugin of this.getAll()) {
-      if (plugin.onAttach) {
-        try {
-          plugin.onAttach(bloc);
-        } catch (error) {
-          console.error(`Plugin '${plugin.name}' error in onAttach:`, error);
-          // Remove failing plugin
-          this.remove(plugin.name);
-        }
-      }
-    }
-
-    this.attached = true;
-  }
-
-  /**
-   * Transform state through all plugins
-   */
-  transformState(previousState: TState, nextState: TState): TState {
-    let transformedState = nextState;
-
-    for (const plugin of this.getAll()) {
-      if (plugin.transformState && this.canTransformState(plugin)) {
-        try {
-          transformedState = plugin.transformState(
-            previousState,
-            transformedState,
-          );
-        } catch (error) {
-          console.error(
-            `Plugin '${plugin.name}' error in transformState:`,
-            error,
-          );
-          // Continue with untransformed state
-        }
-      }
-    }
-
-    return transformedState;
-  }
-
-  /**
-   * Transform event through all plugins
-   */
-  transformEvent(event: TEvent): TEvent | null {
-    let transformedEvent: TEvent | null = event;
-
-    for (const plugin of this.getAll()) {
-      if (transformedEvent === null) break;
-
-      if (plugin.transformEvent && this.canInterceptEvents(plugin)) {
-        try {
-          transformedEvent = plugin.transformEvent(transformedEvent);
-        } catch (error) {
-          console.error(
-            `Plugin '${plugin.name}' error in transformEvent:`,
-            error,
-          );
-          // Continue with untransformed event
-        }
-      }
-    }
-
-    return transformedEvent;
-  }
-
-  /**
-   * Notify plugins of state change
-   */
-  notifyStateChange(previousState: TState, currentState: TState): void {
-    for (const plugin of this.getAll()) {
-      if (plugin.onStateChange && this.canReadState(plugin)) {
-        try {
-          plugin.onStateChange(previousState, currentState);
-        } catch (error) {
-          console.error(
-            `Plugin '${plugin.name}' error in onStateChange:`,
-            error,
-          );
-        }
-      }
-    }
-  }
-
-  /**
-   * Notify plugins of event
-   */
-  notifyEvent(event: TEvent): void {
-    for (const plugin of this.getAll()) {
-      if (plugin.onEvent && this.canReadState(plugin)) {
-        try {
-          plugin.onEvent(event);
-        } catch (error) {
-          console.error(`Plugin '${plugin.name}' error in onEvent:`, error);
-        }
-      }
-    }
-  }
-
-  /**
-   * Notify plugins of error
-   */
-  notifyError(error: Error, context: ErrorContext): void {
-    for (const plugin of this.getAll()) {
-      if (plugin.onError) {
-        try {
-          plugin.onError(error, context);
-        } catch (hookError) {
-          console.error(`Plugin '${plugin.name}' error in onError:`, hookError);
-        }
-      }
-    }
-  }
-
-  private validateCapabilities(plugin: BlocPlugin<TState, TEvent>): void {
-    const caps = plugin.capabilities!;
-
-    // Validate logical constraints
-    if (caps.transformState && !caps.readState) {
-      throw new Error(
-        `Plugin '${plugin.name}': transformState requires readState capability`,
-      );
-    }
-
-    if (caps.interceptEvents && !caps.readState) {
-      throw new Error(
-        `Plugin '${plugin.name}': interceptEvents requires readState capability`,
-      );
-    }
-  }
-
-  private canReadState(plugin: BlocPlugin<TState, TEvent>): boolean {
-    return !plugin.capabilities || plugin.capabilities.readState !== false;
-  }
-
-  private canTransformState(plugin: BlocPlugin<TState, TEvent>): boolean {
-    return !plugin.capabilities || plugin.capabilities.transformState === true;
-  }
-
-  private canInterceptEvents(plugin: BlocPlugin<TState, TEvent>): boolean {
-    return !plugin.capabilities || plugin.capabilities.interceptEvents === true;
-  }
-}