@blac/core 2.0.0-rc-13 → 2.0.0-rc-14

package/src/utils/generateInstanceId.ts

@@ -0,0 +1,54 @@
+/**
+ * Generates a deterministic instance ID from static props by extracting primitive values
+ *
+ * Rules:
+ * 1. Only considers primitive types: string, number, boolean, null, undefined
+ * 2. Ignores complex types: objects, arrays, functions, symbols
+ * 3. Sorts keys alphabetically for deterministic output
+ * 4. Returns undefined if no primitives found (caller should use default ID)
+ */
+export function generateInstanceIdFromProps(
+  props: unknown,
+): string | undefined {
+  if (!props || typeof props !== 'object') {
+    return undefined;
+  }
+
+  const primitives: Array<[string, unknown]> = [];
+
+  // Extract primitive values
+  for (const [key, value] of Object.entries(props)) {
+    const type = typeof value;
+    if (
+      type === 'string' ||
+      type === 'number' ||
+      type === 'boolean' ||
+      value === null ||
+      value === undefined
+    ) {
+      primitives.push([key, value]);
+    }
+  }
+
+  // No primitives found
+  if (primitives.length === 0) {
+    return undefined;
+  }
+
+  // Sort by key for deterministic output
+  primitives.sort(([a], [b]) => a.localeCompare(b));
+
+  // Create instance ID
+  const parts: string[] = [];
+  for (const [key, value] of primitives) {
+    if (value === null) {
+      parts.push(`${key}:null`);
+    } else if (value === undefined) {
+      parts.push(`${key}:undefined`);
+    } else {
+      parts.push(`${key}:${String(value)}`);
+    }
+  }
+
+  return parts.join('|');
+}

package/src/utils/shallowEqual.ts

@@ -37,4 +37,4 @@ export function shallowEqual(a: any, b: any): boolean {
   }
 
   return true;
-}
+}

package/README.md

@@ -1,329 +0,0 @@
-# @blac/core
-
-A lightweight, flexible state management library for JavaScript/TypeScript applications focusing on predictable state transitions.
-
-## Features
-
-- 🔄 Predictable unidirectional data flow
-- 🧩 Modular architecture with Blocs and Cubits
-- 🧪 Unit test friendly
-- 🔒 Isolated state instances when needed
-- 🔌 Plugin system for extensibility
-
-## Installation
-
-Install `@blac/core` using your favorite package manager:
-
-```bash
-# pnpm
-pnpm add @blac/core
-
-# yarn
-yarn add @blac/core
-
-# npm
-npm install @blac/core
-```
-
-## Configuration
-
-BlaC provides global configuration options to customize its behavior:
-
-```typescript
-import { Blac } from '@blac/core';
-
-// Configure BlaC before using it
-Blac.setConfig({
-  // Enable/disable automatic dependency tracking for optimized re-renders
-  proxyDependencyTracking: true, // default: true
-  
-  // Expose Blac instance globally for debugging
-  exposeBlacInstance: false // default: false
-});
-
-// Read current configuration
-const config = Blac.config;
-console.log(config.proxyDependencyTracking); // true
-```
-
-### Configuration Options
-
-- **`proxyDependencyTracking`**: When enabled (default), BlaC automatically tracks which state properties your components access and only triggers re-renders when those specific properties change. Disable this for simpler behavior where any state change triggers re-renders.
-
-- **`exposeBlacInstance`**: When enabled, exposes the BlaC instance globally (useful for debugging). Not recommended for production.
-
-## Testing
-
-Blac provides comprehensive testing utilities to make testing your state management logic simple and powerful:
-
-```typescript
-import { BlocTest, MockCubit, MemoryLeakDetector } from '@blac/core';
-
-describe('Counter Tests', () => {
-  beforeEach(() => BlocTest.setUp());
-  afterEach(() => BlocTest.tearDown());
-
-  it('should increment counter', async () => {
-    const counter = BlocTest.createBloc(CounterCubit);
-    
-    counter.increment();
-    
-    expect(counter.state.count).toBe(1);
-  });
-
-  it('should track state history', () => {
-    const mockCubit = new MockCubit({ count: 0 });
-    
-    mockCubit.emit({ count: 1 });
-    mockCubit.emit({ count: 2 });
-    
-    const history = mockCubit.getStateHistory();
-    expect(history).toHaveLength(3); // Initial + 2 emissions
-  });
-
-  it('should detect memory leaks', () => {
-    const detector = new MemoryLeakDetector();
-    
-    // Create and use blocs...
-    
-    const result = detector.checkForLeaks();
-    expect(result.hasLeaks).toBe(false);
-  });
-});
-```
-
-**[📚 View Complete Testing Documentation](./docs/testing.md)**
-
-## Core Concepts
-
-### Blocs and Cubits
-
-**Cubit**: A simple state container with methods to emit new states.
-
-```typescript
-class CounterCubit extends Cubit<number> {
-  constructor() {
-    super(0); // Initial state
-  }
-
-  increment = () => {
-    this.emit(this.state + 1);
-  }
-
-  decrement = () => {
-    this.emit(this.state - 1);
-  }
-}
-```
-
-**Bloc**: More powerful state container that uses an event-handler pattern for type-safe, event-driven state transitions. Events (instances of classes) are dispatched via `this.add()`, and handlers are registered using `this.on(EventClass, handler)`.
-
-```typescript
-// Define event classes
-class IncrementEvent { constructor(public readonly amount: number = 1) {} }
-class DecrementEvent { constructor(public readonly amount: number = 1) {} }
-
-// Optional: Union type for all events
-type CounterEvent = IncrementEvent | DecrementEvent;
-
-class CounterBloc extends Bloc<number, CounterEvent> {
-  constructor() {
-    super(0); // Initial state
-
-    // Register event handlers
-    this.on(IncrementEvent, (event, emit) => {
-      emit(this.state + event.amount);
-    });
-
-    this.on(DecrementEvent, (event, emit) => {
-      emit(this.state - event.amount);
-    });
-  }
-
-  // Helper methods to dispatch event instances (optional)
-  increment = (amount = 1) => {
-    this.add(new IncrementEvent(amount));
-  }
-
-  decrement = (amount = 1) => {
-    this.add(new DecrementEvent(amount));
-  }
-}
-```
-
-### Important: Arrow Functions Required
-
-All methods in Bloc or Cubit classes must use arrow function syntax (`method = () => {}`) instead of the traditional method syntax (`method() {}`). This is because arrow functions automatically bind `this` to the class instance. Without this binding, methods called from React components would lose their context and could not access instance properties like `this.state` or `this.emit()`.
-
-### State Management Patterns
-
-#### Shared State (Default)
-
-By default, bloc instances are shared across all consumers:
-
-```typescript
-class GlobalCounterCubit extends Cubit<number> {
-  constructor() {
-    super(0);
-  }
-  
-  increment = () => {
-    this.emit(this.state + 1);
-  }
-}
-```
-
-#### Isolated State
-
-When each consumer needs its own state instance:
-
-```typescript
-class LocalCounterCubit extends Cubit<number> {
-  static isolated = true; // Each consumer gets its own instance
-  
-  constructor() {
-    super(0);
-  }
-  
-  increment = () => {
-    this.emit(this.state + 1);
-  }
-}
-```
-
-#### Persistent State
-
-Keep state alive even when no consumers are using it:
-
-```typescript
-class PersistentCounterCubit extends Cubit<number> {
-  static keepAlive = true; // State persists even when no consumers
-  
-  constructor() {
-    super(0);
-  }
-  
-  increment = () => {
-    this.emit(this.state + 1);
-  }
-}
-```
-
-## Advanced Usage
-
-### Custom Plugins
-
-Create plugins to add functionality like logging, persistence, or analytics:
-
-```typescript
-import { BlacPlugin, BlacLifecycleEvent, BlocBase } from '@blac/core';
-
-class LoggerPlugin implements BlacPlugin {
-  name = 'LoggerPlugin';
-  
-  onEvent(event: BlacLifecycleEvent, bloc: BlocBase, params?: any) {
-    if (event === BlacLifecycleEvent.STATE_CHANGED) {
-      console.log(`[${bloc._name}] State changed:`, bloc.state);
-    }
-  }
-}
-
-// Add the plugin to Blac
-import { Blac } from '@blac/core';
-Blac.addPlugin(new LoggerPlugin());
-```
-
-### Using Props with Blocs
-
-Blocs can be designed to accept properties through their constructor, allowing for configurable instances. Here's an example of a `UserProfileBloc` that takes a `userId` prop:
-
-```typescript
-import { Bloc } from '@blac/core'; // Or your specific import path
-
-// Define props interface (optional, but good practice)
-interface UserProfileProps {
-  userId: string;
-}
-
-// Define state interface
-interface UserProfileState {
-  loading: boolean;
-  userData: { id: string; name: string; bio?: string } | null;
-  error: string | null;
-}
-
-// Define Event Classes for UserProfileBloc
-class UserProfileFetchEvent {}
-class UserProfileDataLoadedEvent { constructor(public readonly data: any) {} }
-class UserProfileErrorEvent { constructor(public readonly error: string) {} }
-
-type UserProfileEvents = UserProfileFetchEvent | UserProfileDataLoadedEvent | UserProfileErrorEvent;
-
-class UserProfileBloc extends Bloc<UserProfileState, UserProfileEvents, UserProfileProps> {
-  private userId: string;
-
-  constructor(props: UserProfileProps) {
-    super({ loading: true, userData: null, error: null }); // Initial state
-    this.userId = props.userId;
-    this._name = `UserProfileBloc_${this.userId}`;
-
-    // Register event handlers
-    this.on(UserProfileFetchEvent, this.handleFetchUserProfile);
-    this.on(UserProfileDataLoadedEvent, (event, emit) => {
-      emit({ ...this.state, loading: false, userData: event.data, error: null });
-    });
-    this.on(UserProfileErrorEvent, (event, emit) => {
-      emit({ ...this.state, loading: false, error: event.error });
-    });
-
-    // Initial fetch
-    this.add(new UserProfileFetchEvent());
-  }
-
-  private handleFetchUserProfile = async (_event: UserProfileFetchEvent, emit: (state: UserProfileState) => void) => {
-    // Emit loading state directly if not already covered by initial state or another event
-    // For this example, constructor sets loading: true, so an immediate emit here might be redundant
-    // unless an event handler could set loading to false before this runs.
-    // emit({ ...this.state, loading: true }); // Ensure loading is true
-    try {
-      await new Promise(resolve => setTimeout(resolve, 1000)); // Simulate API call
-      const mockUserData = { id: this.userId, name: `User ${this.userId}`, bio: 'Loves Blac states!' };
-      this.add(new UserProfileDataLoadedEvent(mockUserData));
-    } catch (e:any) {
-      this.add(new UserProfileErrorEvent(e.message || 'Failed to fetch user profile'));
-    }
-  }
-  
-  // Public method to re-trigger fetch if needed
-  refetchUserProfile = () => {
-    this.add(new UserProfileFetchEvent());
-  }
-}
-```
-
-## API Reference
-
-### Core Classes
-
-- `BlocBase<S, P>`: Base class for state containers
-- `Cubit<S, P>`: Simple state container with `emit()` and `patch()`
-- `Bloc<S, E, P>`: Event-driven state container with `on(EventClass, handler)` and `add(eventInstance)` methods.
-- `Blac`: Singleton manager for all Bloc instances
-
-### React Hooks
-
-- `useBloc<B>(BlocClass, options?)`: Connect a component to a Bloc
-
-### Lifecycle Events
-
-- `BLOC_CREATED`: When a new Bloc is instantiated
-- `BLOC_DISPOSED`: When a Bloc is disposed
-- `LISTENER_ADDED`: When a state listener is added
-- `LISTENER_REMOVED`: When a state listener is removed
-- `STATE_CHANGED`: When state is updated
-- `BLOC_CONSUMER_ADDED`: When a new consumer starts using a Bloc
-- `BLOC_CONSUMER_REMOVED`: When a consumer stops using a Bloc
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.

package/src/BlacObserver.ts

@@ -1,189 +0,0 @@
-import { Blac } from './Blac';
-import { BlocLifecycleState } from './BlocBase';
-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 {
-    // Check if bloc is disposed or in disposal process
-    const disposalState = (this.bloc as any)._disposalState;
-    if (
-      disposalState === BlocLifecycleState.DISPOSED ||
-      disposalState === BlocLifecycleState.DISPOSING
-    ) {
-      Blac.log(
-        'BlacObservable.subscribe: Cannot subscribe to disposed/disposing bloc.',
-        this.bloc,
-        observer,
-      );
-      return () => {}; // Return no-op unsubscribe
-    }
-
-    Blac.log(
-      'BlacObservable.subscribe: Subscribing observer.',
-      this.bloc,
-      observer,
-    );
-    this._observers.add(observer);
-
-    // If we're in DISPOSAL_REQUESTED state, cancel the disposal since we have a new observer
-    if (disposalState === BlocLifecycleState.DISPOSAL_REQUESTED) {
-      Blac.log(
-        'BlacObservable.subscribe: Cancelling disposal due to new subscription.',
-        this.bloc,
-      );
-      // Transition back to active state
-      (this.bloc as any)._atomicStateTransition(
-        BlocLifecycleState.DISPOSAL_REQUESTED,
-        BlocLifecycleState.ACTIVE,
-      );
-    }
-
-    // Don't initialize lastState here - let it remain undefined for first-time detection
-    return () => {
-      Blac.log(
-        'BlacObservable.subscribe: Unsubscribing observer.',
-        this.bloc,
-        observer,
-      );
-      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 });
-
-    if (this.size === 0) {
-      Blac.log('BlacObservable.unsubscribe: No observers left.', this.bloc);
-      // Check if bloc should be disposed when both observers and consumers are gone
-      if (
-        this.bloc._consumers.size === 0 &&
-        !this.bloc._keepAlive &&
-        (this.bloc as any)._disposalState === BlocLifecycleState.ACTIVE
-      ) {
-        Blac.log(
-          `[${this.bloc._name}:${this.bloc._id}] No observers or consumers left. Scheduling disposal.`,
-        );
-        (this.bloc as any)._scheduleDisposal();
-      }
-    }
-  }
-
-  /**
-   * 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,
-          oldState,
-          this.bloc,
-        );
-
-        // If this is the first time (no lastState), trigger initial render
-        if (!lastDependencyCheck) {
-          shouldUpdate = true;
-        } else {
-          // Compare dependency arrays
-          if (lastDependencyCheck.length !== newDependencyCheck.length) {
-            shouldUpdate = true;
-          } else {
-            // Compare each dependency value using Object.is (same as React)
-            for (let i = 0; i < newDependencyCheck.length; i++) {
-              if (!Object.is(lastDependencyCheck[i], newDependencyCheck[i])) {
-                shouldUpdate = true;
-                break;
-              }
-            }
-          }
-        }
-
-        observer.lastState = newDependencyCheck;
-      } else {
-        shouldUpdate = true;
-      }
-
-      if (shouldUpdate) {
-        void observer.fn(newState, oldState, action);
-      }
-    });
-
-    // Notify system plugins of state change
-    Blac.instance.plugins.notifyStateChanged(this.bloc, oldState, newState);
-  }
-
-  /**
-   * Clears the observer set
-   */
-  clear() {
-    // Just clear the observers without calling unsubscribe to avoid circular disposal
-    this._observers.clear();
-  }
-}