@blac/core 2.0.0-rc-4 → 2.0.0-rc-6

package/dist/index.d.ts

@@ -13,13 +13,13 @@ export declare class Blac {
     static get instance(): Blac;
     /** Timestamp when the instance was created */
     createdAt: number;
-    static get getAllBlocs(): <B extends BlocConstructor<unknown>>(blocClass: B, options?: {
+    static get getAllBlocs(): <B extends BlocConstructor<any>>(blocClass: B, options?: {
         searchIsolated?: boolean;
     }) => InstanceType<B>[];
     /** Map storing all registered bloc instances by their class name and ID */
     blocInstanceMap: Map<string, BlocBase<unknown>>;
     /** Map storing isolated bloc instances grouped by their constructor */
-    isolatedBlocMap: Map<BlocConstructor<unknown>, BlocBase<unknown>[]>;
+    isolatedBlocMap: Map<BlocConstructor<any>, BlocBase<unknown>[]>;
     /** Map for O(1) lookup of isolated blocs by UID */
     private isolatedBlocIndex;
     /** Map tracking UIDs to prevent memory leaks */
@@ -73,6 +73,7 @@ export declare class Blac {
      * @param bloc - The bloc instance to dispose
      */
     disposeBloc: (bloc: BlocBase<unknown>) => void;
+    static get disposeBloc(): (bloc: BlocBase<unknown>) => void;
     /**
      * Creates a unique key for a bloc instance in the map based on the bloc class name and instance ID
      * @param blocClassName - The name of the bloc class
@@ -96,7 +97,7 @@ export declare class Blac {
      * @param id - The instance ID
      * @returns The found bloc instance or undefined if not found
      */
-    findRegisteredBlocInstance<B extends BlocConstructor<unknown>>(blocClass: B, id: BlocInstanceId): InstanceType<B> | undefined;
+    findRegisteredBlocInstance<B extends BlocConstructor<any>>(blocClass: B, id: BlocInstanceId): InstanceType<B> | undefined;
     /**
      * Registers an isolated bloc instance in the isolated registry
      * @param bloc - The isolated bloc instance to register
@@ -110,7 +111,7 @@ export declare class Blac {
     /**
      * Finds an isolated bloc instance by its class and ID (O(n) lookup)
      */
-    findIsolatedBlocInstance<B extends BlocConstructor<unknown>>(blocClass: B, id: BlocInstanceId): InstanceType<B> | undefined;
+    findIsolatedBlocInstance<B extends BlocConstructor<any>>(blocClass: B, id: BlocInstanceId): InstanceType<B> | undefined;
     /**
      * Finds an isolated bloc instance by UID (O(1) lookup)
      */
@@ -123,7 +124,7 @@ export declare class Blac {
      * @param instanceRef - Optional reference string for the instance
      * @returns The newly created bloc instance
      */
-    createNewBlocInstance<B extends BlocConstructor<BlocBase<unknown>>>(blocClass: B, id: BlocInstanceId, options?: GetBlocOptions<InstanceType<B>>): InstanceType<B>;
+    createNewBlocInstance<B extends BlocConstructor<BlocBase<any>>>(blocClass: B, id: BlocInstanceId, options?: GetBlocOptions<InstanceType<B>>): InstanceType<B>;
     activateBloc: (bloc: BlocBase<unknown>) => void;
     static get activateBloc(): (bloc: BlocBase<unknown>) => void;
     /**
@@ -137,8 +138,8 @@ export declare class Blac {
      *   - instanceRef: Optional reference string for the instance
      * @returns The bloc instance
      */
-    getBloc: <B extends BlocConstructor<BlocBase<unknown>>>(blocClass: B, options?: GetBlocOptions<InstanceType<B>>) => InstanceType<B>;
-    static get getBloc(): <B extends BlocConstructor<BlocBase<unknown>>>(blocClass: B, options?: GetBlocOptions<InstanceType<B>>) => InstanceType<B>;
+    getBloc: <B extends BlocConstructor<BlocBase<any>>>(blocClass: B, options?: GetBlocOptions<InstanceType<B>>) => InstanceType<B>;
+    static get getBloc(): <B extends BlocConstructor<BlocBase<any>>>(blocClass: B, options?: GetBlocOptions<InstanceType<B>>) => InstanceType<B>;
     /**
      * Gets a bloc instance or throws an error if it doesn't exist
      * @param blocClass - The bloc class to get
@@ -147,12 +148,12 @@ export declare class Blac {
      *   - props: Properties to pass to the bloc constructor
      *   - instanceRef: Optional reference string for the instance
      */
-    getBlocOrThrow: <B extends BlocConstructor<unknown>>(blocClass: B, options?: {
+    getBlocOrThrow: <B extends BlocConstructor<any>>(blocClass: B, options?: {
         id?: BlocInstanceId;
         props?: InferPropsFromGeneric<B>;
         instanceRef?: string;
     }) => InstanceType<B>;
-    static get getBlocOrThrow(): <B extends BlocConstructor<unknown>>(blocClass: B, options?: {
+    static get getBlocOrThrow(): <B extends BlocConstructor<any>>(blocClass: B, options?: {
         id?: BlocInstanceId;
         props?: InferPropsFromGeneric<B> | undefined;
         instanceRef?: string;
@@ -164,15 +165,15 @@ export declare class Blac {
      *   - searchIsolated: Whether to search in isolated blocs (defaults to bloc's isolated property)
      * @returns Array of matching bloc instances
      */
-    getAllBlocs: <B extends BlocConstructor<unknown>>(blocClass: B, options?: {
+    getAllBlocs: <B extends BlocConstructor<any>>(blocClass: B, options?: {
         searchIsolated?: boolean;
     }) => InstanceType<B>[];
     /**
      * Disposes all keep-alive blocs of a specific type
      * @param blocClass - The bloc class to dispose
      */
-    disposeKeepAliveBlocs: <B extends BlocConstructor<unknown>>(blocClass?: B) => void;
-    static get disposeKeepAliveBlocs(): <B extends BlocConstructor<unknown>>(blocClass?: B | undefined) => void;
+    disposeKeepAliveBlocs: <B extends BlocConstructor<any>>(blocClass?: B) => void;
+    static get disposeKeepAliveBlocs(): <B extends BlocConstructor<any>>(blocClass?: B | undefined) => void;
     /**
      * Disposes all blocs matching a pattern
      * @param predicate - Function to test each bloc for disposal
@@ -285,9 +286,11 @@ export declare type BlacObserver<S> = {
 };
 
 export declare abstract class Bloc<S, // State type
-A extends object, // Base Action/Event type, constrained to object
+A extends BlocEventConstraint = BlocEventConstraint, // Base Action/Event type with proper constraints
 P = unknown> extends BlocBase<S, P> {
     readonly eventHandlers: Map<new (...args: any[]) => A, (event: A, emit: (newState: S) => void) => void | Promise<void>>;
+    /* Excluded from this release type: _eventQueue */
+    /* Excluded from this release type: _isProcessingEvent */
     /**
      * Registers an event handler for a specific event type.
      * This method is typically called in the constructor of a derived Bloc class.
@@ -298,11 +301,12 @@ P = unknown> extends BlocBase<S, P> {
     protected on<E extends A>(eventConstructor: new (...args: any[]) => E, handler: (event: E, emit: (newState: S) => void) => void | Promise<void>): void;
     /**
      * Dispatches an action/event to the Bloc.
-     * If a handler is registered for this specific event type (via 'on'), it will be invoked.
-     * Asynchronous handlers are awaited.
+     * Events are queued and processed sequentially to prevent race conditions.
      * @param action The action/event instance to be processed.
      */
     add: (action: A) => Promise<void>;
+    /* Excluded from this release type: _processEventQueue */
+    /* Excluded from this release type: _processEvent */
 }
 
 /**
@@ -314,7 +318,7 @@ P = unknown> extends BlocBase<S, P> {
  * @template P The type of props that can be passed during instance creation (optional)
  */
 export declare abstract class BlocBase<S, P = unknown> {
-    uid: `${string}-${string}-${string}-${string}-${string}`;
+    uid: string;
     /**
      * When true, every consumer will receive its own unique instance of this Bloc.
      * Use this when state should not be shared between components.
@@ -348,6 +352,7 @@ export declare abstract class BlocBase<S, P = unknown> {
      * Timestamp when this Bloc instance was created, useful for debugging and performance tracking.
      */
     readonly _createdAt: number;
+    /* Excluded from this release type: _disposalState */
     /* Excluded from this release type: _state */
     /* Excluded from this release type: _oldState */
     /**
@@ -355,6 +360,10 @@ export declare abstract class BlocBase<S, P = unknown> {
      * Can be used to configure or parameterize the Bloc's behavior.
      */
     props: P | null;
+    /* Excluded from this release type: _batchingLock */
+    /* Excluded from this release type: _pendingUpdates */
+    /* Excluded from this release type: _consumerRefs */
+    /* Excluded from this release type: _validateConsumers */
     /**
      * Creates a new BlocBase instance with the given initial state.
      * Sets up the observer, registers with the Blac manager, and initializes addons.
@@ -372,7 +381,6 @@ export declare abstract class BlocBase<S, P = unknown> {
     /* Excluded from this release type: _dispose */
     /* Excluded from this release type: onDispose */
     /* Excluded from this release type: _consumers */
-    /* Excluded from this release type: _consumerRefs */
     /* Excluded from this release type: _addConsumer */
     /* Excluded from this release type: _removeConsumer */
     /* Excluded from this release type: _disposalHandler */
@@ -380,7 +388,6 @@ export declare abstract class BlocBase<S, P = unknown> {
     /* Excluded from this release type: _scheduleDisposal */
     lastUpdate: number;
     /* Excluded from this release type: _batchingEnabled */
-    /* Excluded from this release type: _pendingUpdates */
     /* Excluded from this release type: _pushState */
     /**
      * Enables batching for multiple state updates
@@ -413,8 +420,34 @@ export declare type BlocConstructor<B> = new (...args: any) => B;
 export declare type BlocConstructorParameters<B extends BlocBase<any>> = BlocConstructor<B> extends new (...args: infer P) => B ? P : never;
 
 /**
- * Represents a function type for determining hook dependencies based on state changes
- * @template B - The BlocGeneric type
+ * Error boundary interface for Bloc error handling
+ */
+export declare interface BlocErrorBoundary<S, A extends BlocEventConstraint> {
+    onError: (error: Error, event: A, currentState: S, bloc: {
+        name: string;
+        id: string;
+    }) => void | Promise<void>;
+    shouldRethrow?: (error: Error, event: A) => boolean;
+}
+
+/**
+ * Base interface for all Bloc events
+ * Events must be objects with a constructor to enable proper type matching
+ */
+export declare interface BlocEvent {
+    readonly type?: string;
+    readonly timestamp?: number;
+}
+
+/**
+ * Enhanced constraint for Bloc events - must be objects with proper constructor
+ */
+export declare type BlocEventConstraint = BlocEvent & object;
+
+/**
+ * Function type for determining dependencies that trigger re-renders
+ * @template S The state type
+ * @returns Array of dependency arrays - if any dependency in any array changes, a re-render is triggered
  */
 export declare type BlocHookDependencyArrayFn<S> = (newState: S) => unknown[][];
 
@@ -426,6 +459,33 @@ export declare type BlocInstanceId = string | number | undefined;
  */
 export declare type BlocState<T> = T extends BlocBase<infer S> ? S : never;
 
+/**
+ * Test utilities for Blac state management
+ */
+export declare class BlocTest {
+    private static originalInstance;
+    /**
+     * Sets up a clean test environment
+     */
+    static setUp(): void;
+    /**
+     * Tears down the test environment and restores original state
+     */
+    static tearDown(): void;
+    /**
+     * Creates a test bloc with automatic cleanup
+     */
+    static createBloc<T extends BlocBase<any>>(BlocClass: new (...args: any[]) => T, ...args: any[]): T;
+    /**
+     * Waits for a bloc to emit a specific state
+     */
+    static waitForState<T extends BlocBase<S>, S>(bloc: T, predicate: (state: S) => boolean, timeout?: number): Promise<S>;
+    /**
+     * Expects a bloc to emit specific states in order
+     */
+    static expectStates<T extends BlocBase<S>, S>(bloc: T, expectedStates: S[], timeout?: number): Promise<void>;
+}
+
 /**
  * A Cubit is a simpler version of a Bloc that doesn't handle events.
  * It manages state and provides methods to update it.
@@ -453,6 +513,16 @@ export declare abstract class Cubit<S, P = null> extends BlocBase<S, P> {
 
 declare type DependencySelector<S> = (newState: S) => unknown[][];
 
+/**
+ * Cross-platform UUID v4 generator that works in all environments including React Native/Hermes
+ * Falls back to crypto.randomUUID() when available, otherwise uses Math.random()
+ */
+/**
+ * Generates a UUID v4 string compatible with all JavaScript environments
+ * @returns A UUID v4 string in the format xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+ */
+export declare function generateUUID(): string;
+
 export declare interface GetBlocOptions<B extends BlocBase<unknown>> {
     id?: string;
     selector?: BlocHookDependencyArrayFn<BlocState<B>>;
@@ -468,6 +538,62 @@ export declare interface GetBlocOptions<B extends BlocBase<unknown>> {
  */
 export declare type InferPropsFromGeneric<T> = T extends Bloc<any, any, infer P> ? P : T extends Cubit<any, infer P> ? P : never;
 
+/**
+ * Memory leak detector for tests
+ */
+export declare class MemoryLeakDetector {
+    private initialStats;
+    constructor();
+    /**
+     * Check for memory leaks and return a report
+     */
+    checkForLeaks(): {
+        hasLeaks: boolean;
+        report: string;
+        stats: ReturnType<typeof Blac.getMemoryStats>;
+    };
+}
+
+/**
+ * Mock Bloc for testing
+ */
+export declare class MockBloc<S, A extends BlocEventConstraint = BlocEventConstraint> extends Bloc<S, A> {
+    private mockHandlers;
+    constructor(initialState: S);
+    /**
+     * Mock an event handler for testing
+     */
+    mockEventHandler<E extends A>(eventConstructor: new (...args: any[]) => E, handler: (event: E, emit: (newState: S) => void) => void | Promise<void>): void;
+    /**
+     * Get the number of registered handlers
+     */
+    getHandlerCount(): number;
+    /**
+     * Check if a handler is registered for an event type
+     */
+    hasHandler(eventConstructor: new (...args: any[]) => A): boolean;
+}
+
+/**
+ * Mock Cubit for testing
+ */
+export declare class MockCubit<S> extends Cubit<S> {
+    private stateHistory;
+    constructor(initialState: S);
+    /**
+     * Override emit to track state history
+     */
+    emit(newState: S): void;
+    /**
+     * Get the history of all states
+     */
+    getStateHistory(): S[];
+    /**
+     * Clear state history
+     */
+    clearStateHistory(): void;
+}
+
 /**
  * Sets a custom instance manager (useful for testing or advanced patterns)
  */