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

package/dist/index.d.ts

@@ -1,3 +1,9 @@
+import { BlacPlugin as BlacPlugin_2 } from '../core/types';
+import { BlocPlugin as BlocPlugin_2 } from '../core/types';
+import { ErrorContext as ErrorContext_2 } from '../core/types';
+import { PluginMetrics as PluginMetrics_2 } from '../core/types';
+import { PluginRegistry as PluginRegistry_2 } from '../core/types';
+
 export declare interface AdapterOptions<B extends BlocBase<any>> {
     id?: string;
     dependencies?: (bloc: B) => unknown[];
@@ -45,6 +51,8 @@ export declare class Blac {
     keepAliveBlocs: Set<BlocBase<unknown>>;
     /** Flag to control whether changes should be posted to document */
     postChangesToDocument: boolean;
+    /** System plugin registry */
+    readonly plugins: SystemPluginRegistry;
     /**
      * Creates a new Blac instance.
      * @param options - Configuration options including singleton control
@@ -221,6 +229,14 @@ export declare class Blac {
      */
     validateConsumers: () => void;
     static get validateConsumers(): () => void;
+    /**
+     * Bootstrap the Blac instance and all plugins
+     */
+    bootstrap(): void;
+    /**
+     * Shutdown the Blac instance and all plugins
+     */
+    shutdown(): void;
 }
 
 /**
@@ -361,6 +377,21 @@ export declare type BlacObserver<S> = {
     id: string;
 };
 
+/**
+ * System-wide plugin that observes all blocs
+ */
+export declare interface BlacPlugin extends Plugin_2 {
+    beforeBootstrap?(): void;
+    afterBootstrap?(): void;
+    beforeShutdown?(): void;
+    afterShutdown?(): void;
+    onBlocCreated?(bloc: BlocBase<any>): void;
+    onBlocDisposed?(bloc: BlocBase<any>): void;
+    onStateChanged?(bloc: BlocBase<any>, previousState: any, currentState: any): void;
+    onEventAdded?(bloc: Bloc<any, any>, event: any): void;
+    onError?(error: Error, bloc: BlocBase<unknown>, context: ErrorContext): void;
+}
+
 export declare abstract class Bloc<S, // State type
 A extends BlocEventConstraint = BlocEventConstraint, // Base Action/Event type with proper constraints
 P = unknown> extends BlocBase<S, P> {
@@ -440,6 +471,10 @@ export declare abstract class BlocBase<S, P = unknown> {
     /* Excluded from this release type: _batchingLock */
     /* Excluded from this release type: _pendingUpdates */
     /* Excluded from this release type: _consumerRefs */
+    /**
+     * Plugin registry for this bloc instance
+     */
+    protected _plugins: BlocPluginRegistry<S, any>;
     /* Excluded from this release type: _validateConsumers */
     /**
      * Creates a new BlocBase instance with the given initial state.
@@ -473,11 +508,29 @@ export declare abstract class BlocBase<S, P = unknown> {
     lastUpdate: number;
     /* Excluded from this release type: _batchingEnabled */
     /* Excluded from this release type: _pushState */
+    /* Excluded from this release type: _notifyObservers */
     /**
      * Enables batching for multiple state updates
      * @param batchFn Function to execute with batching enabled
      */
     batch: <T>(batchFn: () => T) => T;
+    /**
+     * Add a plugin to this bloc instance
+     */
+    addPlugin(plugin: BlocPlugin<S, any>): void;
+    /**
+     * Remove a plugin from this bloc instance
+     */
+    removePlugin(pluginName: string): boolean;
+    /**
+     * Get a plugin by name
+     */
+    getPlugin(pluginName: string): BlocPlugin<S, any> | undefined;
+    /**
+     * Get all plugins
+     */
+    getPlugins(): ReadonlyArray<BlocPlugin<S, any>>;
+    /* Excluded from this release type: _activatePlugins */
 }
 
 /**
@@ -547,6 +600,76 @@ export declare enum BlocLifecycleState {
     DISPOSED = "disposed"
 }
 
+/**
+ * Bloc-specific plugin that can transform behavior
+ */
+export declare interface BlocPlugin<TState = any, TEvent = never> extends Plugin_2 {
+    transformState?(previousState: TState, nextState: TState): TState;
+    transformEvent?(event: TEvent): TEvent | null;
+    onAttach?(bloc: BlocBase<TState, any>): void;
+    onDetach?(): void;
+    onStateChange?(previousState: TState, currentState: TState): void;
+    onEvent?(event: TEvent): void;
+    onError?(error: Error, context: ErrorContext): void;
+}
+
+/**
+ * Registry for bloc-specific plugins
+ */
+export declare class BlocPluginRegistry<TState, TEvent = never> implements PluginRegistry_2<BlocPlugin_2<TState, TEvent>> {
+    private plugins;
+    private executionOrder;
+    private attached;
+    /**
+     * Add a bloc plugin
+     */
+    add(plugin: BlocPlugin_2<TState, TEvent>): void;
+    /**
+     * Remove a bloc plugin
+     */
+    remove(pluginName: string): boolean;
+    /**
+     * Get a plugin by name
+     */
+    get(pluginName: string): BlocPlugin_2<TState, TEvent> | undefined;
+    /**
+     * Get all plugins in execution order
+     */
+    getAll(): ReadonlyArray<BlocPlugin_2<TState, TEvent>>;
+    /**
+     * Clear all plugins
+     */
+    clear(): void;
+    /**
+     * Attach all plugins to a bloc
+     */
+    attach(bloc: any): void;
+    /**
+     * Transform state through all plugins
+     */
+    transformState(previousState: TState, nextState: TState): TState;
+    /**
+     * Transform event through all plugins
+     */
+    transformEvent(event: TEvent): TEvent | null;
+    /**
+     * Notify plugins of state change
+     */
+    notifyStateChange(previousState: TState, currentState: TState): void;
+    /**
+     * Notify plugins of event
+     */
+    notifyEvent(event: TEvent): void;
+    /**
+     * Notify plugins of error
+     */
+    notifyError(error: Error, context: ErrorContext_2): void;
+    private validateCapabilities;
+    private canReadState;
+    private canTransformState;
+    private canInterceptEvents;
+}
+
 /**
  * Extracts the state type from either a Bloc or Cubit
  * @template T - The Bloc or Cubit type to extract the state from
@@ -660,6 +783,15 @@ export declare interface DependencyArray {
 
 declare type DependencySelector<S> = (currentState: S, previousState: S | undefined, instance: any) => unknown[];
 
+/**
+ * Error context provided to error handlers
+ */
+export declare interface ErrorContext {
+    readonly phase: 'initialization' | 'state-change' | 'event-processing' | 'disposal';
+    readonly operation: string;
+    readonly metadata?: Record<string, unknown>;
+}
+
 /**
  * Cross-platform UUID v4 generator that works in all environments including React Native/Hermes
  * Falls back to crypto.randomUUID() when available, otherwise uses Math.random()
@@ -743,6 +875,60 @@ export declare class MockCubit<S> extends Cubit<S> {
     clearStateHistory(): void;
 }
 
+/**
+ * Base interface for all plugins
+ */
+declare interface Plugin_2 {
+    readonly name: string;
+    readonly version: string;
+    readonly capabilities?: PluginCapabilities;
+}
+export { Plugin_2 as Plugin }
+
+/**
+ * Plugin capabilities for security model
+ */
+export declare interface PluginCapabilities {
+    readonly readState: boolean;
+    readonly transformState: boolean;
+    readonly interceptEvents: boolean;
+    readonly persistData: boolean;
+    readonly accessMetadata: boolean;
+}
+
+/**
+ * Plugin execution context for performance monitoring
+ */
+export declare interface PluginExecutionContext {
+    readonly pluginName: string;
+    readonly hookName: string;
+    readonly startTime: number;
+    readonly blocName?: string;
+    readonly blocId?: string;
+}
+
+/**
+ * Plugin metrics for monitoring
+ */
+export declare interface PluginMetrics {
+    readonly executionTime: number;
+    readonly executionCount: number;
+    readonly errorCount: number;
+    readonly lastError?: Error;
+    readonly lastExecutionTime?: number;
+}
+
+/**
+ * Plugin registry interface
+ */
+export declare interface PluginRegistry<T extends Plugin_2> {
+    add(plugin: T): void;
+    remove(pluginName: string): boolean;
+    get(pluginName: string): T | undefined;
+    getAll(): ReadonlyArray<T>;
+    clear(): void;
+}
+
 export declare class PropsUpdated<P = any> {
     readonly props: P;
     constructor(props: P);
@@ -810,6 +996,74 @@ export declare interface StateTransitionResult {
     previousState: BlocLifecycleState;
 }
 
+/**
+ * Registry for system-wide plugins
+ */
+export declare class SystemPluginRegistry implements PluginRegistry_2<BlacPlugin_2> {
+    private plugins;
+    private metrics;
+    private executionOrder;
+    /**
+     * Add a system plugin
+     */
+    add(plugin: BlacPlugin_2): void;
+    /**
+     * Remove a system plugin
+     */
+    remove(pluginName: string): boolean;
+    /**
+     * Get a plugin by name
+     */
+    get(pluginName: string): BlacPlugin_2 | undefined;
+    /**
+     * Get all plugins in execution order
+     */
+    getAll(): ReadonlyArray<BlacPlugin_2>;
+    /**
+     * Clear all plugins
+     */
+    clear(): void;
+    /**
+     * Execute a hook on all plugins
+     */
+    executeHook(hookName: keyof BlacPlugin_2, args: unknown[], errorHandler?: (error: Error, plugin: BlacPlugin_2) => void): void;
+    /**
+     * Bootstrap all plugins
+     */
+    bootstrap(): void;
+    /**
+     * Shutdown all plugins
+     */
+    shutdown(): void;
+    /**
+     * Notify plugins of bloc creation
+     */
+    notifyBlocCreated(bloc: BlocBase<any>): void;
+    /**
+     * Notify plugins of bloc disposal
+     */
+    notifyBlocDisposed(bloc: BlocBase<any>): void;
+    /**
+     * Notify plugins of state change
+     */
+    notifyStateChanged(bloc: BlocBase<any>, previousState: any, currentState: any): void;
+    /**
+     * Notify plugins of event addition
+     */
+    notifyEventAdded(bloc: Bloc<any, any>, event: any): void;
+    /**
+     * Notify plugins of errors
+     */
+    notifyError(error: Error, bloc: BlocBase<unknown>, context: ErrorContext_2): void;
+    /**
+     * Get metrics for a plugin
+     */
+    getMetrics(pluginName: string): Map<string, PluginMetrics_2> | undefined;
+    private initializeMetrics;
+    private recordSuccess;
+    private recordError;
+}
+
 export declare interface TrackedValue {
     value: any;
     lastAccessTime: number;