@blac/core 2.0.0 → 2.0.1

package/README.md

@@ -1,252 +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
 ```
 
 ## 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(this.state + 1);
+  increment() {
+    this.emit({ count: this.state.count + 1 });
   }
 
-  decrement = () => {
-    this.emit(this.state - 1);
+  decrement() {
+    this.update((state) => ({ count: state.count - 1 }));
+  }
+
+  reset() {
+    this.patch({ count: 0 });
   }
 }
 ```
 
-**Bloc**: More powerful state container with a reducer pattern for action-based state transitions.
+### Vertex
+
+Event-driven state container using discriminated union events. Use when you need structured event handling with type-safe exhaustive checking.
 
 ```typescript
-// Define actions
-type CounterAction = 
-  | { type: 'increment', amount: number }
-  | { type: 'decrement', amount: number };
+import { Vertex } from '@blac/core';
+
+type CounterEvent =
+  | { type: 'increment'; amount: number }
+  | { type: 'decrement' }
+  | { type: 'reset' };
 
-class CounterBloc extends Bloc<number, CounterAction> {
+class CounterVertex extends Vertex<{ count: number }, CounterEvent> {
   constructor() {
-    super(0); // Initial state
+    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 });
+      },
+    });
   }
 
-  reducer = (action: CounterAction, state: number): number => {
-    switch (action.type) {
-      case 'increment':
-        return state + action.amount;
-      case 'decrement':
-        return state - action.amount;
-    }
-  }
+  increment = (amount = 1) => this.add({ type: 'increment', amount });
+  decrement = () => this.add({ type: 'decrement' });
+  reset = () => this.add({ type: 'reset' });
+}
+```
 
-  increment = (amount = 1) => {
-    this.add({ type: 'increment', amount });
-  }
+### StatelessCubit & StatelessVertex
+
+Stateless containers for services that don't need state tracking. Use for actions-only functionality like analytics, API calls, or navigation.
+
+```typescript
+import { StatelessCubit } from '@blac/core';
 
-  decrement = (amount = 1) => {
-    this.add({ type: 'decrement', amount });
+class AnalyticsService extends StatelessCubit {
+  trackEvent(name: string, data?: Record<string, unknown>) {
+    // Send to analytics provider
   }
 }
 ```
 
-### Important: Arrow Functions Required
+## Registry API
 
-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()`.
+Manage state container instances with the registry functions:
 
-### State Management Patterns
+```typescript
+import { acquire, release, borrow, hasInstance, clear } from '@blac/core';
 
-#### Shared State (Default)
+// Acquire an instance (creates if needed, increments ref count)
+const counter = acquire(CounterCubit);
 
-By default, bloc instances are shared across all consumers:
+// Release when done (decrements ref count, disposes when 0)
+release(CounterCubit);
 
-```typescript
-class GlobalCounterCubit extends Cubit<number> {
-  constructor() {
-    super(0);
-  }
-  
-  increment = () => {
-    this.emit(this.state + 1);
-  }
+// 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();
 ```
 
-#### Isolated State
+## Decorators
 
-When each consumer needs its own state instance:
+Use the `@blac` decorator to configure container behavior:
 
 ```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 { 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> {}
 ```
 
-#### Persistent State
+## Utilities
+
+### waitUntil
 
-Keep state alive even when no consumers are using it:
+Wait for a specific state condition:
 
 ```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 { waitUntil } from '@blac/core';
 
-## Advanced Usage
+const counter = acquire(CounterCubit);
+
+// Wait until count reaches 10
+await waitUntil(counter, (state) => state.count >= 10);
+
+// With timeout
+await waitUntil(counter, (state) => state.count >= 10, {
+  timeout: 5000,
+});
+```
 
-### Custom Plugins
+### watch
 
-Create plugins to add functionality like logging, persistence, or analytics:
+Create computed values that react to state changes:
 
 ```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 { watch, instance } from '@blac/core';
+
+class DashboardCubit extends Cubit<DashboardState> {
+  constructor() {
+    super({ items: [] });
+
+    // Watch another bloc's state
+    watch(
+      instance(UserCubit),
+      (userState) => userState.preferences,
+      (preferences) => this.onPreferencesChanged(preferences),
+    );
   }
 }
-
-// Add the plugin to Blac
-import { Blac } from '@blac/core';
-Blac.addPlugin(new LoggerPlugin());
 ```
 
-### Using Props with Blocs
+## Plugins
 
-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:
+Extend functionality with plugins:
 
 ```typescript
-import { Bloc } from '@blac/core'; // Or your specific import path
+import { getPluginManager, type BlacPlugin } from '@blac/core';
 
-// Define props interface (optional, but good practice)
-interface UserProfileProps {
-  userId: string;
-}
+const loggingPlugin: BlacPlugin = {
+  name: 'logging',
+  onStateChange: (container, prevState, newState) => {
+    console.log(`[${container.constructor.name}]`, prevState, '->', newState);
+  },
+};
 
-// Define state interface
-interface UserProfileState {
-  loading: boolean;
-  userData: { id: string; name: string; bio?: string } | null;
-  error: string | null;
-}
+getPluginManager().register(loggingPlugin);
+```
 
-// Define actions (if any, for this example we'll focus on constructor and an async method)
-type UserProfileAction = { type: 'dataLoaded', data: any } | { type: 'error', error: string };
-
-class UserProfileBloc extends Bloc<UserProfileState, UserProfileAction> {
-  private userId: string;
-
-  // The Blac library or its React bindings (like @blac/react)
-  // might provide a way to pass these props during instantiation.
-  // For example, `useBloc(UserProfileBloc, { props: { userId: '123' } })`
-  constructor(props: UserProfileProps) {
-    super({ loading: true, userData: null, error: null }); // Initial state
-    this.userId = props.userId;
-    // Optional: Set a dynamic name for easier debugging with multiple instances
-    this._name = `UserProfileBloc_${this.userId}`; 
-    this.fetchUserProfile();
-  }
+## Configuration
 
-  // Example reducer
-  reducer = (action: UserProfileAction, state: UserProfileState): UserProfileState => {
-    switch (action.type) {
-      case 'dataLoaded':
-        return { ...state, loading: false, userData: action.data, error: null };
-      case 'error':
-        return { ...state, loading: false, error: action.error };
-      default:
-        return state;
-    }
-  }
+Configure global behavior:
 
-  fetchUserProfile = async ()_ => {
-    this.emit({ ...this.state, loading: true }); // Set loading true before fetch
-    try {
-      // Simulate an API call
-      await new Promise(resolve => setTimeout(resolve, 1000));
-      const mockUserData = { id: this.userId, name: `User ${this.userId}`, bio: 'Loves Blac states!' };
-      // Dispatch an action or directly emit a new state
-      this.add({ type: 'dataLoaded', data: mockUserData });
-    } catch (e:any) {
-      this.add({ type: 'error', error: e.message || 'Failed to fetch user profile' });
-    }
-  }
-}
+```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, A, P>`: Action-based state container with a reducer pattern
-- `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