@blac/core 0.1.0 → 2.0.0-rc-2

package/dist/index.d.ts

@@ -0,0 +1,505 @@
+/**
+ * Main Blac class that manages the state management system.
+ * Implements a singleton pattern to ensure only one instance exists.
+ * Handles bloc lifecycle, plugin management, and instance tracking.
+ *
+ * Key responsibilities:
+ * - Managing bloc instances (creation, disposal, lookup)
+ * - Handling isolated and non-isolated blocs
+ * - Managing plugins and lifecycle events
+ * - Providing logging and debugging capabilities
+ */
+export declare class Blac {
+    /** The singleton instance of Blac */
+    static instance: Blac;
+    /** Timestamp when the instance was created */
+    createdAt: number;
+    static getAllBlocs: <B extends BlocConstructor<unknown>>(blocClass: B, options?: {
+        searchIsolated?: boolean;
+    }) => InstanceType<B>[];
+    static addPlugin: (plugin: BlacPlugin) => void;
+    /** Map storing all registered bloc instances by their class name and ID */
+    blocInstanceMap: Map<string, BlocBase<any>>;
+    /** Map storing isolated bloc instances grouped by their constructor */
+    isolatedBlocMap: Map<BlocConstructor<any>, BlocBase<any>[]>;
+    pluginList: BlacPlugin[];
+    /** Flag to control whether changes should be posted to document */
+    postChangesToDocument: boolean;
+    /**
+     * Creates a new Blac instance.
+     * @param options - Configuration options including singleton control
+     */
+    constructor(options?: {
+        __unsafe_ignore_singleton?: boolean;
+    });
+    /** Flag to enable/disable logging */
+    static enableLog: boolean;
+    /**
+     * Logs messages to console when logging is enabled
+     * @param args - Arguments to log
+     */
+    log: (...args: unknown[]) => void;
+    static log: (...args: unknown[]) => void;
+    /**
+     * Gets the singleton instance of Blac
+     * @returns The Blac instance
+     */
+    static getInstance(): Blac;
+    /**
+     * Logs a warning message
+     * @param message - Warning message
+     * @param args - Additional arguments
+     */
+    warn: (message: string, ...args: unknown[]) => void;
+    static warn: (message: string, ...args: unknown[]) => void;
+    /**
+     * Logs an error message
+     * @param message - Error message
+     * @param args - Additional arguments
+     */
+    error: (message: string, ...args: unknown[]) => void;
+    static error: (message: string, ...args: unknown[]) => void;
+    /**
+     * Resets the Blac instance to a new one, disposing non-keepAlive blocs
+     * from the old instance.
+     */
+    resetInstance: () => void;
+    static resetInstance: () => void;
+    /**
+     * Adds a plugin to the Blac instance
+     * @param plugin - The plugin to add
+     */
+    addPlugin: (plugin: BlacPlugin) => void;
+    /**
+     * Dispatches a lifecycle event to all registered plugins
+     * @param event - The lifecycle event to dispatch
+     * @param bloc - The bloc instance involved in the event
+     * @param params - Additional parameters for the event
+     */
+    dispatchEventToPlugins: (event: BlacLifecycleEvent, bloc: BlocBase<any>, params?: unknown) => void;
+    /**
+     * Dispatches a lifecycle event and handles related cleanup actions.
+     * This method is responsible for:
+     * - Logging the event
+     * - Handling bloc disposal when needed
+     * - Managing bloc consumer cleanup
+     * - Forwarding the event to plugins
+     *
+     * @param event - The lifecycle event to dispatch
+     * @param bloc - The bloc instance involved in the event
+     * @param params - Additional parameters for the event
+     */
+    dispatchEvent: (event: BlacLifecycleEvent, bloc: BlocBase<any>, params?: unknown) => void;
+    /**
+     * Disposes of a bloc instance by removing it from the appropriate registry
+     * @param bloc - The bloc instance to dispose
+     */
+    disposeBloc: (bloc: BlocBase<any>) => 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
+     * @param id - The instance ID
+     * @returns A unique key string in the format "className:id"
+     */
+    createBlocInstanceMapKey(blocClassName: string, id: BlocInstanceId): string;
+    /**
+     * Unregister a bloc instance from the main registry
+     * @param bloc - The bloc instance to unregister
+     */
+    unregisterBlocInstance(bloc: BlocBase<any>): void;
+    /**
+     * Registers a bloc instance in the main registry
+     * @param bloc - The bloc instance to register
+     */
+    registerBlocInstance(bloc: BlocBase<any>): void;
+    /**
+     * Finds a registered bloc instance by its class and ID
+     * @param blocClass - The bloc class to search for
+     * @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;
+    /**
+     * Registers an isolated bloc instance in the isolated registry
+     * @param bloc - The isolated bloc instance to register
+     */
+    registerIsolatedBlocInstance(bloc: BlocBase<any>): void;
+    /**
+     * Unregister an isolated bloc instance from the isolated registry
+     * @param bloc - The isolated bloc instance to unregister
+     */
+    unregisterIsolatedBlocInstance(bloc: BlocBase<any>): void;
+    /**
+     * Finds an isolated bloc instance by its class and ID
+     */
+    findIsolatedBlocInstance<B extends BlocConstructor<unknown>>(blocClass: B, id: BlocInstanceId): InstanceType<B> | undefined;
+    /**
+     * Creates a new bloc instance and registers it in the appropriate registry
+     * @param blocClass - The bloc class to instantiate
+     * @param id - The instance ID
+     * @param props - Properties to pass to the bloc constructor
+     * @param instanceRef - Optional reference string for the instance
+     * @returns The newly created bloc instance
+     */
+    createNewBlocInstance<B extends BlocConstructor<BlocBase<any>>>(blocClass: B, id: BlocInstanceId, options?: GetBlocOptions<InstanceType<B>>): InstanceType<B>;
+    /**
+     * Gets or creates a bloc instance based on the provided class and options.
+     * If a bloc with the given ID exists, it will be returned. Otherwise, a new instance will be created.
+     *
+     * @param blocClass - The bloc class to get or create
+     * @param options - Options including:
+     *   - id: The instance ID (defaults to class name if not provided)
+     *   - props: Properties to pass to the bloc constructor
+     *   - instanceRef: Optional reference string for the instance
+     * @returns The bloc instance
+     */
+    getBloc: <B extends BlocConstructor<BlocBase<any>>>(blocClass: B, options?: GetBlocOptions<InstanceType<B>>) => InstanceType<B>;
+    static 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
+     * @param options - Options including:
+     *   - id: The instance ID (defaults to class name if not provided)
+     *   - props: Properties to pass to the bloc constructor
+     *   - instanceRef: Optional reference string for the instance
+     */
+    getBlocOrThrow: <B extends BlocConstructor<unknown>>(blocClass: B, options?: {
+        id?: BlocInstanceId;
+        props?: InferPropsFromGeneric<B>;
+        instanceRef?: string;
+    }) => InstanceType<B>;
+    static getBlocOrThrow: <B extends BlocConstructor<unknown>>(blocClass: B, options?: {
+        id?: BlocInstanceId;
+        props?: InferPropsFromGeneric<B> | undefined;
+        instanceRef?: string;
+    }) => InstanceType<B>;
+    /**
+     * Gets all instances of a specific bloc class
+     * @param blocClass - The bloc class to search for
+     * @param options - Options including:
+     *   - 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?: {
+        searchIsolated?: boolean;
+    }) => InstanceType<B>[];
+}
+
+declare type BlacAddon = {
+    name: string;
+    onInit?: BlacAddonInit;
+    onEmit?: BlacAddonEmit;
+};
+
+declare type BlacAddonEmit = (params: {
+    oldState: unknown;
+    newState: unknown;
+    cubit: BlocBase<any>;
+}) => void;
+
+declare type BlacAddonInit = (bloc: BlocBase<any>) => void;
+
+/**
+ * Configuration options for the Blac instance
+ */
+export declare interface BlacConfig {
+    /** Whether to expose the Blac instance globally */
+    exposeBlacInstance?: boolean;
+}
+
+/**
+ * Enum representing different lifecycle events that can occur in the Blac system.
+ * These events are used to track the lifecycle of blocs and their consumers.
+ */
+export declare enum BlacLifecycleEvent {
+    BLOC_DISPOSED = "BLOC_DISPOSED",
+    BLOC_CREATED = "BLOC_CREATED",
+    LISTENER_REMOVED = "LISTENER_REMOVED",
+    LISTENER_ADDED = "LISTENER_ADDED",
+    STATE_CHANGED = "STATE_CHANGED",
+    BLOC_CONSUMER_REMOVED = "BLOC_CONSUMER_REMOVED",
+    BLOC_CONSUMER_ADDED = "BLOC_CONSUMER_ADDED"
+}
+
+/**
+ * A class that manages observers for a Bloc's state changes
+ * @template S - The type of state being observed
+ */
+export declare class BlacObservable<S = unknown> {
+    /** The Bloc instance this observable is associated with */
+    bloc: BlocBase<S>;
+    /**
+     * Creates a new BlacObservable instance
+     * @param bloc - The Bloc instance to observe
+     */
+    constructor(bloc: BlocBase<S>);
+    private _observers;
+    /**
+     * Gets the number of active observers
+     * @returns The number of observers currently subscribed
+     */
+    get size(): number;
+    /**
+     * Gets the set of all observers
+     * @returns The Set of all BlacObserver instances
+     */
+    get observers(): Set<BlacObserver<S>>;
+    /**
+     * Subscribes an observer to state changes
+     * @param observer - The observer to subscribe
+     * @returns A function that can be called to unsubscribe the observer
+     */
+    subscribe(observer: BlacObserver<S>): () => void;
+    /**
+     * Unsubscribes an observer from state changes
+     * @param observer - The observer to unsubscribe
+     */
+    unsubscribe(observer: BlacObserver<S>): void;
+    /**
+     * Notifies all observers of a state change
+     * @param newState - The new state value
+     * @param oldState - The previous state value
+     * @param action - Optional action that triggered the state change
+     */
+    notify(newState: S, oldState: S, action?: unknown): void;
+    /**
+     * Disposes of all observers and clears the observer set
+     */
+    dispose(): void;
+}
+
+/**
+ * Represents an observer that can subscribe to state changes in a Bloc
+ * @template S - The type of state being observed
+ */
+export declare type BlacObserver<S> = {
+    /** Function to be called when state changes */
+    fn: (newState: S, oldState: S, action?: unknown) => void | Promise<void>;
+    /** Optional function to determine if the observer should be notified of state changes */
+    dependencyArray?: BlocHookDependencyArrayFn<S>;
+    /** Dispose function for the observer */
+    dispose?: () => void;
+    /** Cached state values used for dependency comparison */
+    lastState?: unknown[][];
+    /** Unique identifier for the observer */
+    id: string;
+};
+
+export declare interface BlacPlugin {
+    name: string;
+    onEvent(event: BlacLifecycleEvent, bloc: BlocBase<any>, params?: unknown): void;
+}
+
+export declare abstract class Bloc<S, // State type
+A extends object, // Base Action/Event type, constrained to object
+P = unknown> extends BlocBase<S, P> {
+    readonly eventHandlers: Map<new (...args: any[]) => A, (event: A, emit: (newState: S) => void) => void | Promise<void>>;
+    /**
+     * Registers an event handler for a specific event type.
+     * This method is typically called in the constructor of a derived Bloc class.
+     * @param eventConstructor The constructor of the event to handle (e.g., LoadDataEvent).
+     * @param handler A function that processes the event and can emit new states.
+     *                The 'event' parameter in the handler will be typed to the specific eventConstructor.
+     */
+    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.
+     * @param action The action/event instance to be processed.
+     */
+    add: (action: A) => Promise<void>;
+}
+
+/**
+ * Base class for both Blocs and Cubits that provides core state management functionality.
+ * Handles state transitions, observer notifications, lifecycle management, and addon integration.
+ *
+ * @abstract This class should be extended, not instantiated directly
+ * @template S The type of state managed by this Bloc
+ * @template P The type of props that can be passed during instance creation (optional)
+ */
+export declare abstract class BlocBase<S, P = unknown> {
+    /**
+     * When true, every consumer will receive its own unique instance of this Bloc.
+     * Use this when state should not be shared between components.
+     * @default false
+     */
+    static isolated: boolean;
+    get isIsolated(): boolean;
+    /**
+     * When true, the Bloc instance persists even when there are no active consumers.
+     * Useful for maintaining state between component unmount/remount cycles.
+     * @default false
+     */
+    static keepAlive: boolean;
+    get isKeepAlive(): boolean;
+    /**
+     * Defines how dependencies are selected from the state for efficient updates.
+     * When provided, observers will only be notified when selected dependencies change.
+     */
+    defaultDependencySelector: DependencySelector<S> | undefined;
+    /* Excluded from this release type: _addons */
+    /* Excluded from this release type: _isolated */
+    /* Excluded from this release type: _observer */
+    /* Excluded from this release type: _blac */
+    /**
+     * The unique identifier for this Bloc instance.
+     * Defaults to the class name, but can be customized.
+     */
+    _id: BlocInstanceId;
+    /* Excluded from this release type: _instanceRef */
+    /* Excluded from this release type: _keepAlive */
+    /**
+     * @readonly
+     * Timestamp when this Bloc instance was created, useful for debugging and performance tracking.
+     */
+    readonly _createdAt: number;
+    /* Excluded from this release type: _state */
+    /* Excluded from this release type: _oldState */
+    /**
+     * Props passed during Bloc instance creation.
+     * Can be used to configure or parameterize the Bloc's behavior.
+     */
+    props: P | null;
+    /**
+     * Creates a new BlocBase instance with the given initial state.
+     * Sets up the observer, registers with the Blac manager, and initializes addons.
+     *
+     * @param initialState The initial state value for this Bloc
+     */
+    constructor(initialState: S);
+    /**
+     * Returns the current state of the Bloc.
+     * Use this getter to access the state in a read-only manner.
+     */
+    get state(): S;
+    /* Excluded from this release type: _name */
+    /* Excluded from this release type: _updateId */
+    /* Excluded from this release type: _dispose */
+    /* Excluded from this release type: onDispose */
+    /* Excluded from this release type: _consumers */
+    /* Excluded from this release type: _addConsumer */
+    /* Excluded from this release type: _removeConsumer */
+    /* Excluded from this release type: _connectAddons */
+    lastUpdate: number;
+    /* Excluded from this release type: _pushState */
+}
+
+/**
+ * Represents the abstract base types for Bloc and Cubit
+ */
+export declare type BlocBaseAbstract = typeof Bloc<any, any, any> | typeof Cubit<any, any>;
+
+/**
+ * Represents a constructor type for a Bloc that takes no parameters
+ * @template B - The type of the Bloc instance
+ */
+export declare type BlocClassNoParams<B> = new (args: never[]) => B;
+
+/**
+ * Represents a constructor type for a Bloc that can take any parameters
+ * @template B - The type of the Bloc instance
+ */
+export declare type BlocConstructor<B> = new (...args: any) => B;
+
+/**
+ * Extracts the constructor parameters type from a BlocBase
+ * @template B - The BlocBase type to extract the constructor parameters from
+ */
+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
+ */
+export declare type BlocHookDependencyArrayFn<S> = (newState: S) => unknown[][];
+
+export declare type BlocInstanceId = string | number | undefined;
+
+/**
+ * Extracts the state type from either a Bloc or Cubit
+ * @template T - The Bloc or Cubit type to extract the state from
+ */
+export declare type BlocState<T> = T extends BlocBase<infer S> ? S : never;
+
+/**
+ * A Cubit is a simpler version of a Bloc that doesn't handle events.
+ * It manages state and provides methods to update it.
+ * @template S - The type of state this Cubit manages
+ * @template P - The type of parameters (optional, defaults to null)
+ */
+export declare abstract class Cubit<S, P = null> extends BlocBase<S, P> {
+    /**
+     * Updates the current state and notifies all observers of the change.
+     * If the new state is identical to the current state (using Object.is),
+     * no update will occur.
+     * @param state - The new state to set
+     */
+    emit(state: S): void;
+    /**
+     * Partially updates the current state by merging it with the provided state patch.
+     * This method is only applicable when the state is an object type.
+     *
+     * @param statePatch - A partial state object containing only the properties to update
+     * @param ignoreChangeCheck - If true, skips checking if the state has actually changed
+     * @throws {TypeError} If the state is not an object type
+     */
+    patch(statePatch: S extends object ? Partial<S> : S, ignoreChangeCheck?: boolean): void;
+}
+
+declare type DependencySelector<S> = (newState: S) => unknown[][];
+
+export declare interface GetBlocOptions<B extends BlocBase<any>> {
+    id?: string;
+    selector?: BlocHookDependencyArrayFn<BlocState<B>>;
+    props?: InferPropsFromGeneric<B>;
+    onMount?: (bloc: B) => void;
+    instanceRef?: string;
+}
+
+/**
+ * Extracts the props type from either a Bloc or Cubit
+ * @template T - The Bloc or Cubit type to extract the props from
+ */
+export declare type InferPropsFromGeneric<T> = T extends Bloc<any, any, infer P> ? P : T extends Cubit<any, infer P> ? P : never;
+
+/**
+ * Persist addon
+ *
+ * @param options
+ * @returns BlacAddon
+ */
+export declare function Persist(options?: {
+    /**
+     * @default 'blac'
+     */
+    keyPrefix?: string;
+    /**
+     * @default the bloc's id
+     */
+    keyName?: string;
+    /**
+     * Used when the value is not found in storage
+     */
+    defaultValue?: unknown;
+    /**
+     * @default 'localStorage'
+     * @see StorageType
+     */
+    storageType?: StorageType;
+    /**
+     * @default false
+     */
+    onError?: (e: unknown) => void;
+}): BlacAddon;
+
+declare type StorageType = 'localStorage' | 'sessionStorage';
+
+/**
+ * Extracts the state type from a BlocBase instance
+ * @template B - The BlocBase type to extract the state from
+ */
+export declare type ValueType<B extends BlocBase<any>> = B extends BlocBase<infer U> ? U : never;
+
+export { }