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

package/dist/index.cjs

@@ -276,6 +276,8 @@ var PluginManager = class {
 };
 /**
 * Create a plugin manager instance
+* @param registry - The StateContainerRegistry to monitor for lifecycle events
+* @returns A new PluginManager instance
 */
 function createPluginManager(registry) {
 	return new PluginManager(registry);
@@ -527,22 +529,28 @@ function getStaticProp(Type, propName, defaultValue) {
 	return Type[propName] ?? defaultValue;
 }
 /**
-* 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`
 */
 function isIsolatedClass(Type) {
 	return getStaticProp(Type, BLAC_STATIC_PROPS.ISOLATED) === true;
 }
 /**
-* 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`
 */
 function isKeepAliveClass(Type) {
 	return getStaticProp(Type, BLAC_STATIC_PROPS.KEEP_ALIVE) === true;
 }
 /**
-* 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`
 */
 function isExcludedFromDevTools(Type) {
 	return getStaticProp(Type, BLAC_STATIC_PROPS.EXCLUDE_FROM_DEVTOOLS) === true;
@@ -604,97 +612,111 @@ var StateContainerRegistry = class {
 	getInstancesMap(Type) {
 		return this.instancesByConstructor.get(Type) || /* @__PURE__ */ new Map();
 	}
+	trackExecutionContext(instance) {
+		const context = getGetterExecutionContext();
+		if (context.tracker && context.currentBloc && context.currentBloc !== instance) context.tracker.externalDependencies.add(instance);
+	}
 	/**
-	* 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(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, constructorArgs) {
+	resolve(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, options = {}) {
+		const { canCreate = true, countRef = true, props, trackExecutionContext = false } = options;
 		const registryConfig = this.typeConfigs.get(Type.name);
 		const isolated = isIsolatedClass(Type) || registryConfig?.isolated === true;
 		const config = { instanceId: instanceKey };
+		if (isolated && !canCreate) throw new Error(`${BLAC_ERROR_PREFIX} Cannot get isolated instance "${instanceKey}" of ${Type.name} when creation is disabled.`);
 		if (isolated) {
-			const instance$1 = new Type(constructorArgs);
+			const instance$1 = new Type(props);
 			instance$1.initConfig(config);
 			this.registerType(Type);
+			if (trackExecutionContext) this.trackExecutionContext(instance$1);
 			return instance$1;
 		}
 		const instances = this.ensureInstancesMap(Type);
 		const entry = instances.get(instanceKey);
+		if (entry && (countRef || entry.refCount === 0)) entry.refCount++;
 		if (entry) {
-			entry.refCount++;
+			if (trackExecutionContext) this.trackExecutionContext(entry.instance);
 			return entry.instance;
 		}
-		const instance = new Type(constructorArgs);
+		if (!canCreate) throw new Error(`${BLAC_ERROR_PREFIX} ${Type.name} instance "${instanceKey}" not found and creation is disabled.`);
+		const instance = new Type(props);
 		instance.initConfig(config);
 		instances.set(instanceKey, {
 			instance,
 			refCount: 1
 		});
 		this.registerType(Type);
+		if (trackExecutionContext) this.trackExecutionContext(instance);
 		return instance;
 	}
 	/**
-	* 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(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
-		const entry = this.ensureInstancesMap(Type).get(instanceKey);
-		if (!entry) throw new Error(`${BLAC_ERROR_PREFIX} ${Type.name} instance "${instanceKey}" not found.\nUse .resolve() to create and claim ownership, or .getSafe() for conditional access.`);
-		const context = getGetterExecutionContext();
-		if (context.tracker && context.currentBloc && context.currentBloc !== entry.instance) context.tracker.externalDependencies.add(entry.instance);
-		return entry.instance;
+		return this.resolve(Type, instanceKey, {
+			canCreate: false,
+			trackExecutionContext: true
+		});
 	}
 	/**
-	* 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(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
-		const entry = this.ensureInstancesMap(Type).get(instanceKey);
-		if (!entry) return {
-			error: /* @__PURE__ */ new Error(`${BLAC_ERROR_PREFIX} ${Type.name} instance "${instanceKey}" not found`),
-			instance: null
-		};
-		const context = getGetterExecutionContext();
-		if (context.tracker && context.currentBloc && context.currentBloc !== entry.instance) context.tracker.externalDependencies.add(entry.instance);
-		return {
-			error: null,
-			instance: entry.instance
-		};
+		try {
+			return {
+				error: null,
+				instance: this.get(Type, instanceKey)
+			};
+		} catch (error$1) {
+			return {
+				error: error$1,
+				instance: null
+			};
+		}
 	}
 	/**
-	* 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(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, constructorArgs) {
-		const registryConfig = this.typeConfigs.get(Type.name);
-		if (isIsolatedClass(Type) || registryConfig?.isolated === true) throw new Error(`${BLAC_ERROR_PREFIX} Cannot use .connect() with isolated bloc "${Type.name}".\nIsolated blocs are component-scoped. Use .resolve() in components instead.`);
-		const instances = this.ensureInstancesMap(Type);
-		let entry = instances.get(instanceKey);
-		if (!entry) {
-			const instance = new Type(constructorArgs);
-			const config = { instanceId: instanceKey };
-			instance.initConfig(config);
-			entry = {
-				instance,
-				refCount: 1
-			};
-			instances.set(instanceKey, entry);
-			this.registerType(Type);
-		}
-		const context = getGetterExecutionContext();
-		if (context.tracker && context.currentBloc && context.currentBloc !== entry.instance) context.tracker.externalDependencies.add(entry.instance);
-		return entry.instance;
+	connect(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+		return this.resolve(Type, instanceKey, {
+			canCreate: true,
+			countRef: false,
+			trackExecutionContext: true
+		});
 	}
 	/**
-	* 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(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, forceDispose = false) {
 		const instances = this.ensureInstancesMap(Type);
@@ -713,7 +735,9 @@ var StateContainerRegistry = class {
 		}
 	}
 	/**
-	* 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(Type) {
 		const instances = this.ensureInstancesMap(Type);
@@ -722,7 +746,10 @@ var StateContainerRegistry = class {
 		return result;
 	}
 	/**
-	* 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(Type, callback) {
 		const instances = this.ensureInstancesMap(Type);
@@ -736,7 +763,8 @@ var StateContainerRegistry = class {
 		}
 	}
 	/**
-	* Clear all instances of a specific type
+	* Clear all instances of a specific type (disposes them).
+	* @param Type - The StateContainer class constructor
 	*/
 	clear(Type) {
 		const instances = this.ensureInstancesMap(Type);
@@ -744,13 +772,19 @@ var StateContainerRegistry = class {
 		instances.clear();
 	}
 	/**
-	* 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(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
 		return this.ensureInstancesMap(Type).get(instanceKey)?.refCount ?? 0;
 	}
 	/**
-	* 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(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
 		return this.ensureInstancesMap(Type).has(instanceKey);
@@ -767,7 +801,8 @@ var StateContainerRegistry = class {
 		this.typeConfigs.clear();
 	}
 	/**
-	* Get registry statistics (for debugging)
+	* Get registry statistics for debugging.
+	* @returns Object with registeredTypes, totalInstances, and typeBreakdown
 	*/
 	getStats() {
 		const typeBreakdown = {};
@@ -785,7 +820,8 @@ var StateContainerRegistry = class {
 		};
 	}
 	/**
-	* Get all registered types (for plugin system)
+	* Get all registered types (for plugin system).
+	* @returns Array of all registered StateContainer class constructors
 	*/
 	getTypes() {
 		return Array.from(this.types);
@@ -890,11 +926,11 @@ var StateContainer = class StateContainer {
 	* @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(instanceKey, constructorArgs) {
-		return StateContainer._registry.resolve(this, instanceKey, constructorArgs);
+	static resolve(instanceKey, options) {
+		return StateContainer._registry.resolve(this, instanceKey, options);
 	}
 	/**
 	* Get an existing instance without incrementing ref count (borrowing semantics).
@@ -920,14 +956,14 @@ var StateContainer = class StateContainer {
 	/**
 	* 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(instanceKey, constructorArgs) {
-		return StateContainer._registry.connect(this, instanceKey, constructorArgs);
+	static connect(instanceKey) {
+		return StateContainer._registry.connect(this, instanceKey);
 	}
 	/**
 	* Release a reference to an instance.