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

package/dist/index.d.ts

@@ -1,3 +1,11 @@
+export declare interface AdapterOptions<B extends BlocBase<any>> {
+    id?: string;
+    dependencies?: (bloc: B) => unknown[];
+    props?: InferPropsFromGeneric<B>;
+    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,7 +17,6 @@
  * - 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;
@@ -21,7 +28,7 @@ export declare class Blac {
     /** 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 */
@@ -37,6 +44,8 @@ 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
@@ -204,6 +213,54 @@ 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;
+    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;
+    private hasDependencyValuesChanged;
+}
+
 /**
  * Configuration options for the Blac instance
  */
@@ -280,7 +337,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;
 };
@@ -353,6 +410,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 */
     /**
@@ -374,10 +432,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 */
@@ -411,7 +476,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
@@ -446,13 +514,29 @@ export declare type BlocEventConstraint = BlocEvent & 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
- * @returns Array of dependency arrays - if any dependency in any array changes, a re-render is triggered
+ * @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> = (newState: S) => unknown[][];
+export declare type BlocHookDependencyArrayFn<S, I = any> = (currentState: S, previousState: S | undefined, instance: I) => unknown[];
 
 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
@@ -486,6 +570,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.
@@ -511,7 +638,12 @@ export declare abstract class Cubit<S, P = null> extends BlocBase<S, P> {
     patch(statePatch: S extends object ? Partial<S> : S, ignoreChangeCheck?: boolean): void;
 }
 
-declare type DependencySelector<S> = (newState: S) => unknown[][];
+export declare interface DependencyArray {
+    statePaths: string[];
+    classPaths: string[];
+}
+
+declare type DependencySelector<S> = (currentState: S, previousState: S | undefined, instance: any) => unknown[];
 
 /**
  * Cross-platform UUID v4 generator that works in all environments including React Native/Hermes
@@ -530,6 +662,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;
 }
 
 /**
@@ -594,11 +728,64 @@ export declare class MockCubit<S> extends Cubit<S> {
     clearStateHistory(): void;
 }
 
+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;
 
+/**
+ * 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