@blac/core 2.0.0-rc-14 → 2.0.0-rc-16

package/dist/index.d.ts

@@ -1,1303 +0,0 @@
-/**
- * Adapter metadata provided to plugins
- */
-export declare interface AdapterMetadata {
-    componentName?: string;
-    blocInstance: BlocBase<any>;
-    renderCount: number;
-    trackedPaths?: string[];
-    isUsingDependencies?: boolean;
-    lastState?: any;
-    lastDependencyValues?: any[];
-    currentDependencyValues?: any[];
-}
-
-export declare interface AdapterOptions<B extends BlocBase<any>> {
-    instanceId?: string;
-    dependencies?: (bloc: B) => unknown[];
-    staticProps?: any;
-    onMount?: (bloc: B) => void;
-    onUnmount?: (bloc: B) => void;
-}
-
-/**
- * Main Blac class that manages the state management system.
- * Can work with singleton pattern or dependency injection.
- * Handles bloc lifecycle, and instance tracking.
- *
- * Key responsibilities:
- * - Managing bloc instances (creation, disposal, lookup)
- * - Handling isolated and non-isolated blocs
- * - Providing logging and debugging capabilities
- */
-export declare class Blac {
-    static get instance(): Blac;
-    /** Timestamp when the instance was created */
-    createdAt: number;
-    private errorManager;
-    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 */
-    isolatedBlocMap: Map<BlocConstructor<any>, BlocBase<unknown>[]>;
-    /** Map for O(1) lookup of isolated blocs by UID */
-    isolatedBlocIndex: Map<string, BlocBase<unknown>>;
-    /** Map tracking UIDs to prevent memory leaks */
-    uidRegistry: Map<string, BlocBase<unknown>>;
-    /** Set of keep-alive blocs for controlled cleanup */
-    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
-     */
-    constructor(options?: {
-        __unsafe_ignore_singleton?: boolean;
-    });
-    /** Flag to enable/disable logging */
-    static enableLog: boolean;
-    static logLevel: 'warn' | 'log';
-    static logSpy: ((...args: unknown[]) => void) | null;
-    /**
-     * Logs messages to console when logging is enabled
-     * @param args - Arguments to log
-     */
-    log: (...args: unknown[]) => void;
-    static get log(): (...args: unknown[]) => void;
-    /**
-     * Gets the current Blac instance
-     * @returns The Blac instance
-     */
-    static getInstance(): Blac;
-    /**
-     * Logs a warning message
-     * @param message - Warning message
-     * @param args - Additional arguments
-     */
-    warn: (message: string, ...args: unknown[]) => void;
-    static get warn(): (message: string, ...args: unknown[]) => void;
-    /**
-     * Logs an error message
-     * @param message - Error message
-     * @param args - Additional arguments
-     */
-    error: (message: string, ...args: unknown[]) => void;
-    static get error(): (message: string, ...args: unknown[]) => void;
-    /**
-     * Resets the Blac instance to a new one, disposing non-keepAlive blocs
-     * from the old instance.
-     */
-    resetInstance: () => void;
-    static resetInstance: () => void;
-    /**
-     * Disposes of a bloc instance by removing it from the appropriate registry
-     * @param bloc - The bloc instance to dispose
-     */
-    disposeBloc: (bloc: BlocBase<unknown>) => void;
-    static get disposeBloc(): (bloc: BlocBase<unknown>) => void;
-    /**
-     * Creates a unique key for a bloc instance in the map based on the bloc class name and instance ID
-     * @param blocClassName - The name of the bloc class
-     * @param id - The instance ID
-     * @returns A unique key string in the format "className:id"
-     */
-    createBlocInstanceMapKey(blocClassName: string, id: BlocInstanceId): string;
-    /**
-     * Unregister a bloc instance from the main registry
-     * @param bloc - The bloc instance to unregister
-     */
-    unregisterBlocInstance(bloc: BlocBase<unknown>): void;
-    /**
-     * Registers a bloc instance in the main registry
-     * @param bloc - The bloc instance to register
-     */
-    registerBlocInstance(bloc: BlocBase<unknown>): void;
-    /**
-     * Finds a registered bloc instance by its class and ID
-     * @param blocClass - The bloc class to search for
-     * @param id - The instance ID
-     * @returns The found bloc instance or undefined if not found
-     */
-    findRegisteredBlocInstance<B extends BlocConstructor<any>>(blocClass: B, id: BlocInstanceId): InstanceType<B> | undefined;
-    /**
-     * Registers an isolated bloc instance in the isolated registry
-     * @param bloc - The isolated bloc instance to register
-     */
-    registerIsolatedBlocInstance(bloc: BlocBase<unknown>): void;
-    /**
-     * Unregister an isolated bloc instance from the isolated registry
-     * @param bloc - The isolated bloc instance to unregister
-     */
-    unregisterIsolatedBlocInstance(bloc: BlocBase<unknown>): void;
-    /**
-     * Finds an isolated bloc instance by its class and ID (O(n) lookup)
-     */
-    findIsolatedBlocInstance<B extends BlocConstructor<any>>(blocClass: B, id: BlocInstanceId): InstanceType<B> | undefined;
-    /**
-     * Finds an isolated bloc instance by UID (O(1) lookup)
-     */
-    findIsolatedBlocInstanceByUid<B extends BlocBase<unknown>>(uid: string): B | undefined;
-    /**
-     * Creates a new bloc instance and registers it in the appropriate registry
-     * @param blocClass - The bloc class to instantiate
-     * @param id - The instance ID
-     * @param props - Properties to pass to the bloc constructor
-     * @param instanceRef - Optional reference string for the instance
-     * @returns The newly created bloc instance
-     */
-    createNewBlocInstance<B extends BlocConstructor<BlocBase<any>>>(blocClass: B, id: BlocInstanceId, options?: GetBlocOptions<InstanceType<B>>): InstanceType<B>;
-    activateBloc: (bloc: BlocBase<unknown>) => void;
-    static get activateBloc(): (bloc: BlocBase<unknown>) => void;
-    /**
-     * Gets or creates a bloc instance based on the provided class and options.
-     * If a bloc with the given ID exists, it will be returned. Otherwise, a new instance will be created.
-     *
-     * @param blocClass - The bloc class to get or create
-     * @param options - Options including:
-     *   - id: The instance ID (defaults to class name if not provided)
-     *   - props: Properties to pass to the bloc constructor
-     *   - instanceRef: Optional reference string for the instance
-     * @returns The bloc instance
-     */
-    getBloc: <B extends BlocConstructor<BlocBase<any>>>(blocClass: B, options?: GetBlocOptions<InstanceType<B>>) => InstanceType<B>;
-    static get getBloc(): <B extends BlocConstructor<BlocBase<any>>>(blocClass: B, options?: GetBlocOptions<InstanceType<B>>) => InstanceType<B>;
-    /**
-     * Gets all instances of a specific bloc class
-     * @param blocClass - The bloc class to search for
-     * @param options - Options including:
-     *   - searchIsolated: Whether to search in isolated blocs (defaults to bloc's isolated property)
-     * @returns Array of matching bloc instances
-     */
-    getAllBlocs: <B extends BlocConstructor<any>>(blocClass: B, options?: {
-        searchIsolated?: boolean;
-    }) => InstanceType<B>[];
-    /**
-     * Disposes all keep-alive blocs of a specific type
-     * @param blocClass - The bloc class to dispose
-     */
-    disposeKeepAliveBlocs: <B extends BlocConstructor<any>>(blocClass?: B) => void;
-    static get disposeKeepAliveBlocs(): <B extends BlocConstructor<any>>(blocClass?: B | undefined) => void;
-    /**
-     * Disposes all blocs matching a pattern
-     * @param predicate - Function to test each bloc for disposal
-     */
-    disposeBlocs: (predicate: (bloc: BlocBase<unknown>) => boolean) => void;
-    static get disposeBlocs(): (predicate: (bloc: BlocBase<unknown>) => boolean) => void;
-    /**
-     * Gets memory usage statistics for debugging
-     */
-    getMemoryStats: () => {
-        totalBlocs: number;
-        registeredBlocs: number;
-        isolatedBlocs: number;
-        keepAliveBlocs: number;
-        isolatedBlocTypes: number;
-    };
-    static get getMemoryStats(): () => {
-        totalBlocs: number;
-        registeredBlocs: number;
-        isolatedBlocs: number;
-        keepAliveBlocs: number;
-        isolatedBlocTypes: number;
-    };
-    /**
-     * Validates subscription references and cleans up orphaned blocs
-     */
-    validateConsumers: () => void;
-    static get validateConsumers(): () => void;
-    /**
-     * Bootstrap the Blac instance and all plugins
-     */
-    bootstrap(): void;
-    /**
-     * Shutdown the Blac instance and all plugins
-     */
-    shutdown(): void;
-}
-
-/**
- * BlacAdapter orchestrates the connection between Bloc instances and React components.
- * It manages dependency tracking, lifecycle hooks, and proxy creation.
- */
-export declare class BlacAdapter<B extends BlocConstructor<BlocBase<any>>> {
-    readonly id: string;
-    readonly blocConstructor: B;
-    readonly componentRef: {
-        current: object;
-    };
-    blocInstance: InstanceType<B>;
-    unmountTime: number;
-    mountTime: number;
-    private subscriptionId?;
-    private unsubscribe?;
-    private dependencyValues?;
-    private isUsingDependencies;
-    private trackedPaths;
-    private pendingTrackedPaths;
-    private cachedStateProxy?;
-    private cachedBlocProxy?;
-    private lastProxiedState?;
-    private hasMounted;
-    private mountCount;
-    private lastState?;
-    private lastDependencyValues?;
-    private componentName?;
-    private renderCount;
-    private lastDependenciesFn?;
-    options?: AdapterOptions<InstanceType<B>>;
-    constructor(instanceProps: {
-        componentRef: {
-            current: object;
-        };
-        blocConstructor: B;
-    }, options?: typeof BlacAdapter.options);
-    trackAccess(consumerRef: object, type: 'state' | 'class', path: string, value?: any): void;
-    updateBlocInstance(): InstanceType<B>;
-    createSubscription: (options: {
-        onChange: () => void;
-    }) => () => void;
-    hasDependencyValuesChanged: (oldValues: unknown[] | undefined, newValues: unknown[]) => boolean;
-    getStateProxy: () => BlocState<InstanceType<B>>;
-    getBlocProxy: () => InstanceType<B>;
-    createStateProxy: <T extends object>(props: {
-        target: T;
-    }) => T;
-    createClassProxy: <T extends object>(props: {
-        target: T;
-    }) => T;
-    mount: () => void;
-    unmount: () => void;
-    resetTracking(): void;
-    setComponentName(name: string): void;
-    notifyRender(): void;
-    private getAdapterMetadata;
-    private getValueAtPath;
-    private getStateChangedPaths;
-    private getDeepChangedPaths;
-    getLastRerenderReason(): any;
-}
-
-/**
- * Configuration options for the Blac instance
- */
-export declare interface BlacConfig {
-    /**
-     * 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;
-}
-
-export declare class BlacError extends Error {
-    readonly category: ErrorCategory;
-    readonly severity: ErrorSeverity;
-    readonly context?: BlacErrorContext | undefined;
-    readonly cause?: unknown | undefined;
-    constructor(message: string, category: ErrorCategory, severity: ErrorSeverity, context?: BlacErrorContext | undefined, cause?: unknown | undefined);
-    toString(): string;
-}
-
-export declare type BlacErrorContext = {
-    blocName?: string;
-    blocId?: string;
-    consumerId?: string;
-    pluginName?: string;
-    operation?: string;
-    metadata?: Record<string, unknown>;
-};
-
-/**
- * Interface for Blac instance management
- */
-export declare interface BlacInstanceManager {
-    getInstance(): Blac;
-    setInstance(instance: Blac): void;
-    resetInstance(): void;
-}
-
-/**
- * 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;
-    onAdapterCreated?(adapter: any, metadata: AdapterMetadata): void;
-    onAdapterMount?(adapter: any, metadata: AdapterMetadata): void;
-    onAdapterUnmount?(adapter: any, metadata: AdapterMetadata): void;
-    onAdapterRender?(adapter: any, metadata: AdapterMetadata): void;
-    onAdapterDisposed?(adapter: any, metadata: AdapterMetadata): void;
-}
-
-export declare abstract class Bloc<S, // State type
-A extends BlocEventConstraint = BlocEventConstraint> extends BlocBase<S> {
-    readonly eventHandlers: Map<new (...args: any[]) => A, (event: A, emit: (newState: S) => void) => void | Promise<void>>;
-    /* Excluded from this release type: _eventQueue */
-    /* Excluded from this release type: _isProcessingEvent */
-    /**
-     * 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;
-    /**
-     * 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.
-     */
-    add: (action: A) => Promise<void>;
-    /* Excluded from this release type: _processEventQueue */
-    /* Excluded from this release type: _processEvent */
-}
-
-/**
- * Base class for both Blocs and Cubits using unified subscription model.
- */
-export declare abstract class BlocBase<S> {
-    uid: string;
-    blacInstance?: Blac;
-    static isolated: boolean;
-    get isIsolated(): boolean;
-    static keepAlive: boolean;
-    get isKeepAlive(): boolean;
-    _isolated: boolean;
-    _id: BlocInstanceId;
-    _instanceRef?: string;
-    _name: string;
-    /**
-     * Unified subscription manager for all state notifications
-     */
-    _subscriptionManager: SubscriptionManager<S>;
-    _state: S;
-    private _lifecycleManager;
-    private _batchingManager;
-    _keepAlive: boolean;
-    lastUpdate?: number;
-    _plugins: BlocPluginRegistry<S, any>;
-    onDispose?: () => void;
-    /**
-     * Creates a new BlocBase instance with unified subscription management
-     */
-    constructor(initialState: S);
-    /**
-     * Returns the current state
-     */
-    get state(): S;
-    /**
-     * Subscribe to all state changes
-     */
-    subscribe(callback: (state: S) => void): () => void;
-    /**
-     * Subscribe with a selector for optimized updates
-     */
-    subscribeWithSelector<T>(selector: (state: S) => T, callback: (value: T) => void, equalityFn?: (a: T, b: T) => boolean): () => void;
-    /**
-     * Subscribe with React component reference for automatic cleanup
-     */
-    subscribeComponent(componentRef: WeakRef<object>, callback: () => void): () => void;
-    /**
-     * Get current subscription count
-     */
-    get subscriptionCount(): number;
-    /**
-     * Track property access for a subscription
-     */
-    trackAccess(subscriptionId: string, path: string, value?: unknown): void;
-    /**
-     * Emit a new state
-     */
-    protected emit(newState: S, action?: unknown): void;
-    /**
-     * Internal state push method used by Bloc
-     */
-    _pushState(newState: S, oldState: S, action?: unknown): void;
-    _batchUpdates(callback: () => void): void;
-    /**
-     * Add a plugin
-     */
-    addPlugin(plugin: BlocPlugin<S, any>): void;
-    /**
-     * Remove a plugin
-     */
-    removePlugin(plugin: BlocPlugin<S, any>): void;
-    /**
-     * Get all plugins
-     */
-    get plugins(): ReadonlyArray<BlocPlugin<S, any>>;
-    /**
-     * Disposal management
-     */
-    get isDisposed(): boolean;
-    /**
-     * Atomic state transition for disposal
-     */
-    _atomicStateTransition(expectedState: BlocLifecycleState, newState: BlocLifecycleState): StateTransitionResult;
-    /**
-     * Dispose the bloc and clean up resources
-     */
-    dispose(): Promise<void>;
-    /**
-     * Schedule disposal when no subscriptions remain
-     */
-    _scheduleDisposal(): void;
-    /**
-     * Set disposal handler
-     */
-    setDisposalHandler(handler: (bloc: BlocBase<unknown>) => void): void;
-    /**
-     * Check if disposal should be scheduled (called by subscription manager)
-     */
-    checkDisposal(): void;
-    /**
-     * Cancel disposal if bloc is in disposal_requested state
-     */
-    _cancelDisposalIfRequested(): void;
-}
-
-/**
- * Represents the abstract base types for Bloc and Cubit
- */
-export declare type BlocBaseAbstract = typeof Bloc<any, any> | typeof Cubit<any>;
-
-/**
- * Represents a constructor type for a Bloc that takes no parameters
- * @template B - The type of the Bloc instance
- */
-export declare type BlocClassNoParams<B> = new (args: never[]) => B;
-
-/**
- * Represents a constructor type for a Bloc that can take any parameters
- * @template B - The type of the Bloc instance
- */
-export declare type BlocConstructor<B> = (new (...args: any) => B) & {
-    isolated?: boolean;
-    keepAlive?: boolean;
-};
-
-export declare type BlocConstructorParams<B extends BlocConstructor<BlocBase<any>>> = ConstructorParameters<B>[0];
-
-/**
- * Error boundary interface for Bloc error handling
- */
-export declare interface BlocErrorBoundary<S, A extends BlocEventConstraint> {
-    onError: (error: Error, event: A, currentState: S, bloc: {
-        name: string;
-        id: string;
-    }) => void | Promise<void>;
-    shouldRethrow?: (error: Error, event: A) => boolean;
-}
-
-/**
- * Enhanced constraint for Bloc events - must be objects with proper constructor
- */
-export declare type BlocEventConstraint = object;
-
-/**
- * Function type for determining dependencies that trigger re-renders
- * Similar to React's useEffect dependency array - if any dependency changes, a re-render is triggered
- * @template S The state type
- * @template I The bloc instance type
- * @param currentState The current state
- * @param previousState The previous state (undefined on first call)
- * @param instance The bloc instance
- * @returns Array of dependencies - if any dependency changes, a re-render is triggered
- */
-export declare type BlocHookDependencyArrayFn<S, I = any> = (currentState: S, previousState: S | undefined, instance: I) => unknown[];
-
-export declare type BlocInstanceId = string | number | undefined;
-
-/**
- * Manages the lifecycle state transitions for Bloc instances.
- * Ensures atomic state transitions to prevent race conditions during disposal.
- */
-export declare class BlocLifecycleManager {
-    private disposalState;
-    private disposalLock;
-    private disposalTimer?;
-    private disposalHandler?;
-    get currentState(): BlocLifecycleState;
-    get isDisposed(): boolean;
-    /**
-     * Atomic state transition for disposal
-     */
-    atomicStateTransition(expectedState: BlocLifecycleState, newState: BlocLifecycleState): StateTransitionResult;
-    /**
-     * Schedule disposal after a delay
-     */
-    scheduleDisposal(delay: number, canDispose: () => boolean, onDispose: () => void): void;
-    /**
-     * Cancel disposal if in disposal requested state
-     */
-    cancelDisposal(): boolean;
-    /**
-     * Set disposal handler
-     */
-    setDisposalHandler(handler: (bloc: unknown) => void): void;
-    /**
-     * Get disposal handler
-     */
-    getDisposalHandler(): ((bloc: unknown) => void) | undefined;
-    /**
-     * Clear disposal timer
-     */
-    clearDisposalTimer(): void;
-}
-
-/**
- * Enum representing the lifecycle states of a Bloc instance
- */
-export declare enum BlocLifecycleState {
-    ACTIVE = "active",
-    DISPOSAL_REQUESTED = "disposal_requested",
-    DISPOSING = "disposing",
-    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>): 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<BlocPlugin<TState, TEvent>> {
-    private plugins;
-    private executionOrder;
-    private attached;
-    /**
-     * Add a bloc plugin
-     */
-    add(plugin: BlocPlugin<TState, TEvent>): void;
-    /**
-     * Remove a bloc plugin
-     */
-    remove(pluginName: string): boolean;
-    /**
-     * Get a plugin by name
-     */
-    get(pluginName: string): BlocPlugin<TState, TEvent> | undefined;
-    /**
-     * Get all plugins in execution order
-     */
-    getAll(): ReadonlyArray<BlocPlugin<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): 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
- */
-export declare type BlocState<T> = T extends BlocBase<infer S> ? S : never;
-
-/**
- * Test utilities for Blac state management
- */
-export declare class BlocTest {
-    private static originalInstance;
-    /**
-     * Sets up a clean test environment
-     */
-    static setUp(): void;
-    /**
-     * Tears down the test environment and restores original state
-     */
-    static tearDown(): void;
-    /**
-     * Creates a test bloc with automatic cleanup
-     */
-    static createBloc<T extends BlocBase<any>>(BlocClass: new (...args: any[]) => T, ...args: any[]): T;
-    /**
-     * Waits for a bloc to emit a specific state
-     */
-    static waitForState<T extends BlocBase<S>, S>(bloc: T, predicate: (state: S) => boolean, timeout?: number): Promise<S>;
-    /**
-     * Expects a bloc to emit specific states in order
-     */
-    static expectStates<T extends BlocBase<S>, S>(bloc: T, expectedStates: S[], timeout?: number): Promise<void>;
-}
-
-declare interface ConsumerTracker {
-    trackAccess: (consumerRef: object, type: 'state' | 'class', path: string, value?: any) => void;
-}
-
-/**
- * Creates a proxy for bloc instances that tracks getter access
- */
-export declare const createBlocProxy: <T extends object>(target: T, consumerRef: object, consumerTracker: ConsumerTracker) => T;
-
-/**
- * Creates a proxy for state objects that tracks property access
- */
-export declare const createStateProxy: <T extends object>(target: T, consumerRef: object, consumerTracker: ConsumerTracker, path?: string) => T;
-
-/**
- * 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 declare 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;
-    /**
-     * 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?: boolean): void;
-}
-
-export declare const DefaultErrorStrategy: ErrorHandlingStrategy;
-
-export declare enum ErrorCategory {
-    LIFECYCLE = "LIFECYCLE",
-    STATE = "STATE",
-    PLUGIN = "PLUGIN",
-    VALIDATION = "VALIDATION",
-    DISPOSAL = "DISPOSAL",
-    CONSUMER = "CONSUMER"
-}
-
-/**
- * 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>;
-}
-
-export declare type ErrorHandler = (error: BlacError) => void;
-
-export declare type ErrorHandlingStrategy = {
-    shouldPropagate: (error: BlacError) => boolean;
-    shouldLog: (error: BlacError) => boolean;
-    handle: (error: BlacError) => void;
-};
-
-/**
- * Centralized error management system for BlaC framework.
- * Handles error processing, logging, and propagation strategies.
- */
-export declare class ErrorManager {
-    private static instance;
-    private handlers;
-    private strategy;
-    /**
-     * Get the singleton instance of ErrorManager
-     */
-    static getInstance(): ErrorManager;
-    /**
-     * Set a custom error handling strategy
-     */
-    setStrategy(strategy: ErrorHandlingStrategy): void;
-    /**
-     * Add a custom error handler that will be called for all errors
-     */
-    addHandler(handler: ErrorHandler): void;
-    /**
-     * Remove a previously added error handler
-     */
-    removeHandler(handler: ErrorHandler): void;
-    /**
-     * Process an error through all handlers and apply the configured strategy
-     */
-    handle(error: BlacError): void;
-    /**
-     * Convenience method for wrapping operations with error handling
-     */
-    wrap<T>(operation: () => T, errorFactory: (error: unknown) => BlacError): T;
-    /**
-     * Async version of wrap
-     */
-    wrapAsync<T>(operation: () => Promise<T>, errorFactory: (error: unknown) => BlacError): Promise<T>;
-}
-
-export declare enum ErrorSeverity {
-    FATAL = "FATAL",// System cannot continue
-    ERROR = "ERROR",// Operation failed but system continues
-    WARNING = "WARNING",// Potential issue but operation succeeded
-    INFO = "INFO"
-}
-
-/**
- * Generates a deterministic instance ID from static props by extracting primitive values
- *
- * Rules:
- * 1. Only considers primitive types: string, number, boolean, null, undefined
- * 2. Ignores complex types: objects, arrays, functions, symbols
- * 3. Sorts keys alphabetically for deterministic output
- * 4. Returns undefined if no primitives found (caller should use default ID)
- */
-export declare function generateInstanceIdFromProps(props: unknown): string | undefined;
-
-/**
- * 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()
- */
-/**
- * Generates a UUID v4 string compatible with all JavaScript environments
- * @returns A UUID v4 string in the format xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
- */
-export declare function generateUUID(): string;
-
-export declare interface GetBlocOptions<B extends BlocBase<unknown>> {
-    id?: string;
-    selector?: BlocHookDependencyArrayFn<BlocState<B>>;
-    constructorParams?: ConstructorParameters<BlocConstructor<B>>[];
-    onMount?: (bloc: B) => void;
-    instanceRef?: string;
-    throwIfNotFound?: boolean;
-    /** Force creation of a new instance for isolated blocs, bypassing instance lookup */
-    forceNewInstance?: boolean;
-}
-
-/**
- * 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 declare const handleError: {
-    fatal: (message: string, category: ErrorCategory, context?: BlacErrorContext, cause?: unknown) => never;
-    error: (message: string, category: ErrorCategory, context?: BlacErrorContext, cause?: unknown) => void;
-    warn: (message: string, category: ErrorCategory, context?: BlacErrorContext, cause?: unknown) => void;
-    info: (message: string, category: ErrorCategory, context?: BlacErrorContext) => void;
-    /**
-     * Wraps a function to catch and handle errors
-     */
-    wrap: <T>(fn: () => T, category: ErrorCategory, context?: BlacErrorContext, severity?: ErrorSeverity) => T | undefined;
-    /**
-     * Wraps an async function to catch and handle errors
-     */
-    wrapAsync: <T>(fn: () => Promise<T>, category: ErrorCategory, context?: BlacErrorContext, severity?: ErrorSeverity) => Promise<T | undefined>;
-};
-
-/**
- * Memory leak detector for tests
- */
-export declare class MemoryLeakDetector {
-    private initialStats;
-    constructor();
-    /**
-     * Check for memory leaks and return a report
-     */
-    checkForLeaks(): {
-        hasLeaks: boolean;
-        report: string;
-        stats: ReturnType<typeof Blac.getMemoryStats>;
-    };
-}
-
-/**
- * Mock Bloc for testing
- */
-export declare class MockBloc<S, A extends BlocEventConstraint = BlocEventConstraint> extends Bloc<S, A> {
-    private mockHandlers;
-    constructor(initialState: S);
-    /**
-     * Mock an event handler for testing
-     */
-    mockEventHandler<E extends A>(eventConstructor: new (...args: any[]) => E, handler: (event: E, emit: (newState: S) => void) => void | Promise<void>): void;
-    /**
-     * Get the number of registered handlers
-     */
-    getHandlerCount(): number;
-    /**
-     * Check if a handler is registered for an event type
-     */
-    hasHandler(eventConstructor: new (...args: any[]) => A): boolean;
-}
-
-/**
- * Mock Cubit for testing
- */
-export declare class MockCubit<S> extends Cubit<S> {
-    private stateHistory;
-    constructor(initialState: S);
-    /**
-     * Override emit to track state history
-     */
-    emit(newState: S): void;
-    /**
-     * Get the history of all states
-     */
-    getStateHistory(): S[];
-    /**
-     * Clear state history
-     */
-    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;
-}
-
-/**
- * Event fired when props are updated on a Bloc or Cubit instance.
- * This is primarily used internally by the framework to notify
- * about prop changes in React components.
- * @template P - The type of props being updated
- */
-export declare class PropsUpdated<P = any> {
-    readonly props: P;
-    constructor(props: P);
-}
-
-export declare const ProxyFactory: {
-    createStateProxy: (options: {
-        target: any;
-        consumerRef: object;
-        consumerTracker: ConsumerTracker;
-        path?: string;
-    }) => any;
-    createClassProxy: (options: {
-        target: any;
-        consumerRef: object;
-        consumerTracker: ConsumerTracker;
-    }) => any;
-    getProxyState: <B extends BlocBase<any>>(options: {
-        state: any;
-        consumerRef: object;
-        consumerTracker: ConsumerTracker;
-    }) => any;
-    getProxyBlocInstance: <B extends BlocBase<any>>(options: {
-        blocInstance: B;
-        consumerRef: object;
-        consumerTracker: ConsumerTracker;
-    }) => B;
-    getStats: () => {
-        propertyAccesses: number;
-        nestedProxiesCreated: number;
-        cacheEfficiency: string;
-        lifetime: string;
-        proxiesPerSecond: string;
-        stateProxiesCreated: number;
-        classProxiesCreated: number;
-        cacheHits: number;
-        cacheMisses: number;
-        totalProxiesCreated: number;
-    };
-    resetStats: () => void;
-};
-
-export declare interface RerenderInfo {
-    componentName: string;
-    blocName: string;
-    blocId: string;
-    renderCount: number;
-    reason: RerenderReason;
-    timestamp: number;
-    duration?: number;
-    stackTrace?: string;
-}
-
-/**
- * Utility class for logging component rerenders with detailed debugging information
- */
-export declare class RerenderLogger {
-    private static componentRenderCounts;
-    private static lastRenderTimestamps;
-    private static groupedLogs;
-    private static groupTimeouts;
-    /**
-     * Log a component rerender with detailed information
-     */
-    static logRerender(info: RerenderInfo): void;
-    /**
-     * Parse the logging configuration
-     */
-    private static parseConfig;
-    /**
-     * Log immediately without grouping
-     */
-    private static logImmediate;
-    /**
-     * Log with grouping (batch multiple rerenders)
-     */
-    private static logGrouped;
-    /**
-     * Format the log message based on level
-     */
-    private static formatMessage;
-    /**
-     * Get emoji for reason type
-     */
-    private static getReasonEmoji;
-    /**
-     * Clear all tracking data
-     */
-    static clear(): void;
-    /**
-     * Get render count for a component
-     */
-    static getRenderCount(componentName: string, blocId: string): number;
-}
-
-export declare interface RerenderReason {
-    type: 'state-change' | 'dependency-change' | 'mount' | 'props-change' | 'unknown';
-    changedPaths?: string[];
-    oldValues?: Record<string, any>;
-    newValues?: Record<string, any>;
-    dependencies?: string[];
-    description?: string;
-}
-
-/**
- * Sets a custom instance manager (useful for testing or advanced patterns)
- */
-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;
-
-export declare interface StateTransitionResult {
-    success: boolean;
-    currentState: BlocLifecycleState;
-    previousState: BlocLifecycleState;
-}
-
-/**
- * Unified subscription interface that replaces the dual consumer/observer system
- */
-export declare interface Subscription<S = unknown> {
-    /** Unique identifier for the subscription */
-    id: string;
-    /** Type of subscription for backward compatibility */
-    type: 'consumer' | 'observer';
-    /** Optional selector function to derive values from state */
-    selector?: (state: S, bloc?: BlocBase<S>) => unknown;
-    /** Custom equality function for selector results (defaults to Object.is) */
-    equalityFn?: (prev: unknown, next: unknown) => boolean;
-    /** Notification callback when state changes */
-    notify: (value: unknown, oldValue?: unknown, action?: unknown) => void;
-    /** Priority for notification order (higher = earlier) */
-    priority?: number;
-    /** WeakRef to the subscriber for automatic cleanup (React components) */
-    weakRef?: WeakRef<object>;
-    /** Last computed selector value for comparison */
-    lastValue?: unknown;
-    /** Tracked state path dependencies */
-    dependencies?: Set<string>;
-    /** Metadata for tracking and debugging */
-    metadata?: SubscriptionMetadata;
-}
-
-/**
- * Unified subscription manager that replaces the dual consumer/observer system.
- * Handles all state change subscriptions with a single, consistent interface.
- */
-export declare class SubscriptionManager<S = unknown> {
-    private bloc;
-    private subscriptions;
-    private pathToSubscriptions;
-    private weakRefCleanupScheduled;
-    private totalNotifications;
-    constructor(bloc: BlocBase<S>);
-    /**
-     * Subscribe to state changes
-     */
-    subscribe(options: SubscriptionOptions<S>): () => void;
-    /**
-     * Unsubscribe by ID
-     */
-    unsubscribe(id: string): void;
-    /**
-     * Notify all subscriptions of state change
-     */
-    notify(newState: S, oldState: S, action?: unknown): void;
-    /**
-     * Track a path access for a subscription
-     */
-    trackAccess(subscriptionId: string, path: string, value?: unknown): void;
-    /**
-     * Get the paths that changed between two states
-     */
-    private getChangedPaths;
-    /**
-     * Check if a subscription should be notified based on changed paths
-     */
-    shouldNotifyForPaths(subscriptionId: string, changedPaths: Set<string>): boolean;
-    /**
-     * Get statistics about subscriptions
-     */
-    getStats(): SubscriptionManagerStats;
-    /**
-     * Clear all subscriptions
-     */
-    clear(): void;
-    /**
-     * Get subscription by ID
-     */
-    getSubscription(id: string): Subscription<S> | undefined;
-    /**
-     * Check if there are any active subscriptions
-     */
-    get hasSubscriptions(): boolean;
-    /**
-     * Get count of active subscriptions
-     */
-    get size(): number;
-    /**
-     * Clean up subscriptions with dead weak references
-     */
-    private cleanupDeadReferences;
-    /**
-     * Schedule weak reference cleanup for next tick
-     */
-    private scheduleWeakRefCleanup;
-}
-
-export declare interface SubscriptionManagerStats {
-    /** Total number of active subscriptions */
-    activeSubscriptions: number;
-    /** Number of consumer subscriptions */
-    consumerCount: number;
-    /** Number of observer subscriptions */
-    observerCount: number;
-    /** Total notifications sent */
-    totalNotifications: number;
-    /** Number of tracked dependencies */
-    trackedDependencies: number;
-}
-
-export declare interface SubscriptionMetadata {
-    /** Timestamp of last notification */
-    lastNotified?: number;
-    /** Whether the subscriber has rendered (React-specific) */
-    hasRendered?: boolean;
-    /** Number of times this subscription accessed state */
-    accessCount?: number;
-    /** First access timestamp */
-    firstAccessTime?: number;
-    /** Last access timestamp */
-    lastAccessTime?: number;
-}
-
-export declare interface SubscriptionOptions<S> {
-    /** Type of subscription */
-    type: 'consumer' | 'observer';
-    /** Optional selector function */
-    selector?: (state: S, bloc?: BlocBase<S>) => unknown;
-    /** Custom equality function */
-    equalityFn?: (prev: unknown, next: unknown) => boolean;
-    /** Notification callback */
-    notify: (value: unknown, oldValue?: unknown, action?: unknown) => void;
-    /** Priority for notifications */
-    priority?: number;
-    /** WeakRef to subscriber */
-    weakRef?: WeakRef<object>;
-}
-
-/**
- * Registry for system-wide plugins
- */
-export declare class SystemPluginRegistry implements PluginRegistry<BlacPlugin> {
-    private plugins;
-    private metrics;
-    private executionOrder;
-    /**
-     * Add a system plugin
-     */
-    add(plugin: BlacPlugin): void;
-    /**
-     * Remove a system plugin
-     */
-    remove(pluginName: string): boolean;
-    /**
-     * Get a plugin by name
-     */
-    get(pluginName: string): BlacPlugin | undefined;
-    /**
-     * Get all plugins in execution order
-     */
-    getAll(): ReadonlyArray<BlacPlugin>;
-    /**
-     * Clear all plugins
-     */
-    clear(): void;
-    /**
-     * Execute a hook on all plugins
-     */
-    executeHook(hookName: keyof BlacPlugin, args: unknown[], errorHandler?: (error: Error, plugin: BlacPlugin) => 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): void;
-    /**
-     * Notify plugins of adapter lifecycle events
-     */
-    notifyAdapterCreated(adapter: any, metadata: AdapterMetadata): void;
-    notifyAdapterMount(adapter: any, metadata: AdapterMetadata): void;
-    notifyAdapterUnmount(adapter: any, metadata: AdapterMetadata): void;
-    notifyAdapterRender(adapter: any, metadata: AdapterMetadata): void;
-    notifyAdapterDisposed(adapter: any, metadata: AdapterMetadata): void;
-    /**
-     * Get metrics for a plugin
-     */
-    getMetrics(pluginName: string): Map<string, PluginMetrics> | undefined;
-    private initializeMetrics;
-    private recordSuccess;
-    private recordError;
-}
-
-/**
- * Extracts the state type from a BlocBase instance
- * @template B - The BlocBase type to extract the state from
- */
-export declare type ValueType<B extends BlocBase<any>> = B extends BlocBase<infer U> ? U : never;
-
-export { }