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

package/dist/index.d.cts

@@ -15,19 +15,6 @@ export declare interface AdapterState<TBloc extends StateContainerConstructor> {
     proxiedBloc: InstanceState<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;
-}
-
 /**
  * Decorator to configure StateContainer classes.
  *
@@ -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).
@@ -177,7 +174,7 @@ export declare interface BlacPlugin {
     /**
      * 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
      */
@@ -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
  *
@@ -425,6 +442,21 @@ export declare const debug: (context: string, message: string, data?: any) => vo
  */
 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)
  * @param context - Context identifier (module or component name)
@@ -434,19 +466,45 @@ export declare function disableGetterTracking<TBloc extends StateContainerConstr
 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.
@@ -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
@@ -535,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 */
@@ -670,6 +746,11 @@ export declare type InstanceState<T extends StateContainerConstructor = any> = O
 
 /* 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.
@@ -887,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 */
@@ -1336,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 extends object = any, 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)

package/dist/index.d.ts

@@ -15,19 +15,6 @@ export declare interface AdapterState<TBloc extends StateContainerConstructor> {
     proxiedBloc: InstanceState<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;
-}
-
 /**
  * Decorator to configure StateContainer classes.
  *
@@ -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).
@@ -177,7 +174,7 @@ export declare interface BlacPlugin {
     /**
      * 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
      */
@@ -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
  *
@@ -425,6 +442,21 @@ export declare const debug: (context: string, message: string, data?: any) => vo
  */
 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)
  * @param context - Context identifier (module or component name)
@@ -434,19 +466,45 @@ export declare function disableGetterTracking<TBloc extends StateContainerConstr
 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.
@@ -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
@@ -535,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 */
@@ -670,6 +746,11 @@ export declare type InstanceState<T extends StateContainerConstructor = any> = O
 
 /* 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.
@@ -887,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 */
@@ -1336,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 extends object = any, 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)