@blac/core 2.0.0-rc.5 → 2.0.0-rc.8

package/dist/core/StateContainerRegistry.d.ts

@@ -0,0 +1,176 @@
+/**
+ * StateContainerRegistry - Centralized instance and lifecycle management
+ *
+ * Responsibilities:
+ * - Instance storage and management (WeakMap per constructor)
+ * - Type registration and tracking
+ * - Lifecycle event notifications (plugin system)
+ * - Global operations (clearAllInstances)
+ */
+import type { StateContainer } from './StateContainer';
+import type { Vertex } from './Vertex';
+/**
+ * Internal entry for instance storage
+ * Each entry tracks an instance and its reference count
+ */
+export interface InstanceEntry<T = any> {
+    instance: T;
+    refCount: number;
+}
+/**
+ * Lifecycle events that can be observed
+ */
+export type LifecycleEvent = 'created' | 'stateChanged' | 'eventAdded' | 'disposed';
+/**
+ * Listener function types for each lifecycle event
+ */
+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 'eventAdded' ? (container: Vertex<any, any>, event: any) => void : E extends 'disposed' ? (container: StateContainer<any>) => void : never;
+/**
+ * Registry for coordinating StateContainer lifecycle and managing instances
+ *
+ * Centralizes all instance management using WeakMap to ensure proper isolation.
+ */
+export declare class StateContainerRegistry {
+    /**
+     * Global storage for all instance Maps, keyed by constructor
+     *
+     * IMPORTANT: JavaScript/TypeScript static properties are inherited by reference,
+     * meaning all subclasses would share the same Map. To ensure each subclass has
+     * its own instance storage, we use a WeakMap keyed by the constructor function.
+     *
+     * This approach guarantees:
+     * - CounterBloc instances are separate from UserBloc instances
+     * - Each class owns and manages its own instances
+     * - Automatic garbage collection when classes are no longer referenced
+     */
+    private readonly instancesByConstructor;
+    /**
+     * Strong Set for tracking all registered types
+     * Used for clearAllInstances() and getStats()
+     */
+    private readonly types;
+    /**
+     * Type configurations (isolated flag)
+     */
+    private readonly typeConfigs;
+    /**
+     * Lifecycle event listeners
+     */
+    private readonly listeners;
+    /**
+     * Register a type for tracking
+     * Called automatically on first instance creation
+     */
+    registerType<T extends StateContainer<any>>(constructor: new (...args: any[]) => T): void;
+    /**
+     * Register a type with isolation mode (explicit registration)
+     */
+    register<T extends StateContainer<any>>(constructor: new (...args: any[]) => T, isolated?: boolean): void;
+    /**
+     * Get the instances Map for a specific class
+     * Creates a new Map on first access.
+     */
+    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>;
+    /**
+     * Resolve an instance with ref counting (ownership semantics)
+     */
+    resolve<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    /**
+     * Get an existing instance without ref counting (borrowing semantics)
+     * @throws Error if instance doesn't exist
+     */
+    get<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): T;
+    /**
+     * Safely get an existing instance (borrowing semantics with error handling)
+     * Returns discriminated union for type-safe conditional access
+     */
+    getSafe<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): {
+        error: Error;
+        instance: null;
+    } | {
+        error: null;
+        instance: T;
+    };
+    /**
+     * 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
+     */
+    connect<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    /**
+     * Release a reference to an instance
+     */
+    release<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string, forceDispose?: boolean): void;
+    /**
+     * Get all instances of a specific type
+     */
+    getAll<T extends StateContainer<any>>(Type: new (...args: any[]) => T): T[];
+    /**
+     * Safely iterate over all instances of a type
+     */
+    forEach<T extends StateContainer<any>>(Type: new (...args: any[]) => T, callback: (instance: T) => void): void;
+    /**
+     * Clear all instances of a specific type
+     */
+    clear<T extends StateContainer<any>>(Type: new (...args: any[]) => T): void;
+    /**
+     * Get reference count for an instance
+     */
+    getRefCount<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): number;
+    /**
+     * Check if an instance exists
+     */
+    hasInstance<T extends StateContainer<any>>(Type: new (...args: any[]) => 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)
+     */
+    getStats(): {
+        registeredTypes: number;
+        totalInstances: number;
+        typeBreakdown: Record<string, number>;
+    };
+    /**
+     * Get all registered types (for plugin system)
+     */
+    getTypes(): Array<new (...args: any[]) => StateContainer<any>>;
+    /**
+     * 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/Vertex 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;
+//# sourceMappingURL=StateContainerRegistry.d.ts.map

package/dist/core/StateContainerRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateContainerRegistry.d.ts","sourceRoot":"","sources":["../../src/core/StateContainerRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAwB,MAAM,kBAAkB,CAAC;AAC7E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAUvC;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,GAAG;IACpC,QAAQ,EAAE,CAAC,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,cAAc,GACd,YAAY,GACZ,UAAU,CAAC;AAEf;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,cAAc,IAAI,CAAC,SAAS,SAAS,GACzE,CAAC,SAAS,EAAE,cAAc,CAAC,GAAG,CAAC,KAAK,IAAI,GACxC,CAAC,SAAS,cAAc,GACtB,CACE,SAAS,EAAE,cAAc,CAAC,GAAG,CAAC,EAC9B,aAAa,EAAE,GAAG,EAClB,YAAY,EAAE,GAAG,EACjB,SAAS,CAAC,EAAE,MAAM,KACf,IAAI,GACT,CAAC,SAAS,YAAY,GACpB,CAAC,SAAS,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,GAAG,KAAK,IAAI,GACjD,CAAC,SAAS,UAAU,GAClB,CAAC,SAAS,EAAE,cAAc,CAAC,GAAG,CAAC,KAAK,IAAI,GACxC,KAAK,CAAC;AAEhB;;;;GAIG;AACH,qBAAa,sBAAsB;IACjC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAGnC;IAEJ;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAElB;IAEJ;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiC;IAE7D;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAGtB;IAEJ;;;OAGG;IACH,YAAY,CAAC,CAAC,SAAS,cAAc,CAAC,GAAG,CAAC,EACxC,WAAW,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GACrC,IAAI;IAIP;;OAEG;IACH,QAAQ,CAAC,CAAC,SAAS,cAAc,CAAC,GAAG,CAAC,EACpC,WAAW,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EACtC,QAAQ,UAAQ,GACf,IAAI;IAoBP;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAW1B;;OAEG;IACH,eAAe,CAAC,CAAC,SAAS,cAAc,CAAC,GAAG,CAAC,EAC3C,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAC9B,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC;IAI7B;;OAEG;IACH,OAAO,CAAC,CAAC,SAAS,cAAc,CAAC,GAAG,CAAC,EACnC,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAC/B,WAAW,GAAE,MAA2C,EACxD,eAAe,CAAC,EAAE,GAAG,GACpB,CAAC;IAsCJ;;;OAGG;IACH,GAAG,CAAC,CAAC,SAAS,cAAc,CAAC,GAAG,CAAC,EAC/B,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAC/B,WAAW,GAAE,MAA2C,GACvD,CAAC;IAyBJ;;;OAGG;IACH,OAAO,CAAC,CAAC,SAAS,cAAc,CAAC,GAAG,CAAC,EACnC,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAC/B,WAAW,GAAE,MAA2C,GACvD;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,QAAQ,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,QAAQ,EAAE,CAAC,CAAA;KAAE;IA2BlE;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,CAAC,SAAS,cAAc,CAAC,GAAG,CAAC,EACnC,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAC/B,WAAW,GAAE,MAA2C,EACxD,eAAe,CAAC,EAAE,GAAG,GACpB,CAAC;IA6CJ;;OAEG;IACH,OAAO,CAAC,CAAC,SAAS,cAAc,CAAC,GAAG,CAAC,EACnC,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAC/B,WAAW,GAAE,MAA2C,EACxD,YAAY,UAAQ,GACnB,IAAI;IA8BP;;OAEG;IACH,MAAM,CAAC,CAAC,SAAS,cAAc,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE;IAS3E;;OAEG;IACH,OAAO,CAAC,CAAC,SAAS,cAAc,CAAC,GAAG,CAAC,EACnC,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAC/B,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,GAC9B,IAAI;IAiBP;;OAEG;IACH,KAAK,CAAC,CAAC,SAAS,cAAc,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,IAAI;IAY3E;;OAEG;IACH,WAAW,CAAC,CAAC,SAAS,cAAc,CAAC,GAAG,CAAC,EACvC,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAC/B,WAAW,GAAE,MAA2C,GACvD,MAAM;IAMT;;OAEG;IACH,WAAW,CAAC,CAAC,SAAS,cAAc,CAAC,GAAG,CAAC,EACvC,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAC/B,WAAW,GAAE,MAA2C,GACvD,OAAO;IAKV;;;;;OAKG;IACH,QAAQ,IAAI,IAAI;IAUhB;;OAEG;IACH,QAAQ,IAAI;QACV,eAAe,EAAE,MAAM,CAAC;QACxB,cAAc,EAAE,MAAM,CAAC;QACvB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACvC;IAqBD;;OAEG;IACH,QAAQ,IAAI,KAAK,CAAC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,cAAc,CAAC,GAAG,CAAC,CAAC;IAI9D;;;;;OAKG;IACH,EAAE,CAAC,CAAC,SAAS,cAAc,EACzB,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC7B,MAAM,IAAI;IAYb;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;CAelD;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,wBAA+B,CAAC;AAO3D;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,GAAG,CAKtC"}

package/dist/core/Vertex.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Vertex - Event-driven state container (Bloc pattern)
+ *
+ * Simplified version that includes its own event handling,
+ * since events are only needed for the Vertex pattern.
+ */
+import { StateContainer } from './StateContainer';
+import { BaseEvent } from '../types/events';
+/**
+ * Event handler signature (synchronous only)
+ */
+export type EventHandler<E extends BaseEvent, S> = (event: E, emit: (state: S) => void) => void;
+/**
+ * Type-safe event constructor
+ */
+export type EventConstructor<T extends BaseEvent = BaseEvent> = new (...args: never[]) => T;
+/**
+ * Vertex is an event-driven state container (Bloc pattern)
+ *
+ * Includes its own simple event system since events are only needed
+ * for the Vertex pattern, not for the base StateContainer.
+ */
+export declare abstract class Vertex<S, E extends BaseEvent = BaseEvent> extends StateContainer<S> {
+    private eventHandlers;
+    private isProcessing;
+    private eventQueue;
+    /**
+     * Create a new Vertex
+     * @param initialState Initial state value
+     */
+    constructor(initialState: S);
+    /**
+     * Register an event handler
+     * Arrow function to maintain correct 'this' binding
+     */
+    protected on: <T extends E>(EventClass: EventConstructor<T>, handler: EventHandler<T, S>) => void;
+    /**
+     * Add an event to be processed
+     * Arrow function to maintain correct 'this' binding in React
+     */
+    add: (event: E) => void;
+    /**
+     * Process an event (synchronously)
+     */
+    private processEvent;
+    /**
+     * Handle a single event (synchronously)
+     */
+    private handleEvent;
+    /**
+     * Hook for handling event processing errors
+     */
+    protected onEventError(_event: E, _error: Error): void;
+}
+/**
+ * Example: Counter Events
+ */
+export declare class IncrementEvent implements BaseEvent {
+    readonly amount: number;
+    readonly type = "increment";
+    readonly timestamp: number;
+    constructor(amount?: number);
+}
+export declare class DecrementEvent implements BaseEvent {
+    readonly amount: number;
+    readonly type = "decrement";
+    readonly timestamp: number;
+    constructor(amount?: number);
+}
+export declare class ResetEvent implements BaseEvent {
+    readonly type = "reset";
+    readonly timestamp: number;
+}
+/**
+ * Example: Counter Vertex
+ * Demonstrates proper typing and event handling
+ */
+export declare class CounterVertex extends Vertex<number> {
+    constructor();
+    increment: (amount?: number) => void;
+    decrement: (amount?: number) => void;
+    reset: () => void;
+}
+/**
+ * Auth State and Events for testing async handlers
+ */
+export interface AuthState {
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    user: {
+        id: string;
+        name: string;
+        email: string;
+    } | null;
+    error: string | null;
+}
+export declare class LoginEvent implements BaseEvent {
+    readonly email: string;
+    readonly password: string;
+    readonly type = "login";
+    readonly timestamp: number;
+    constructor(email: string, password: string);
+}
+export declare class LogoutEvent implements BaseEvent {
+    readonly type = "logout";
+    readonly timestamp: number;
+}
+export declare class AuthVertex extends Vertex<AuthState> {
+    constructor();
+    login: (email: string, password: string) => void;
+    logout: () => void;
+}
+//# sourceMappingURL=Vertex.d.ts.map

package/dist/core/Vertex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Vertex.d.ts","sourceRoot":"","sources":["../../src/core/Vertex.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,IAAI,CACjD,KAAK,EAAE,CAAC,EACR,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KACrB,IAAI,CAAC;AAEV;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,IAAI,KAC9D,GAAG,IAAI,EAAE,KAAK,EAAE,KACb,CAAC,CAAC;AAUP;;;;;GAKG;AACH,8BAAsB,MAAM,CAC1B,CAAC,EACD,CAAC,SAAS,SAAS,GAAG,SAAS,CAC/B,SAAQ,cAAc,CAAC,CAAC,CAAC;IACzB,OAAO,CAAC,aAAa,CAAuD;IAC5E,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,UAAU,CAAW;IAE7B;;;OAGG;gBACS,YAAY,EAAE,CAAC;IAI3B;;;OAGG;IACH,SAAS,CAAC,EAAE,GAAI,CAAC,SAAS,CAAC,EACzB,YAAY,gBAAgB,CAAC,CAAC,CAAC,EAC/B,SAAS,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,KAC1B,IAAI,CAQL;IAEF;;;OAGG;IACI,GAAG,GAAI,OAAO,CAAC,KAAG,IAAI,CAK3B;IAEF;;OAEG;IACH,OAAO,CAAC,YAAY;IAsBpB;;OAEG;IACH,OAAO,CAAC,WAAW;IA8BnB;;OAEG;IACH,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,GAAG,IAAI;CAGvD;AAED;;GAEG;AACH,qBAAa,cAAe,YAAW,SAAS;aAIlB,MAAM,EAAE,MAAM;IAH1C,QAAQ,CAAC,IAAI,eAAe;IAC5B,QAAQ,CAAC,SAAS,SAAc;gBAEJ,MAAM,GAAE,MAAU;CAC/C;AAED,qBAAa,cAAe,YAAW,SAAS;aAIlB,MAAM,EAAE,MAAM;IAH1C,QAAQ,CAAC,IAAI,eAAe;IAC5B,QAAQ,CAAC,SAAS,SAAc;gBAEJ,MAAM,GAAE,MAAU;CAC/C;AAED,qBAAa,UAAW,YAAW,SAAS;IAC1C,QAAQ,CAAC,IAAI,WAAW;IACxB,QAAQ,CAAC,SAAS,SAAc;CACjC;AAED;;;GAGG;AACH,qBAAa,aAAc,SAAQ,MAAM,CAAC,MAAM,CAAC;;IAkB/C,SAAS,GAAI,eAAU,UAErB;IAEF,SAAS,GAAI,eAAU,UAErB;IAEF,KAAK,aAEH;CACH;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,eAAe,EAAE,OAAO,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACzD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,qBAAa,UAAW,YAAW,SAAS;aAIxB,KAAK,EAAE,MAAM;aACb,QAAQ,EAAE,MAAM;IAJlC,QAAQ,CAAC,IAAI,WAAW;IACxB,QAAQ,CAAC,SAAS,SAAc;gBAEd,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM;CAEnC;AAED,qBAAa,WAAY,YAAW,SAAS;IAC3C,QAAQ,CAAC,IAAI,YAAY;IACzB,QAAQ,CAAC,SAAS,SAAc;CACjC;AAED,qBAAa,UAAW,SAAQ,MAAM,CAAC,SAAS,CAAC;;IA2C/C,KAAK,GAAI,OAAO,MAAM,EAAE,UAAU,MAAM,UAEtC;IAEF,MAAM,aAEJ;CACH"}