@blac/core 2.0.0-rc.13 → 2.0.0-rc.14

package/dist/index.d.cts

@@ -4,7 +4,7 @@
  * Internal state for framework adapters, holding tracking and caching data.
  * @template TBloc - The state container type
  */
-export declare interface AdapterState<TBloc extends StateContainer<any, any>> {
+export declare interface AdapterState<TBloc extends StateContainer<any>> {
     /** Proxy tracker for state property access tracking */
     tracker: TrackerState<ExtractState<TBloc>> | null;
     /** Cached manual dependencies for comparison */
@@ -199,21 +199,27 @@ export declare interface BlacPluginWithInit extends BlacPlugin {
  * Used for type-safe hook parameters.
  * @template TBloc - The StateContainer instance type
  */
-export declare type BlocConstructor<TBloc extends StateContainer<any, any>> = (new (...args: any[]) => TBloc) & {
-    resolve<S = never>(instanceKey?: string, ...args: any[]): StateOverride<TBloc, S>;
-    get<S = never>(instanceKey?: string): StateOverride<TBloc, S>;
-    getSafe<S = never>(instanceKey?: string): {
+export declare type BlocConstructor<S = any, T extends new (...args: any[]) => StateContainer<S, any> = new (...args: any[]) => StateContainer<S, any>> = (new (...args: any[]) => InstanceType<T>) & {
+    resolve(instanceKey?: string, ...args: any[]): InstanceType<T>;
+    get(instanceKey?: string, ...args: any[]): InstanceType<T> | null;
+    getSafe(instanceKey?: string, ...args: any[]): {
         error: Error;
         instance: null;
     } | {
         error: null;
-        instance: StateOverride<TBloc, S>;
+        instance: InstanceType<T>;
     };
     release(instanceKey?: string): void;
     isolated?: boolean;
     keepAlive?: boolean;
 };
 
+/**
+ * Extract instance type from an abstract class constructor
+ * @template T - The abstract class constructor type
+ */
+export declare type BlocInstanceType<T extends abstract new (...args: any) => any> = T extends abstract new (...args: any) => infer R ? R : any;
+
 /**
  * Utility type for creating branded/nominal types.
  * Prevents accidental type confusion between similar primitive types.
@@ -333,7 +339,7 @@ export declare function createLogger(config: LogConfig): {
  * @param config - Configuration with dependencies function
  * @returns Snapshot function for use with useSyncExternalStore
  */
-export declare function createManualDepsSnapshot<TBloc extends StateContainer<any, any>>(instance: TBloc, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+export declare function createManualDepsSnapshot<TBloc extends StateContainer<any, any>>(instance: TBloc, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SnapshotFunction<ExtractState<StateContainerConstructor>>;
 
 /**
  * Create a subscribe function for manual dependency tracking mode.
@@ -363,6 +369,8 @@ export declare function createNoTrackSubscribe<TBloc extends StateContainer<any,
 
 /**
  * Create a plugin manager instance
+ * @param registry - The StateContainerRegistry to monitor for lifecycle events
+ * @returns A new PluginManager instance
  */
 export declare function createPluginManager(registry: StateContainerRegistry): PluginManager;
 
@@ -474,13 +482,13 @@ export declare type ExtractConstructorArgs<T> = T extends new (...args: infer P)
  * Extract the props type from a StateContainer
  * @template T - The StateContainer type
  */
-export declare type ExtractProps<T> = T extends StateContainer<any, infer P> ? P : undefined;
+export declare type ExtractProps<T> = T extends StateContainerConstructor<any, infer P> ? P : undefined;
 
 /**
  * Extract the state type from a StateContainer
  * @template T - The StateContainer type
  */
-export declare type ExtractState<T> = T extends StateContainer<infer S, any> ? S : never;
+export declare type ExtractState<T> = T extends StateContainerConstructor<infer S, any> ? S : never;
 
 /**
  * Generate ID with timestamp, counter, and random suffix (tree-shakeable)
@@ -534,9 +542,6 @@ export declare function generateSimpleId(prefix: string, affix?: string): string
  */
 export declare function getPluginManager(): any;
 
-/**
- * Utility functions for accessing static properties on StateContainer classes
- */
 /**
  * Get a static property from a class constructor
  * Type-safe helper that avoids (Type as any) casts
@@ -546,7 +551,7 @@ export declare function getPluginManager(): any;
  * @param defaultValue - Optional default value if property is undefined
  * @returns The property value or default
  */
-export declare function getStaticProp<T>(Type: new (...args: any[]) => any, propName: string, defaultValue?: T): T | undefined;
+export declare function getStaticProp<V, T extends StateContainerConstructor = StateContainerConstructor>(Type: T, propName: string, defaultValue?: V): V | undefined;
 
 declare interface GetterExecutionContext {
     tracker: GetterTrackerState | null;
@@ -656,18 +661,22 @@ export declare interface InstanceMetadata {
 /* Excluded from this release type: invalidateRenderCache */
 
 /**
- * Check if a class should be excluded from DevTools
- * Used to prevent infinite loops when DevTools tracks itself
+ * Check if a class should be excluded from DevTools.
+ * Used to prevent infinite loops when DevTools tracks itself.
+ * @param Type - The class constructor to check
+ * @returns true if the class has `static __excludeFromDevTools = true`
  */
-export declare function isExcludedFromDevTools(Type: new (...args: any[]) => any): boolean;
+export declare function isExcludedFromDevTools<T extends StateContainerConstructor>(Type: T): boolean;
 
 /* Excluded from this release type: isGetter */
 
 /**
- * Check if a class is marked as isolated
- * Isolated classes create separate instances per component
+ * Check if a class is marked as isolated.
+ * Isolated classes create separate instances per component.
+ * @param Type - The class constructor to check
+ * @returns true if the class has `static isolated = true`
  */
-export declare function isIsolatedClass(Type: new (...args: any[]) => any): boolean;
+export declare function isIsolatedClass<T extends StateContainerConstructor>(Type: T): boolean;
 
 /**
  * Check if a key is an isolated instance key
@@ -677,10 +686,12 @@ export declare function isIsolatedClass(Type: new (...args: any[]) => any): bool
 export declare function isIsolatedKey(key: string): boolean;
 
 /**
- * Check if a class is marked as keepAlive
- * KeepAlive classes are never auto-disposed when ref count reaches 0
+ * Check if a class is marked as keepAlive.
+ * KeepAlive classes are never auto-disposed when ref count reaches 0.
+ * @param Type - The class constructor to check
+ * @returns true if the class has `static keepAlive = true`
  */
-export declare function isKeepAliveClass(Type: new (...args: any[]) => any): boolean;
+export declare function isKeepAliveClass<T extends StateContainerConstructor>(Type: T): boolean;
 
 /* Excluded from this release type: isProxyable */
 
@@ -741,9 +752,9 @@ export declare enum LogLevel {
  * Configuration for manual dependency tracking mode
  * @template TBloc - The state container type
  */
-export declare interface ManualDepsConfig<TBloc extends StateContainer<any, any>> {
+export declare interface ManualDepsConfig<TBloc extends StateContainer<any>> {
     /** Function that returns dependency array from state and bloc */
-    dependencies: (state: any, bloc: TBloc) => unknown[];
+    dependencies: (state: any, bloc: TBloc) => any[];
 }
 
 /* Excluded from this release type: parsePath */
@@ -902,7 +913,7 @@ export declare type SnapshotFunction<TState> = () => TState;
  * }
  * ```
  */
-export declare abstract class StateContainer<S, P = undefined> {
+export declare abstract class StateContainer<S = any, P = any> {
     /* Excluded from this release type: __excludeFromDevTools */
     /* Excluded from this release type: _registry */
     /**
@@ -919,17 +930,22 @@ export declare abstract class StateContainer<S, P = undefined> {
      * Register this class with the global registry
      * @param isolated - Whether instances should be isolated (component-scoped)
      */
-    static register<T extends StateContainer<any>>(this: new (...args: any[]) => T, isolated?: boolean): void;
+    static register<T extends StateContainerConstructor>(this: T, isolated?: boolean): void;
     /**
      * Resolve an instance with ref counting (ownership semantics).
      * Creates a new instance if one doesn't exist, or returns existing and increments ref count.
      * @template S - Optional state type override for generic StateContainers
      * @template T - The StateContainer type (inferred from class)
      * @param instanceKey - Optional instance key (defaults to 'default')
-     * @param constructorArgs - Arguments to pass to constructor if creating new instance
+     * @param options - Resolution options (canCreate, countRef, props, trackExecutionContext)
      * @returns The state container instance
      */
-    static resolve<S = never, T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): StateOverride<T, S>;
+    static resolve<T extends StateContainerConstructor = StateContainerConstructor>(this: T, instanceKey?: string, options?: {
+        canCreate?: boolean;
+        countRef?: boolean;
+        props?: ExtractProps<T>;
+        trackExecutionContext?: boolean;
+    }): InstanceType<T>;
     /**
      * Get an existing instance without incrementing ref count (borrowing semantics).
      * @template S - Optional state type override for generic StateContainers
@@ -938,7 +954,7 @@ export declare abstract class StateContainer<S, P = undefined> {
      * @returns The state container instance
      * @throws Error if instance doesn't exist
      */
-    static get<S = never, T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): StateOverride<T, S>;
+    static get<T extends StateContainerConstructor<any> = StateContainerConstructor<any>>(this: T, instanceKey?: string): InstanceType<T>;
     /**
      * Safely get an existing instance with error handling.
      * @template S - Optional state type override for generic StateContainers
@@ -946,44 +962,44 @@ export declare abstract class StateContainer<S, P = undefined> {
      * @param instanceKey - Optional instance key (defaults to 'default')
      * @returns Discriminated union with either the instance or an error
      */
-    static getSafe<S = never, T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): {
+    static getSafe<T extends StateContainerConstructor<any> = StateContainerConstructor<any>>(this: T, instanceKey?: string): {
         error: Error;
         instance: null;
     } | {
         error: null;
-        instance: StateOverride<T, S>;
+        instance: InstanceType<T>;
     };
     /**
      * Connect to an instance for bloc-to-bloc communication (borrowing semantics).
      * Gets or creates instance without incrementing ref count.
+     * Tracks cross-bloc dependency for reactive updates.
      * @template S - Optional state type override for generic StateContainers
      * @template T - The StateContainer type (inferred from class)
      * @param instanceKey - Optional instance key (defaults to 'default')
-     * @param constructorArgs - Arguments to pass to constructor if creating new instance
      * @returns The state container instance
      */
-    static connect<S = never, T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): StateOverride<T, S>;
+    static connect<T extends StateContainerConstructor<any> = StateContainerConstructor<any>>(this: T, instanceKey?: string): InstanceType<T>;
     /**
      * Release a reference to an instance.
      * Decrements ref count and disposes when it reaches 0 (unless keepAlive).
      * @param instanceKey - Optional instance key (defaults to 'default')
      * @param forceDispose - Force immediate disposal regardless of ref count
      */
-    static release<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, forceDispose?: boolean): void;
+    static release<T extends StateContainerConstructor = StateContainerConstructor>(this: T, instanceKey?: string, forceDispose?: boolean): void;
     /**
      * Get all instances of this class
      * @returns Array of all instances
      */
-    static getAll<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T): T[];
+    static getAll<T extends StateContainerConstructor = StateContainerConstructor>(this: T): InstanceType<T>[];
     /**
      * Iterate over all instances of this class
      * @param callback - Function to call for each instance
      */
-    static forEach<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, callback: (instance: T) => void): void;
+    static forEach<T extends StateContainerConstructor = StateContainerConstructor>(this: T, callback: (instance: InstanceType<T>) => void): void;
     /**
      * Clear all instances of this class (disposes them)
      */
-    static clear<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T): void;
+    static clear<T extends StateContainerConstructor = StateContainerConstructor>(this: T): void;
     /**
      * Clear all instances from all registered types
      */
@@ -1002,13 +1018,13 @@ export declare abstract class StateContainer<S, P = undefined> {
      * @param instanceKey - Optional instance key (defaults to 'default')
      * @returns Current ref count (0 if instance doesn't exist)
      */
-    static getRefCount<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): number;
+    static getRefCount<T extends StateContainerConstructor = StateContainerConstructor>(this: T, instanceKey?: string): number;
     /**
      * Check if an instance exists
      * @param instanceKey - Optional instance key (defaults to 'default')
      * @returns true if instance exists
      */
-    static hasInstance<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): boolean;
+    static hasInstance<T extends StateContainerConstructor = StateContainerConstructor>(this: T, instanceKey?: string): boolean;
     private _state;
     private readonly listeners;
     private _disposed;
@@ -1095,6 +1111,13 @@ export declare interface StateContainerConfig {
     instanceId?: string;
 }
 
+/**
+ * Constructor type for StateContainer classes
+ * @template S - State type managed by the container
+ * @template P - Props type passed to the container
+ */
+export declare type StateContainerConstructor<S = any, P = any> = new (...args: any[]) => StateContainer<S, P>;
+
 /**
  * Central registry for managing StateContainer instances.
  * Handles instance lifecycle, ref counting, and lifecycle event emission.
@@ -1117,77 +1140,113 @@ export declare class StateContainerRegistry {
      * Register a type for lifecycle event tracking
      * @param constructor - The StateContainer class constructor
      */
-    registerType<T extends StateContainer<any>>(constructor: new (...args: any[]) => T): void;
+    registerType<T extends StateContainerConstructor>(constructor: T): void;
     /**
      * Register a StateContainer class with configuration
      * @param constructor - The StateContainer class constructor
      * @param isolated - Whether instances should be isolated (component-scoped)
      * @throws Error if type is already registered
      */
-    register<T extends StateContainer<any>>(constructor: new (...args: any[]) => T, isolated?: boolean): void;
+    register<T extends StateContainerConstructor>(constructor: T, isolated?: boolean): void;
     private ensureInstancesMap;
     /**
      * Get the instances Map for a specific class (public API for stats/debugging)
      */
-    getInstancesMap<T extends StateContainer<any>>(Type: new (...args: any[]) => T): Map<string, InstanceEntry>;
+    getInstancesMap<T extends StateContainerConstructor>(Type: T): Map<string, InstanceEntry>;
+    private trackExecutionContext;
     /**
-     * Resolve an instance with ref counting (ownership semantics)
+     * Resolve an instance with ref counting (ownership semantics).
+     * Creates a new instance if one doesn't exist, or returns existing and increments ref count.
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @param options - Resolution options
+     * @param options.canCreate - Whether to create new instance if not found (default: true)
+     * @param options.countRef - Whether to increment ref count (default: true)
+     * @param options.props - Props to pass to constructor if creating new instance
+     * @param options.trackExecutionContext - Whether to track cross-bloc dependency (default: false)
+     * @returns The state container instance
      */
-    resolve<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    resolve<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string, options?: {
+        canCreate?: boolean;
+        countRef?: boolean;
+        props?: ExtractProps<T>;
+        trackExecutionContext?: boolean;
+    }): InstanceType<T>;
     /**
-     * Get an existing instance without ref counting (borrowing semantics)
+     * Get an existing instance without incrementing ref count (borrowing semantics).
+     * Tracks cross-bloc dependency for reactive updates.
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns The state container instance
      * @throws Error if instance doesn't exist
      */
-    get<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): T;
+    get<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): InstanceType<T>;
     /**
-     * Safely get an existing instance (borrowing semantics with error handling)
-     * Returns discriminated union for type-safe conditional access
+     * Safely get an existing instance (borrowing semantics with error handling).
+     * Returns discriminated union for type-safe conditional access.
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns Discriminated union with either the instance or an error
      */
-    getSafe<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): {
+    getSafe<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): {
         error: Error;
         instance: null;
     } | {
         error: null;
-        instance: T;
+        instance: InstanceType<T>;
     };
     /**
-     * Connect to an instance with borrowing semantics (for B2B communication)
+     * Connect to an instance with borrowing semantics (for B2B communication).
      * Gets existing instance OR creates it if it doesn't exist, without incrementing ref count.
      * Tracks cross-bloc dependency for reactive updates.
      *
      * Use this in bloc-to-bloc communication when you need to ensure an instance exists
      * but don't want to claim ownership (no ref count increment).
-     *
-     * @param Type - The bloc class constructor
-     * @param instanceKey - Optional instance key (defaults to 'default')
-     * @param constructorArgs - Constructor arguments (only used if creating new instance)
-     * @returns The bloc instance
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns The state container instance
      */
-    connect<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    connect<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): InstanceType<T>;
     /**
-     * Release a reference to an instance
+     * Release a reference to an instance.
+     * Decrements ref count and disposes when it reaches 0 (unless keepAlive).
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @param forceDispose - Force immediate disposal regardless of ref count
      */
-    release<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string, forceDispose?: boolean): void;
+    release<T extends StateContainerConstructor>(Type: T, instanceKey?: string, forceDispose?: boolean): void;
     /**
-     * Get all instances of a specific type
+     * Get all instances of a specific type.
+     * @param Type - The StateContainer class constructor
+     * @returns Array of all instances
      */
-    getAll<T extends StateContainer<any>>(Type: new (...args: any[]) => T): T[];
+    getAll<T extends StateContainerConstructor>(Type: T): InstanceType<T>[];
     /**
-     * Safely iterate over all instances of a type
+     * Safely iterate over all instances of a type.
+     * Skips disposed instances and catches callback errors.
+     * @param Type - The StateContainer class constructor
+     * @param callback - Function to call for each instance
      */
-    forEach<T extends StateContainer<any>>(Type: new (...args: any[]) => T, callback: (instance: T) => void): void;
+    forEach<T extends StateContainerConstructor>(Type: T, callback: (instance: InstanceType<T>) => void): void;
     /**
-     * Clear all instances of a specific type
+     * Clear all instances of a specific type (disposes them).
+     * @param Type - The StateContainer class constructor
      */
-    clear<T extends StateContainer<any>>(Type: new (...args: any[]) => T): void;
+    clear<T extends StateContainerConstructor>(Type: T): void;
     /**
-     * Get reference count for an instance
+     * Get reference count for an instance.
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns Current ref count (0 if instance doesn't exist)
      */
-    getRefCount<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): number;
+    getRefCount<T extends StateContainerConstructor>(Type: T, instanceKey?: string): number;
     /**
-     * Check if an instance exists
+     * Check if an instance exists.
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns true if instance exists
      */
-    hasInstance<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): boolean;
+    hasInstance<T extends StateContainerConstructor>(Type: T, instanceKey?: string): boolean;
     /**
      * Clear all instances from all types (for testing)
      *
@@ -1196,7 +1255,8 @@ export declare class StateContainerRegistry {
      */
     clearAll(): void;
     /**
-     * Get registry statistics (for debugging)
+     * Get registry statistics for debugging.
+     * @returns Object with registeredTypes, totalInstances, and typeBreakdown
      */
     getStats(): {
         registeredTypes: number;
@@ -1204,9 +1264,10 @@ export declare class StateContainerRegistry {
         typeBreakdown: Record<string, number>;
     };
     /**
-     * Get all registered types (for plugin system)
+     * Get all registered types (for plugin system).
+     * @returns Array of all registered StateContainer class constructors
      */
-    getTypes(): Array<new (...args: any[]) => StateContainer<any>>;
+    getTypes(): StateContainerConstructor[];
     /**
      * Subscribe to lifecycle events
      * @param event - The lifecycle event to listen for
@@ -1219,25 +1280,6 @@ export declare class StateContainerRegistry {
 
 /* Excluded from this release type: StateListener */
 
-/**
- * Conditionally override the state type of a StateContainer.
- * When S is `never`, returns T unchanged (inferred state type).
- * When S is provided, replaces the state type while preserving all other properties.
- *
- * @template T - The StateContainer type
- * @template S - The state type override (defaults to never)
- *
- * @example
- * // Without override - returns original type
- * type Result1 = StateOverride<MyBloc>; // MyBloc
- *
- * // With override - replaces state type
- * type Result2 = StateOverride<MyBloc, CustomState>; // Omit<MyBloc, 'state'> & { readonly state: CustomState }
- */
-export declare type StateOverride<T extends StateContainer<any, any>, S = never> = [S] extends [never] ? T : Omit<T, 'state'> & {
-    readonly state: S;
-};
-
 /* Excluded from this release type: stopProxyTracking */
 
 /**