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

package/dist/index.d.ts

@@ -1,7 +1,13 @@
+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[];
-    props?: InferPropsFromGeneric<B>;
+    props?: any;
     onMount?: (bloc: B) => void;
     onUnmount?: (bloc: B) => void;
 }
@@ -23,6 +29,16 @@ export declare class Blac {
     static get getAllBlocs(): <B extends BlocConstructor<any>>(blocClass: B, options?: {
         searchIsolated?: boolean;
     }) => InstanceType<B>[];
+    /** Private static configuration */
+    private static _config;
+    /** Get current configuration */
+    static get config(): Readonly<BlacConfig>;
+    /**
+     * Set or update Blac configuration
+     * @param config - Partial configuration to merge with existing config
+     * @throws Error if configuration is invalid
+     */
+    static setConfig(config: Partial<BlacConfig>): void;
     /** Map storing all registered bloc instances by their class name and ID */
     blocInstanceMap: Map<string, BlocBase<unknown>>;
     /** Map storing isolated bloc instances grouped by their constructor */
@@ -35,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
@@ -211,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;
 }
 
 /**
@@ -225,6 +251,8 @@ export declare class BlacAdapter<B extends BlocConstructor<BlocBase<any>>> {
     };
     blocInstance: InstanceType<B>;
     private consumerTracker;
+    private static propsOwners;
+    private lastProps?;
     unmountTime: number;
     mountTime: number;
     private dependencyValues?;
@@ -258,6 +286,7 @@ export declare class BlacAdapter<B extends BlocConstructor<BlocBase<any>>> {
     getProxyState: (state: BlocState<InstanceType<B>>) => BlocState<InstanceType<B>>;
     getProxyBlocInstance: () => InstanceType<B>;
     get calledOnMount(): boolean;
+    updateProps(props: any): void;
     private hasDependencyValuesChanged;
 }
 
@@ -267,6 +296,12 @@ export declare class BlacAdapter<B extends BlocConstructor<BlocBase<any>>> {
 export declare interface BlacConfig {
     /** Whether to expose the Blac instance globally */
     exposeBlacInstance?: boolean;
+    /**
+     * Whether to enable proxy dependency tracking for automatic re-render optimization.
+     * When false, state changes always cause re-renders unless dependencies are manually specified.
+     * Default: true
+     */
+    proxyDependencyTracking?: boolean;
 }
 
 /**
@@ -342,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> {
@@ -421,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.
@@ -454,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 */
 }
 
 /**
@@ -498,19 +570,10 @@ export declare interface BlocErrorBoundary<S, A extends BlocEventConstraint> {
     shouldRethrow?: (error: Error, event: A) => boolean;
 }
 
-/**
- * Base interface for all Bloc events
- * Events must be objects with a constructor to enable proper type matching
- */
-export declare interface BlocEvent {
-    readonly type?: string;
-    readonly timestamp?: number;
-}
-
 /**
  * Enhanced constraint for Bloc events - must be objects with proper constructor
  */
-export declare type BlocEventConstraint = BlocEvent & object;
+export declare type BlocEventConstraint = object;
 
 /**
  * Function type for determining dependencies that trigger re-renders
@@ -537,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
@@ -620,6 +753,11 @@ declare interface ConsumerTracker_2 {
  * @template P - The type of parameters (optional, defaults to null)
  */
 export declare abstract class Cubit<S, P = null> extends BlocBase<S, P> {
+    /* Excluded from this release type: _updateProps */
+    /**
+     * Optional override for props handling
+     */
+    protected onPropsChanged?(oldProps: P | undefined, newProps: P): void;
     /**
      * Updates the current state and notifies all observers of the change.
      * If the new state is identical to the current state (using Object.is),
@@ -645,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()
@@ -728,6 +875,65 @@ 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);
+}
+
 export declare class ProxyFactory {
     static createStateProxy<T extends object>(options: {
         target: T;
@@ -772,6 +978,15 @@ export declare class ProxyFactory {
  */
 export declare function setBlacInstanceManager(manager: BlacInstanceManager): void;
 
+/**
+ * Performs a shallow equality comparison between two values.
+ * For objects, it checks if all top-level properties are equal using Object.is.
+ * @param a First value to compare
+ * @param b Second value to compare
+ * @returns true if values are shallowly equal, false otherwise
+ */
+export declare function shallowEqual(a: any, b: any): boolean;
+
 /**
  * Result of an atomic state transition operation
  */
@@ -781,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;