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

package/dist/index.d.cts

@@ -4,7 +4,7 @@
  * Internal state for framework adapters, holding tracking and caching data.
  * @template TBloc - The state container type
  */
-export declare interface AdapterState<TBloc extends StateContainer<any>> {
+export declare interface AdapterState<TBloc extends StateContainerConstructor> {
     /** Proxy tracker for state property access tracking */
     tracker: TrackerState<ExtractState<TBloc>> | null;
     /** Cached manual dependencies for comparison */
@@ -12,20 +12,7 @@ export declare interface AdapterState<TBloc extends StateContainer<any>> {
     /** Getter tracker for computed property tracking */
     getterTracker: GetterTrackerState | null;
     /** Proxied bloc instance for auto-tracking */
-    proxiedBloc: TBloc | null;
-}
-
-/**
- * Base event interface
- * Used by Vertex for event-driven state management
- */
-export declare interface BaseEvent {
-    /** Event type identifier (typically the class name) */
-    readonly type: string;
-    /** Unix timestamp when the event was created */
-    readonly timestamp: number;
-    /** Optional source identifier for debugging */
-    readonly source?: string;
+    proxiedBloc: InstanceState<TBloc> | null;
 }
 
 /**
@@ -132,6 +119,16 @@ export declare const BLAC_STATIC_PROPS: {
     readonly EXCLUDE_FROM_DEVTOOLS: "__excludeFromDevTools";
 };
 
+/**
+ * Global configuration for @blac/core
+ */
+export declare interface BlacConfig {
+    /** Enable development mode (enables additional warnings and checks) */
+    devMode: boolean;
+    /** Logger configuration */
+    logger: Partial<LogConfig>;
+}
+
 /**
  * Configuration options for the @blac decorator.
  * Only one option can be specified at a time (union type).
@@ -173,11 +170,11 @@ export declare interface BlacPlugin {
     /**
      * Called when state changes in a container instance
      */
-    onStateChanged?<S>(instance: StateContainer<S>, previousState: S, currentState: S, callstack: string | undefined, context: PluginContext): void;
+    onStateChanged?<S extends object = any>(instance: StateContainer<S>, previousState: S, currentState: S, callstack: string | undefined, context: PluginContext): void;
     /**
      * Called when an event is added to a Vertex instance
      */
-    onEventAdded?<E extends BaseEvent>(vertex: Vertex<any, E>, event: E, context: PluginContext): void;
+    onEventAdded?<E extends DiscriminatedEvent>(vertex: Vertex<any, E>, event: EventWithMetadata<E>, context: PluginContext): void;
     /**
      * Called when a state container instance is disposed
      */
@@ -199,7 +196,7 @@ export declare interface BlacPluginWithInit extends BlacPlugin {
  * Used for type-safe hook parameters.
  * @template TBloc - The StateContainer instance type
  */
-export declare type BlocConstructor<S = any, T extends new (...args: any[]) => StateContainer<S, any> = new (...args: any[]) => StateContainer<S, any>> = (new (...args: any[]) => InstanceType<T>) & {
+export declare type BlocConstructor<S extends object = any, T extends new (...args: any[]) => StateContainer<S, any> = new (...args: any[]) => StateContainer<S, any>> = (new (...args: any[]) => InstanceType<T>) & {
     resolve(instanceKey?: string, ...args: any[]): InstanceType<T>;
     get(instanceKey?: string, ...args: any[]): InstanceType<T> | null;
     getSafe(instanceKey?: string, ...args: any[]): {
@@ -246,6 +243,26 @@ export declare type BrandedId<B> = Brand<string, B>;
 
 /* Excluded from this release type: commitTrackedGetters */
 
+/**
+ * Configure global defaults for @blac/core.
+ *
+ * @example
+ * ```ts
+ * import { configureBlac, LogLevel } from '@blac/core';
+ *
+ * configureBlac({
+ *   devMode: true,
+ *   logger: {
+ *     enabled: true,
+ *     level: LogLevel.DEBUG
+ *   }
+ * });
+ * ```
+ *
+ * @param config - Partial configuration to merge with defaults
+ */
+export declare function configureBlac(config: Partial<BlacConfig>): void;
+
 /**
  * Configuration function that recreates the default logger
  *
@@ -267,7 +284,7 @@ export declare function configureLogger(opts: Partial<LogConfig>): void;
  * @param adapterState - The adapter state for tracking
  * @returns Snapshot function for use with useSyncExternalStore
  */
-export declare function createAutoTrackSnapshot<TBloc extends StateContainer<any, any>>(instance: TBloc, adapterState: AdapterState<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+export declare function createAutoTrackSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>, adapterState: AdapterState<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
 
 /**
  * Create a subscribe function for auto-tracking mode.
@@ -276,7 +293,7 @@ export declare function createAutoTrackSnapshot<TBloc extends StateContainer<any
  * @param adapterState - The adapter state for tracking
  * @returns Subscribe function for use with useSyncExternalStore
  */
-export declare function createAutoTrackSubscribe<TBloc extends StateContainer<any, any>>(instance: TBloc, adapterState: AdapterState<TBloc>): SubscribeFunction;
+export declare function createAutoTrackSubscribe<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>, adapterState: AdapterState<TBloc>): SubscribeFunction;
 
 /* Excluded from this release type: createBlocProxy */
 
@@ -339,7 +356,7 @@ export declare function createLogger(config: LogConfig): {
  * @param config - Configuration with dependencies function
  * @returns Snapshot function for use with useSyncExternalStore
  */
-export declare function createManualDepsSnapshot<TBloc extends StateContainer<any, any>>(instance: TBloc, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SnapshotFunction<ExtractState<StateContainerConstructor>>;
+export declare function createManualDepsSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
 
 /**
  * Create a subscribe function for manual dependency tracking mode.
@@ -349,7 +366,7 @@ export declare function createManualDepsSnapshot<TBloc extends StateContainer<an
  * @param config - Configuration with dependencies function
  * @returns Subscribe function for use with useSyncExternalStore
  */
-export declare function createManualDepsSubscribe<TBloc extends StateContainer<any, any>>(instance: TBloc, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SubscribeFunction;
+export declare function createManualDepsSubscribe<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SubscribeFunction;
 
 /**
  * Create a snapshot function for no-tracking mode.
@@ -357,7 +374,7 @@ export declare function createManualDepsSubscribe<TBloc extends StateContainer<a
  * @param instance - The state container instance
  * @returns Snapshot function for use with useSyncExternalStore
  */
-export declare function createNoTrackSnapshot<TBloc extends StateContainer<any, any>>(instance: TBloc): SnapshotFunction<ExtractState<TBloc>>;
+export declare function createNoTrackSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
 
 /**
  * Create a subscribe function for no-tracking mode.
@@ -365,7 +382,7 @@ export declare function createNoTrackSnapshot<TBloc extends StateContainer<any,
  * @param instance - The state container instance
  * @returns Subscribe function for use with useSyncExternalStore
  */
-export declare function createNoTrackSubscribe<TBloc extends StateContainer<any, any>>(instance: TBloc): SubscribeFunction;
+export declare function createNoTrackSubscribe<TBloc extends StateContainerInstance>(instance: TBloc): SubscribeFunction;
 
 /**
  * Create a plugin manager instance
@@ -391,7 +408,7 @@ export declare function createPluginManager(registry: StateContainerRegistry): P
  * @template S - State type
  * @template P - Props type (optional)
  */
-export declare abstract class Cubit<S, P = undefined> extends StateContainer<S, P> {
+export declare abstract class Cubit<S extends object = any, P = undefined> extends StateContainer<S, P> {
     constructor(initialState: S);
     /**
      * Replace state with a new value and notify all listeners
@@ -423,7 +440,22 @@ export declare const debug: (context: string, message: string, data?: any) => vo
  * @param adapterState - The adapter state
  * @param rawInstance - The raw bloc instance
  */
-export declare function disableGetterTracking<TBloc extends StateContainer<any, any>>(adapterState: AdapterState<TBloc>, rawInstance: TBloc): void;
+export declare function disableGetterTracking<TBloc extends StateContainerConstructor>(adapterState: AdapterState<TBloc>, rawInstance: InstanceState<TBloc>): void;
+
+/**
+ * Base type for discriminated union events.
+ * All events must have a `type` property as the discriminator.
+ *
+ * @example
+ * ```typescript
+ * type MyEvent =
+ *   | { type: 'increment'; amount: number }
+ *   | { type: 'decrement' };
+ * ```
+ */
+export declare interface DiscriminatedEvent {
+    readonly type: string;
+}
 
 /**
  * Log an error message (tree-shakeable export)
@@ -434,19 +466,45 @@ export declare function disableGetterTracking<TBloc extends StateContainer<any,
 export declare const error: (context: string, message: string, data?: any) => void;
 
 /**
- * Constructor type for event classes
- * @template T - Event type
+ * Map of event handlers requiring exhaustive coverage.
+ * TypeScript enforces that every event type in the union has a handler.
+ *
+ * @template E - The discriminated event union type
+ * @template S - The state type
+ *
+ * @example
+ * ```typescript
+ * type CounterEvent =
+ *   | { type: 'increment'; amount: number }
+ *   | { type: 'reset' };
+ *
+ * // All event types must be handled:
+ * const handlers: EventHandlerMap<CounterEvent, { count: number }> = {
+ *   increment: (event, emit) => emit({ count: event.amount }),
+ *   reset: (_, emit) => emit({ count: 0 }),
+ * };
+ * ```
  */
-export declare type EventConstructor<T extends BaseEvent = BaseEvent> = new (...args: never[]) => T;
+export declare type EventHandlerMap<E extends DiscriminatedEvent, S extends object> = {
+    [K in EventType<E>]: VertexEventHandler<ExtractEvent<E, K>, S>;
+};
+
+/* Excluded from this release type: EventMetadata */
 
 /**
- * Handler function for processing events in Vertex
- * @template E - Event type
- * @template S - State type
- * @param event - The event being handled
- * @param emit - Function to emit new state
+ * Extract the `type` literal union from a discriminated event union.
+ *
+ * @template E - The discriminated event union type
+ *
+ * @example
+ * ```typescript
+ * type MyEvent = { type: 'a' } | { type: 'b' };
+ * type Types = EventType<MyEvent>; // 'a' | 'b'
+ * ```
  */
-export declare type EventHandler<E extends BaseEvent, S> = (event: E, emit: (state: S) => void) => void;
+export declare type EventType<E extends DiscriminatedEvent> = E['type'];
+
+/* Excluded from this release type: EventWithMetadata */
 
 /**
  * Manages subscriptions to external bloc dependencies for getter tracking.
@@ -465,7 +523,7 @@ export declare class ExternalDependencyManager {
      * @param onGetterChange - Callback to invoke when external dependency changes
      * @returns true if subscriptions were updated, false if unchanged
      */
-    updateSubscriptions(getterTracker: GetterTrackerState | null, rawInstance: StateContainer<any, any>, onGetterChange: () => void): boolean;
+    updateSubscriptions(getterTracker: GetterTrackerState | null, rawInstance: StateContainerInstance, onGetterChange: () => void): boolean;
     /**
      * Clean up all active subscriptions
      */
@@ -478,6 +536,22 @@ export declare class ExternalDependencyManager {
  */
 export declare type ExtractConstructorArgs<T> = T extends new (...args: infer P) => any ? P : never[];
 
+/**
+ * Extract a specific event variant from a union by its type.
+ *
+ * @template E - The discriminated event union type
+ * @template T - The type literal to extract
+ *
+ * @example
+ * ```typescript
+ * type MyEvent = { type: 'a'; value: number } | { type: 'b' };
+ * type EventA = ExtractEvent<MyEvent, 'a'>; // { type: 'a'; value: number }
+ * ```
+ */
+export declare type ExtractEvent<E extends DiscriminatedEvent, T extends EventType<E>> = Extract<E, {
+    type: T;
+}>;
+
 /**
  * Extract the props type from a StateContainer
  * @template T - The StateContainer type
@@ -488,7 +562,9 @@ export declare type ExtractProps<T> = T extends StateContainerConstructor<any, i
  * Extract the state type from a StateContainer
  * @template T - The StateContainer type
  */
-export declare type ExtractState<T> = T extends StateContainerConstructor<infer S, any> ? S : never;
+export declare type ExtractState<T> = T extends StateContainerConstructor<infer S, any> ? Readonly<S> : never;
+
+export declare type ExtractStateMutable<T> = T extends StateContainerConstructor<infer S, any> ? S : never;
 
 /**
  * Generate ID with timestamp, counter, and random suffix (tree-shakeable)
@@ -533,6 +609,8 @@ export declare function generateSimpleId(prefix: string, affix?: string): string
 
 /* Excluded from this release type: getActiveTracker */
 
+/* Excluded from this release type: getBlacConfig */
+
 /* Excluded from this release type: getDescriptor */
 
 /* Excluded from this release type: getGetterExecutionContext */
@@ -555,9 +633,9 @@ export declare function getStaticProp<V, T extends StateContainerConstructor = S
 
 declare interface GetterExecutionContext {
     tracker: GetterTrackerState | null;
-    currentBloc: StateContainer<any> | null;
+    currentBloc: StateContainerInstance | null;
     depth: number;
-    visitedBlocs: Set<StateContainer<any>>;
+    visitedBlocs: Set<StateContainerInstance>;
 }
 
 /* Excluded from this release type: GetterTrackerState */
@@ -596,7 +674,7 @@ export declare const info: (context: string, message: string, data?: any) => voi
  * @param instance - The state container instance
  * @returns Initialized adapter state
  */
-export declare function initAutoTrackState<TBloc extends StateContainer<any, any>>(instance: TBloc): AdapterState<TBloc>;
+export declare function initAutoTrackState<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;
 
 /**
  * Initialize adapter state for manual dependency tracking mode.
@@ -604,7 +682,7 @@ export declare function initAutoTrackState<TBloc extends StateContainer<any, any
  * @param instance - The state container instance
  * @returns Initialized adapter state
  */
-export declare function initManualDepsState<TBloc extends StateContainer<any, any>>(instance: TBloc): AdapterState<TBloc>;
+export declare function initManualDepsState<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;
 
 /**
  * Initialize adapter state for no-tracking mode.
@@ -612,7 +690,7 @@ export declare function initManualDepsState<TBloc extends StateContainer<any, an
  * @param instance - The state container instance
  * @returns Initialized adapter state
  */
-export declare function initNoTrackState<TBloc extends StateContainer<any, any>>(instance: TBloc): AdapterState<TBloc>;
+export declare function initNoTrackState<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;
 
 /**
  * Entry in the instance registry, tracking the instance and its reference count
@@ -658,8 +736,21 @@ export declare interface InstanceMetadata {
     currentState?: any;
 }
 
+export declare type InstanceReadonlyState<T extends StateContainerConstructor = any> = Omit<InstanceType<T>, 'state'> & {
+    state: ExtractState<T>;
+};
+
+export declare type InstanceState<T extends StateContainerConstructor = any> = Omit<InstanceType<T>, 'state'> & {
+    state: ExtractStateMutable<T>;
+};
+
 /* Excluded from this release type: invalidateRenderCache */
 
+/**
+ * Check if development mode is enabled.
+ */
+export declare function isDevMode(): boolean;
+
 /**
  * Check if a class should be excluded from DevTools.
  * Used to prevent infinite loops when DevTools tracks itself.
@@ -752,9 +843,9 @@ export declare enum LogLevel {
  * Configuration for manual dependency tracking mode
  * @template TBloc - The state container type
  */
-export declare interface ManualDepsConfig<TBloc extends StateContainer<any>> {
+export declare interface ManualDepsConfig<TBloc extends StateContainerConstructor> {
     /** Function that returns dependency array from state and bloc */
-    dependencies: (state: any, bloc: TBloc) => any[];
+    dependencies: (state: ExtractState<TBloc>, bloc: InstanceState<TBloc>) => any[];
 }
 
 /* Excluded from this release type: parsePath */
@@ -782,7 +873,7 @@ export declare interface PluginContext {
     /**
      * Get current state from a container
      */
-    getState<S>(instance: StateContainer<S>): S;
+    getState<S extends object = any>(instance: StateContainer<S>): S;
     /**
      * Get all instances of a specific type
      */
@@ -877,6 +968,8 @@ export declare class PluginManager {
 
 /* Excluded from this release type: ProxyTrackerState */
 
+/* Excluded from this release type: resetBlacConfig */
+
 /* Excluded from this release type: resetGetterTracker */
 
 /* Excluded from this release type: setActiveTracker */
@@ -903,17 +996,17 @@ export declare type SnapshotFunction<TState> = () => TState;
  *
  * @example
  * ```ts
- * class CounterBloc extends StateContainer<number> {
+ * class CounterBloc extends StateContainer<{ count: number }> {
  *   constructor() {
- *     super(0);
+ *     super({ count: 0 });
  *   }
  *   increment() {
- *     this.emit(this.state + 1);
+ *     this.emit({ count: this.state.count + 1 });
  *   }
  * }
  * ```
  */
-export declare abstract class StateContainer<S = any, P = any> {
+export declare abstract class StateContainer<S extends object = any, P = any> {
     /* Excluded from this release type: __excludeFromDevTools */
     /* Excluded from this release type: _registry */
     /**
@@ -990,12 +1083,12 @@ export declare abstract class StateContainer<S = any, P = any> {
      * Get all instances of this class
      * @returns Array of all instances
      */
-    static getAll<T extends StateContainerConstructor = StateContainerConstructor>(this: T): InstanceType<T>[];
+    static getAll<T extends StateContainerConstructor = StateContainerConstructor>(this: T): InstanceReadonlyState<T>[];
     /**
      * Iterate over all instances of this class
      * @param callback - Function to call for each instance
      */
-    static forEach<T extends StateContainerConstructor = StateContainerConstructor>(this: T, callback: (instance: InstanceType<T>) => void): void;
+    static forEach<T extends StateContainerConstructor = StateContainerConstructor>(this: T, callback: (instance: InstanceReadonlyState<T>) => void): void;
     /**
      * Clear all instances of this class (disposes them)
      */
@@ -1049,7 +1142,7 @@ export declare abstract class StateContainer<S = any, P = any> {
      */
     initConfig(config: StateContainerConfig): void;
     /** Current state value */
-    get state(): S;
+    get state(): Readonly<S>;
     /** Whether this instance has been disposed */
     get isDisposed(): boolean;
     /**
@@ -1116,7 +1209,11 @@ export declare interface StateContainerConfig {
  * @template S - State type managed by the container
  * @template P - Props type passed to the container
  */
-export declare type StateContainerConstructor<S = any, P = any> = new (...args: any[]) => StateContainer<S, P>;
+export declare type StateContainerConstructor<S extends object = any, P = any> = new (...args: any[]) => StateContainer<S, P>;
+
+export declare type StateContainerInstance<S extends object = any, P = any> = Omit<StateContainer<S, P>, 'state'> & {
+    state: Readonly<S>;
+};
 
 /**
  * Central registry for managing StateContainer instances.
@@ -1220,14 +1317,14 @@ export declare class StateContainerRegistry {
      * @param Type - The StateContainer class constructor
      * @returns Array of all instances
      */
-    getAll<T extends StateContainerConstructor>(Type: T): InstanceType<T>[];
+    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: InstanceType<T>) => void): void;
+    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
@@ -1322,40 +1419,76 @@ export declare interface SystemEventPayloads<S, P> {
 /* Excluded from this release type: TrackerState */
 
 /**
- * Event-driven state container that processes events to update state.
- * Use with event handlers registered via the on() method.
+ * Event-driven state container using discriminated union events.
+ * Extends StateContainer with event-based state transitions and
+ * compile-time exhaustive checking for event handlers.
  *
- * @template S - State type
- * @template E - Event type (extends BaseEvent)
+ * @template S - State type (must be an object)
+ * @template E - Event union type (discriminated by 'type' property)
  * @template P - Props type (optional)
+ *
+ * @example
+ * ```typescript
+ * type CounterEvent =
+ *   | { type: 'increment'; amount: number }
+ *   | { type: 'decrement' }
+ *   | { type: 'reset' };
+ *
+ * class CounterVertex extends Vertex<{ count: number }, CounterEvent> {
+ *   constructor() {
+ *     super({ count: 0 });
+ *     this.createHandlers({
+ *       increment: (event, emit) => {
+ *         emit({ count: this.state.count + event.amount });
+ *       },
+ *       decrement: (_, emit) => {
+ *         emit({ count: this.state.count - 1 });
+ *       },
+ *       reset: (_, emit) => {
+ *         emit({ count: 0 });
+ *       },
+ *     });
+ *   }
+ *
+ *   increment = (amount = 1) => this.add({ type: 'increment', amount });
+ * }
+ * ```
  */
-export declare abstract class Vertex<S, E extends BaseEvent = BaseEvent, P = undefined> extends StateContainer<S, P> {
-    private eventHandlers;
-    private isProcessing;
-    private eventQueue;
+export declare abstract class Vertex<S extends object = object, E extends DiscriminatedEvent = DiscriminatedEvent, P = undefined> extends StateContainer<S, P> {
+    /* Excluded from this release type: handlers */
+    /* Excluded from this release type: isProcessing */
+    /* Excluded from this release type: eventQueue */
     constructor(initialState: S);
     /**
-     * Register a handler for a specific event type
-     * @param EventClass - The event class constructor
-     * @param handler - Function to handle events of this type
+     * Register all event handlers with exhaustive type checking.
+     * TypeScript will error if any event type from the union is missing.
+     *
+     * @param handlers - Map of event type to handler function
      */
-    protected on: <T extends E>(EventClass: EventConstructor<T>, handler: EventHandler<T, S>) => void;
+    protected createHandlers(handlers: EventHandlerMap<E, S>): void;
     /**
-     * Add an event to the event stream for processing
-     * @param event - The event to process
+     * Dispatch an event for processing.
+     * Events are processed synchronously; if called during processing,
+     * the event is queued and processed after the current event completes.
+     *
+     * @param event - The event to process (must match the event union type)
      */
     add: (event: E) => void;
-    private processEvent;
-    private handleEvent;
+    /* Excluded from this release type: enrichEvent */
+    /* Excluded from this release type: processEvent */
+    /* Excluded from this release type: handleEvent */
     /**
-     * Handle errors that occur during event processing.
-     * Override this method to implement custom error handling.
+     * Called when an error occurs during event processing.
+     * Override to implement custom error handling.
+     *
      * @param _event - The event that caused the error
      * @param _error - The error that occurred
      */
-    protected onEventError(_event: E, _error: Error): void;
+    protected onEventError(_event: EventWithMetadata<E>, _error: Error): void;
 }
 
+/* Excluded from this release type: VertexEventHandler */
+
 /**
  * Log a warning message (tree-shakeable export)
  * @param context - Context identifier (module or component name)