@blac/core 2.0.0-rc-2 → 2.0.0-rc-4

package/dist/index.d.ts

@@ -1,28 +1,31 @@
 /**
  * Main Blac class that manages the state management system.
- * Implements a singleton pattern to ensure only one instance exists.
- * Handles bloc lifecycle, plugin management, and instance tracking.
+ * 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
- * - Managing plugins and lifecycle events
  * - Providing logging and debugging capabilities
  */
 export declare class Blac {
-    /** The singleton instance of Blac */
-    static instance: Blac;
+    /** @deprecated Use getInstance() instead */
+    static get instance(): Blac;
     /** Timestamp when the instance was created */
     createdAt: number;
-    static getAllBlocs: <B extends BlocConstructor<unknown>>(blocClass: B, options?: {
+    static get getAllBlocs(): <B extends BlocConstructor<unknown>>(blocClass: B, options?: {
         searchIsolated?: boolean;
     }) => InstanceType<B>[];
-    static addPlugin: (plugin: BlacPlugin) => void;
     /** Map storing all registered bloc instances by their class name and ID */
-    blocInstanceMap: Map<string, BlocBase<any>>;
+    blocInstanceMap: Map<string, BlocBase<unknown>>;
     /** Map storing isolated bloc instances grouped by their constructor */
-    isolatedBlocMap: Map<BlocConstructor<any>, BlocBase<any>[]>;
-    pluginList: BlacPlugin[];
+    isolatedBlocMap: Map<BlocConstructor<unknown>, BlocBase<unknown>[]>;
+    /** Map for O(1) lookup of isolated blocs by UID */
+    private isolatedBlocIndex;
+    /** 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;
     /**
@@ -39,9 +42,9 @@ export declare class Blac {
      * @param args - Arguments to log
      */
     log: (...args: unknown[]) => void;
-    static log: (...args: unknown[]) => void;
+    static get log(): (...args: unknown[]) => void;
     /**
-     * Gets the singleton instance of Blac
+     * Gets the current Blac instance
      * @returns The Blac instance
      */
     static getInstance(): Blac;
@@ -51,50 +54,25 @@ export declare class Blac {
      * @param args - Additional arguments
      */
     warn: (message: string, ...args: unknown[]) => void;
-    static 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 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;
-    /**
-     * Adds a plugin to the Blac instance
-     * @param plugin - The plugin to add
-     */
-    addPlugin: (plugin: BlacPlugin) => void;
-    /**
-     * Dispatches a lifecycle event to all registered plugins
-     * @param event - The lifecycle event to dispatch
-     * @param bloc - The bloc instance involved in the event
-     * @param params - Additional parameters for the event
-     */
-    dispatchEventToPlugins: (event: BlacLifecycleEvent, bloc: BlocBase<any>, params?: unknown) => void;
-    /**
-     * Dispatches a lifecycle event and handles related cleanup actions.
-     * This method is responsible for:
-     * - Logging the event
-     * - Handling bloc disposal when needed
-     * - Managing bloc consumer cleanup
-     * - Forwarding the event to plugins
-     *
-     * @param event - The lifecycle event to dispatch
-     * @param bloc - The bloc instance involved in the event
-     * @param params - Additional parameters for the event
-     */
-    dispatchEvent: (event: BlacLifecycleEvent, bloc: BlocBase<any>, params?: unknown) => void;
     /**
      * Disposes of a bloc instance by removing it from the appropriate registry
      * @param bloc - The bloc instance to dispose
      */
-    disposeBloc: (bloc: BlocBase<any>) => void;
+    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
@@ -106,12 +84,12 @@ export declare class Blac {
      * Unregister a bloc instance from the main registry
      * @param bloc - The bloc instance to unregister
      */
-    unregisterBlocInstance(bloc: BlocBase<any>): void;
+    unregisterBlocInstance(bloc: BlocBase<unknown>): void;
     /**
      * Registers a bloc instance in the main registry
      * @param bloc - The bloc instance to register
      */
-    registerBlocInstance(bloc: BlocBase<any>): void;
+    registerBlocInstance(bloc: BlocBase<unknown>): void;
     /**
      * Finds a registered bloc instance by its class and ID
      * @param blocClass - The bloc class to search for
@@ -123,16 +101,20 @@ export declare class Blac {
      * Registers an isolated bloc instance in the isolated registry
      * @param bloc - The isolated bloc instance to register
      */
-    registerIsolatedBlocInstance(bloc: BlocBase<any>): void;
+    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<any>): void;
+    unregisterIsolatedBlocInstance(bloc: BlocBase<unknown>): void;
     /**
-     * Finds an isolated bloc instance by its class and ID
+     * Finds an isolated bloc instance by its class and ID (O(n) lookup)
      */
     findIsolatedBlocInstance<B extends BlocConstructor<unknown>>(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
@@ -141,7 +123,9 @@ export declare class Blac {
      * @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>;
+    createNewBlocInstance<B extends BlocConstructor<BlocBase<unknown>>>(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.
@@ -153,8 +137,8 @@ export declare class Blac {
      *   - 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 getBloc: <B extends BlocConstructor<BlocBase<any>>>(blocClass: B, options?: GetBlocOptions<InstanceType<B>>) => InstanceType<B>;
+    getBloc: <B extends BlocConstructor<BlocBase<unknown>>>(blocClass: B, options?: GetBlocOptions<InstanceType<B>>) => InstanceType<B>;
+    static get getBloc(): <B extends BlocConstructor<BlocBase<unknown>>>(blocClass: B, options?: GetBlocOptions<InstanceType<B>>) => InstanceType<B>;
     /**
      * Gets a bloc instance or throws an error if it doesn't exist
      * @param blocClass - The bloc class to get
@@ -168,7 +152,7 @@ export declare class Blac {
         props?: InferPropsFromGeneric<B>;
         instanceRef?: string;
     }) => InstanceType<B>;
-    static getBlocOrThrow: <B extends BlocConstructor<unknown>>(blocClass: B, options?: {
+    static get getBlocOrThrow(): <B extends BlocConstructor<unknown>>(blocClass: B, options?: {
         id?: BlocInstanceId;
         props?: InferPropsFromGeneric<B> | undefined;
         instanceRef?: string;
@@ -183,22 +167,42 @@ export declare class Blac {
     getAllBlocs: <B extends BlocConstructor<unknown>>(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<unknown>>(blocClass?: B) => void;
+    static get disposeKeepAliveBlocs(): <B extends BlocConstructor<unknown>>(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 consumer references and cleans up orphaned consumers
+     */
+    validateConsumers: () => void;
+    static get validateConsumers(): () => void;
 }
 
-declare type BlacAddon = {
-    name: string;
-    onInit?: BlacAddonInit;
-    onEmit?: BlacAddonEmit;
-};
-
-declare type BlacAddonEmit = (params: {
-    oldState: unknown;
-    newState: unknown;
-    cubit: BlocBase<any>;
-}) => void;
-
-declare type BlacAddonInit = (bloc: BlocBase<any>) => void;
-
 /**
  * Configuration options for the Blac instance
  */
@@ -208,17 +212,12 @@ export declare interface BlacConfig {
 }
 
 /**
- * Enum representing different lifecycle events that can occur in the Blac system.
- * These events are used to track the lifecycle of blocs and their consumers.
+ * Interface for Blac instance management
  */
-export declare enum BlacLifecycleEvent {
-    BLOC_DISPOSED = "BLOC_DISPOSED",
-    BLOC_CREATED = "BLOC_CREATED",
-    LISTENER_REMOVED = "LISTENER_REMOVED",
-    LISTENER_ADDED = "LISTENER_ADDED",
-    STATE_CHANGED = "STATE_CHANGED",
-    BLOC_CONSUMER_REMOVED = "BLOC_CONSUMER_REMOVED",
-    BLOC_CONSUMER_ADDED = "BLOC_CONSUMER_ADDED"
+export declare interface BlacInstanceManager {
+    getInstance(): Blac;
+    setInstance(instance: Blac): void;
+    resetInstance(): void;
 }
 
 /**
@@ -263,9 +262,9 @@ export declare class BlacObservable<S = unknown> {
      */
     notify(newState: S, oldState: S, action?: unknown): void;
     /**
-     * Disposes of all observers and clears the observer set
+     * Clears the observer set
      */
-    dispose(): void;
+    clear(): void;
 }
 
 /**
@@ -285,11 +284,6 @@ export declare type BlacObserver<S> = {
     id: string;
 };
 
-export declare interface BlacPlugin {
-    name: string;
-    onEvent(event: BlacLifecycleEvent, bloc: BlocBase<any>, params?: unknown): void;
-}
-
 export declare abstract class Bloc<S, // State type
 A extends object, // Base Action/Event type, constrained to object
 P = unknown> extends BlocBase<S, P> {
@@ -320,6 +314,7 @@ P = unknown> extends BlocBase<S, P> {
  * @template P The type of props that can be passed during instance creation (optional)
  */
 export declare abstract class BlocBase<S, P = unknown> {
+    uid: `${string}-${string}-${string}-${string}-${string}`;
     /**
      * When true, every consumer will receive its own unique instance of this Bloc.
      * Use this when state should not be shared between components.
@@ -339,10 +334,8 @@ export declare abstract class BlocBase<S, P = unknown> {
      * When provided, observers will only be notified when selected dependencies change.
      */
     defaultDependencySelector: DependencySelector<S> | undefined;
-    /* Excluded from this release type: _addons */
     /* Excluded from this release type: _isolated */
     /* Excluded from this release type: _observer */
-    /* Excluded from this release type: _blac */
     /**
      * The unique identifier for this Bloc instance.
      * Defaults to the class name, but can be customized.
@@ -379,11 +372,21 @@ export declare abstract class BlocBase<S, P = unknown> {
     /* Excluded from this release type: _dispose */
     /* Excluded from this release type: onDispose */
     /* Excluded from this release type: _consumers */
+    /* Excluded from this release type: _consumerRefs */
     /* Excluded from this release type: _addConsumer */
     /* Excluded from this release type: _removeConsumer */
-    /* Excluded from this release type: _connectAddons */
+    /* Excluded from this release type: _disposalHandler */
+    /* Excluded from this release type: _setDisposalHandler */
+    /* Excluded from this release type: _scheduleDisposal */
     lastUpdate: number;
+    /* Excluded from this release type: _batchingEnabled */
+    /* Excluded from this release type: _pendingUpdates */
     /* Excluded from this release type: _pushState */
+    /**
+     * Enables batching for multiple state updates
+     * @param batchFn Function to execute with batching enabled
+     */
+    batch: <T>(batchFn: () => T) => T;
 }
 
 /**
@@ -450,12 +453,13 @@ export declare abstract class Cubit<S, P = null> extends BlocBase<S, P> {
 
 declare type DependencySelector<S> = (newState: S) => unknown[][];
 
-export declare interface GetBlocOptions<B extends BlocBase<any>> {
+export declare interface GetBlocOptions<B extends BlocBase<unknown>> {
     id?: string;
     selector?: BlocHookDependencyArrayFn<BlocState<B>>;
     props?: InferPropsFromGeneric<B>;
     onMount?: (bloc: B) => void;
     instanceRef?: string;
+    throwIfNotFound?: boolean;
 }
 
 /**
@@ -465,36 +469,9 @@ export declare interface GetBlocOptions<B extends BlocBase<any>> {
 export declare type InferPropsFromGeneric<T> = T extends Bloc<any, any, infer P> ? P : T extends Cubit<any, infer P> ? P : never;
 
 /**
- * Persist addon
- *
- * @param options
- * @returns BlacAddon
+ * Sets a custom instance manager (useful for testing or advanced patterns)
  */
-export declare function Persist(options?: {
-    /**
-     * @default 'blac'
-     */
-    keyPrefix?: string;
-    /**
-     * @default the bloc's id
-     */
-    keyName?: string;
-    /**
-     * Used when the value is not found in storage
-     */
-    defaultValue?: unknown;
-    /**
-     * @default 'localStorage'
-     * @see StorageType
-     */
-    storageType?: StorageType;
-    /**
-     * @default false
-     */
-    onError?: (e: unknown) => void;
-}): BlacAddon;
-
-declare type StorageType = 'localStorage' | 'sessionStorage';
+export declare function setBlacInstanceManager(manager: BlacInstanceManager): void;
 
 /**
  * Extracts the state type from a BlocBase instance