@asaidimu/utils-store 1.0.0 → 2.0.0

package/README.md

@@ -1,10 +1,12 @@
-# `@asaidimu/utils-store` - Reactive Data Store
+# `@asaidimu/utils-store` 
+
+**A Reactive Data Store**
 
 A comprehensive, type-safe, and reactive state management library for TypeScript applications, featuring robust middleware, transactional updates, deep observability, and an optional persistence layer.
 
 [![npm version](https://img.shields.io/npm/v/@asaidimu/utils-store?style=flat-square)](https://www.npmjs.com/package/@asaidimu/utils-store)
 [![License](https://img.shields.io/npm/l/@asaidimu/utils-store?style=flat-square)](LICENSE)
-[![Build Status](https://img.shields.io/badge/Build-Passing-brightgreen?style=flat-square)](https://github.com/asaidimu/utils-actions?query=workflow%3ACI)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/asaidimu/erp-utils/ci.yml?branch=main&style=flat-square)](https://github.com/asaidimu/erp-utils/actions?query=workflow%3ACI)
 
 ---
 
@@ -17,7 +19,7 @@ A comprehensive, type-safe, and reactive state management library for TypeScript
   - [Persistence Integration](#persistence-integration)
   - [Middleware System](#middleware-system)
   - [Transaction Support](#transaction-support)
-  - [Store Observability](#store-observability)
+  - [Store Observer](#store-observability)
   - [Event System](#event-system)
 - [Project Architecture](#project-architecture)
 - [Development & Contributing](#development--contributing)
@@ -29,7 +31,7 @@ A comprehensive, type-safe, and reactive state management library for TypeScript
 
 `@asaidimu/utils-store` is a powerful and flexible state management solution designed for modern TypeScript applications. It provides a highly performant and observable way to manage your application's data, ensuring type safety and predictability across complex state interactions. Built on principles of immutability and explicit updates, it makes state changes easy to track, debug, and extend.
 
-Whether you're building a simple utility or a complex application, this library offers the tools to handle your state with confidence, enabling features like atomic transactions, a pluggable middleware pipeline, and deep runtime introspection for unparalleled debugging capabilities. It emphasizes a component-based design internally, allowing for clear separation of concerns for state management, middleware processing, persistence, and observability.
+This library offers tools to handle your state with confidence, enabling features like atomic transactions, a pluggable middleware pipeline, and deep runtime introspection for unparalleled debugging capabilities. It emphasizes a component-based design internally, allowing for clear separation of concerns for state management, middleware processing, persistence, and observability.
 
 ### Key Features
 
@@ -40,8 +42,8 @@ Whether you're building a simple utility or a complex application, this library
     *   **Blocking Middleware**: Implement custom validation or authorization logic to prevent invalid state changes from occurring. These middlewares return a boolean.
 *   📦 **Atomic Transaction Support**: Group multiple state updates into a single, atomic operation. If any update within the transaction fails, the entire transaction is rolled back to the state before the transaction began, guaranteeing data integrity.
 *   💾 **Optional Persistence Layer**: Seamlessly integrate with any `SimplePersistence<T>` implementation (e.g., for local storage, IndexedDB, or backend sync) to load and save state, ensuring data durability and synchronization across instances.
-*   🔍 **Deep Observability & Debugging**: An optional `StoreObservability` class provides unparalleled runtime introspection:
-    *   **Event History**: Keep a detailed log of all internal store events (`update:start`, `middleware:complete`, `transaction:error`, `persistence:ready`, etc.).
+*   🔍 **Deep Observer & Debugging**: An optional `StoreObserver` class provides unparalleled runtime introspection:
+    *   **Event History**: Keep a detailed log of all internal store events (`update:start`, `middleware:complete`, `transaction:error`, `persistence:ready`, `middleware:executed`, etc.).
     *   **State Snapshots**: Maintain a configurable history of your state over time, allowing for easy inspection of changes between updates.
     *   **Time-Travel Debugging**: Undo and redo state changes using the recorded state history, providing powerful capabilities for debugging complex scenarios.
     *   **Performance Metrics**: Track real-time performance indicators like total update count, listener executions, average update times, and largest update size to identify bottlenecks.
@@ -60,6 +62,12 @@ Install the entire collection using your preferred package manager. You can then
 ```bash
 # Using Bun
 bun add @asaidimu/utils-store
+
+# Using npm
+npm install @asaidimu/utils-store
+
+# Using yarn
+yarn add @asaidimu/utils-store
 ```
 
 ### Prerequisites
@@ -82,18 +90,31 @@ interface MyState {
 
 const store = new ReactiveDataStore<MyState>({ count: 0, message: "Hello" });
 
+// Subscribing to "count" will only log when 'count' path changes
 store.subscribe("count", (state) => {
   console.log(`Count changed to: ${state.count}`);
 });
 
-await store.set({ count: 1 });
-await store.set({ message: "World" }); // This won't trigger the 'count' listener
+// Subscribing to "" (empty string) will log for any store update
+store.subscribe("", (state) => {
+    console.log(`Store updated to: ${JSON.stringify(state)}`);
+});
 
-console.log("Current state:", store.get());
+console.log("Initial state:", store.get());
+// Output: Initial state: { count: 0, message: "Hello" }
 
-// Expected Output:
+await store.set({ count: 1 });
+// Output:
 // Count changed to: 1
-// Current state: { count: 1, message: "World" }
+// Store updated to: {"count":1,"message":"Hello"}
+
+await store.set({ message: "World" });
+// Output:
+// Store updated to: {"count":1,"message":"World"}
+// (The 'count' listener won't be triggered as only 'message' changed)
+
+console.log("Current state:", store.get());
+// Output: Current state: { count: 1, message: "World" }
 ```
 
 Run this file:
@@ -112,7 +133,7 @@ This section provides practical examples of how to use `@asaidimu/utils-store` t
 Creating a store, getting state, and setting updates.
 
 ```typescript
-import { ReactiveDataStore, DeepPartial } from '@asaidimu/utils-store';
+import { ReactiveDataStore, type DeepPartial } from '@asaidimu/utils-store';
 
 // 1. Define your state interface for type safety
 interface AppState {
@@ -182,8 +203,8 @@ await store.set((state) => ({
   lastUpdated: Date.now(),
 }));
 
-console.log('State after functional update:', store.get().products.length);
-// Output: State after functional update: 3
+console.log('State after functional update, products count:', store.get().products.length);
+// Output: State after functional update, products count: 3
 
 // 6. Subscribing to state changes
 // You can subscribe to the entire state or specific paths.
@@ -202,19 +223,19 @@ const unsubscribeMulti = store.subscribe(['user.name', 'products'], (state) => {
 
 // Subscribe to any change in the store
 const unsubscribeAll = store.subscribe('', (state) => {
-  console.log('Store updated (any path changed).');
+  console.log('Store updated (any path changed). Current products count:', state.products.length);
 });
 
 await store.set({ user: { email: 'jane.smith@example.com' } });
 // Output:
 // User data changed: { id: '123', name: 'Jane Smith', email: 'jane.smith@example.com', isActive: false }
 // User name or products changed: Jane Smith 3
-// Store updated (any path changed).
+// Store updated (any path changed). Current products count: 3
 
 await store.set({ settings: { notificationsEnabled: false } });
 // Output:
 // Notifications setting changed: false
-// Store updated (any path changed).
+// Store updated (any path changed). Current products count: 3
 
 // 7. Unsubscribe from changes
 unsubscribeUser();
@@ -227,10 +248,11 @@ await store.set({ user: { isActive: true } });
 
 // 8. Deleting properties
 // Use Symbol.for("delete") to remove a property from the state.
-const deleteSymbol = Symbol.for("delete");
+// Note: You might need a type cast for TypeScript if strict type checking is enabled.
+const DELETE_ME = Symbol.for("delete");
 await store.set({
   user: {
-    email: deleteSymbol as DeepPartial<string> // Cast is needed for type inference
+    email: DELETE_ME as DeepPartial<string> // Cast is needed for type inference
   }
 });
 console.log('User email after deletion:', store.get().user.email);
@@ -239,18 +261,24 @@ console.log('User email after deletion:', store.get().user.email);
 
 ### Persistence Integration
 
-The `ReactiveDataStore` can integrate with any persistence layer that implements the `SimplePersistence<T>` interface. This allows you to load an initial state and save subsequent changes.
+The `ReactiveDataStore` can integrate with any persistence layer that implements the `SimplePersistence<T>` interface. This allows you to load an initial state and save subsequent changes. The store emits a `persistence:ready` event once the persistence layer has loaded any initial state.
 
 ```typescript
-import { ReactiveDataStore, StoreEvent } from '@asaidimu/utils-store';
-import { SimplePersistence } from '@core/persistence'; // Your persistence implementation
+import { ReactiveDataStore, type StoreEvent } from '@asaidimu/utils-store';
+// Assuming @core/persistence or similar is available from your utility package
+import type { SimplePersistence } from '@core/persistence'; 
 
 // Example: A simple in-memory persistence for demonstration
 // In a real app, this would interact with localStorage, IndexedDB, a backend, etc.
 class InMemoryPersistence<T> implements SimplePersistence<T> {
   private data: T | null = null;
+  // Using a map to simulate different instances subscribing to common data
   private subscribers: Map<string, (state: T) => void> = new Map();
 
+  constructor(initialData: T | null = null) {
+      this.data = initialData;
+  }
+
   async get(): Promise<T | null> {
     console.log('Persistence: Loading state...');
     return this.data;
@@ -261,8 +289,9 @@ class InMemoryPersistence<T> implements SimplePersistence<T> {
     this.data = state;
     // Simulate external change notification for other instances
     this.subscribers.forEach((callback, subId) => {
-      if (subId !== instanceId) { // Don't notify the instance that just saved
-        callback(this.data!);
+      // Only notify other instances, not the one that just saved
+      if (subId !== instanceId) { 
+        callback(structuredClone(this.data!)); // Pass a clone to prevent mutation
       }
     });
     return true;
@@ -283,35 +312,42 @@ interface UserConfig {
   fontSize: number;
 }
 
-// Create a persistence instance
-const userConfigPersistence = new InMemoryPersistence<UserConfig>();
+// Create a persistence instance, possibly with some pre-existing data
+const userConfigPersistence = new InMemoryPersistence<UserConfig>({ theme: 'dark', fontSize: 18 });
 
-// Optionally, listen for persistence readiness
-const storeReady = new Promise<void>(resolve => {
+// Initialize the store with persistence
+const store = new ReactiveDataStore<UserConfig>(
+  { theme: 'light', fontSize: 16 }, // Initial state if no persisted data found or persistence is not used
+  userConfigPersistence // Pass your persistence implementation here
+);
+
+// Optionally, listen for persistence readiness (important for UIs that depend on loaded state)
+const storeReadyPromise = new Promise<void>(resolve => {
   store.onStoreEvent('persistence:ready', () => {
     console.log('Store is ready and persistence is initialized!');
     resolve();
   });
 });
 
-// Initialize the store with persistence
-const store = new ReactiveDataStore<UserConfig>(
-  { theme: 'light', fontSize: 16 }, // Initial state if no persisted data
-  userConfigPersistence // Pass your persistence implementation here
-);
+console.log('Store initial state (before persistence loads):', store.get());
 
-console.log('Store initial state:', store.get()); // May reflect initial state if persistence is empty
+await storeReadyPromise; // Wait for persistence to load/initialize
 
-await storeReady; // Wait for persistence to load/initialize
+// Now, store.get() will reflect the loaded state from persistence
+console.log('Store state after persistence load:', store.get()); 
+// Output: Store state after persistence load: { theme: 'dark', fontSize: 18 } (from InMemoryPersistence)
 
 // Now update the state, which will trigger persistence.set()
-await store.set({ theme: 'dark' });
+await store.set({ theme: 'light' });
 console.log('Current theme:', store.get().theme);
+// Output: Current theme: light
 
 // Simulate an external change (e.g., another tab updating the state)
-await userConfigPersistence.set('another-instance-id', { theme: 'light', fontSize: 18 });
-// Store will automatically update its state and notify its listeners.
+// Note: This 'another-instance-id' ensures the current store instance gets the update via subscription.
+await userConfigPersistence.set('another-instance-id', { theme: 'system', fontSize: 20 } as UserConfig); // Simulating a state update from outside the store
+// The store will automatically update its state and notify its listeners due to the internal subscription.
 console.log('Current theme after external update:', store.get().theme);
+// Output: Current theme after external update: system
 ```
 
 ### Middleware System
@@ -323,36 +359,37 @@ Middleware functions allow you to intercept and modify state updates.
 These middlewares can transform the `DeepPartial` update or perform side effects. They receive the current state and the incoming partial update, and can return a new partial state to be merged.
 
 ```typescript
-import { ReactiveDataStore, DeepPartial } from '@asaidimu/utils-store';
+import { ReactiveDataStore, type DeepPartial } from '@asaidimu/utils-store';
 
 interface MyState {
   counter: number;
   logs: string[];
   lastAction: string | null;
+  version: number;
 }
 
 const store = new ReactiveDataStore<MyState>({
   counter: 0,
   logs: [],
   lastAction: null,
+  version: 0,
 });
 
 // Middleware 1: Logger
-// Logs the incoming update before it's processed
+// Logs the incoming update before it's processed. Does not return anything (void).
 store.use({
   name: 'LoggerMiddleware',
   action: (state, update) => {
     console.log('Middleware: Incoming update:', update);
-    // You don't need to return anything if you just want to observe or perform side effects
   },
 });
 
 // Middleware 2: Timestamp and Action Tracker
-// Modifies the update to add a timestamp and track the last action
+// Modifies the update to add a timestamp and track the last action. Returns a partial state.
 store.use({
   name: 'TimestampActionMiddleware',
   action: (state, update) => {
-    // This middleware transforms the update by adding `lastAction`
+    // This middleware transforms the update by adding `lastAction` and a log entry
     const actionDescription = JSON.stringify(update);
     return {
       lastAction: `Updated at ${new Date().toLocaleTimeString()} with ${actionDescription}`,
@@ -361,12 +398,22 @@ store.use({
   },
 });
 
-// Middleware 3: Counter Incrementor
-// Increments the counter whenever a specific property is updated
+// Middleware 3: Version Incrementor
+// Increments a version counter for every update.
+store.use({
+  name: 'VersionIncrementMiddleware',
+  action: (state) => {
+    return { version: state.version + 1 };
+  },
+});
+
+// Middleware 4: Counter Incrementor
+// Increments the counter by the incoming value if the update is a number.
 store.use({
   name: 'CounterIncrementMiddleware',
   action: (state, update) => {
-    if (update.counter !== undefined && typeof update.counter === 'number') {
+    // Only apply if the incoming update is a number for 'counter'
+    if (typeof update.counter === 'number') {
       return { counter: state.counter + update.counter };
     }
     // Return original update or void if no transformation needed
@@ -375,23 +422,30 @@ store.use({
 });
 
 await store.set({ counter: 5 }); // Will increment counter by 5, not set to 5
-// Output:
-// Middleware: Incoming update: { counter: 5 }
+// Expected console output from LoggerMiddleware: Middleware: Incoming update: { counter: 5 }
 console.log('State after counter set:', store.get());
-// Output: counter: 5 (initial) + 5 (update) = 10, lastAction, logs updated
-
-await store.set({ lastAction: 'Manual update' });
-// Output:
-// Middleware: Incoming update: { lastAction: 'Manual update' }
+/* Output will show:
+  counter: 5 (initial) + 5 (update) = 10,
+  lastAction updated by TimestampActionMiddleware,
+  logs updated by TimestampActionMiddleware,
+  version: 1 (incremented by VersionIncrementMiddleware)
+*/
+
+await store.set({ lastAction: 'Manual update from outside middleware' });
+// Expected console output from LoggerMiddleware: Middleware: Incoming update: { lastAction: 'Manual update from outside middleware' }
 console.log('State after manual action:', store.get());
-// Output: lastAction will be overwritten by TimestampActionMiddleware logic
-//         and a new log entry will be added.
+/* Output will show:
+  lastAction will be overwritten by TimestampActionMiddleware logic,
+  a new log entry will be added,
+  version: 2
+*/
 
 // Unuse a middleware by its ID
-const loggerId = store.use({ name: 'AnotherLogger', action: (s, u) => console.log('Another logger', u) });
+const temporaryLoggerId = store.use({ name: 'TemporaryLogger', action: (s, u) => console.log('Temporary logger saw:', u) });
 await store.set({ counter: 1 });
-store.unuse(loggerId);
-await store.set({ counter: 1 }); // AnotherLogger will not be called now
+// Output: Temporary logger saw: { counter: 1 }
+store.unuse(temporaryLoggerId);
+await store.set({ counter: 1 }); // TemporaryLogger will not be called now
 ```
 
 #### Blocking Middleware
@@ -399,26 +453,28 @@ await store.set({ counter: 1 }); // AnotherLogger will not be called now
 These middlewares can prevent an update from proceeding if certain conditions are not met. They return a boolean: `true` to allow, `false` to block. If a blocking middleware throws an error, the update is also blocked.
 
 ```typescript
-import { ReactiveDataStore, DeepPartial } from '@asaidimu/utils-store';
+import { ReactiveDataStore, type DeepPartial } from '@asaidimu/utils-store';
 
 interface UserProfile {
   name: string;
   age: number;
   isAdmin: boolean;
+  isVerified: boolean;
 }
 
 const store = new ReactiveDataStore<UserProfile>({
   name: 'Guest',
   age: 0,
   isAdmin: false,
+  isVerified: false,
 });
 
-// Blocking middleware: Age validation
+// Blocking middleware 1: Age validation
 store.use({
   block: true, // Mark as a blocking middleware
   name: 'AgeValidationMiddleware',
   action: (state, update) => {
-    if (update.age !== undefined && update.age < 18) {
+    if (update.age !== undefined && typeof update.age === 'number' && update.age < 18) {
       console.warn('Blocking update: Age must be 18 or older.');
       return false; // Block the update
     }
@@ -426,15 +482,21 @@ store.use({
   },
 });
 
-// Blocking middleware: Admin check
+// Blocking middleware 2: Admin check
 store.use({
   block: true,
   name: 'AdminRestrictionMiddleware',
   action: (state, update) => {
+    // Cannot become admin if under 21
     if (update.isAdmin === true && state.age < 21) {
       console.warn('Blocking update: User must be 21+ to become admin.');
       return false;
     }
+    // Cannot become admin if not verified
+    if (update.isAdmin === true && !state.isVerified) {
+        console.warn('Blocking update: User must be verified to become admin.');
+        return false;
+    }
     return true;
   },
 });
@@ -447,12 +509,17 @@ console.log('User age after valid update:', store.get().age); // Output: 25
 await store.set({ age: 16 });
 console.log('User age after invalid update attempt (should be 25):', store.get().age); // Output: 25
 
-// Attempt to make user admin under age 21
-await store.set({ age: 20 });
+// Attempt to make user admin while not verified (should fail)
 await store.set({ isAdmin: true });
 console.log('User admin status after failed attempt (should be false):', store.get().isAdmin); // Output: false
 
-// Now make user old enough and try again
+// Verify user, then attempt to make admin again (should fail due to age)
+await store.set({ isVerified: true });
+await store.set({ age: 20 });
+await store.set({ isAdmin: true });
+console.log('User admin status after failed age attempt (should be false):', store.get().isAdmin); // Output: false
+
+// Now make user old enough and verified, then try again (should succeed)
 await store.set({ age: 25 });
 await store.set({ isAdmin: true });
 console.log('User admin status after successful attempt (should be true):', store.get().isAdmin); // Output: true
@@ -466,95 +533,108 @@ Use `store.transaction()` to group multiple state updates into a single atomic o
 import { ReactiveDataStore } from '@asaidimu/utils-store';
 
 interface BankAccount {
+  name: string;
   balance: number;
   transactions: string[];
 }
 
-const store = new ReactiveDataStore<BankAccount>({
-  balance: 1000,
-  transactions: ['Initial deposit'],
-});
+// Set up two bank accounts
+const accountA = new ReactiveDataStore<BankAccount>({ name: 'Account A', balance: 500, transactions: [] });
+const accountB = new ReactiveDataStore<BankAccount>({ name: 'Account B', balance: 200, transactions: [] });
 
+// A function to transfer funds using transactions
 async function transferFunds(
   fromStore: ReactiveDataStore<BankAccount>,
   toStore: ReactiveDataStore<BankAccount>,
   amount: number,
 ) {
+  // All operations inside this transaction will be atomic
   await fromStore.transaction(async () => {
     console.log(`Starting transfer of ${amount}. From: ${fromStore.get().balance}, To: ${toStore.get().balance}`);
 
     // Deduct from sender
     await fromStore.set((state) => {
       if (state.balance < amount) {
+        // Throwing an error here will cause the entire transaction to roll back
         throw new Error('Insufficient funds');
       }
       return {
         balance: state.balance - amount,
-        transactions: [...state.transactions, `Debited ${amount}`],
+        transactions: [...state.transactions, `Debited ${amount} from ${state.name}`],
       };
     });
 
-    // Simulate a delay or another async operation
+    // Simulate a network delay or another async operation that might fail
     await new Promise(resolve => setTimeout(resolve, 50));
 
     // Add to receiver
     await toStore.set((state) => ({
       balance: state.balance + amount,
-      transactions: [...state.transactions, `Credited ${amount}`],
+      transactions: [...state.transactions, `Credited ${amount} to ${state.name}`],
     }));
 
-    console.log(`Transfer complete. From: ${fromStore.get().balance}, To: ${toStore.get().balance}`);
+    console.log(`Transfer in progress. From: ${fromStore.get().balance}, To: ${toStore.get().balance}`);
   });
+  console.log(`Transfer successful. From: ${fromStore.get().balance}, To: ${toStore.get().balance}`);
 }
 
-const accountA = new ReactiveDataStore<BankAccount>({ balance: 500, transactions: [] });
-const accountB = new ReactiveDataStore<BankAccount>({ balance: 200, transactions: [] });
+console.log('--- Initial Balances ---');
+console.log('Account A:', accountA.get().balance); // Expected: 500
+console.log('Account B:', accountB.get().balance); // Expected: 200
 
-// Successful transfer
+// --- Scenario 1: Successful transfer ---
+console.log('\n--- Attempting successful transfer (100) ---');
 try {
   await transferFunds(accountA, accountB, 100);
-  console.log('Transfer 1 successful:');
-  console.log('Account A:', accountA.get()); // Expected: balance 400
-  console.log('Account B:', accountB.get()); // Expected: balance 300
+  console.log('\nTransfer 1 successful:');
+  console.log('Account A:', accountA.get()); // Expected: balance 400, transactions: ['Debited 100 from Account A']
+  console.log('Account B:', accountB.get()); // Expected: balance 300, transactions: ['Credited 100 to Account B']
 } catch (error: any) {
   console.error('Transfer 1 failed:', error.message);
 }
 
-// Failed transfer (insufficient funds)
+// --- Scenario 2: Failed transfer (insufficient funds) ---
+console.log('\n--- Attempting failed transfer (1000) ---');
 try {
-  await transferFunds(accountA, accountB, 1000); // Account A only has 400
+  // Account A only has 400 now, so this should fail
+  await transferFunds(accountA, accountB, 1000); 
 } catch (error: any) {
-  console.error('Transfer 2 failed:', error.message);
+  console.error('Transfer 2 failed as expected:', error.message);
 } finally {
   console.log('Transfer 2 attempt, state after rollback:');
-  console.log('Account A:', accountA.get()); // Expected: balance 400 (rolled back to state before transfer attempt)
-  console.log('Account B:', accountB.get()); // Expected: balance 300 (rolled back to state before transfer attempt)
+  // State should be rolled back to its state *before* the transaction attempt
+  console.log('Account A:', accountA.get()); 
+  // Expected: balance 400 (rolled back)
+  console.log('Account B:', accountB.get()); 
+  // Expected: balance 300 (rolled back)
 }
 ```
 
-### Store Observability
+### Store Observer
 
-The `StoreObservability` class provides advanced debugging and monitoring capabilities for any `ReactiveDataStore` instance. It allows you to inspect event history, state changes, and time-travel through your application's state.
+The `StoreObserver` class provides advanced debugging and monitoring capabilities for any `ReactiveDataStore` instance. It allows you to inspect event history, state changes, and time-travel through your application's state.
 
 ```typescript
-import { ReactiveDataStore, StoreObservability } from '@asaidimu/utils-store';
+import { ReactiveDataStore, StoreObserver, type StoreEvent, type DeepPartial } from '@asaidimu/utils-store';
 
 interface DebuggableState {
   user: { name: string; status: 'online' | 'offline' };
   messages: string[];
-  settings: { debugMode: boolean };
+  settings: { debugMode: boolean; logLevel: string };
+  metrics: { updates: number };
 }
 
 const store = new ReactiveDataStore<DebuggableState>({
   user: { name: 'Debugger', status: 'online' },
   messages: [],
-  settings: { debugMode: true },
+  settings: { debugMode: true, logLevel: 'info' },
+  metrics: { updates: 0 },
 });
 
 // Initialize observability for the store
-const observability = new StoreObservability(store, {
-  maxEvents: 100,            // Keep up to 100 events in history
-  maxStateHistory: 10,       // Keep up to 10 state snapshots for time-travel
+const observer = new StoreObserver(store, {
+  maxEvents: 50,             // Keep up to 50 events in history
+  maxStateHistory: 5,        // Keep up to 5 state snapshots for time-travel
   enableConsoleLogging: true, // Log events to console for immediate feedback
   logEvents: {
     updates: true,           // Log all update lifecycle events
@@ -567,70 +647,92 @@ const observability = new StoreObservability(store, {
   },
 });
 
+// Add a simple middleware to demonstrate middleware logging
+store.use({ name: 'SimpleMiddleware', action: async (state, update) => {
+  await new Promise(resolve => setTimeout(resolve, 10)); // Simulate work
+  return { metrics: { updates: state.metrics.updates + 1 } };
+}});
+
 // Perform some state updates
 await store.set({ user: { status: 'offline' } });
 await store.set({ messages: ['Hello World!'] });
 await store.set({ settings: { debugMode: false } });
 
+// Simulate a slow update
+await new Promise(resolve => setTimeout(resolve, 60)); // Artificially delay
+await store.set({ messages: ['Another message', 'And another'] });
+// This last set will cause a console warning for "Slow update detected" if enableConsoleLogging is true.
+
 // 1. Get Event History
-console.log('\n--- Event History ---');
-const events = observability.getEventHistory();
+console.log('\n--- Event History (Most Recent First) ---');
+const events = observer.getEventHistory();
 // Events will include: update:start, update:complete (multiple times), middleware:start, middleware:complete, etc.
-events.forEach(event => console.log(`${event.type} at ${new Date(event.timestamp).toLocaleTimeString()}`));
+events.slice(0, 5).forEach(event => console.log(`Type: ${event.type}, Data: ${JSON.stringify(event.data).substring(0, 70)}...`));
 
 // 2. Get State History
 console.log('\n--- State History (Most Recent First) ---');
-const stateSnapshots = observability.getStateHistory();
-stateSnapshots.forEach((snapshot, index) => console.log(`State #${index}:`, snapshot));
+const stateSnapshots = observer.getStateHistory();
+stateSnapshots.forEach((snapshot, index) => console.log(`State #${index}:`, snapshot.messages, snapshot.user.status));
 
 // 3. Get Recent Changes
-console.log('\n--- Recent State Changes (Diff) ---');
-const recentChanges = observability.getRecentChanges(3); // Show diffs for last 3 changes
+console.log('\n--- Recent State Changes (Diffs) ---');
+const recentChanges = observer.getRecentChanges(3); // Show diffs for last 3 changes
 recentChanges.forEach((change, index) => {
-  console.log(`Change #${index}:`, {
-    timestamp: new Date(change.timestamp).toLocaleTimeString(),
-    changedPaths: change.changedPaths,
-    from: change.from,
-    to: change.to,
-  });
+  console.log(`\nChange #${index}:`);
+  console.log(`  Timestamp: ${new Date(change.timestamp).toLocaleTimeString()}`);
+  console.log(`  Changed Paths: ${change.changedPaths.join(', ')}`);
+  console.log(`  From:`, change.from);
+  console.log(`  To:`, change.to);
 });
 
 // 4. Time-Travel Debugging
 console.log('\n--- Time-Travel ---');
-const timeTravel = observability.createTimeTravel();
+const timeTravel = observer.createTimeTravel();
 
-await store.set({ user: { status: 'online' } }); // State 4
-await store.set({ messages: ['First message'] }); // State 3
-await store.set({ messages: ['Second message'] }); // State 2
+// Add more states to the history for time-travel
+await store.set({ user: { status: 'online' } });   // State A (latest)
+await store.set({ messages: ['First message'] });  // State B
+await store.set({ messages: ['Second message'] }); // State C
 
-console.log('Current state (latest):', store.get().messages);
+console.log('Current state (latest):', store.get().messages); // Output: ['Second message']
 
 if (timeTravel.canUndo()) {
-  await timeTravel.undo(); // Go back to State 3
-  console.log('After undo 1:', store.get().messages);
+  await timeTravel.undo(); // Go back to State B
+  console.log('After undo 1:', store.get().messages); // Output: ['First message']
 }
 
 if (timeTravel.canUndo()) {
-  await timeTravel.undo(); // Go back to State 4
-  console.log('After undo 2:', store.get().messages);
+  await timeTravel.undo(); // Go back to State A
+  console.log('After undo 2:', store.get().messages); // Output: [] (original initial state)
 }
 
 if (timeTravel.canRedo()) {
-  await timeTravel.redo(); // Go forward to State 3
-  console.log('After redo 1:', store.get().messages);
+  await timeTravel.redo(); // Go forward to State B
+  console.log('After redo 1:', store.get().messages); // Output: ['First message']
 }
 
-// 5. Custom Debugging Middleware
-const loggingMiddleware = observability.createLoggingMiddleware({
-  logLevel: 'info',
+console.log('Time-Travel history length:', timeTravel.getHistoryLength()); // Will be `maxStateHistory` (5 in this case) + any initial states.
+
+// 5. Custom Debugging Middleware (provided by StoreObserver for convenience)
+const loggingMiddleware = observer.createLoggingMiddleware({
+  logLevel: 'info', // 'debug', 'info', 'warn'
   logUpdates: true,
 });
-store.use({ name: 'DebugLogging', action: loggingMiddleware });
+const loggingMiddlewareId = store.use({ name: 'DebugLogging', action: loggingMiddleware });
+
+await store.set({ user: { name: 'New User Via Debug Logger' } }); // This update will be logged by the created middleware.
+// Expected console output: "State Update: { user: { name: 'New User Via Debug Logger' } }"
 
-await store.set({ user: { name: 'New User' } }); // This update will be logged by the created middleware.
+// 6. Clear history
+observer.clearHistory();
+console.log('\nHistory cleared. Events:', observer.getEventHistory().length, 'State snapshots:', observer.getStateHistory().length);
+// Output: History cleared. Events: 0 State snapshots: 1 (keeps current state)
 
-// 6. Disconnect observability when no longer needed to prevent memory leaks
-observability.disconnect();
+// 7. Disconnect observer when no longer needed to prevent memory leaks
+observer.disconnect();
+console.log('\nObserver disconnected. No more events or state changes will be tracked.');
+// After disconnect, new updates won't be logged or tracked by Observer
+await store.set({ messages: ['Final message after disconnect'] });
 ```
 
 ### Event System
@@ -642,75 +744,104 @@ import { ReactiveDataStore, StoreEvent } from '@asaidimu/utils-store';
 
 interface MyState {
   value: number;
+  status: string;
 }
 
-const store = new ReactiveDataStore<MyState>({ value: 0 });
+const store = new ReactiveDataStore<MyState>({ value: 0, status: 'idle' });
 
 // Subscribe to 'update:start' event
 store.onStoreEvent('update:start', (data) => {
-  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] Update started.`);
+  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ⚡ Update started.`);
 });
 
 // Subscribe to 'update:complete' event
 store.onStoreEvent('update:complete', (data) => {
   if (data.blocked) {
-    console.warn(`[${new Date(data.timestamp).toLocaleTimeString()}] Update blocked. Error:`, data.error?.message);
+    console.warn(`[${new Date(data.timestamp).toLocaleTimeString()}] ✋ Update blocked. Error:`, data.error?.message);
   } else {
-    console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] Update complete. Changed paths: ${data.changedPaths?.join(', ')} (took ${data.duration?.toFixed(2)}ms)`);
+    console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ✅ Update complete. Changed paths: ${data.changedPaths?.join(', ')} (took ${data.duration?.toFixed(2)}ms)`);
   }
 });
 
 // Subscribe to middleware events
 store.onStoreEvent('middleware:start', (data) => {
-  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] Middleware "${data.name}" (${data.type}) started.`);
+  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ▶ Middleware "${data.name}" (${data.type}) started.`);
 });
 
 store.onStoreEvent('middleware:complete', (data) => {
-  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] Middleware "${data.name}" (${data.type}) completed in ${data.duration?.toFixed(2)}ms.`);
+  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ◀ Middleware "${data.name}" (${data.type}) completed in ${data.duration?.toFixed(2)}ms.`);
 });
 
 store.onStoreEvent('middleware:error', (data) => {
-  console.error(`[${new Date(data.timestamp).toLocaleTimeString()}] Middleware "${data.name}" failed:`, data.error);
+  console.error(`[${new Date(data.timestamp).toLocaleTimeString()}] ❌ Middleware "${data.name}" failed:`, data.error);
+});
+
+store.onStoreEvent('middleware:blocked', (data) => {
+  console.warn(`[${new Date(data.timestamp).toLocaleTimeString()}] 🛑 Middleware "${data.name}" blocked an update.`);
+});
+
+store.onStoreEvent('middleware:executed', (data) => {
+  // This event captures detailed execution info for all middlewares
+  console.debug(`[${new Date(data.timestamp).toLocaleTimeString()}] 📊 Middleware executed: "${data.name}" - Duration: ${data.duration?.toFixed(2)}ms, Blocked: ${data.blocked}`);
 });
 
 // Subscribe to transaction events
 store.onStoreEvent('transaction:start', (data) => {
-  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] Transaction started.`);
+  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] 📦 Transaction started.`);
 });
 
 store.onStoreEvent('transaction:complete', (data) => {
-  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] Transaction complete.`);
+  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] 📦 Transaction complete.`);
 });
 
 store.onStoreEvent('transaction:error', (data) => {
-  console.error(`[${new Date(data.timestamp).toLocaleTimeString()}] Transaction failed:`, data.error);
+  console.error(`[${new Date(data.timestamp).toLocaleTimeString()}] 📦 Transaction failed:`, data.error);
 });
 
 // Subscribe to persistence events
 store.onStoreEvent('persistence:ready', (data) => {
-  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] Persistence layer is ready.`);
+  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] 💾 Persistence layer is ready.`);
 });
 
 
-// Add a middleware to demonstrate
+// Add a transform middleware to demonstrate
 store.use({
-  name: 'SampleMiddleware',
+  name: 'ValueIncrementMiddleware',
   action: (state, update) => {
     return { value: state.value + (update.value || 0) };
   },
 });
 
+// Add a blocking middleware to demonstrate
+store.use({
+  name: 'StatusValidationMiddleware',
+  block: true,
+  action: (state, update) => {
+    if (update.status === 'error' && state.value < 10) {
+      throw new Error('Cannot set status to error if value is too low!');
+    }
+    return true;
+  },
+});
+
 // Perform operations
-await store.set({ value: 10 });
+console.log('\n--- Perform Initial Update ---');
+await store.set({ value: 5, status: 'active' }); // Will increment value by 5
 
+console.log('\n--- Perform Transactional Update (Success) ---');
 await store.transaction(async () => {
-  await store.set({ value: 5 }); // Inside transaction
-  if (store.get().value > 15) {
-    throw new Error('Value too high!');
-  }
+  await store.set({ value: 3 }); // Inside transaction, value becomes 5 + 3 = 8
+  await store.set({ status: 'processing' });
 });
 
-console.log('Final value:', store.get().value);
+console.log('\n--- Perform Update (Blocked by Middleware) ---');
+try {
+  await store.set({ status: 'error' }); // This should be blocked by StatusValidationMiddleware (value is 8, which is < 10)
+} catch (e: any) {
+  console.log(`Caught expected error: ${e.message}`);
+}
+
+console.log('Final value:', store.get().value, 'Final status:', store.get().status);
 ```
 
 ---
@@ -719,58 +850,47 @@ console.log('Final value:', store.get().value);
 
 The `@asaidimu/utils-store` library is built with a modular, component-based architecture to promote maintainability, testability, and extensibility.
 
-```
-src/store/
-├─── diff.ts              # Efficient change detection and path derivation
-├─── metrics.ts           # Gathers performance metrics from store events
-├─── middleware.ts        # Manages and executes state transformation and blocking middlewares
-├─── observability.ts     # Optional module for deep debugging, state history, and time-travel
-├─── persistence.ts       # Handles integration with external SimplePersistence implementations
-├─── state.ts             # Core immutable state management and internal change notifications
-├─── store.ts             # The main ReactiveDataStore class, orchestrates all components
-├─── transactions.ts      # Provides atomic state update transactions with rollback
-├─── types.ts             # Central TypeScript type definitions for the entire store
-└─── index.ts             # Export barrel file for the store module
-```
-
 ### Core Components
 
 *   **`ReactiveDataStore<T>` (store.ts)**: The primary entry point and public API for the state management system. It acts as an orchestrator, delegating tasks to specialized internal components. It manages the update queue and public interfaces like `set`, `get`, `subscribe`, `transaction`, `use`, and `onStoreEvent`.
 *   **`CoreStateManager<T>` (state.ts)**: Encapsulates the actual, immutable state (`cache`). It's responsible for applying incoming state changes, performing efficient `diff`ing to identify modified paths, and notifying internal listeners (via an `updateBus`) about concrete state changes.
-*   **`MiddlewareEngine<T>` (middleware.ts)**: Manages the registration and execution of middleware functions. It differentiates between `blocking` middleware (which can halt an update) and `transform` middleware (which can modify the update payload), ensuring they run in the correct order.
+*   **`MiddlewareEngine<T>` (middleware.ts)**: Manages the registration and execution of middleware functions. It differentiates between `blocking` middleware (which can halt an update) and `transform` middleware (which can modify the update payload), ensuring they run in the correct order. It also emits detailed lifecycle events for observability.
 *   **`PersistenceHandler<T>` (persistence.ts)**: Deals with external data persistence. It loads initial state from a provided `SimplePersistence` implementation and saves subsequent state changes. It also listens for external updates from the persistence layer to keep the in-memory state synchronized.
-*   **`TransactionManager<T>` (transactions.ts)**: Provides atomic state operations. It creates a snapshot of the state before an `operation` and, if the operation fails, it ensures the state is reverted to this snapshot, guaranteeing data integrity.
-*   **`MetricsCollector` (metrics.ts)**: Observes the internal `eventBus` to gather and expose performance metrics of the store, such as update counts, listener executions, and average update times.
-*   **`StoreObservability<T>` (observability.ts)**: An optional, but highly recommended, debugging companion. It taps into the `ReactiveDataStore`'s events and state changes to build a comprehensive history of events and state snapshots, enabling time-travel debugging, detailed console logging, and performance monitoring.
-*   **`merge` (merge.ts)**: A utility function for deep merging objects, preserving immutability and handling `Symbol.for("delete")` for property removal.
-*   **`diff` (diff.ts)**: A utility function that efficiently compares two objects (original and partial) and returns an array of paths that have changed. This is crucial for optimizing listener notifications.
+*   **`TransactionManager<T>` (transactions.ts)**: Provides atomic state operations. It creates a snapshot of the state before an `operation` and, if the operation fails, it ensures the state is reverted to this snapshot, guaranteeing data integrity. It integrates closely with the store's event system for tracking.
+*   **`MetricsCollector` (metrics.ts)**: Observes the internal `eventBus` to gather and expose real-time performance metrics of the store, such as update counts, listener executions, and average update times.
+*   **`StoreObserver<T>` (observability.ts)**: An optional, but highly recommended, debugging companion. It taps into the `ReactiveDataStore`'s events and state changes to build a comprehensive history of events and state snapshots, enabling time-travel debugging, detailed console logging, and performance monitoring.
+*   **`createMerge` (merge.ts)**: A factory function that returns a configurable deep merging utility. This utility preserves immutability and specifically handles `Symbol.for("delete")` for explicit property removal.
+*   **`createDiff` / `createDerivePaths` (diff.ts)**: Factory functions returning utilities for efficient comparison between two objects (original vs. changes) to identify changed paths (`diff`) and for deriving all parent paths from a set of changes (`derivePaths`). This is crucial for optimizing listener notifications and change detection.
 
 ### Data Flow
 
 The `ReactiveDataStore` handles state updates in a robust, queued manner.
 
 1.  **`store.set(update)` call**:
-    *   If an update is already in progress (`isUpdating`), the new `update` is queued in `pendingUpdates`.
+    *   If an update is already in progress (`isUpdating`), the new `update` is queued in `pendingUpdates` (available via `store.state().pendingChanges`). This ensures sequential processing and prevents race conditions.
     *   An `update:start` event is emitted.
 2.  **Middleware Execution**:
-    *   The `MiddlewareEngine` first runs all `blocking` middlewares with the current state and incoming `DeepPartial` update. If any blocking middleware returns `false` or throws an error, the update is halted, an `update:complete` (blocked) event is emitted, and the process stops.
-    *   If not blocked, `transform` middlewares are executed sequentially. Each transform middleware can modify the update payload.
+    *   The `MiddlewareEngine` first runs all `blocking` middlewares (registered via `store.use({ block: true, ... })`). If any blocking middleware returns `false` or throws an error, the update is halted, an `update:complete` (blocked) event is emitted, and the process stops.
+    *   If not blocked, `transform` middlewares (registered via `store.use({ action: ... })`) are executed sequentially. Each transform middleware receives the current state and the incoming partial update, and can return a new partial state that is merged into the effective update payload.
+    *   Lifecycle events (`middleware:start`, `middleware:complete`, `middleware:error`, `middleware:blocked`, `middleware:executed`) are emitted during this phase for observability.
 3.  **State Application**:
-    *   The `CoreStateManager` receives the (potentially transformed) update.
-    *   It performs a `diff` comparison between the current state and the new state to identify all changed paths.
-    *   If changes are detected, the `CoreStateManager` updates its internal immutable state (`cache`) and then emits an `update` event for each changed path on its internal `updateBus`.
+    *   The `CoreStateManager` receives the (potentially transformed) final `DeepPartial` update.
+    *   It internally uses the `merge` function to create the new full state object immutably.
+    *   It then performs a `diff` comparison between the *previous* state and the *new* state to identify all changed paths (`string[]`).
+    *   If changes are detected, the `CoreStateManager` updates its internal immutable `cache` to the `newState` and then emits an `update` event for each granular `changedPath` on its internal `updateBus`.
 4.  **Listener Notification**:
-    *   Any external subscribers (from `store.subscribe()`) whose registered paths match or are parent paths of the `changedPaths` are notified with the latest state.
+    *   Any external subscribers (registered with `store.subscribe()`) whose registered paths match or are parent paths of the `changedPaths` are notified with the latest state. The `MetricsCollector` tracks `listenerExecutions`.
 5.  **Persistence Handling**:
-    *   The `PersistenceHandler` receives the `changedPaths` and the new state. If a `SimplePersistence` implementation is configured, it attempts to save the new state.
+    *   The `PersistenceHandler` receives the `changedPaths` and the new state. If a `SimplePersistence` implementation was configured during store initialization, it attempts to save the new state using `persistence.set()`.
+    *   The `PersistenceHandler` also manages loading initial state and reacting to external state changes (e.g., from other browser tabs or processes) through `persistence.subscribe()`.
 6.  **Completion & Queue Processing**:
     *   An `update:complete` event is emitted, containing information about the update's duration, changed paths, and any blocking errors.
-    *   The `isUpdating` flag is reset, and if there are `pendingUpdates`, the next update in the queue is immediately processed.
+    *   The `isUpdating` flag is reset, and if there are `pendingUpdates` in the queue, the next update is immediately pulled and processed, ensuring sequential updates.
 
 ### Extension Points
 
-*   **Custom Middleware**: Users can inject their own `Middleware` and `BlockingMiddleware` functions using `store.use()` to customize update logic, add logging, validation, or side effects.
-*   **Custom Persistence**: The `SimplePersistence<T>` interface allows developers to integrate the store with any storage solution, whether it's local storage, IndexedDB, a backend API, or a WebSocket connection.
+*   **Custom Middleware**: Users can inject their own `Middleware` and `BlockingMiddleware` functions using `store.use()` to customize update logic, add logging, validation, authorization, or trigger side effects.
+*   **Custom Persistence**: The `SimplePersistence<T>` interface allows developers to integrate the store with any storage solution, whether it's local storage, IndexedDB, a backend API, or a WebSocket connection, providing full control over data durability.
 
 ---
 
@@ -782,35 +902,33 @@ Contributions are welcome! Follow these guidelines to get started.
 
 1.  **Clone the repository:**
     ```bash
-    git clone https://github.com/asaidimu/utils.git
-    cd utils
+    git clone https://github.com/asaidimu/erp-utils.git
+    cd erp-utils
     ```
 2.  **Install dependencies:**
-    The `@asaidimu/utils-store` module is part of a monorepo (likely `pnpm` workspaces).
+    The `@asaidimu/utils-store` module is part of a monorepo managed with `pnpm` workspaces.
     ```bash
     pnpm install
-    # Or if you don't have pnpm:
-    # npm install -g pnpm
-    # pnpm install
+    # If you don't have pnpm installed globally: npm install -g pnpm
     ```
 3.  **Build the project:**
-    Navigate to the `store` package directory and run the build script.
+    Navigate to the `store` package directory and run the build script, or build the entire monorepo from the root.
     ```bash
-    cd packages/store # (Assuming the store package is in 'packages/store')
+    cd src/store # (from the monorepo root)
     pnpm build # or npm run build
-    ```
-    Alternatively, you might be able to build the whole monorepo from the root:
-    ```bash
-    pnpm build # (from the monorepo root)
+    # Or, from the monorepo root:
+    # pnpm build
     ```
 
 ### Scripts
 
+From the `src/store` directory:
+
 *   `pnpm test`: Runs all unit tests using Vitest.
-*   `pnpm test:watch`: Runs tests in watch mode.
+*   `pnpm test:watch`: Runs tests in watch mode for continuous development.
 *   `pnpm lint`: Lints the codebase using ESLint.
 *   `pnpm format`: Formats the code using Prettier.
-*   `pnpm build`: Compiles TypeScript to JavaScript.
+*   `pnpm build`: Compiles TypeScript to JavaScript and generates declaration files.
 
 ### Testing
 
@@ -819,12 +937,14 @@ All tests are written with [Vitest](https://vitest.dev/).
 To run tests:
 
 ```bash
+cd src/store
 pnpm test
 ```
 
 To run tests and watch for changes during development:
 
 ```bash
+cd src/store
 pnpm test:watch
 ```
 
@@ -836,11 +956,11 @@ Ensure all new features have comprehensive test coverage and existing tests pass
 2.  **Ensure code quality**: Write clean, readable, and maintainable code. Adhere to existing coding styles.
 3.  **Tests**: Add unit and integration tests for new features or bug fixes. Ensure all existing tests pass.
 4.  **Commit messages**: Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for clear and consistent commit history (e.g., `feat: add new feature`, `fix: resolve bug`).
-5.  **Pull Requests**: Open a pull request to the `main` branch. Describe your changes clearly and link to any relevant issues.
+5.  **Pull Requests**: Open a pull request to the `main` branch of the `erp-utils` repository. Describe your changes clearly and link to any relevant issues.
 
 ### Issue Reporting
 
-If you find a bug or have a feature request, please open an issue on the [GitHub repository](https://github.com/asaidimu/utils-issues).
+If you find a bug or have a feature request, please open an issue on the [GitHub repository](https://github.com/asaidimu/erp-utils/issues).
 *   For bugs, include steps to reproduce, expected behavior, and actual behavior.
 *   For feature requests, describe the use case and proposed solution.
 
@@ -851,47 +971,48 @@ If you find a bug or have a feature request, please open an issue on the [GitHub
 ### Troubleshooting
 
 *   **"Update not triggering listeners"**:
-    *   Ensure you are subscribing to the correct path. `store.subscribe('user.name', ...)` will not trigger if you update `user.email`.
-    *   If the new value is strictly equal (`===`) to the old value, no change will be detected, and listeners will not be notified. The `diff` function effectively handles this.
+    *   Ensure you are subscribing to the correct path. `store.subscribe('user.name', ...)` will not trigger if you update `user.email` (unless you also subscribe to `user` or the root `''`).
+    *   If the new value is strictly equal (`===`) to the old value, no change will be detected by the internal `diff` function, and listeners will not be notified.
     *   Verify your `DeepPartial` update correctly targets the intended part of the state.
 *   **"State not rolling back after transaction error"**:
-    *   Ensure the error is thrown *within* the `transaction` callback. Errors outside will not be caught by the transaction manager.
-    *   Promises within the transaction *must* be `await`ed so the transaction manager can capture potential rejections.
+    *   Ensure the error is thrown *within* the `transaction` callback. Errors caught and handled inside, or thrown outside, will not trigger the rollback mechanism.
+    *   Promises within the transaction *must* be `await`ed so the transaction manager can capture potential rejections and manage the atomic operation.
 *   **"Middleware not being applied"**:
     *   Verify the middleware is registered with `store.use()` *before* the `set` operation it should affect.
-    *   Check middleware `name` if debugging.
-    *   Ensure your middleware returns `DeepPartial<T>` or `void`/`Promise<void>` for transform middleware, and `boolean`/`Promise<boolean>` for blocking middleware.
+    *   Check middleware `name` in console logs (if `StoreObserver` is enabled) to ensure it's being hit.
+    *   Ensure your `transform` middleware returns a `DeepPartial<T>` or `void`/`Promise<void>`, and `blocking` middleware returns `boolean`/`Promise<boolean>`.
 *   **"Performance warnings in console"**:
-    *   If `StoreObservability` is enabled, it will warn about updates or middlewares exceeding defined `performanceThresholds`. This is a warning, not an error. Consider optimizing the specific updates or middlewares identified.
+    *   If `StoreObserver` is enabled with `enableConsoleLogging: true`, it will warn about updates or middlewares exceeding defined `performanceThresholds`. This is an informational warning, not an error, indicating a potentially slow operation that could be optimized.
 
 ### FAQ
 
 **Q: How are arrays handled during updates?**
-A: Arrays are treated as primitive values. When you provide an array in a `DeepPartial` update, the entire array at that path is replaced, not merged. This ensures predictable behavior and prevents complex partial array merging logic.
+A: Arrays are treated as primitive values. When you provide an array in a `DeepPartial` update (e.g., `set({ items: [new Array] })`), the entire array at that path is replaced, not merged. This ensures predictable behavior and prevents complex partial array merging logic.
 
 **Q: What is `Symbol.for("delete")`?**
-A: It's a special symbol used to explicitly remove a property from the state during a `set` operation. If you pass `Symbol.for("delete")` as the value for a key in your `DeepPartial` update, that key will be removed from the state.
+A: It's a special global symbol (`Symbol.for("delete")` evaluates to the same symbol across realms) used to explicitly remove a property from the state during a `set` operation. If you pass `Symbol.for("delete")` as the value for a key in your `DeepPartial` update, that key will be removed from the state object.
 
 **Q: How do I debug my store's state changes?**
-A: The `StoreObservability` class is your primary tool. Instantiate it with your `ReactiveDataStore` instance. It provides methods to get event history, state snapshots, and even time-travel debugging capabilities. Enabling `enableConsoleLogging: true` in `StoreObservability` options provides immediate, formatted console output.
+A: The `StoreObserver` class is your primary tool. Instantiate it with your `ReactiveDataStore` instance. It provides methods to get event history, state snapshots, and even time-travel debugging capabilities. Enabling `enableConsoleLogging: true` in `StoreObserver` options provides immediate, formatted console output during development.
 
 **Q: What is `SimplePersistence<T>`?**
-A: It's a simple interface (`{ get(): Promise<T | null>; set(instanceId: string, state: T): Promise<boolean>; subscribe(instanceId: string, listener: (state: T) => void): () => void; }`) that defines the contract for any persistence layer. You need to provide an implementation of this interface to enable state saving and loading.
+A: It's a simple interface (`{ get(): Promise<T | null>; set(instanceId: string, state: T): Promise<boolean>; subscribe(instanceId: string, listener: (state: T) => void): () => void; }`) that defines the contract for any persistence layer. You need to provide an implementation of this interface to enable state saving and loading. An example can be found in the `InMemoryPersistence` example above.
 
 **Q: Can I use this with React/Vue/Angular?**
-A: Yes. This is a framework-agnostic state management library. You would typically use the `subscribe` method within your framework's lifecycle hooks (e.g., `useEffect` in React) to react to state changes and update your UI components.
+A: Yes. This is a framework-agnostic state management library. You would typically use the `subscribe` method within your framework's lifecycle hooks (e.g., `useEffect` in React, `onMounted` in Vue) to react to state changes and update your UI components.
 
 ### Changelog / Roadmap
 
-*   **Changelog**: For detailed version history, please refer to the [CHANGELOG.md](CHANGELOG.md) file.
+*   **Changelog**: For detailed version history, please refer to the [CHANGELOG.md](https://github.com/asaidimu/erp-utils/blob/main/src/store/CHANGELOG.md) file.
 *   **Roadmap**: Future plans may include:
-    *   Plugins for common integrations (e.g., React hooks, Redux DevTools extension compatibility).
-    *   More advanced query/selector capabilities.
-    *   Built-in serialization options for persistence.
+    *   Official framework integrations (e.g., React hooks library).
+    *   More advanced query/selector capabilities with memoization.
+    *   Built-in serialization/deserialization options for persistence.
+    *   Middleware for common patterns (e.g., async data fetching).
 
 ### License
 
-This project is licensed under the [MIT License](LICENSE).
+This project is licensed under the [MIT License](https://github.com/asaidimu/erp-utils/blob/main/LICENSE).
 
 ### Acknowledgments