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

package/src/Blac.ts

@@ -1,13 +1,18 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-// TODO: Remove this eslint disable once any types are properly replaced
-import { BlocBase, BlocInstanceId } from "./BlocBase";
+// TODO: The 'any' types in this file are necessary for proper type inference in complex generic scenarios.
+// Specifically:
+// 1. BlocConstructor<any> in Maps - allows any bloc type to be stored while maintaining type safety in usage
+// 2. Type assertions for _disposalState - private property access across inheritance hierarchy
+// 3. Constructor argument types - enables flexible bloc instantiation patterns
+// These 'any' usages are carefully controlled and don't compromise runtime type safety.
+import { BlocBase, BlocInstanceId, BlocLifecycleState } from './BlocBase';
 import {
-    BlocBaseAbstract,
-    BlocConstructor,
-    BlocHookDependencyArrayFn,
-    BlocState,
-    InferPropsFromGeneric
-} from "./types";
+  BlocBaseAbstract,
+  BlocConstructor,
+  BlocHookDependencyArrayFn,
+  BlocState,
+  InferPropsFromGeneric,
+} from './types';
 
 /**
  * Configuration options for the Blac instance
@@ -24,6 +29,8 @@ export 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;
 }
 
 /**
@@ -43,7 +50,9 @@ class SingletonBlacManager implements BlacInstanceManager {
 
   getInstance(): Blac {
     if (!SingletonBlacManager._instance) {
-      SingletonBlacManager._instance = new Blac({ __unsafe_ignore_singleton: true });
+      SingletonBlacManager._instance = new Blac({
+        __unsafe_ignore_singleton: true,
+      });
     }
     return SingletonBlacManager._instance;
   }
@@ -54,8 +63,10 @@ class SingletonBlacManager implements BlacInstanceManager {
 
   resetInstance(): void {
     const oldInstance = SingletonBlacManager._instance;
-    SingletonBlacManager._instance = new Blac({ __unsafe_ignore_singleton: true });
-    
+    SingletonBlacManager._instance = new Blac({
+      __unsafe_ignore_singleton: true,
+    });
+
     // Transfer any keep-alive blocs to the new instance
     if (oldInstance) {
       for (const bloc of oldInstance.keepAliveBlocs) {
@@ -82,14 +93,13 @@ export function setBlacInstanceManager(manager: BlacInstanceManager): 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 class Blac {
-  /** @deprecated Use getInstance() instead */
   static get instance(): Blac {
     return instanceManager.getInstance();
   }
@@ -101,9 +111,12 @@ export class Blac {
   /** Map storing all registered bloc instances by their class name and ID */
   blocInstanceMap: Map<string, BlocBase<unknown>> = new Map();
   /** Map storing isolated bloc instances grouped by their constructor */
+  // Using BlocConstructor<BlocBase<unknown>> would break type inference when storing
+  // different bloc types in the same map. The 'any' allows proper polymorphic storage
+  // while maintaining type safety at usage sites through the BlocConstructor constraint.
   isolatedBlocMap: Map<BlocConstructor<any>, BlocBase<unknown>[]> = new Map();
   /** Map for O(1) lookup of isolated blocs by UID */
-  private isolatedBlocIndex: Map<string, BlocBase<unknown>> = new Map();
+  isolatedBlocIndex: Map<string, BlocBase<unknown>> = new Map();
   /** Map tracking UIDs to prevent memory leaks */
   uidRegistry: Map<string, BlocBase<unknown>> = new Map();
   /** Set of keep-alive blocs for controlled cleanup */
@@ -125,15 +138,27 @@ export class Blac {
 
   /** Flag to enable/disable logging */
   static enableLog = false;
+  static logLevel: 'warn' | 'log' = 'warn';
+  static logSpy: ((...args: unknown[]) => void) | null = null;
 
   /**
    * Logs messages to console when logging is enabled
    * @param args - Arguments to log
    */
   log = (...args: unknown[]) => {
-    if (Blac.enableLog) console.warn(`☢️ [Blac ${this.createdAt.toString()}]`, ...args);
+    if (Blac.logSpy) {
+      Blac.logSpy(args);
+    }
+    if (Blac.enableLog && Blac.logLevel === 'warn') {
+      // Logging disabled - console.warn removed
+    }
+    if (Blac.enableLog && Blac.logLevel === 'log') {
+      // Logging disabled - console.log removed
+    }
   };
-  static get log() { return Blac.instance.log; }
+  static get log() {
+    return Blac.instance.log;
+  }
 
   /**
    * Gets the current Blac instance
@@ -143,7 +168,6 @@ export class Blac {
     return instanceManager.getInstance();
   }
 
-
   /**
    * Logs a warning message
    * @param message - Warning message
@@ -151,10 +175,12 @@ export class Blac {
    */
   warn = (message: string, ...args: unknown[]) => {
     if (Blac.enableLog) {
-      console.warn(`🚨 [Blac ${String(Blac.instance.createdAt)}]`, message, ...args);
+      // Logging disabled - console.warn removed
     }
   };
-  static get warn() { return Blac.instance.warn; }
+  static get warn() {
+    return Blac.instance.warn;
+  }
   /**
    * Logs an error message
    * @param message - Error message
@@ -162,17 +188,19 @@ export class Blac {
    */
   error = (message: string, ...args: unknown[]) => {
     if (Blac.enableLog) {
-      console.error(`🚨 [Blac ${String(Blac.instance.createdAt)}]`, message, ...args);
+      // Logging disabled - console.error removed
     }
   };
-  static get error() { return Blac.instance.error; }
+  static get error() {
+    return Blac.instance.error;
+  }
 
   /**
    * Resets the Blac instance to a new one, disposing non-keepAlive blocs
    * from the old instance.
    */
   resetInstance = (): void => {
-    this.log("Reset Blac instance");
+    this.log('Reset Blac instance');
 
     // Create snapshots to avoid concurrent modification issues
     const oldBlocInstanceMap = new Map(this.blocInstanceMap);
@@ -181,14 +209,22 @@ export class Blac {
     // Dispose non-keepAlive blocs from the current instance
     // Use disposeBloc method to ensure proper cleanup
     oldBlocInstanceMap.forEach((bloc) => {
-      if (!bloc._keepAlive && (bloc as any)._disposalState === 'active') {
+      // TODO: Type assertion for private property access (see explanation above)
+      if (
+        !bloc._keepAlive &&
+        (bloc as any)._disposalState === BlocLifecycleState.ACTIVE
+      ) {
         this.disposeBloc(bloc);
       }
     });
 
     oldIsolatedBlocMap.forEach((blocArray) => {
       blocArray.forEach((bloc) => {
-        if (!bloc._keepAlive && (bloc as any)._disposalState === 'active') {
+        // TODO: Type assertion for private property access (see explanation above)
+        if (
+          !bloc._keepAlive &&
+          (bloc as any)._disposalState === BlocLifecycleState.ACTIVE
+        ) {
           this.disposeBloc(bloc);
         }
       });
@@ -201,7 +237,7 @@ export class Blac {
 
     // Use instance manager to reset
     instanceManager.resetInstance();
-  }
+  };
   static resetInstance = (): void => {
     instanceManager.resetInstance();
   };
@@ -212,18 +248,32 @@ export class Blac {
    */
   disposeBloc = (bloc: BlocBase<unknown>): void => {
     // Check if bloc is already disposed to prevent double disposal
-    if ((bloc as any)._disposalState !== 'active') {
-      this.log(`[${bloc._name}:${String(bloc._id)}] disposeBloc called on already disposed bloc`);
+    // TODO: Type assertion needed to access private _disposalState property from external class.
+    // This is safe because we know BlocBase has this property, but TypeScript can't verify
+    // private property access across class boundaries. Alternative would be to make
+    // _disposalState protected, but that would expose internal implementation details.
+    const currentState = (bloc as any)._disposalState;
+    const validStatesForDisposal = [
+      BlocLifecycleState.ACTIVE,
+      BlocLifecycleState.DISPOSAL_REQUESTED,
+    ];
+
+    if (!validStatesForDisposal.includes(currentState)) {
+      this.log(
+        `[${bloc._name}:${String(bloc._id)}] disposeBloc called on bloc in invalid state: ${currentState}`,
+      );
       return;
     }
 
     const base = bloc.constructor as unknown as BlocBaseAbstract;
     const key = this.createBlocInstanceMapKey(bloc._name, bloc._id);
-    this.log(`[${bloc._name}:${String(bloc._id)}] disposeBloc called. Isolated: ${String(base.isolated)}`);
+    this.log(
+      `[${bloc._name}:${String(bloc._id)}] disposeBloc called. Isolated: ${String(base.isolated)}`,
+    );
 
     // First dispose the bloc to prevent further operations
     bloc._dispose();
-    
+
     // Then clean up from registries
     if (base.isolated) {
       this.unregisterIsolatedBlocInstance(bloc);
@@ -231,10 +281,12 @@ export class Blac {
     } else {
       this.unregisterBlocInstance(bloc);
     }
-    
-    this.log('dispatched bloc', bloc)
+
+    this.log('dispatched bloc', bloc);
   };
-  static get disposeBloc() { return Blac.instance.disposeBloc; }
+  static get disposeBloc() {
+    return Blac.instance.disposeBloc;
+  }
 
   /**
    * Creates a unique key for a bloc instance in the map based on the bloc class name and instance ID
@@ -253,10 +305,10 @@ export class Blac {
   unregisterBlocInstance(bloc: BlocBase<unknown>): void {
     const key = this.createBlocInstanceMapKey(bloc._name, bloc._id);
     this.blocInstanceMap.delete(key);
-    
+
     // Clean up UID tracking
     this.uidRegistry.delete(bloc.uid);
-    
+
     // Remove from keep-alive set
     this.keepAliveBlocs.delete(bloc);
   }
@@ -268,10 +320,10 @@ export class Blac {
   registerBlocInstance(bloc: BlocBase<unknown>): void {
     const key = this.createBlocInstanceMapKey(bloc._name, bloc._id);
     this.blocInstanceMap.set(key, bloc);
-    
+
     // Track UID for cleanup
     this.uidRegistry.set(bloc.uid, bloc);
-    
+
     // Track keep-alive blocs
     if (bloc._keepAlive) {
       this.keepAliveBlocs.add(bloc);
@@ -293,7 +345,7 @@ export class Blac {
 
     const key = this.createBlocInstanceMapKey(blocClass.name, id);
     const found = this.blocInstanceMap.get(key) as InstanceType<B> | undefined;
-    return found
+    return found;
   }
 
   /**
@@ -308,13 +360,13 @@ export class Blac {
     } else {
       this.isolatedBlocMap.set(blocClass, [bloc]);
     }
-    
+
     // Add to isolated index for O(1) lookups
     this.isolatedBlocIndex.set(bloc.uid, bloc);
-    
+
     // Track UID for cleanup
     this.uidRegistry.set(bloc.uid, bloc);
-    
+
     // Track keep-alive blocs
     if (bloc._keepAlive) {
       this.keepAliveBlocs.add(bloc);
@@ -328,10 +380,10 @@ export class Blac {
   unregisterIsolatedBlocInstance(bloc: BlocBase<unknown>): void {
     const blocClass = bloc.constructor;
     const blocs = this.isolatedBlocMap.get(blocClass as BlocConstructor<any>);
-    
+
     // Ensure both data structures are synchronized
     let wasRemoved = false;
-    
+
     if (blocs) {
       const index = blocs.findIndex((b) => b.uid === bloc.uid);
       if (index !== -1) {
@@ -343,21 +395,21 @@ export class Blac {
         this.isolatedBlocMap.delete(blocClass as BlocConstructor<any>);
       }
     }
-    
+
     // Always try to remove from isolated index, even if not found in map
     const wasInIndex = this.isolatedBlocIndex.delete(bloc.uid);
-    
+
     // Clean up UID tracking
     this.uidRegistry.delete(bloc.uid);
-    
+
     // Remove from keep-alive set
     this.keepAliveBlocs.delete(bloc);
-    
+
     // Log inconsistency for debugging
     if (wasRemoved !== wasInIndex) {
       this.warn(
         `[Blac] Inconsistent state detected during isolated bloc cleanup for ${bloc._name}:${bloc.uid}. ` +
-        `Map removal: ${wasRemoved}, Index removal: ${wasInIndex}`
+          `Map removal: ${wasRemoved}, Index removal: ${wasInIndex}`,
       );
     }
   }
@@ -377,7 +429,9 @@ export class Blac {
       return undefined;
     }
     // Find the specific bloc by ID within the isolated array
-    const found = blocs.find((b) => b._id === id) as InstanceType<B> | undefined;
+    const found = blocs.find((b) => b._id === id) as
+      | InstanceType<B>
+      | undefined;
     return found;
   }
 
@@ -385,7 +439,7 @@ export class Blac {
    * Finds an isolated bloc instance by UID (O(1) lookup)
    */
   findIsolatedBlocInstanceByUid<B extends BlocBase<unknown>>(
-    uid: string
+    uid: string,
   ): B | undefined {
     return this.isolatedBlocIndex.get(uid) as B | undefined;
   }
@@ -421,29 +475,42 @@ export class Blac {
     return newBloc;
   }
 
-
   activateBloc = (bloc: BlocBase<unknown>): void => {
+    // Don't activate disposed blocs
+    if ((bloc as any)._disposalState !== BlocLifecycleState.ACTIVE) {
+      this.log(
+        `[${bloc._name}:${String(bloc._id)}] activateBloc called on disposed bloc. Ignoring.`,
+      );
+      return;
+    }
+
     const base = bloc.constructor as unknown as BlocConstructor<BlocBase<any>>;
     const isIsolated = bloc.isIsolated;
 
-    let found = isIsolated ? this.findIsolatedBlocInstance(base, bloc._id) : this.findRegisteredBlocInstance(base, bloc._id);
+    let found = isIsolated
+      ? this.findIsolatedBlocInstance(base, bloc._id)
+      : this.findRegisteredBlocInstance(base, bloc._id);
     if (found) {
       return;
     }
 
-    this.log(`[${bloc._name}:${String(bloc._id)}] activateBloc called. Isolated: ${String(bloc.isIsolated)}`);
+    this.log(
+      `[${bloc._name}:${String(bloc._id)}] activateBloc called. Isolated: ${String(bloc.isIsolated)}`,
+    );
     if (bloc.isIsolated) {
       this.registerIsolatedBlocInstance(bloc);
     } else {
       this.registerBlocInstance(bloc);
     }
   };
-  static get activateBloc() { return Blac.instance.activateBloc; }
+  static get activateBloc() {
+    return Blac.instance.activateBloc;
+  }
 
   /**
    * 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)
@@ -455,47 +522,61 @@ export class Blac {
     blocClass: B,
     options: GetBlocOptions<InstanceType<B>> = {},
   ): InstanceType<B> => {
-    const { id } = options;
+    const { id, forceNewInstance } = options;
     const base = blocClass as unknown as BlocBaseAbstract;
     const blocId = id ?? blocClass.name;
+    this.log(`[${blocClass.name}:${String(blocId)}] (getBloc) Called:`, {
+      options,
+      base,
+    });
 
-
-    if (base.isolated) {
-      const isolatedBloc = this.findIsolatedBlocInstance<B>(blocClass, blocId)
-      if (isolatedBloc) {
-        this.log(`[${blocClass.name}:${String(blocId)}] (getBloc) Found existing isolated instance.`, options);
-        return isolatedBloc;
-      } else {
-        if (options.throwIfNotFound) {
-          throw new Error(`Isolated bloc ${blocClass.name} not found`);
+    // Skip instance lookup if forceNewInstance is true for isolated blocs
+    if (!forceNewInstance) {
+      if (base.isolated) {
+        const isolatedBloc = this.findIsolatedBlocInstance<B>(
+          blocClass,
+          options.instanceRef ?? blocId,
+        );
+        if (isolatedBloc) {
+          return isolatedBloc;
+        } else {
+          if (options.throwIfNotFound) {
+            throw new Error(`Isolated bloc ${blocClass.name} not found`);
+          }
         }
-      }
-    } else {
-      const registeredBloc = this.findRegisteredBlocInstance(blocClass, blocId)
-      if (registeredBloc) {
-        this.log(`[${blocClass.name}:${String(blocId)}] (getBloc) Found existing registered instance.`, options);
-        return registeredBloc
       } else {
-        if (options.throwIfNotFound) {
-          throw new Error(`Registered bloc ${blocClass.name} not found`);
+        const registeredBloc = this.findRegisteredBlocInstance(
+          blocClass,
+          blocId,
+        );
+        if (registeredBloc) {
+          return registeredBloc;
+        } else {
+          if (options.throwIfNotFound) {
+            throw new Error(`Registered bloc ${blocClass.name} not found`);
+          }
         }
       }
     }
 
-    const bloc = this.createNewBlocInstance(
-      blocClass,
-      blocId,
+    const bloc = this.createNewBlocInstance(blocClass, blocId, options);
+    this.log(
+      `[${blocClass.name}:${String(blocId)}] (getBloc) No existing instance found. Creating new one.`,
       options,
+      bloc,
     );
-    this.log(`[${blocClass.name}:${String(blocId)}] (getBloc) No existing instance found. Creating new one.`, options, bloc);
-    
+
     if (!bloc) {
-      throw new Error(`[getBloc] Failed to create bloc instance for ${blocClass.name}. This should never happen.`);
+      throw new Error(
+        `[getBloc] Failed to create bloc instance for ${blocClass.name}. This should never happen.`,
+      );
     }
-    
+
     return bloc;
   };
-  static get getBloc() { return Blac.instance.getBloc; }
+  static get getBloc() {
+    return Blac.instance.getBloc;
+  }
 
   /**
    * Gets a bloc instance or throws an error if it doesn't exist
@@ -525,7 +606,9 @@ export class Blac {
     }
     throw new Error(`Bloc ${blocClass.name} not found`);
   };
-  static get getBlocOrThrow() { return Blac.instance.getBlocOrThrow; }
+  static get getBlocOrThrow() {
+    return Blac.instance.getBlocOrThrow;
+  }
 
   /**
    * Gets all instances of a specific bloc class
@@ -545,7 +628,8 @@ export class Blac {
 
     // Search non-isolated blocs
     this.blocInstanceMap.forEach((blocInstance) => {
-      if (blocInstance.constructor === blocClass) { // Strict constructor check
+      if (blocInstance.constructor === blocClass) {
+        // Strict constructor check
         results.push(blocInstance as InstanceType<B>);
       }
     });
@@ -554,7 +638,7 @@ export class Blac {
     if (options.searchIsolated !== false) {
       const isolatedBlocs = this.isolatedBlocMap.get(blocClass);
       if (isolatedBlocs) {
-        results.push(...isolatedBlocs.map(bloc => bloc as InstanceType<B>));
+        results.push(...isolatedBlocs.map((bloc) => bloc as InstanceType<B>));
       }
     }
 
@@ -566,19 +650,21 @@ export class Blac {
    * @param blocClass - The bloc class to dispose
    */
   disposeKeepAliveBlocs = <B extends BlocConstructor<any>>(
-    blocClass?: B
+    blocClass?: B,
   ): void => {
     const toDispose: BlocBase<unknown>[] = [];
-    
+
     for (const bloc of this.keepAliveBlocs) {
       if (!blocClass || bloc.constructor === blocClass) {
         toDispose.push(bloc);
       }
     }
-    
-    toDispose.forEach(bloc => bloc._dispose());
+
+    toDispose.forEach((bloc) => bloc._dispose());
   };
-  static get disposeKeepAliveBlocs() { return Blac.instance.disposeKeepAliveBlocs; }
+  static get disposeKeepAliveBlocs() {
+    return Blac.instance.disposeKeepAliveBlocs;
+  }
 
   /**
    * Disposes all blocs matching a pattern
@@ -586,14 +672,14 @@ export class Blac {
    */
   disposeBlocs = (predicate: (bloc: BlocBase<unknown>) => boolean): void => {
     const toDispose: BlocBase<unknown>[] = [];
-    
+
     // Check registered blocs
     for (const bloc of this.blocInstanceMap.values()) {
       if (predicate(bloc)) {
         toDispose.push(bloc);
       }
     }
-    
+
     // Check isolated blocs
     for (const blocs of this.isolatedBlocMap.values()) {
       for (const bloc of blocs) {
@@ -602,10 +688,12 @@ export class Blac {
         }
       }
     }
-    
-    toDispose.forEach(bloc => bloc._dispose());
+
+    toDispose.forEach((bloc) => bloc._dispose());
   };
-  static get disposeBlocs() { return Blac.instance.disposeBlocs; }
+  static get disposeBlocs() {
+    return Blac.instance.disposeBlocs;
+  }
 
   /**
    * Gets memory usage statistics for debugging
@@ -614,12 +702,17 @@ export class Blac {
     return {
       totalBlocs: this.uidRegistry.size,
       registeredBlocs: this.blocInstanceMap.size,
-      isolatedBlocs: Array.from(this.isolatedBlocMap.values()).reduce((sum, arr) => sum + arr.length, 0),
+      isolatedBlocs: Array.from(this.isolatedBlocMap.values()).reduce(
+        (sum, arr) => sum + arr.length,
+        0,
+      ),
       keepAliveBlocs: this.keepAliveBlocs.size,
       isolatedBlocTypes: this.isolatedBlocMap.size,
     };
   };
-  static get getMemoryStats() { return Blac.instance.getMemoryStats; }
+  static get getMemoryStats() {
+    return Blac.instance.getMemoryStats;
+  }
 
   /**
    * Validates consumer references and cleans up orphaned consumers
@@ -628,18 +721,30 @@ export class Blac {
     for (const bloc of this.uidRegistry.values()) {
       // Validate consumers using the bloc's own validation method
       bloc._validateConsumers();
-      
+
       // Check if bloc should be disposed after validation
-      if (bloc._consumers.size === 0 && !bloc._keepAlive && (bloc as any)._disposalState === 'active') {
+      // TODO: Type assertion for private property access (see explanation above)
+      if (
+        bloc._consumers.size === 0 &&
+        !bloc._keepAlive &&
+        (bloc as any)._disposalState === BlocLifecycleState.ACTIVE
+      ) {
         // Schedule disposal for blocs with no consumers
         setTimeout(() => {
           // Double-check conditions before disposal
-          if (bloc._consumers.size === 0 && !bloc._keepAlive && (bloc as any)._disposalState === 'active') {
+          // TODO: Type assertion for private property access (see explanation above)
+          if (
+            bloc._consumers.size === 0 &&
+            !bloc._keepAlive &&
+            (bloc as any)._disposalState === BlocLifecycleState.ACTIVE
+          ) {
             this.disposeBloc(bloc);
           }
         }, 1000); // Give a grace period
       }
     }
   };
-  static get validateConsumers() { return Blac.instance.validateConsumers; }
+  static get validateConsumers() {
+    return Blac.instance.validateConsumers;
+  }
 }