@blac/core 2.0.4 → 2.0.6

package/dist/core/StateContainerRegistry.d.ts

@@ -0,0 +1,189 @@
+import type { StateContainer } from './StateContainer';
+import { InstanceReadonlyState, StateContainerConstructor } from '../types/utilities';
+/**
+ * Entry in the instance registry, tracking the instance and its reference count
+ * @template T - Instance type
+ */
+export interface InstanceEntry<T = any> {
+    /** The state container instance */
+    instance: T;
+    /** Number of active references to this instance */
+    refCount: number;
+}
+/**
+ * Lifecycle events emitted by the registry
+ */
+export type LifecycleEvent = 'created' | 'stateChanged' | 'disposed';
+/**
+ * Listener function type for each lifecycle event
+ * @template E - The lifecycle event type
+ */
+export type LifecycleListener<E extends LifecycleEvent> = E extends 'created' ? (container: StateContainer<any>) => void : E extends 'stateChanged' ? (container: StateContainer<any>, previousState: any, currentState: any, callstack?: string) => void : E extends 'disposed' ? (container: StateContainer<any>) => void : never;
+/**
+ * Central registry for managing StateContainer instances.
+ * Handles instance lifecycle, ref counting, 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);
+ * });
+ * ```
+ */
+export declare class StateContainerRegistry {
+    private readonly instancesByConstructor;
+    private readonly types;
+    private readonly typeConfigs;
+    private readonly listeners;
+    /**
+     * Register a type for lifecycle event tracking
+     * @param constructor - The StateContainer class constructor
+     */
+    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 StateContainerConstructor>(constructor: T, isolated?: boolean): void;
+    private ensureInstancesMap;
+    /**
+     * Get the instances Map for a specific class (public API for stats/debugging)
+     */
+    getInstancesMap<T extends StateContainerConstructor>(Type: T): Map<string, InstanceEntry>;
+    /**
+     * Acquire an instance with ref counting (ownership semantics).
+     * Creates a new instance if one doesn't exist, or returns existing and increments ref count.
+     * You must call `release()` when done to decrement the ref count.
+     * @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 increment ref count (default: true)
+     * @returns The state container instance
+     */
+    acquire<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string, options?: {
+        canCreate?: boolean;
+        countRef?: boolean;
+    }): InstanceType<T>;
+    /**
+     * Borrow 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
+     */
+    borrow<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): InstanceType<T>;
+    /**
+     * 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<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): {
+        error: Error;
+        instance: null;
+    } | {
+        error: null;
+        instance: InstanceType<T>;
+    };
+    /**
+     * Ensure an instance exists without taking ownership (for bloc-to-bloc 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 StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns The state container instance
+     */
+    ensure<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): InstanceType<T>;
+    /**
+     * 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 StateContainerConstructor>(Type: T, instanceKey?: string, forceDispose?: boolean): void;
+    /**
+     * Get all instances of a specific type.
+     * @param Type - The StateContainer class constructor
+     * @returns Array of all instances
+     */
+    getAll<T extends StateContainerConstructor>(Type: T): InstanceReadonlyState<T>[];
+    /**
+     * 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 StateContainerConstructor>(Type: T, callback: (instance: InstanceReadonlyState<T>) => void): void;
+    /**
+     * Clear all instances of a specific type (disposes them).
+     * @param Type - The StateContainer class constructor
+     */
+    clear<T extends StateContainerConstructor>(Type: T): void;
+    /**
+     * 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 StateContainerConstructor>(Type: T, instanceKey?: string): number;
+    /**
+     * 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 StateContainerConstructor>(Type: T, instanceKey?: string): boolean;
+    /**
+     * 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(): void;
+    /**
+     * Get registry statistics for debugging.
+     * @returns Object with registeredTypes, totalInstances, and typeBreakdown
+     */
+    getStats(): {
+        registeredTypes: number;
+        totalInstances: number;
+        typeBreakdown: Record<string, number>;
+    };
+    /**
+     * Get all registered types (for plugin system).
+     * @returns Array of all registered StateContainer class constructors
+     */
+    getTypes(): StateContainerConstructor[];
+    /**
+     * 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<E extends LifecycleEvent>(event: E, listener: LifecycleListener<E>): () => void;
+    /**
+     * Emit lifecycle event to all listeners
+     * @internal - Called by StateContainer lifecycle methods
+     */
+    emit(event: LifecycleEvent, ...args: any[]): void;
+}
+/**
+ * Global default registry instance
+ */
+export declare const globalRegistry: StateContainerRegistry;
+/**
+ * Get the global plugin manager
+ */
+export declare function getPluginManager(): any;

package/dist/debug.cjs

@@ -1,27 +1,12 @@
-const require_StateContainerRegistry = require('./StateContainerRegistry.cjs');
-const require_management = require('./management.cjs');
-
-//#region src/registry/config.ts
-let _registry = require_StateContainerRegistry.globalRegistry;
-function getRegistry() {
-	return _registry;
-}
-function setRegistry(registry) {
-	_registry.clearAll();
-	_registry = registry;
-}
-function getStats() {
-	return _registry.getStats();
-}
-
-//#endregion
-exports.forEach = require_management.forEach;
-exports.getAll = require_management.getAll;
-exports.getRefCount = require_management.getRefCount;
-exports.getRegistry = getRegistry;
-exports.getStats = getStats;
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_StateContainerRegistry = require("./StateContainerRegistry-CVPTMaHn.cjs");
+const require_config = require("./config-BInS_9WT.cjs");
+exports.forEach = require_config.forEach;
+exports.getAll = require_config.getAll;
+exports.getRefCount = require_config.getRefCount;
+exports.getRegistry = require_config.getRegistry;
+exports.getStats = require_config.getStats;
 exports.globalRegistry = require_StateContainerRegistry.globalRegistry;
-exports.hasInstance = require_management.hasInstance;
-exports.register = require_management.register;
-exports.setRegistry = setRegistry;
-//# sourceMappingURL=debug.cjs.map
+exports.hasInstance = require_config.hasInstance;
+exports.register = require_config.register;
+exports.setRegistry = require_config.setRegistry;

package/dist/debug.d.cts

@@ -0,0 +1,35 @@
+/**
+ * Debug/Advanced Subpath Export
+ *
+ * Advanced registry introspection and debugging utilities.
+ * Import from '@blac/core/debug'
+ *
+ * These utilities are intended for debugging, testing, and advanced use cases.
+ * Most applications don't need these - use the main '@blac/core' exports instead.
+ *
+ * @example
+ * ```typescript
+ * import { getStats, globalRegistry, hasInstance } from '@blac/core/debug';
+ *
+ * // Get registry statistics
+ * const stats = getStats();
+ * console.log(`Total instances: ${stats.totalInstances}`);
+ *
+ * // Check if an instance exists
+ * if (hasInstance(UserBloc)) {
+ *   console.log('UserBloc is registered');
+ * }
+ *
+ * // Iterate over all instances of a type
+ * forEach(UserBloc, (instance) => {
+ *   console.log(instance.state);
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { hasInstance, getRefCount, getAll, forEach } from './registry/queries';
+export { register } from './registry/management';
+export { getRegistry, setRegistry, getStats } from './registry/config';
+export { globalRegistry } from './core/StateContainerRegistry';
+export type { LifecycleEvent, LifecycleListener, InstanceEntry, } from './core/StateContainerRegistry';

package/dist/debug.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Debug/Advanced Subpath Export
+ *
+ * Advanced registry introspection and debugging utilities.
+ * Import from '@blac/core/debug'
+ *
+ * These utilities are intended for debugging, testing, and advanced use cases.
+ * Most applications don't need these - use the main '@blac/core' exports instead.
+ *
+ * @example
+ * ```typescript
+ * import { getStats, globalRegistry, hasInstance } from '@blac/core/debug';
+ *
+ * // Get registry statistics
+ * const stats = getStats();
+ * console.log(`Total instances: ${stats.totalInstances}`);
+ *
+ * // Check if an instance exists
+ * if (hasInstance(UserBloc)) {
+ *   console.log('UserBloc is registered');
+ * }
+ *
+ * // Iterate over all instances of a type
+ * forEach(UserBloc, (instance) => {
+ *   console.log(instance.state);
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { hasInstance, getRefCount, getAll, forEach } from './registry/queries';
+export { register } from './registry/management';
+export { getRegistry, setRegistry, getStats } from './registry/config';
+export { globalRegistry } from './core/StateContainerRegistry';
+export type { LifecycleEvent, LifecycleListener, InstanceEntry, } from './core/StateContainerRegistry';

package/dist/debug.js

@@ -1,19 +1,3 @@
-import { n as globalRegistry } from "./StateContainerRegistry.js";
-import { a as getAll, i as forEach, o as getRefCount, r as register, s as hasInstance } from "./management.js";
-
-//#region src/registry/config.ts
-let _registry = globalRegistry;
-function getRegistry() {
-	return _registry;
-}
-function setRegistry(registry) {
-	_registry.clearAll();
-	_registry = registry;
-}
-function getStats() {
-	return _registry.getStats();
-}
-
-//#endregion
+import { n as globalRegistry } from "./StateContainerRegistry-Brmferpf.js";
+import { c as getAll, l as getRefCount, n as getStats, o as register, r as setRegistry, s as forEach, t as getRegistry, u as hasInstance } from "./config-BmFnPVM0.js";
 export { forEach, getAll, getRefCount, getRegistry, getStats, globalRegistry, hasInstance, register, setRegistry };
-//# sourceMappingURL=debug.js.map

package/dist/decorators/blac.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Configuration options for the @blac decorator.
+ * Only one option can be specified at a time (union type).
+ */
+export type BlacOptions = 
+/** Mark bloc as isolated (each component gets its own instance) */
+{
+    isolated: true;
+}
+/** Mark bloc to never be auto-disposed when ref count reaches 0 */
+ | {
+    keepAlive: true;
+}
+/** Exclude bloc from DevTools tracking (prevents infinite loops) */
+ | {
+    excludeFromDevTools: true;
+};
+/**
+ * Decorator to configure StateContainer classes.
+ *
+ * @example Decorator syntax (requires experimentalDecorators or TC39 decorators)
+ * ```ts
+ * @blac({ isolated: true })
+ * class FormBloc extends Cubit<FormState> {}
+ *
+ * @blac({ keepAlive: true })
+ * class AuthBloc extends Cubit<AuthState> {}
+ *
+ * @blac({ excludeFromDevTools: true })
+ * class InternalBloc extends Cubit<InternalState> {}
+ * ```
+ *
+ * @example Function syntax (no decorator support needed)
+ * ```ts
+ * const FormBloc = blac({ isolated: true })(
+ *   class extends Cubit<FormState> {}
+ * );
+ * ```
+ */
+export declare function blac(options: BlacOptions): <T extends new (...args: any[]) => any>(target: T, _context?: ClassDecoratorContext) => T;

package/dist/decorators/index.d.ts

@@ -0,0 +1 @@
+export { blac, type BlacOptions } from './blac';