@blac/core 2.0.0-rn-12 → 2.0.1

package/README.md

@@ -1,329 +1,263 @@
 # @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
+Core state management library implementing the BloC pattern for TypeScript applications.
 
 ## Installation
 
-Install `@blac/core` using your favorite package manager:
-
 ```bash
-# pnpm
+npm install @blac/core
+# or
 pnpm add @blac/core
-
-# yarn
+# or
 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
 
-**Cubit**: A simple state container with methods to emit new states.
+Simple state container with direct state emission. Use when you need straightforward state updates.
 
 ```typescript
-class CounterCubit extends Cubit<number> {
+import { Cubit } from '@blac/core';
+
+class CounterCubit extends Cubit<{ count: number }> {
   constructor() {
-    super(0); // Initial state
+    super({ count: 0 });
+  }
+
+  increment() {
+    this.emit({ count: this.state.count + 1 });
   }
 
-  increment = () => {
-    this.emit(this.state + 1);
+  decrement() {
+    this.update((state) => ({ count: state.count - 1 }));
   }
 
-  decrement = () => {
-    this.emit(this.state - 1);
+  reset() {
+    this.patch({ count: 0 });
   }
 }
 ```
 
-**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)`.
+### Vertex
+
+Event-driven state container using discriminated union events. Use when you need structured event handling with type-safe exhaustive checking.
 
 ```typescript
-// Define event classes
-class IncrementEvent { constructor(public readonly amount: number = 1) {} }
-class DecrementEvent { constructor(public readonly amount: number = 1) {} }
+import { Vertex } from '@blac/core';
 
-// Optional: Union type for all events
-type CounterEvent = IncrementEvent | DecrementEvent;
+type CounterEvent =
+  | { type: 'increment'; amount: number }
+  | { type: 'decrement' }
+  | { type: 'reset' };
 
-class CounterBloc extends Bloc<number, CounterEvent> {
+class CounterVertex extends Vertex<{ count: 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);
+    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 });
+      },
     });
   }
 
-  // Helper methods to dispatch event instances (optional)
-  increment = (amount = 1) => {
-    this.add(new IncrementEvent(amount));
-  }
-
-  decrement = (amount = 1) => {
-    this.add(new DecrementEvent(amount));
-  }
+  increment = (amount = 1) => this.add({ type: 'increment', amount });
+  decrement = () => this.add({ type: 'decrement' });
+  reset = () => this.add({ type: 'reset' });
 }
 ```
 
-### Important: Arrow Functions Required
+### StatelessCubit & StatelessVertex
 
-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:
+Stateless containers for services that don't need state tracking. Use for actions-only functionality like analytics, API calls, or navigation.
 
 ```typescript
-class GlobalCounterCubit extends Cubit<number> {
-  constructor() {
-    super(0);
-  }
-  
-  increment = () => {
-    this.emit(this.state + 1);
+import { StatelessCubit } from '@blac/core';
+
+class AnalyticsService extends StatelessCubit {
+  trackEvent(name: string, data?: Record<string, unknown>) {
+    // Send to analytics provider
   }
 }
 ```
 
-#### Isolated State
+## Registry API
 
-When each consumer needs its own state instance:
+Manage state container instances with the registry functions:
 
 ```typescript
-class LocalCounterCubit extends Cubit<number> {
-  static isolated = true; // Each consumer gets its own instance
-  
-  constructor() {
-    super(0);
-  }
-  
-  increment = () => {
-    this.emit(this.state + 1);
-  }
+import { acquire, release, borrow, hasInstance, clear } from '@blac/core';
+
+// Acquire an instance (creates if needed, increments ref count)
+const counter = acquire(CounterCubit);
+
+// Release when done (decrements ref count, disposes when 0)
+release(CounterCubit);
+
+// Borrow without affecting ref count
+const instance = borrow(CounterCubit);
+
+// Check if instance exists
+if (hasInstance(CounterCubit)) {
+  // ...
 }
+
+// Clear a specific class
+clear(CounterCubit);
+
+// Clear all instances
+clearAll();
 ```
 
-#### Persistent State
+## Decorators
 
-Keep state alive even when no consumers are using it:
+Use the `@blac` decorator to configure container behavior:
 
 ```typescript
-class PersistentCounterCubit extends Cubit<number> {
-  static keepAlive = true; // State persists even when no consumers
-  
-  constructor() {
-    super(0);
-  }
-  
-  increment = () => {
-    this.emit(this.state + 1);
-  }
-}
+import { Cubit, blac } from '@blac/core';
+
+@blac({ isolated: true }) // Each consumer gets its own instance
+class FormCubit extends Cubit<FormState> {}
+
+@blac({ keepAlive: true }) // Never auto-dispose
+class AuthCubit extends Cubit<AuthState> {}
+
+@blac({ excludeFromDevTools: true }) // Hide from DevTools
+class InternalCubit extends Cubit<State> {}
 ```
 
-## Advanced Usage
+## Utilities
 
-### Custom Plugins
+### waitUntil
 
-Create plugins to add functionality like logging, persistence, or analytics:
+Wait for a specific state condition:
 
 ```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);
-    }
-  }
-}
+import { waitUntil } from '@blac/core';
+
+const counter = acquire(CounterCubit);
 
-// Add the plugin to Blac
-import { Blac } from '@blac/core';
-Blac.addPlugin(new LoggerPlugin());
+// Wait until count reaches 10
+await waitUntil(counter, (state) => state.count >= 10);
+
+// With timeout
+await waitUntil(counter, (state) => state.count >= 10, {
+  timeout: 5000,
+});
 ```
 
-### Using Props with Blocs
+### watch
 
-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:
+Create computed values that react to state changes:
 
 ```typescript
-import { Bloc } from '@blac/core'; // Or your specific import path
+import { watch, instance } from '@blac/core';
 
-// Define props interface (optional, but good practice)
-interface UserProfileProps {
-  userId: string;
+class DashboardCubit extends Cubit<DashboardState> {
+  constructor() {
+    super({ items: [] });
+
+    // Watch another bloc's state
+    watch(
+      instance(UserCubit),
+      (userState) => userState.preferences,
+      (preferences) => this.onPreferencesChanged(preferences),
+    );
+  }
 }
+```
 
-// Define state interface
-interface UserProfileState {
-  loading: boolean;
-  userData: { id: string; name: string; bio?: string } | null;
-  error: string | null;
-}
+## Plugins
 
-// Define Event Classes for UserProfileBloc
-class UserProfileFetchEvent {}
-class UserProfileDataLoadedEvent { constructor(public readonly data: any) {} }
-class UserProfileErrorEvent { constructor(public readonly error: string) {} }
+Extend functionality with plugins:
 
-type UserProfileEvents = UserProfileFetchEvent | UserProfileDataLoadedEvent | UserProfileErrorEvent;
+```typescript
+import { getPluginManager, type BlacPlugin } from '@blac/core';
 
-class UserProfileBloc extends Bloc<UserProfileState, UserProfileEvents, UserProfileProps> {
-  private userId: string;
+const loggingPlugin: BlacPlugin = {
+  name: 'logging',
+  onStateChange: (container, prevState, newState) => {
+    console.log(`[${container.constructor.name}]`, prevState, '->', newState);
+  },
+};
 
-  constructor(props: UserProfileProps) {
-    super({ loading: true, userData: null, error: null }); // Initial state
-    this.userId = props.userId;
-    this._name = `UserProfileBloc_${this.userId}`;
+getPluginManager().register(loggingPlugin);
+```
 
-    // 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 });
-    });
+## Configuration
 
-    // Initial fetch
-    this.add(new UserProfileFetchEvent());
-  }
+Configure global behavior:
 
-  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());
-  }
-}
+```typescript
+import { configureBlac } from '@blac/core';
+
+configureBlac({
+  devMode: import.meta.env.DEV,
+});
 ```
 
 ## API Reference
 
-### Core Classes
+### State Containers
 
-- `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
+| Class                | Description                                                 |
+| -------------------- | ----------------------------------------------------------- |
+| `Cubit<S, P>`        | Simple state container with `emit()`, `update()`, `patch()` |
+| `Vertex<S, E, P>`    | Event-driven container with `add()` and `createHandlers()`  |
+| `StatelessCubit`     | Stateless service container                                 |
+| `StatelessVertex<E>` | Stateless event-driven container                            |
 
-### React Hooks
+### Registry Functions
 
-- `useBloc<B>(BlocClass, options?)`: Connect a component to a Bloc
+| Function                         | Description                                 |
+| -------------------------------- | ------------------------------------------- |
+| `acquire(Class, key?, options?)` | Get or create instance, increment ref count |
+| `release(Class, key?)`           | Decrement ref count, dispose when 0         |
+| `borrow(Class, key?)`            | Get instance without affecting ref count    |
+| `borrowSafe(Class, key?)`        | Borrow or return undefined                  |
+| `ensure(Class, key?, options?)`  | Acquire without incrementing ref count      |
+| `hasInstance(Class, key?)`       | Check if instance exists                    |
+| `getRefCount(Class, key?)`       | Get current reference count                 |
+| `clear(Class)`                   | Remove all instances of a class             |
+| `clearAll()`                     | Remove all instances                        |
 
-### Lifecycle Events
+### Exports
 
-- `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
+```typescript
+// Core classes
+export { Cubit, Vertex, StatelessCubit, StatelessVertex } from '@blac/core';
+
+// Registry
+export {
+  acquire,
+  release,
+  borrow,
+  ensure,
+  hasInstance,
+  clear,
+  clearAll,
+} from '@blac/core';
+
+// Utilities
+export { waitUntil, watch, instance } from '@blac/core';
+
+// Decorators
+export { blac } from '@blac/core';
+
+// Plugin system
+export { getPluginManager, type BlacPlugin } from '@blac/core';
+
+// Configuration
+export { configureBlac, getBlacConfig, isDevMode } from '@blac/core';
+```
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.
+MIT