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

package/dist/index.d.cts

@@ -200,14 +200,14 @@ export declare interface BlacPluginWithInit extends BlacPlugin {
  * @template TBloc - The StateContainer instance type
  */
 export declare type BlocConstructor<TBloc extends StateContainer<any, any>> = (new (...args: any[]) => TBloc) & {
-    resolve(instanceKey?: string, ...args: any[]): TBloc;
-    get(instanceKey?: string): TBloc;
-    getSafe(instanceKey?: string): {
+    resolve<S = never>(instanceKey?: string, ...args: any[]): StateOverride<TBloc, S>;
+    get<S = never>(instanceKey?: string): StateOverride<TBloc, S>;
+    getSafe<S = never>(instanceKey?: string): {
         error: Error;
         instance: null;
     } | {
         error: null;
-        instance: TBloc;
+        instance: StateOverride<TBloc, S>;
     };
     release(instanceKey?: string): void;
     isolated?: boolean;
@@ -923,59 +923,67 @@ export declare abstract class StateContainer<S, P = undefined> {
     /**
      * 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
      * @returns The state container instance
      */
-    static resolve<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    static resolve<S = never, T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): StateOverride<T, S>;
     /**
      * Get an existing instance without incrementing ref count (borrowing semantics).
+     * @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')
      * @returns The state container instance
      * @throws Error if instance doesn't exist
      */
-    static get<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): T;
+    static get<S = never, T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): StateOverride<T, S>;
     /**
      * Safely get an existing instance with error handling.
+     * @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')
      * @returns Discriminated union with either the instance or an error
      */
-    static getSafe<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): {
+    static getSafe<S = never, T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): {
         error: Error;
         instance: null;
     } | {
         error: null;
-        instance: T;
+        instance: StateOverride<T, S>;
     };
     /**
      * Connect to an instance for bloc-to-bloc communication (borrowing semantics).
      * Gets or creates instance without incrementing 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
      * @returns The state container instance
      */
-    static connect<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    static connect<S = never, T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): StateOverride<T, S>;
     /**
      * 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>>(this: new (...args: any[]) => T, instanceKey?: string, forceDispose?: boolean): void;
+    static release<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, forceDispose?: boolean): void;
     /**
      * Get all instances of this class
      * @returns Array of all instances
      */
-    static getAll<T extends StateContainer<any>>(this: new (...args: any[]) => T): T[];
+    static getAll<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T): T[];
     /**
      * Iterate over all instances of this class
      * @param callback - Function to call for each instance
      */
-    static forEach<T extends StateContainer<any>>(this: new (...args: any[]) => T, callback: (instance: T) => void): void;
+    static forEach<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, callback: (instance: T) => void): void;
     /**
      * Clear all instances of this class (disposes them)
      */
-    static clear<T extends StateContainer<any>>(this: new (...args: any[]) => T): void;
+    static clear<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T): void;
     /**
      * Clear all instances from all registered types
      */
@@ -994,13 +1002,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>>(this: new (...args: any[]) => T, instanceKey?: string): number;
+    static getRefCount<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => 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>>(this: new (...args: any[]) => T, instanceKey?: string): boolean;
+    static hasInstance<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): boolean;
     private _state;
     private readonly listeners;
     private _disposed;
@@ -1211,6 +1219,25 @@ 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 */
 
 /**

package/dist/index.d.ts

@@ -200,14 +200,14 @@ export declare interface BlacPluginWithInit extends BlacPlugin {
  * @template TBloc - The StateContainer instance type
  */
 export declare type BlocConstructor<TBloc extends StateContainer<any, any>> = (new (...args: any[]) => TBloc) & {
-    resolve(instanceKey?: string, ...args: any[]): TBloc;
-    get(instanceKey?: string): TBloc;
-    getSafe(instanceKey?: string): {
+    resolve<S = never>(instanceKey?: string, ...args: any[]): StateOverride<TBloc, S>;
+    get<S = never>(instanceKey?: string): StateOverride<TBloc, S>;
+    getSafe<S = never>(instanceKey?: string): {
         error: Error;
         instance: null;
     } | {
         error: null;
-        instance: TBloc;
+        instance: StateOverride<TBloc, S>;
     };
     release(instanceKey?: string): void;
     isolated?: boolean;
@@ -923,59 +923,67 @@ export declare abstract class StateContainer<S, P = undefined> {
     /**
      * 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
      * @returns The state container instance
      */
-    static resolve<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    static resolve<S = never, T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): StateOverride<T, S>;
     /**
      * Get an existing instance without incrementing ref count (borrowing semantics).
+     * @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')
      * @returns The state container instance
      * @throws Error if instance doesn't exist
      */
-    static get<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): T;
+    static get<S = never, T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): StateOverride<T, S>;
     /**
      * Safely get an existing instance with error handling.
+     * @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')
      * @returns Discriminated union with either the instance or an error
      */
-    static getSafe<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): {
+    static getSafe<S = never, T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): {
         error: Error;
         instance: null;
     } | {
         error: null;
-        instance: T;
+        instance: StateOverride<T, S>;
     };
     /**
      * Connect to an instance for bloc-to-bloc communication (borrowing semantics).
      * Gets or creates instance without incrementing 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
      * @returns The state container instance
      */
-    static connect<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    static connect<S = never, T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): StateOverride<T, S>;
     /**
      * 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>>(this: new (...args: any[]) => T, instanceKey?: string, forceDispose?: boolean): void;
+    static release<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, forceDispose?: boolean): void;
     /**
      * Get all instances of this class
      * @returns Array of all instances
      */
-    static getAll<T extends StateContainer<any>>(this: new (...args: any[]) => T): T[];
+    static getAll<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T): T[];
     /**
      * Iterate over all instances of this class
      * @param callback - Function to call for each instance
      */
-    static forEach<T extends StateContainer<any>>(this: new (...args: any[]) => T, callback: (instance: T) => void): void;
+    static forEach<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, callback: (instance: T) => void): void;
     /**
      * Clear all instances of this class (disposes them)
      */
-    static clear<T extends StateContainer<any>>(this: new (...args: any[]) => T): void;
+    static clear<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T): void;
     /**
      * Clear all instances from all registered types
      */
@@ -994,13 +1002,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>>(this: new (...args: any[]) => T, instanceKey?: string): number;
+    static getRefCount<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => 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>>(this: new (...args: any[]) => T, instanceKey?: string): boolean;
+    static hasInstance<T extends StateContainer<any> = StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): boolean;
     private _state;
     private readonly listeners;
     private _disposed;
@@ -1211,6 +1219,25 @@ 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 */
 
 /**

package/dist/index.js

@@ -886,6 +886,8 @@ var StateContainer = class StateContainer {
 	/**
 	* 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
 	* @returns The state container instance
@@ -895,6 +897,8 @@ var StateContainer = class StateContainer {
 	}
 	/**
 	* Get an existing instance without incrementing ref count (borrowing semantics).
+	* @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')
 	* @returns The state container instance
 	* @throws Error if instance doesn't exist
@@ -904,6 +908,8 @@ var StateContainer = class StateContainer {
 	}
 	/**
 	* Safely get an existing instance with error handling.
+	* @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')
 	* @returns Discriminated union with either the instance or an error
 	*/
@@ -913,6 +919,8 @@ var StateContainer = class StateContainer {
 	/**
 	* Connect to an instance for bloc-to-bloc communication (borrowing semantics).
 	* Gets or creates instance without incrementing 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
 	* @returns The state container instance