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

package/dist/index.d.ts

@@ -1,3 +1,11 @@
+export declare interface AdapterOptions<B extends BlocBase<any>> {
+    id?: string;
+    dependencies?: (bloc: B) => unknown[];
+    props?: 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.
@@ -9,19 +17,28 @@
  * - Providing logging and debugging capabilities
  */
 export declare class Blac {
-    /** @deprecated Use getInstance() instead */
     static get instance(): Blac;
     /** Timestamp when the instance was created */
     createdAt: number;
     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 */
-    private isolatedBlocIndex;
+    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 */
@@ -38,6 +55,7 @@ export declare class Blac {
     /** 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
@@ -205,12 +223,69 @@ export declare class Blac {
     static get validateConsumers(): () => 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>;
+    private consumerTracker;
+    private static propsOwners;
+    private lastProps?;
+    unmountTime: number;
+    mountTime: number;
+    private dependencyValues?;
+    private isUsingDependencies;
+    private hasMounted;
+    private mountCount;
+    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;
+    getConsumerDependencies(consumerRef: object): DependencyArray | null;
+    shouldNotifyConsumer(consumerRef: object, changedPaths: Set<string>): boolean;
+    updateLastNotified(consumerRef: object): void;
+    resetConsumerTracking(): void;
+    createStateProxy: <T extends object>(props: {
+        target: T;
+    }) => T;
+    createClassProxy: <T extends object>(props: {
+        target: T;
+    }) => T;
+    updateBlocInstance(): InstanceType<B>;
+    createSubscription: (options: {
+        onChange: () => void;
+    }) => () => void;
+    mount: () => void;
+    unmount: () => void;
+    getProxyState: (state: BlocState<InstanceType<B>>) => BlocState<InstanceType<B>>;
+    getProxyBlocInstance: () => InstanceType<B>;
+    get calledOnMount(): boolean;
+    updateProps(props: any): void;
+    private hasDependencyValuesChanged;
+}
+
 /**
  * Configuration options for the Blac instance
  */
 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;
 }
 
 /**
@@ -281,7 +356,7 @@ export declare type BlacObserver<S> = {
     /** Dispose function for the observer */
     dispose?: () => void;
     /** Cached state values used for dependency comparison */
-    lastState?: unknown[][];
+    lastState?: unknown[];
     /** Unique identifier for the observer */
     id: string;
 };
@@ -354,6 +429,7 @@ export declare abstract class BlocBase<S, P = unknown> {
      */
     readonly _createdAt: number;
     /* Excluded from this release type: _disposalState */
+    /* Excluded from this release type: _disposalRequestTime */
     /* Excluded from this release type: _state */
     /* Excluded from this release type: _oldState */
     /**
@@ -375,10 +451,17 @@ export declare abstract class BlocBase<S, P = unknown> {
     /**
      * Returns the current state of the Bloc.
      * Use this getter to access the state in a read-only manner.
+     * Returns the state even during transitional lifecycle states for React compatibility.
      */
     get state(): S;
+    /**
+     * Returns whether this Bloc instance has been disposed.
+     * @returns true if the bloc is in DISPOSED state
+     */
+    get isDisposed(): boolean;
     /* Excluded from this release type: _name */
     /* Excluded from this release type: _updateId */
+    /* Excluded from this release type: _atomicStateTransition */
     /* Excluded from this release type: _dispose */
     /* Excluded from this release type: onDispose */
     /* Excluded from this release type: _consumers */
@@ -412,7 +495,10 @@ 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;
+export declare type BlocConstructor<B> = (new (...args: any) => B) & {
+    isolated?: boolean;
+    keepAlive?: boolean;
+};
 
 /**
  * Extracts the constructor parameters type from a BlocBase
@@ -431,19 +517,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
@@ -459,6 +536,17 @@ export declare type BlocHookDependencyArrayFn<S, I = any> = (currentState: S, pr
 
 export declare type BlocInstanceId = string | number | undefined;
 
+/**
+ * Enum representing the lifecycle states of a Bloc instance
+ * Used for atomic state transitions to prevent race conditions
+ */
+export declare enum BlocLifecycleState {
+    ACTIVE = "active",
+    DISPOSAL_REQUESTED = "disposal_requested",
+    DISPOSING = "disposing",
+    DISPOSED = "disposed"
+}
+
 /**
  * Extracts the state type from either a Bloc or Cubit
  * @template T - The Bloc or Cubit type to extract the state from
@@ -492,6 +580,49 @@ export declare class BlocTest {
     static expectStates<T extends BlocBase<S>, S>(bloc: T, expectedStates: S[], timeout?: number): Promise<void>;
 }
 
+export declare interface ConsumerInfo {
+    id: string;
+    lastNotified: number;
+    hasRendered: boolean;
+    stateAccesses: Set<string>;
+    classAccesses: Set<string>;
+    stateValues: Map<string, TrackedValue>;
+    classValues: Map<string, TrackedValue>;
+    accessCount: number;
+    lastAccessTime: number;
+    firstAccessTime: number;
+}
+
+/**
+ * ConsumerTracker manages both consumer registration and dependency tracking.
+ * It uses a WeakMap for automatic garbage collection when consumers are no longer referenced.
+ */
+export declare class ConsumerTracker {
+    private consumers;
+    private registrationCount;
+    private activeConsumers;
+    register(consumerRef: object, consumerId: string): void;
+    unregister(consumerRef: object): void;
+    trackAccess(consumerRef: object, type: 'state' | 'class', path: string, value?: any): void;
+    resetTracking(consumerRef: object): void;
+    getDependencies(consumerRef: object): DependencyArray | null;
+    hasValuesChanged(consumerRef: object, newState: any, newBlocInstance: any): boolean;
+    shouldNotifyConsumer(consumerRef: object, changedPaths: Set<string>): boolean;
+    updateLastNotified(consumerRef: object): void;
+    getConsumerInfo(consumerRef: object): ConsumerInfo | undefined;
+    setHasRendered(consumerRef: object, hasRendered: boolean): void;
+    hasConsumer(consumerRef: object): boolean;
+    getStats(): {
+        totalRegistrations: number;
+        activeConsumers: number;
+    };
+    private getValueAtPath;
+}
+
+declare interface ConsumerTracker_2 {
+    trackAccess: (consumerRef: object, type: 'state' | 'class', path: string, value?: any) => void;
+}
+
 /**
  * A Cubit is a simpler version of a Bloc that doesn't handle events.
  * It manages state and provides methods to update it.
@@ -499,6 +630,11 @@ export declare class BlocTest {
  * @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),
@@ -517,6 +653,11 @@ export declare abstract class Cubit<S, P = null> extends BlocBase<S, P> {
     patch(statePatch: S extends object ? Partial<S> : S, ignoreChangeCheck?: boolean): void;
 }
 
+export declare interface DependencyArray {
+    statePaths: string[];
+    classPaths: string[];
+}
+
 declare type DependencySelector<S> = (currentState: S, previousState: S | undefined, instance: any) => unknown[];
 
 /**
@@ -536,6 +677,8 @@ export declare interface GetBlocOptions<B extends BlocBase<unknown>> {
     onMount?: (bloc: B) => void;
     instanceRef?: string;
     throwIfNotFound?: boolean;
+    /** Force creation of a new instance for isolated blocs, bypassing instance lookup */
+    forceNewInstance?: boolean;
 }
 
 /**
@@ -600,11 +743,78 @@ export declare class MockCubit<S> extends Cubit<S> {
     clearStateHistory(): 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;
+        consumerRef: object;
+        consumerTracker: ConsumerTracker_2;
+        path?: string;
+    }): T;
+    static createClassProxy<T extends object>(options: {
+        target: T;
+        consumerRef: object;
+        consumerTracker: ConsumerTracker_2;
+    }): T;
+    static getProxyState<B extends BlocBase<any>>(options: {
+        state: BlocState<B>;
+        consumerRef: object;
+        consumerTracker: ConsumerTracker_2;
+    }): BlocState<B>;
+    static getProxyBlocInstance<B extends BlocBase<any>>(options: {
+        blocInstance: B;
+        consumerRef: object;
+        consumerTracker: ConsumerTracker_2;
+    }): B;
+    static getStats(): {
+        totalProxies: number;
+        cacheEfficiency: string;
+        lifetime: string;
+        proxiesPerSecond: string;
+        stateProxiesCreated: number;
+        classProxiesCreated: number;
+        cacheHits: number;
+        cacheMisses: number;
+        propertyAccesses: number;
+        nestedProxiesCreated: number;
+        totalProxiesCreated: number;
+        createdAt: number;
+    };
+    static resetStats(): void;
+}
+
 /**
  * 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;
+
+/**
+ * Result of an atomic state transition operation
+ */
+export declare interface StateTransitionResult {
+    success: boolean;
+    currentState: BlocLifecycleState;
+    previousState: BlocLifecycleState;
+}
+
+export declare interface TrackedValue {
+    value: any;
+    lastAccessTime: number;
+}
+
 /**
  * Extracts the state type from a BlocBase instance
  * @template B - The BlocBase type to extract the state from