@blac/core 2.0.11 → 2.0.13

package/dist/StateContainerRegistry-D1lVJFGL.cjs

@@ -0,0 +1,693 @@
+//#region src/constants.ts
+/**
+* Default configuration constants for BlaC
+*
+* Centralized location for all magic numbers and default values.
+*/
+/**
+* Default configuration constants for BlaC
+*/
+const BLAC_DEFAULTS = {
+	DEFAULT_INSTANCE_KEY: "default",
+	MAX_GETTER_DEPTH: 10
+};
+/**
+* Static property names for StateContainer classes
+* Used for feature flags and configuration on bloc classes
+*/
+const BLAC_STATIC_PROPS = {
+	KEEP_ALIVE: "keepAlive",
+	EXCLUDE_FROM_DEVTOOLS: "__excludeFromDevTools"
+};
+/**
+* Standard error message prefix
+*/
+const BLAC_ERROR_PREFIX = "[BlaC]";
+//#endregion
+//#region src/plugin/PluginManager.ts
+/**
+* Manages plugin lifecycle for the BlaC state management system.
+* Plugins receive notifications about state container lifecycle events.
+*
+* @example
+* ```ts
+* const manager = createPluginManager(registry);
+* manager.install(myPlugin, { environment: 'development' });
+* ```
+*/
+var PluginManager = class {
+	/**
+	* Create a new PluginManager
+	* @param registry - The StateContainerRegistry to monitor for lifecycle events
+	*/
+	constructor(registry) {
+		this.plugins = /* @__PURE__ */ new Map();
+		this.lifecycleUnsubscribers = [];
+		this.registry = registry;
+		this.setupLifecycleHooks();
+	}
+	/**
+	* Install a plugin with optional configuration
+	* @param plugin - The plugin to install
+	* @param config - Optional plugin configuration
+	* @throws Error if plugin is already installed
+	*/
+	install(plugin, config = {}) {
+		const effectiveConfig = {
+			enabled: true,
+			environment: "all",
+			...config
+		};
+		if (!this.shouldEnablePlugin(effectiveConfig)) {
+			console.log(`[BlaC] Plugin "${plugin.name}" skipped (environment mismatch)`);
+			return;
+		}
+		if (this.plugins.has(plugin.name)) throw new Error(`Plugin "${plugin.name}" is already installed`);
+		const context = this.createPluginContext();
+		this.plugins.set(plugin.name, {
+			plugin,
+			config: effectiveConfig,
+			context
+		});
+		if (plugin.onInstall) try {
+			plugin.onInstall(context);
+		} catch (error) {
+			console.error(`[BlaC] Error installing plugin "${plugin.name}":`, error);
+			this.plugins.delete(plugin.name);
+			throw error;
+		}
+		console.log(`[BlaC] Plugin "${plugin.name}" v${plugin.version} installed`);
+	}
+	/**
+	* Uninstall a plugin by name
+	* @param pluginName - The name of the plugin to uninstall
+	* @throws Error if plugin is not installed
+	*/
+	uninstall(pluginName) {
+		const installed = this.plugins.get(pluginName);
+		if (!installed) throw new Error(`Plugin "${pluginName}" is not installed`);
+		if (installed.plugin.onUninstall) try {
+			installed.plugin.onUninstall();
+		} catch (error) {
+			console.error(`[BlaC] Error uninstalling plugin "${pluginName}":`, error);
+		}
+		this.plugins.delete(pluginName);
+		console.log(`[BlaC] Plugin "${pluginName}" uninstalled`);
+	}
+	/**
+	* Get an installed plugin by name
+	* @param pluginName - The name of the plugin to retrieve
+	* @returns The plugin instance or undefined if not found
+	*/
+	getPlugin(pluginName) {
+		return this.plugins.get(pluginName)?.plugin;
+	}
+	/**
+	* Get all installed plugins
+	* @returns Array of all installed plugins
+	*/
+	getAllPlugins() {
+		return Array.from(this.plugins.values()).map((p) => p.plugin);
+	}
+	/**
+	* Check if a plugin is installed
+	* @param pluginName - The name of the plugin to check
+	* @returns true if the plugin is installed
+	*/
+	hasPlugin(pluginName) {
+		return this.plugins.has(pluginName);
+	}
+	/**
+	* Uninstall all plugins
+	*/
+	clear() {
+		for (const name of this.plugins.keys()) this.uninstall(name);
+	}
+	destroy() {
+		this.clear();
+		for (const unsub of this.lifecycleUnsubscribers) unsub();
+		this.lifecycleUnsubscribers = [];
+	}
+	/**
+	* Setup lifecycle hooks to notify plugins
+	*/
+	setupLifecycleHooks() {
+		this.lifecycleUnsubscribers = [
+			this.registry.on("created", (instance) => {
+				this.notifyPlugins("onInstanceCreated", instance);
+			}),
+			this.registry.on("stateChanged", (instance, previousState, currentState) => {
+				this.notifyPlugins("onStateChanged", instance, previousState, currentState);
+			}),
+			this.registry.on("disposed", (instance) => {
+				this.notifyPlugins("onInstanceDisposed", instance);
+			}),
+			this.registry.on("refAcquired", (instance, refId) => {
+				this.notifyPlugins("onRefAcquired", instance, refId);
+			}),
+			this.registry.on("refReleased", (instance, refId) => {
+				this.notifyPlugins("onRefReleased", instance, refId);
+			})
+		];
+	}
+	/**
+	* Notify all plugins of a lifecycle event
+	*/
+	notifyPlugins(hookName, ...args) {
+		for (const { plugin, config, context } of this.plugins.values()) {
+			if (!config.enabled) continue;
+			const hook = plugin[hookName];
+			if (typeof hook === "function") try {
+				hook.apply(plugin, [...args, context]);
+			} catch (error) {
+				console.error(`[BlaC] Error in plugin "${plugin.name}" ${hookName}:`, error);
+			}
+		}
+	}
+	/**
+	* Create plugin context with safe API access
+	*/
+	createPluginContext() {
+		return {
+			getInstanceMetadata: (instance) => {
+				return {
+					id: instance.instanceId,
+					className: instance.constructor.name,
+					isDisposed: instance.isDisposed,
+					name: instance.name,
+					createdAt: instance.createdAt,
+					state: instance.state,
+					hydrationStatus: instance.hydrationStatus,
+					isHydrated: instance.isHydrated,
+					hydrationError: instance.hydrationError,
+					changedWhileHydrating: instance.changedWhileHydrating
+				};
+			},
+			getState: (instance) => {
+				return instance.state;
+			},
+			getHydrationStatus: (instance) => {
+				return instance.hydrationStatus;
+			},
+			startHydration: (instance) => {
+				instance.beginHydration();
+			},
+			applyHydratedState: (instance, state) => {
+				return instance.applyHydratedState(state);
+			},
+			finishHydration: (instance) => {
+				instance.finishHydration();
+			},
+			failHydration: (instance, error) => {
+				instance.failHydration(error);
+			},
+			waitForHydration: (instance) => {
+				return instance.waitForHydration();
+			},
+			queryInstances: (typeClass) => {
+				return this.registry.getAll(typeClass);
+			},
+			getAllTypes: () => {
+				return this.registry.getTypes();
+			},
+			getStats: () => {
+				return this.registry.getStats();
+			},
+			getRefIds: (instanceId) => {
+				for (const Type of this.registry.getTypes()) {
+					const map = this.registry.getInstancesMap(Type);
+					for (const [, entry] of map) if (entry.instance.instanceId === instanceId) return Array.from(entry.refs.keys());
+				}
+				return [];
+			}
+		};
+	}
+	/**
+	* Check if plugin should be enabled based on environment
+	*/
+	shouldEnablePlugin(config) {
+		if (!config.enabled) return false;
+		if (config.environment === "all") return true;
+		return this.getCurrentEnvironment() === config.environment;
+	}
+	/**
+	* Get current environment
+	*/
+	getCurrentEnvironment() {
+		if (typeof process !== "undefined") {
+			if (process.env.NODE_ENV === "test") return "test";
+			if (process.env.NODE_ENV === "production") return "production";
+			return "development";
+		}
+		return "development";
+	}
+};
+/**
+* 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);
+}
+//#endregion
+//#region src/utils/static-props.ts
+/**
+* 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
+*
+* @param Type - The class constructor
+* @param propName - The property name to access
+* @param defaultValue - Optional default value if property is undefined
+* @returns The property value or default
+*/
+function getStaticProp(Type, propName, defaultValue) {
+	return Type[propName] ?? defaultValue;
+}
+/**
+* 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;
+}
+//#endregion
+//#region src/core/StateContainerRegistry.ts
+/**
+* Central registry for managing StateContainer instances.
+* Handles instance lifecycle, named ref tracking, and lifecycle event emission.
+*
+* @example
+* ```ts
+* const registry = new StateContainerRegistry();
+* const instance = registry.acquire(MyBloc);  // ownership, must release
+* const other = registry.ensure(OtherBloc);   // no ownership, bloc-to-bloc
+* registry.on('stateChanged', (container, prev, next) => {
+*   console.log('State changed:', prev, '->', next);
+* });
+* ```
+*/
+var StateContainerRegistry = class {
+	constructor() {
+		this.instancesByConstructor = /* @__PURE__ */ new WeakMap();
+		this.types = /* @__PURE__ */ new Set();
+		this.registeredTypeNames = /* @__PURE__ */ new Set();
+		this.listeners = /* @__PURE__ */ new Map();
+		this._stateChangedListenerCount = 0;
+		this._pendingStateChanges = null;
+		this._autoRefIdCounter = 0;
+	}
+	/**
+	* Register a type for lifecycle event tracking
+	* @param constructor - The StateContainer class constructor
+	*/
+	registerType(constructor) {
+		this.types.add(constructor);
+	}
+	/**
+	* Register a StateContainer class with configuration
+	* @param constructor - The StateContainer class constructor
+	* @throws Error if type is already registered
+	*/
+	register(constructor) {
+		const className = constructor.name;
+		if (this.registeredTypeNames.has(className)) throw new Error(`${BLAC_ERROR_PREFIX} Type "${className}" is already registered`);
+		this.registeredTypeNames.add(className);
+		this.registerType(constructor);
+	}
+	ensureInstancesMap(Type) {
+		let instances = this.instancesByConstructor.get(Type);
+		if (!instances) {
+			instances = /* @__PURE__ */ new Map();
+			this.instancesByConstructor.set(Type, instances);
+		}
+		return instances;
+	}
+	/**
+	* Get the instances Map for a specific class (public API for stats/debugging)
+	*/
+	getInstancesMap(Type) {
+		return this.instancesByConstructor.get(Type) || /* @__PURE__ */ new Map();
+	}
+	/**
+	* Acquire an instance with ref tracking (ownership semantics).
+	* Creates a new instance if one doesn't exist, or returns existing and adds a ref.
+	* You must call `release()` with the same refId when done.
+	* @param Type - The StateContainer class constructor
+	* @param instanceKey - Instance key (defaults to 'default')
+	* @param options - Acquisition options
+	* @param options.canCreate - Whether to create new instance if not found (default: true)
+	* @param options.countRef - Whether to add a reference (default: true)
+	* @param options.refId - Named reference ID for debugging; auto-generated if omitted
+	* @returns The state container instance
+	*/
+	acquire(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, options = {}) {
+		const { canCreate = true, countRef = true } = options;
+		const config = { instanceId: instanceKey };
+		const instances = this.ensureInstancesMap(Type);
+		let entry = instances.get(instanceKey);
+		if (entry?.instance.isDisposed) {
+			instances.delete(instanceKey);
+			entry = void 0;
+		}
+		if (entry && countRef) {
+			const refId = options.refId ?? `_auto_${this._autoRefIdCounter++}`;
+			entry.refs.set(refId, (entry.refs.get(refId) ?? 0) + 1);
+			this.emit("refAcquired", entry.instance, refId);
+		}
+		if (entry) return entry.instance;
+		if (!canCreate) throw new Error(`${BLAC_ERROR_PREFIX} ${Type.name} instance "${instanceKey}" not found and creation is disabled.`);
+		const instance = new Type();
+		instance.initConfig(config);
+		const initialRefs = /* @__PURE__ */ new Map();
+		let initialRefId;
+		if (countRef) {
+			initialRefId = options.refId ?? `_auto_${this._autoRefIdCounter++}`;
+			initialRefs.set(initialRefId, 1);
+		}
+		instances.set(instanceKey, {
+			instance,
+			refs: initialRefs
+		});
+		this.registerType(Type);
+		if (initialRefId) this.emit("refAcquired", instance, initialRefId);
+		return instance;
+	}
+	/**
+	* Borrow an existing instance without adding a ref (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
+	*/
+	borrow(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+		return this.acquire(Type, instanceKey, {
+			canCreate: false,
+			countRef: false
+		});
+	}
+	/**
+	* Safely borrow 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
+	*/
+	borrowSafe(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+		try {
+			return {
+				error: null,
+				instance: this.borrow(Type, instanceKey)
+			};
+		} catch (error) {
+			return {
+				error,
+				instance: null
+			};
+		}
+	}
+	/**
+	* Ensure an instance exists without taking ownership (for bloc-to-bloc communication).
+	* Gets existing instance OR creates it if it doesn't exist, without adding a ref.
+	* 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 added).
+	* @param Type - The StateContainer class constructor
+	* @param instanceKey - Instance key (defaults to 'default')
+	* @returns The state container instance
+	*/
+	ensure(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+		return this.acquire(Type, instanceKey, {
+			canCreate: true,
+			countRef: false
+		});
+	}
+	/**
+	* Release a reference to an instance.
+	* Removes the ref and disposes when refs is empty (unless keepAlive).
+	* Releasing an already-removed refId is a no-op (idempotent).
+	* @param Type - The StateContainer class constructor
+	* @param instanceKey - Instance key (defaults to 'default')
+	* @param forceDispose - Force immediate disposal regardless of refs
+	* @param refId - The specific ref to remove; removes one arbitrary ref if omitted
+	*/
+	release(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY, forceDispose = false, refId) {
+		const instances = this.ensureInstancesMap(Type);
+		const entry = instances.get(instanceKey);
+		if (!entry) return;
+		if (forceDispose) {
+			if (!entry.instance.isDisposed) entry.instance.dispose();
+			instances.delete(instanceKey);
+			return;
+		}
+		let releasedRefId;
+		if (refId !== void 0) {
+			const count = entry.refs.get(refId) ?? 0;
+			if (count <= 1) entry.refs.delete(refId);
+			else entry.refs.set(refId, count - 1);
+			releasedRefId = refId;
+		} else {
+			const firstKey = entry.refs.keys().next().value;
+			if (firstKey !== void 0) {
+				const count = entry.refs.get(firstKey) ?? 0;
+				if (count <= 1) entry.refs.delete(firstKey);
+				else entry.refs.set(firstKey, count - 1);
+				releasedRefId = firstKey;
+			}
+		}
+		if (releasedRefId) this.emit("refReleased", entry.instance, releasedRefId);
+		const keepAlive = isKeepAliveClass(Type);
+		if (entry.refs.size === 0 && !keepAlive) {
+			const deps = entry.instance.dependencies;
+			if (!entry.instance.isDisposed) entry.instance.dispose();
+			instances.delete(instanceKey);
+			for (const [DepType, depKey] of deps) {
+				const depInstances = this.ensureInstancesMap(DepType);
+				const depEntry = depInstances.get(depKey);
+				if (depEntry && depEntry.refs.size === 0 && !isKeepAliveClass(DepType) && !depEntry.instance.isDisposed) {
+					depEntry.instance.dispose();
+					depInstances.delete(depKey);
+				}
+			}
+		}
+	}
+	/**
+	* 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);
+		const result = [];
+		for (const entry of instances.values()) result.push(entry.instance);
+		return result;
+	}
+	/**
+	* 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);
+		for (const entry of instances.values()) {
+			const instance = entry.instance;
+			if (!instance.isDisposed) try {
+				callback(instance);
+			} catch (error) {
+				console.error(`${BLAC_ERROR_PREFIX} forEach callback error for ${Type.name}:`, error);
+			}
+		}
+	}
+	/**
+	* Clear all instances of a specific type (disposes them).
+	* @param Type - The StateContainer class constructor
+	*/
+	clear(Type) {
+		const instances = this.ensureInstancesMap(Type);
+		for (const entry of instances.values()) if (!entry.instance.isDisposed) entry.instance.dispose();
+		instances.clear();
+	}
+	/**
+	* Get reference count for an instance (number of active refs).
+	* @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)?.refs.size ?? 0;
+	}
+	/**
+	* Get all active reference IDs for an instance.
+	* @param Type - The StateContainer class constructor
+	* @param instanceKey - Instance key (defaults to 'default')
+	* @returns Array of ref ID strings (empty if instance doesn't exist)
+	*/
+	getRefIds(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
+		const instances = this.instancesByConstructor.get(Type);
+		if (!instances) return [];
+		const entry = instances.get(instanceKey);
+		return entry ? Array.from(entry.refs.keys()) : [];
+	}
+	/**
+	* 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);
+	}
+	/**
+	* Clear all instances from all types (for testing)
+	*
+	* Iterates all registered types and clears their instances.
+	* Also clears type tracking to reset the registry state.
+	*/
+	clearAll() {
+		for (const Type of this.types) this.clear(Type);
+		this.types.clear();
+		this.registeredTypeNames.clear();
+	}
+	/**
+	* Get registry statistics for debugging.
+	* @returns Object with registeredTypes, totalInstances, and typeBreakdown
+	*/
+	getStats() {
+		const typeBreakdown = {};
+		let totalInstances = 0;
+		for (const Type of this.types) {
+			const typeName = Type.name;
+			const count = this.getInstancesMap(Type).size;
+			typeBreakdown[typeName] = count;
+			totalInstances += count;
+		}
+		return {
+			registeredTypes: this.types.size,
+			totalInstances,
+			typeBreakdown
+		};
+	}
+	/**
+	* Get all registered types (for plugin system).
+	* @returns Array of all registered StateContainer class constructors
+	*/
+	getTypes() {
+		return Array.from(this.types);
+	}
+	/**
+	* Subscribe to lifecycle events
+	* @param event - The lifecycle event to listen for
+	* @param listener - The listener function to call when the event occurs
+	* @returns Unsubscribe function
+	*/
+	on(event, listener) {
+		if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
+		const instance = this.listeners.get(event);
+		if (!instance) throw new Error(`${BLAC_ERROR_PREFIX} Failed to register listener for event '${event}'`);
+		instance.add(listener);
+		if (event === "stateChanged") this._stateChangedListenerCount++;
+		return () => {
+			if (this.listeners.get(event)?.delete(listener) && event === "stateChanged") this._stateChangedListenerCount--;
+		};
+	}
+	emit(event, ...args) {
+		const listeners = this.listeners.get(event);
+		if (!listeners || listeners.size === 0) return;
+		for (const listener of listeners) try {
+			listener(...args);
+		} catch (error) {
+			console.error(`${BLAC_ERROR_PREFIX} Listener error for '${event}':`, error);
+		}
+	}
+	/**
+	* Schedule a deferred stateChanged notification via microtask.
+	* Skips entirely when no stateChanged listeners are registered.
+	* @internal - Called by StateContainer.applyState
+	*/
+	notifyStateChanged(container, previousState, newState) {
+		if (this._stateChangedListenerCount === 0) return;
+		if (!this._pendingStateChanges) {
+			this._pendingStateChanges = [];
+			queueMicrotask(() => this.flushStateChanged());
+		}
+		this._pendingStateChanges.push([
+			container,
+			previousState,
+			newState
+		]);
+	}
+	flushStateChanged() {
+		const pending = this._pendingStateChanges;
+		this._pendingStateChanges = null;
+		if (!pending) return;
+		for (const [container, prev, next] of pending) this.emit("stateChanged", container, prev, next);
+	}
+};
+/**
+* Global default registry instance
+*/
+const globalRegistry = new StateContainerRegistry();
+/**
+* Global plugin manager (initialized lazily)
+*/
+let _globalPluginManager = null;
+/**
+* Get the global plugin manager
+*/
+function getPluginManager() {
+	if (!_globalPluginManager) _globalPluginManager = createPluginManager(globalRegistry);
+	return _globalPluginManager;
+}
+//#endregion
+Object.defineProperty(exports, "BLAC_DEFAULTS", {
+	enumerable: true,
+	get: function() {
+		return BLAC_DEFAULTS;
+	}
+});
+Object.defineProperty(exports, "BLAC_ERROR_PREFIX", {
+	enumerable: true,
+	get: function() {
+		return BLAC_ERROR_PREFIX;
+	}
+});
+Object.defineProperty(exports, "BLAC_STATIC_PROPS", {
+	enumerable: true,
+	get: function() {
+		return BLAC_STATIC_PROPS;
+	}
+});
+Object.defineProperty(exports, "PluginManager", {
+	enumerable: true,
+	get: function() {
+		return PluginManager;
+	}
+});
+Object.defineProperty(exports, "StateContainerRegistry", {
+	enumerable: true,
+	get: function() {
+		return StateContainerRegistry;
+	}
+});
+Object.defineProperty(exports, "getPluginManager", {
+	enumerable: true,
+	get: function() {
+		return getPluginManager;
+	}
+});
+Object.defineProperty(exports, "globalRegistry", {
+	enumerable: true,
+	get: function() {
+		return globalRegistry;
+	}
+});
+
+//# sourceMappingURL=StateContainerRegistry-D1lVJFGL.cjs.map