@blac/core 0.1.0 → 2.0.0-rc-2

package/src/BlacEvent.ts

@@ -0,0 +1,5 @@
+export default class BlacEvent<T = any> extends CustomEvent<T> {
+  constructor(type: string, eventInitDict?: CustomEventInit<T> | undefined) {
+    super(type, eventInitDict);
+  }
+}

package/src/BlacObservable.ts

@@ -0,0 +1,85 @@
+import { Blac, BlacLifecycleEvent } from './Blac';
+import { BlocBase } from './BlocBase';
+import { BlocHookDependencyArrayFn } from './types';
+
+/**
+ * Represents an observer that can subscribe to state changes in a Bloc
+ * @template S - The type of state being observed
+ */
+export 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>;
+  /** Cached state values used for dependency comparison */
+  lastState?: unknown[][];
+  /** Unique identifier for the observer */
+  id: string;
+};
+
+/**
+ * A class that manages observers for a Bloc's state changes
+ * @template S - The type of state being observed
+ */
+export 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>) {
+    this.bloc = bloc;
+  }
+
+  private _observers = new Set<BlacObserver<S>>();
+
+  /**
+   * Gets the number of active observers
+   * @returns The number of observers currently subscribed
+   */
+  get size(): number {
+    return this._observers.size;
+  }
+
+  /**
+   * Gets the set of all observers
+   * @returns The Set of all BlacObserver instances
+   */
+  get observers() {
+    return this._observers;
+  }
+
+  /**
+   * 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 {
+    this._observers.add(observer);
+    Blac.instance.dispatchEvent(BlacLifecycleEvent.LISTENER_ADDED, this.bloc, { listenerId: observer.id });
+    
+    // Immediately notify the new observer with the current state
+    // Pass current state as both newState and oldState for initial notification context
+    void observer.fn(this.bloc.state, this.bloc.state, { initialSubscription: true });
+
+    if (!observer.lastState) {
+      observer.lastState = observer.dependencyArray
+        ? observer.dependencyArray(this.bloc.state)
+        : [];
+    }
+    return () => {
+      this.unsubscribe(observer);
+    }
+  }
+
+  /**
+   * Unsubscribes an observer from state changes
+   * @param observer - The observer to unsubscribe
+   */
+  unsubscribe(observer: BlacObserver<S>) {
+    this._observers.delete(observer);
+    Blac.instance.dispatchEvent(BlacLifecycleEvent.LISTENER_REMOVED, this.bloc, { listenerId: observer.id });
+  }
+}

package/src/BlacObserver.ts

@@ -0,0 +1,129 @@
+import { Blac, BlacLifecycleEvent } from './Blac';
+import { BlocBase } from './BlocBase';
+import { BlocHookDependencyArrayFn } from './types';
+
+/**
+ * Represents an observer that can subscribe to state changes in a Bloc
+ * @template S - The type of state being observed
+ */
+export 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;
+};
+
+/**
+ * A class that manages observers for a Bloc's state changes
+ * @template S - The type of state being observed
+ */
+export 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>) {
+    this.bloc = bloc;
+  }
+
+  private _observers = new Set<BlacObserver<S>>();
+
+  /**
+   * Gets the number of active observers
+   * @returns The number of observers currently subscribed
+   */
+  get size(): number {
+    return this._observers.size;
+  }
+
+  /**
+   * Gets the set of all observers
+   * @returns The Set of all BlacObserver instances
+   */
+  get observers() {
+    return this._observers;
+  }
+
+  /**
+   * 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 {
+    this._observers.add(observer);
+    Blac.instance.dispatchEvent(BlacLifecycleEvent.LISTENER_ADDED, this.bloc, { listenerId: observer.id });
+    if (!observer.lastState) {
+      observer.lastState = observer.dependencyArray
+        ? observer.dependencyArray(this.bloc.state)
+        : [];
+    }
+    return () => {
+      this.unsubscribe(observer);
+    }
+  }
+
+  /**
+   * Unsubscribes an observer from state changes
+   * @param observer - The observer to unsubscribe
+   */
+  unsubscribe(observer: BlacObserver<S>) {
+    observer.dispose?.();
+    this._observers.delete(observer);
+    Blac.instance.dispatchEvent(BlacLifecycleEvent.LISTENER_REMOVED, this.bloc, { listenerId: observer.id });
+  }
+
+  /**
+   * 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) {
+    this._observers.forEach((observer) => {
+      let shouldUpdate = false;
+
+      if (observer.dependencyArray) {
+        const lastDependencyCheck = observer.lastState || [];
+        const newDependencyCheck = observer.dependencyArray(newState);
+
+        for (let o = 0; o < newDependencyCheck.length; o++) {
+          const partNew = newDependencyCheck[o];
+          const partOld = lastDependencyCheck[o] || [];
+          for (let i = 0; i < partNew.length; i++) {
+            if (!Object.is(partNew[i], partOld[i])) {
+              shouldUpdate = true;
+              break;
+            }
+          }
+        }
+
+        observer.lastState = newDependencyCheck;
+      } else {
+        shouldUpdate = true;
+      }
+
+      if (shouldUpdate) {
+        void observer.fn(newState, oldState, action);
+      }
+    });
+  }
+
+  /**
+   * Disposes of all observers and clears the observer set
+   */
+  dispose() {
+    this._observers.forEach((observer) => {
+      this.unsubscribe(observer);
+    });
+    this._observers.clear();
+  }
+}

package/src/BlacPlugin.ts

@@ -0,0 +1,13 @@
+import { BlacLifecycleEvent } from './Blac';
+import { BlocBase } from './BlocBase';
+
+export interface BlacPlugin {
+  name: string;
+
+  onEvent(
+    event: BlacLifecycleEvent,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    bloc: BlocBase<any>,
+    params?: unknown,
+  ): void;
+}

package/src/Bloc.ts

@@ -0,0 +1,109 @@
+import { Blac } from './Blac';
+import { BlocBase } from './BlocBase';
+
+// A should be the base type for all events this Bloc handles and must be an object type
+// to access action.constructor. Events are typically class instances.
+// P is for props, changed from any to unknown.
+export abstract class Bloc<
+    S, // State type
+    A extends object, // Base Action/Event type, constrained to object
+    P = unknown // Props type
+> extends BlocBase<S, P> {
+    // Stores handlers: Map<EventConstructor (subtype of A), HandlerFunction>
+    // The handler's event parameter will be correctly typed to the specific EventConstructor
+    // by the 'on' method's signature.
+    readonly eventHandlers: Map<
+        // Key: Constructor of a specific event E (where E extends A)
+        // Using 'any[]' for constructor arguments for broader compatibility.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        new (...args: any[]) => A,
+        // Value: Handler function. 'event: A' is used here for the stored function type.
+        // The 'on' method ensures the specific handler (event: E) is correctly typed.
+        (event: A, emit: (newState: S) => void) => void | Promise<void>
+    > = new Map();
+
+    /**
+     * 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>(
+        // Using 'any[]' for constructor arguments for broader compatibility.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        eventConstructor: new (...args: any[]) => E, 
+        handler: (event: E, emit: (newState: S) => void) => void | Promise<void>
+    ): void {
+        if (this.eventHandlers.has(eventConstructor)) {
+            // Using Blac.warn or a similar logging mechanism from BlocBase if available,
+            // otherwise console.warn. Assuming this._name and this._id are available from BlocBase.
+            Blac.warn(
+                `[Bloc ${this._name}:${String(this._id)}] Handler for event '${eventConstructor.name}' already registered. It will be overwritten.`
+            );
+        }
+        // Cast the specific handler (event: E) to a more general (event: A) for storage.
+        // This is safe because E extends A. When the handler is called with an 'action' of type A,
+        // if it was originally registered for type E, 'action' must be an instance of E.
+        this.eventHandlers.set(
+            eventConstructor,
+            handler as (event: A, emit: (newState: S) => void) => void | Promise<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.
+     */
+    public add = async (action: A): Promise<void> => {
+        // Using 'any[]' for constructor arguments for broader compatibility.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const eventConstructor = action.constructor as new (...args: any[]) => A;
+        const handler = this.eventHandlers.get(eventConstructor);
+
+        if (handler) {
+            // Define the 'emit' function that handlers will use to update state.
+            // It captures the current state ('this.state') right before each emission
+            // to provide the correct 'previousState' to _pushState.
+            const emit = (newState: S): void => {
+                const previousState = this.state; // State just before this specific emission
+                // The 'action' passed to _pushState is the original action that triggered the handler,
+                // providing context for the state change (e.g., for logging or plugins).
+                this._pushState(newState, previousState, action);
+            };
+
+            try {
+                // Await the handler in case it's an async function (e.g., performs API calls).
+                // The 'action' is passed to the handler, and due to the way 'on' is typed,
+                // the 'event' parameter within the handler function will be correctly
+                // typed to its specific class (e.g., LoadMyFeatureData).
+                await handler(action, emit);
+            } catch (error) {
+                // It's good practice to handle errors occurring within event handlers.
+                Blac.error(
+                    `[Bloc ${this._name}:${String(this._id)}] Error in event handler for '${eventConstructor.name}':`,
+                    error,
+                    "Action:", action
+                );
+                // Depending on the desired error handling strategy, you might:
+                // 1. Emit a specific error state: this.emit(new MyErrorState(error));
+                // 2. Re-throw the error: throw error;
+                // 3. Log and ignore (as done here by default).
+                // This should be decided based on application requirements.
+            }
+        } else {
+            // action.constructor.name should be safe due to 'A extends object' and common JS practice for constructors.
+            // If linting still complains, it might be overly strict for this common pattern.
+            const constructorName = (action.constructor as { name?: string }).name || 'UnnamedConstructor';
+            Blac.warn(
+                `[Bloc ${this._name}:${String(this._id)}] No handler registered for action type: '${constructorName}'. Action was:`,
+                action
+            );
+            // If no handler is found, the action is effectively ignored.
+            // Consider if this is the desired behavior or if an error should be thrown
+            // or a default handler should be invoked.
+        }
+    };
+}

package/src/BlocBase.ts

@@ -0,0 +1,248 @@
+import { Blac, BlacLifecycleEvent } from './Blac';
+import { BlacObservable } from './BlacObserver';
+import BlacAddon from './addons/BlacAddon';
+import { BlocConstructor } from './types';
+
+export type BlocInstanceId = string | number | undefined;
+type DependencySelector<S> = (newState: S) => unknown[][];
+
+// Define an interface for the static properties expected on a Bloc/Cubit constructor
+interface BlocStaticProperties {
+  isolated: boolean;
+  keepAlive: boolean;
+  addons?: BlacAddon[];
+}
+
+/**
+ * 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 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 = false;
+  get isIsolated() {
+    return this._isolated;
+  }
+  
+  /**
+   * 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 = false;
+  get isKeepAlive() {
+    return this._keepAlive;
+  }
+  
+  /**
+   * 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;
+
+  /**
+   * @internal
+   * Optional array of addons to extend the functionality of this Bloc.
+   */
+  public _addons?: BlacAddon[];
+  
+  /**
+   * @internal
+   * Indicates if this specific Bloc instance is isolated from others of the same type.
+   */
+  public _isolated = false;
+  
+  /**
+   * @internal
+   * Observable responsible for managing state listeners and notifying consumers.
+   */
+  public _observer: BlacObservable<S>;
+  
+  /**
+   * @internal
+   * Reference to the global Blac manager instance.
+   */
+  public _blac = Blac.getInstance();
+  
+  /**
+   * The unique identifier for this Bloc instance.
+   * Defaults to the class name, but can be customized.
+   */
+  public _id: BlocInstanceId;
+  
+  /**
+   * @internal
+   * Reference string used internally for tracking and debugging.
+   */
+  public _instanceRef?: string;
+  
+  /**
+   * @internal
+   * Indicates if this specific Bloc instance should be kept alive when no consumers are present.
+   */
+  public _keepAlive = false;
+  
+  /**
+   * @readonly
+   * Timestamp when this Bloc instance was created, useful for debugging and performance tracking.
+   */
+  public readonly _createdAt = Date.now();
+
+  /**
+   * @internal
+   * The current state of the Bloc.
+   */
+  public _state: S;
+  
+  /**
+   * @internal
+   * The previous state of the Bloc, maintained for comparison and history.
+   */
+  public _oldState: S | undefined;
+  
+  /**
+   * Props passed during Bloc instance creation.
+   * Can be used to configure or parameterize the Bloc's behavior.
+   */
+  public props: P | null = 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) {
+    this._state = initialState;
+    this._observer = new BlacObservable(this);
+    this._blac.dispatchEvent(BlacLifecycleEvent.BLOC_CREATED, this);
+    this._id = this.constructor.name;
+
+    // Use a type assertion for the constructor to access static properties safely
+    const constructorWithStaticProps = this.constructor as BlocConstructor<this> & BlocStaticProperties;
+
+    this._keepAlive = constructorWithStaticProps.keepAlive;
+    this._isolated = constructorWithStaticProps.isolated;
+    this._addons = constructorWithStaticProps.addons;
+
+    this._connectAddons();
+  }
+
+  /**
+   * Returns the current state of the Bloc.
+   * Use this getter to access the state in a read-only manner.
+   */
+  get state(): S {
+    return this._state;
+  }
+
+  /**
+   * @internal
+   * Returns the name of the Bloc class for identification and debugging.
+   */
+  get _name() {
+    return this.constructor.name;
+  }
+
+  /**
+   * @internal
+   * Updates the Bloc instance's ID to a new value.
+   * Only updates if the new ID is defined and different from the current one.
+   * 
+   * @param id The new ID to assign to this Bloc instance
+   */
+  _updateId = (id?: BlocInstanceId) => {
+    const originalId = this._id;
+    if (!id || id === originalId) return;
+    this._id = id;
+  };
+
+  /**
+   * @internal
+   * Cleans up resources and removes this Bloc from the system.
+   * Notifies the Blac manager and clears all observers.
+   */
+  _dispose() {
+    this._observer.dispose();
+    this._blac.dispatchEvent(BlacLifecycleEvent.BLOC_DISPOSED, this);
+    this.onDispose?.();
+  }
+
+  /**
+   * @internal
+   * Optional function to be called when the Bloc is disposed.
+   */
+  onDispose?: () => void;
+
+  /**
+   * @internal
+   * Set of consumer IDs currently listening to this Bloc's state changes.
+   */
+  _consumers = new Set<string>();
+
+  /**
+   * @internal
+   * Registers a new consumer to this Bloc instance.
+   * Notifies the Blac manager that a consumer has been added.
+   * 
+   * @param consumerId The unique ID of the consumer being added
+   */
+  _addConsumer = (consumerId: string) => {
+    this._consumers.add(consumerId);
+    this._blac.dispatchEvent(BlacLifecycleEvent.BLOC_CONSUMER_ADDED, this, { consumerId });
+  };
+
+  /**
+   * @internal
+   * Unregisters a consumer from this Bloc instance.
+   * Notifies the Blac manager that a consumer has been removed.
+   * 
+   * @param consumerId The unique ID of the consumer being removed
+   */
+  _removeConsumer = (consumerId: string) => {
+    this._blac.log(`[${this._name}:${String(this._id ?? 'default_id')}] Removing consumer: ${consumerId}`);
+    this._consumers.delete(consumerId);
+    this._blac.dispatchEvent(BlacLifecycleEvent.BLOC_CONSUMER_REMOVED, this, { consumerId });
+  };
+
+  /**
+   * @internal
+   * Initializes all registered addons for this Bloc instance.
+   * Calls the onInit lifecycle method on each addon if defined.
+   */
+  _connectAddons = () => {
+    const { _addons: addons } = this;
+    if (addons) {
+      addons.forEach(addon => {
+        addon.onInit?.(this);
+      });
+    }
+  };
+
+  lastUpdate = Date.now();
+
+  /**
+   * @internal
+   * Updates the state and notifies all observers of the change.
+   * 
+   * @param newState The new state to be set
+   * @param oldState The previous state for comparison
+   * @param action Optional metadata about what caused the state change
+   */
+  _pushState = (newState: S, oldState: S, action?: unknown): void => {
+    this._state = newState;
+    this._observer.notify(newState, oldState, action);
+    this.lastUpdate = Date.now();
+  };
+}

package/src/Cubit.ts

@@ -0,0 +1,69 @@
+import { Blac } from './Blac';
+import { BlocBase } from './BlocBase';
+
+/**
+ * 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 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 {
+    if (Object.is(state, this.state)) {
+      return;
+    }
+
+    const oldState = this.state;
+    const newState = state;
+    this._pushState(newState, oldState);
+  }
+
+  /**
+   * 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 = false,
+  ): void {
+    if (typeof this.state !== 'object' || this.state === null) {
+      Blac.warn(
+        'Cubit.patch: was called on a cubit where the state is not an object. This is a no-op.',
+      );
+      return;
+    }
+
+    let changes = false;
+    if (!ignoreChangeCheck) {
+      for (const key in statePatch) {
+        if (Object.prototype.hasOwnProperty.call(statePatch, key)) {
+          const s = this.state;
+          const current = s[key as keyof S];
+          if (!Object.is(statePatch[key as keyof S], current)) {
+            changes = true;
+            break;
+          }
+        }
+      }
+    } else {
+      changes = true;
+    }
+
+    if (changes) {
+      this.emit({
+        ...this.state,
+        ...(statePatch as Partial<S>),
+      } as S);
+    }
+  }
+}

package/src/addons/BlacAddon.ts

@@ -0,0 +1,17 @@
+import { BlocBase } from '../BlocBase';
+
+export type BlacAddonInit = (bloc: BlocBase<any>) => void;
+
+export type BlacAddonEmit = (params: {
+  oldState: unknown;
+  newState: unknown;
+  cubit: BlocBase<any>;
+}) => void;
+
+type BlacAddon = {
+  name: string;
+  onInit?: BlacAddonInit;
+  onEmit?: BlacAddonEmit;
+};
+
+export default BlacAddon;