@asaidimu/utils-store 2.0.4 → 2.1.0

package/README.md

@@ -1,11 +1,11 @@
-# `@asaidimu/utils-store` 
+# `@asaidimu/utils-store`
 
-**A Reactive Data Store**
+**A Reactive Data Store for TypeScript Applications**
 
-A comprehensive, type-safe, and reactive state management library for TypeScript applications, featuring robust middleware, transactional updates, deep observability, and an optional persistence layer.
+A comprehensive, type-safe, and reactive state management library for TypeScript applications, featuring robust middleware, transactional updates, deep observability, and an optional persistence layer. It simplifies complex state interactions by promoting immutability, explicit updates, and a modular design.
 
 [![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)
+[![License](https://img.shields.io/npm/l/@asaidimu/utils-store?style=flat-square)](https://github.com/asaidimu/erp-utils/blob/main/LICENSE)
 [![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)
 
 ---
@@ -19,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 Observer](#store-observability)
+  - [Store Observer (Debugging & Observability)](#store-observer-debugging--observability)
   - [Event System](#event-system)
 - [Project Architecture](#project-architecture)
 - [Development & Contributing](#development--contributing)
@@ -31,33 +31,32 @@ 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.
 
-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.
+This library offers robust 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 core state management, middleware processing, persistence, and observability.
 
 ### Key Features
 
-*   📊 **Type-safe State Management**: Full TypeScript support for defining and interacting with your application state, leveraging `DeepPartial<T>` for precise, structural updates.
-*   🔄 **Reactive Updates**: Subscribe to granular changes at specific paths within your state or listen for any change, ensuring efficient re-renders or side effects.
+*   📊 **Type-safe State Management**: Full TypeScript support for defining and interacting with your application state, leveraging `DeepPartial<T>` for precise, structural updates while maintaining strong type inference.
+*   🔄 **Reactive Updates & Granular Subscriptions**: Subscribe to granular changes at specific paths within your state or listen for any change, ensuring efficient re-renders or side effects. The internal `diff` algorithm optimizes notifications by identifying only truly changed paths.
 *   🧠 **Composable Middleware System**:
-    *   **Transform Middleware**: Modify, normalize, or enrich state updates before they are applied. Return a `DeepPartial<T>` to apply further changes.
-    *   **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 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.
-    *   **Console Logging**: Configurable, human-readable logging of store events directly to the browser console for immediate feedback during development.
-    *   **Pre-built Debugging Middlewares**: Includes helpers to create a generic logging middleware and a validation middleware.
-*   ✨ **Efficient Change Detection**: Utilizes a custom `diff` algorithm to identify only the truly changed paths (`string[]`), optimizing listener notifications and ensuring minimal overhead.
-*   🗑️ **Property Deletion**: Supports explicit property deletion within partial updates using `Symbol.for("delete")`.
-*   ⚡ **Concurrency Handling**: Automatically queues and processes `set` updates to prevent race conditions during concurrent calls, ensuring updates are applied in order.
+    *   **Transform Middleware**: Intercept, modify, normalize, or enrich state updates before they are applied. These can return a `DeepPartial<T>` to apply further changes or `void` for side effects.
+    *   **Blocking Middleware**: Implement custom validation, authorization, or other conditional logic to prevent invalid state changes from occurring. If a blocking middleware returns `false` or throws an error, the update is immediately halted and rolled back.
+*   📦 **Atomic Transaction Support**: Group multiple state updates into a single, atomic operation. If any update within the transaction fails or an error is thrown, the entire transaction is rolled back to the state before the transaction began, guaranteeing data integrity. Supports both synchronous and asynchronous operations.
+*   💾 **Optional Persistence Layer**: Seamlessly integrate with any `SimplePersistence<T>` implementation (e.g., for local storage, IndexedDB, or backend synchronization) to load an initial state and save subsequent changes. The store emits a `persistence:ready` event and listens for external updates.
+*   🔍 **Deep Observer & Debugging (`StoreObserver`)**: An optional but highly recommended class for unparalleled runtime introspection and debugging:
+    *   **Comprehensive Event History**: Captures a detailed log of all internal store events (`update:start`, `middleware:complete`, `transaction:error`, `persistence:ready`, `middleware:executed`, etc.).
+    *   **State Snapshots**: Maintains a configurable history of your application's state over time, allowing for easy inspection of changes between updates and post-mortem analysis.
+    *   **Time-Travel Debugging**: Leverage the recorded state history to `undo` and `redo` state changes, providing powerful capabilities for debugging complex asynchronous flows and state transitions.
+    *   **Performance Metrics**: Track real-time performance indicators like total update count, listener executions, average update times, largest update size, and slow operation warnings to identify bottlenecks.
+    *   **Configurable Console Logging**: Provides human-readable, color-coded logging of store events directly to the browser console for immediate feedback during development.
+    *   **Pre-built Debugging Middlewares**: Includes helper methods to easily create a generic logging middleware and a validation middleware for immediate use.
+*   🗑️ **Property Deletion**: Supports explicit property deletion within partial updates using the global `Symbol.for("delete")`or a custom marker.
+*   ⚡ **Concurrency Handling**: Automatically queues and processes `set` updates to prevent race conditions during concurrent calls, ensuring updates are applied in a predictable, sequential order.
 
 ---
 
 ## Installation & Setup
 
-Install the entire collection using your preferred package manager. You can then import specific utilities as needed. This library is designed for browser and Node.js environments.
+Install `@asaidimu/utils-store` using your preferred package manager. This library is designed for browser and Node.js environments, providing both CommonJS and ES Module exports.
 
 ```bash
 # Using Bun
@@ -72,12 +71,12 @@ yarn add @asaidimu/utils-store
 
 ### Prerequisites
 
-*   Node.js (LTS version recommended)
-*   TypeScript (for type-safe development)
+*   **Node.js**: (LTS version recommended) for development and compilation.
+*   **TypeScript**: (v4.0+ recommended) for full type-safety during development.
 
 ### Verification
 
-To verify the installation, you can run a simple test script:
+To verify that the library is installed and working correctly, create a small TypeScript file (e.g., `verify.ts`) and run it.
 
 ```typescript
 // verify.ts
@@ -101,24 +100,25 @@ store.subscribe("", (state) => {
 });
 
 console.log("Initial state:", store.get());
-// Output: Initial state: { count: 0, message: "Hello" }
 
 await store.set({ count: 1 });
-// Output:
+// Expected Output:
 // Count changed to: 1
 // Store updated to: {"count":1,"message":"Hello"}
 
 await store.set({ message: "World" });
-// Output:
+// Expected 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" }
+// Expected Output: Current state: { count: 1, message: "World" }
 ```
 
-Run this file:
+Run this file using `ts-node` or compile it first:
+
 ```bash
+# Install ts-node if you don't have it: npm install -g ts-node
 npx ts-node verify.ts
 ```
 
@@ -126,11 +126,11 @@ npx ts-node verify.ts
 
 ## Usage Documentation
 
-This section provides practical examples of how to use `@asaidimu/utils-store` to manage your application state.
+This section provides practical examples and detailed explanations of how to use `@asaidimu/utils-store` to manage your application state effectively.
 
 ### Basic Usage
 
-Creating a store, getting state, and setting updates.
+Learn how to create a store, read state, and update state with partial objects or functions.
 
 ```typescript
 import { ReactiveDataStore, type DeepPartial } from '@asaidimu/utils-store';
@@ -173,25 +173,40 @@ const initialState: AppState = {
 const store = new ReactiveDataStore<AppState>(initialState);
 
 // 3. Get the current state
+// `store.get()` returns a reference to the internal state.
+// Use `store.get(true)` to get a deep clone, ensuring immutability if you modify it directly.
 const currentState = store.get();
 console.log('Initial state:', currentState);
-// Output: Initial state: { user: { ... }, products: [ ... ], ... }
+/* Output:
+Initial state: {
+  user: { id: '123', name: 'Jane Doe', email: 'jane@example.com', isActive: true },
+  products: [ { id: 'p1', name: 'Laptop', price: 1200 }, { id: 'p2', name: 'Mouse', price: 25 } ],
+  settings: { theme: 'light', notificationsEnabled: true },
+  lastUpdated: <timestamp>
+}
+*/
 
-// 4. Update the state using a partial object
-// You can update deeply nested properties without affecting siblings
+// 4. Update the state using a partial object (`DeepPartial<T>`)
+// You can update deeply nested properties without affecting siblings.
 await store.set({
   user: {
-    name: 'Jane Smith',
-    isActive: false,
+    name: 'Jane Smith', // Changes user's name
+    isActive: false,     // Changes user's active status
   },
   settings: {
-    theme: 'dark',
+    theme: 'dark',       // Changes theme
   },
 });
 
 console.log('State after partial update:', store.get());
-// Output: User name is now 'Jane Smith', isActive is false, theme is 'dark'.
-//         Email and products remain unchanged.
+/* Output:
+State after partial update: {
+  user: { id: '123', name: 'Jane Smith', email: 'jane@example.com', isActive: false },
+  products: [ { id: 'p1', name: 'Laptop', price: 1200 }, { id: 'p2', name: 'Mouse', price: 25 } ],
+  settings: { theme: 'dark', notificationsEnabled: true },
+  lastUpdated: <timestamp> // Email and products remain unchanged.
+}
+*/
 
 // 5. Update the state using a function (StateUpdater)
 // This is useful when the new state depends on the current state.
@@ -200,14 +215,14 @@ await store.set((state) => ({
     ...state.products, // Keep existing products
     { id: 'p3', name: 'Keyboard', price: 75 }, // Add a new product
   ],
-  lastUpdated: Date.now(),
+  lastUpdated: Date.now(), // Update timestamp
 }));
 
 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.
+// You can subscribe to the entire state (path: '') or specific paths (e.g., 'user.name', 'settings.notificationsEnabled').
 const unsubscribeUser = store.subscribe('user', (state) => {
   console.log('User data changed:', state.user);
 });
@@ -216,26 +231,28 @@ const unsubscribeNotifications = store.subscribe('settings.notificationsEnabled'
   console.log('Notifications setting changed:', state.settings.notificationsEnabled);
 });
 
-// Subscribe to multiple paths
+// Subscribe to multiple paths at once
 const unsubscribeMulti = store.subscribe(['user.name', 'products'], (state) => {
   console.log('User name or products changed:', state.user.name, state.products.length);
 });
 
-// Subscribe to any change in the store
+// Subscribe to any change in the store (root listener)
 const unsubscribeAll = store.subscribe('', (state) => {
   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). Current products count: 3
+/* Output (order may vary slightly depending on async operations):
+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). Current products count: 3
+*/
 
 await store.set({ settings: { notificationsEnabled: false } });
-// Output:
-// Notifications setting changed: false
-// Store updated (any path changed). Current products count: 3
+/* Output:
+Notifications setting changed: false
+Store updated (any path changed). Current products count: 3
+*/
 
 // 7. Unsubscribe from changes
 unsubscribeUser();
@@ -247,8 +264,8 @@ await store.set({ user: { isActive: true } });
 // No console output from the above listeners after unsubscribing.
 
 // 8. Deleting properties
-// Use Symbol.for("delete") to remove a property from the state.
-// Note: You might need a type cast for TypeScript if strict type checking is enabled.
+// Use `Symbol.for("delete")` to explicitly remove a property from the state.
+// Note: You might need a type cast (e.g., `as DeepPartial<string>`) for TypeScript if strict type checking is enabled.
 const DELETE_ME = Symbol.for("delete");
 await store.set({
   user: {
@@ -261,16 +278,22 @@ 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 store emits a `persistence:ready` event once the persistence layer has loaded any initial state.
+The `ReactiveDataStore` can integrate with any persistence layer that implements the `SimplePersistence<T>` interface. This allows you to load an initial state and automatically save subsequent changes. The store emits a `persistence:ready` event once the persistence layer has loaded any initial state.
 
 ```typescript
 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'; 
+
+// Define the SimplePersistence interface (from `@asaidimu/utils-persistence` or your own)
+interface SimplePersistence<T extends object> {
+  get(): Promise<T | null>;
+  set(instanceId: string, state: T): Promise<boolean>;
+  subscribe(instanceId: string, listener: (state: T) => void): () => void;
+  // An unsubscribe method for the persistence layer is recommended but not enforced by this interface
+}
 
 // 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> {
+// In a real application, this would interact with localStorage, IndexedDB, a backend API, etc.
+class InMemoryPersistence<T extends object> 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();
@@ -281,16 +304,16 @@ class InMemoryPersistence<T> implements SimplePersistence<T> {
 
   async get(): Promise<T | null> {
     console.log('Persistence: Loading state...');
-    return this.data;
+    return this.data ? structuredClone(this.data) : null;
   }
 
   async set(instanceId: string, state: T): Promise<boolean> {
     console.log(`Persistence: Saving state for instance ${instanceId}...`);
-    this.data = state;
-    // Simulate external change notification for other instances
+    this.data = structuredClone(state); // Store a clone
+    // Simulate external change notification for *other* instances
     this.subscribers.forEach((callback, subId) => {
       // Only notify other instances, not the one that just saved
-      if (subId !== instanceId) { 
+      if (subId !== instanceId) {
         callback(structuredClone(this.data!)); // Pass a clone to prevent mutation
       }
     });
@@ -317,34 +340,37 @@ const userConfigPersistence = new InMemoryPersistence<UserConfig>({ theme: 'dark
 
 // 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
+  { theme: 'light', fontSize: 16 }, // Initial state if no persisted data found (or if 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!');
+  store.onStoreEvent('persistence:ready', (data) => {
+    console.log(`Store is ready and persistence is initialized! Timestamp: ${new Date(data.timestamp).toLocaleTimeString()}`);
     resolve();
   });
 });
 
 console.log('Store initial state (before persistence loads):', store.get());
+// Output: Store initial state (before persistence loads): { theme: 'light', fontSize: 16 } (initial state provided to constructor)
 
 await storeReadyPromise; // 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()); 
+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: 'light' });
 console.log('Current theme:', store.get().theme);
 // Output: Current theme: light
+// Persistence: Saving state for instance <uuid>...
 
-// Simulate an external change (e.g., another tab updating the state)
-// 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
+// Simulate an external change (e.g., another tab or process updating the state)
+// Note: The `instanceId` here should be different from the store's `store.id()`
+// to simulate an external change and trigger the store's internal persistence subscription.
+await userConfigPersistence.set('another-instance-id-123', { theme: 'system', fontSize: 20 });
 // 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
@@ -352,11 +378,11 @@ console.log('Current theme after external update:', store.get().theme);
 
 ### Middleware System
 
-Middleware functions allow you to intercept and modify state updates.
+Middleware functions allow you to intercept and modify state updates or prevent them from proceeding.
 
 #### Transform Middleware
 
-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.
+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. If they don't return anything (`void`), the update proceeds as is.
 
 ```typescript
 import { ReactiveDataStore, type DeepPartial } from '@asaidimu/utils-store';
@@ -376,7 +402,7 @@ const store = new ReactiveDataStore<MyState>({
 });
 
 // Middleware 1: Logger
-// Logs the incoming update before it's processed. Does not return anything (void).
+// Logs the incoming update before it's processed. Does not return anything (void), so it doesn't modify the update.
 store.use({
   name: 'LoggerMiddleware',
   action: (state, update) => {
@@ -385,11 +411,10 @@ store.use({
 });
 
 // Middleware 2: Timestamp and Action Tracker
-// Modifies the update to add a timestamp and track the last action. Returns a partial state.
+// Modifies the update to add a timestamp and track the last action. Returns a partial state that gets merged.
 store.use({
   name: 'TimestampActionMiddleware',
   action: (state, update) => {
-    // 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}`,
@@ -399,7 +424,7 @@ store.use({
 });
 
 // Middleware 3: Version Incrementor
-// Increments a version counter for every update.
+// Increments a version counter for every successful update.
 store.use({
   name: 'VersionIncrementMiddleware',
   action: (state) => {
@@ -408,7 +433,8 @@ store.use({
 });
 
 // Middleware 4: Counter Incrementor
-// Increments the counter by the incoming value if the update is a number.
+// This middleware intercepts updates to 'counter' and increments it by the value provided,
+// instead of setting it directly.
 store.use({
   name: 'CounterIncrementMiddleware',
   action: (state, update) => {
@@ -416,13 +442,15 @@ store.use({
     if (typeof update.counter === 'number') {
       return { counter: state.counter + update.counter };
     }
-    // Return original update or void if no transformation needed
+    // Return the original update or void if no transformation is needed for other paths
     return update;
   },
 });
 
 await store.set({ counter: 5 }); // Will increment counter by 5, not set to 5
-// Expected console output from LoggerMiddleware: Middleware: Incoming update: { counter: 5 }
+/* Expected console output from LoggerMiddleware:
+Middleware: Incoming update: { counter: 5 }
+*/
 console.log('State after counter set:', store.get());
 /* Output will show:
   counter: 5 (initial) + 5 (update) = 10,
@@ -432,7 +460,9 @@ console.log('State after counter set:', store.get());
 */
 
 await store.set({ lastAction: 'Manual update from outside middleware' });
-// Expected console output from LoggerMiddleware: Middleware: Incoming update: { 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 will show:
   lastAction will be overwritten by TimestampActionMiddleware logic,
@@ -444,13 +474,13 @@ console.log('State after manual action:', store.get());
 const temporaryLoggerId = store.use({ name: 'TemporaryLogger', action: (s, u) => console.log('Temporary logger saw:', u) });
 await store.set({ counter: 1 });
 // Output: Temporary logger saw: { counter: 1 }
-store.unuse(temporaryLoggerId);
+store.unuse(temporaryLoggerId); // Remove the temporary logger
 await store.set({ counter: 1 }); // TemporaryLogger will not be called now
 ```
 
 #### Blocking Middleware
 
-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.
+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. When an update is blocked, the `update:complete` event will contain `blocked: true` and an `error` property.
 
 ```typescript
 import { ReactiveDataStore, type DeepPartial } from '@asaidimu/utils-store';
@@ -487,17 +517,18 @@ 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.');
+    // If attempting to become admin, check conditions
+    if (update.isAdmin === true) {
+      if (state.age < 21) {
+        console.warn('Blocking update: User must be 21+ to become admin.');
         return false;
+      }
+      if (!state.isVerified) {
+          console.warn('Blocking update: User must be verified to become admin.');
+          return false;
+      }
     }
-    return true;
+    return true; // Allow the update
   },
 });
 
@@ -505,15 +536,15 @@ store.use({
 await store.set({ age: 25 });
 console.log('User age after valid update:', store.get().age); // Output: 25
 
-// Attempt to set an invalid age
+// Attempt to set an invalid age (will be blocked)
 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 while not verified (should fail)
+// Attempt to make user admin while not verified (will be blocked)
 await store.set({ isAdmin: true });
 console.log('User admin status after failed attempt (should be false):', store.get().isAdmin); // Output: false
 
-// Verify user, then attempt to make admin again (should fail due to age)
+// Verify user, then attempt to make admin again (will still be blocked due to age)
 await store.set({ isVerified: true });
 await store.set({ age: 20 });
 await store.set({ isAdmin: true });
@@ -527,7 +558,7 @@ console.log('User admin status after successful attempt (should be true):', stor
 
 ### Transaction Support
 
-Use `store.transaction()` to group multiple state updates into a single atomic operation. If an error occurs during the transaction, all changes made within that transaction will be rolled back.
+Use `store.transaction()` to group multiple state updates into a single atomic operation. If an error occurs during the transaction (either thrown by your `operation` function or by an internal `store.set` call), all changes made within that transaction will be rolled back to the state *before* the transaction began. This guarantees data integrity for complex, multi-step operations.
 
 ```typescript
 import { ReactiveDataStore } from '@asaidimu/utils-store';
@@ -548,7 +579,8 @@ async function transferFunds(
   toStore: ReactiveDataStore<BankAccount>,
   amount: number,
 ) {
-  // All operations inside this transaction will be atomic
+  // All operations inside this transaction will be atomic.
+  // If `operation()` throws an error, the state will revert.
   await fromStore.transaction(async () => {
     console.log(`Starting transfer of ${amount}. From: ${fromStore.get().balance}, To: ${toStore.get().balance}`);
 
@@ -565,6 +597,7 @@ async function transferFunds(
     });
 
     // Simulate a network delay or another async operation that might fail
+    // If an error happens here, the state will still roll back.
     await new Promise(resolve => setTimeout(resolve, 50));
 
     // Add to receiver
@@ -590,29 +623,29 @@ try {
   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);
+  console.error('Transfer 1 failed unexpectedly:', error.message);
 }
 
 // --- Scenario 2: Failed transfer (insufficient funds) ---
 console.log('\n--- Attempting failed transfer (1000) ---');
 try {
-  // Account A only has 400 now, so this should fail
-  await transferFunds(accountA, accountB, 1000); 
+  // Account A now has 400, so this should fail
+  await transferFunds(accountA, accountB, 1000);
 } catch (error: any) {
   console.error('Transfer 2 failed as expected:', error.message);
 } finally {
   console.log('Transfer 2 attempt, state after rollback:');
   // 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)
+  console.log('Account A:', accountA.get());
+  // Expected: balance 400 (rolled back to state before this transaction)
+  console.log('Account B:', accountB.get());
+  // Expected: balance 300 (rolled back to state before this transaction)
 }
 ```
 
-### Store Observer
+### Store Observer (Debugging & Observability)
 
-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.
+The `StoreObserver` class provides advanced debugging and monitoring capabilities for any `ReactiveDataStore` instance. It allows you to inspect event history, state changes, and even time-travel through your application's state. It's an invaluable tool for understanding complex state flows.
 
 ```typescript
 import { ReactiveDataStore, StoreObserver, type StoreEvent, type DeepPartial } from '@asaidimu/utils-store';
@@ -632,23 +665,24 @@ const store = new ReactiveDataStore<DebuggableState>({
 });
 
 // Initialize observability for the store
+// Options allow granular control over what is tracked and logged.
 const observer = new StoreObserver(store, {
-  maxEvents: 50,             // Keep up to 50 events in history
+  maxEvents: 50,             // Keep up to 50 internal store events in history
   maxStateHistory: 5,        // Keep up to 5 state snapshots for time-travel
-  enableConsoleLogging: true, // Log events to console for immediate feedback
+  enableConsoleLogging: true, // Log events to browser console for immediate feedback
   logEvents: {
-    updates: true,           // Log all update lifecycle events
-    middleware: true,        // Log middleware start/complete/error
-    transactions: true,      // Log transaction start/complete/error
+    updates: true,           // Log all update lifecycle events (start/complete)
+    middleware: true,        // Log middleware start/complete/error/blocked/executed events
+    transactions: true,      // Log transaction start/complete/error events
   },
   performanceThresholds: {
-    updateTime: 50,          // Warn if an update takes > 50ms
+    updateTime: 50,          // Warn in console if an update takes > 50ms
     middlewareTime: 20,      // Warn if a middleware takes > 20ms
   },
 });
 
-// Add a simple middleware to demonstrate middleware logging
-store.use({ name: 'SimpleMiddleware', action: async (state, update) => {
+// Add a simple middleware to demonstrate middleware logging and metrics update
+store.use({ name: 'UpdateMetricsMiddleware', action: async (state, update) => {
   await new Promise(resolve => setTimeout(resolve, 10)); // Simulate work
   return { metrics: { updates: state.metrics.updates + 1 } };
 }});
@@ -658,7 +692,7 @@ await store.set({ user: { status: 'offline' } });
 await store.set({ messages: ['Hello World!'] });
 await store.set({ settings: { debugMode: false } });
 
-// Simulate a slow update
+// Simulate a slow update to trigger performance warning
 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.
@@ -672,27 +706,27 @@ events.slice(0, 5).forEach(event => console.log(`Type: ${event.type}, Data: ${JS
 // 2. Get State History
 console.log('\n--- State History (Most Recent First) ---');
 const stateSnapshots = observer.getStateHistory();
-stateSnapshots.forEach((snapshot, index) => console.log(`State #${index}:`, snapshot.messages, snapshot.user.status));
+stateSnapshots.forEach((snapshot, index) => console.log(`State #${index}: Messages: ${snapshot.messages.join(', ')}, User Status: ${snapshot.user.status}`));
 
-// 3. Get Recent Changes
+// 3. Get Recent Changes (Diffs)
 console.log('\n--- Recent State Changes (Diffs) ---');
 const recentChanges = observer.getRecentChanges(3); // Show diffs for last 3 changes
 recentChanges.forEach((change, index) => {
   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);
+  console.log(`  From (partial):`, change.from); // Only changed parts of the state
+  console.log(`  To (partial):`, change.to);     // Only changed parts of the state
 });
 
 // 4. Time-Travel Debugging
 console.log('\n--- Time-Travel ---');
 const timeTravel = observer.createTimeTravel();
 
-// 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
+// Add more states to the history for time-travel demonstration
+await store.set({ user: { status: 'online' } });   // Current State (A)
+await store.set({ messages: ['First message'] });  // Previous State (B)
+await store.set({ messages: ['Second message'] }); // Previous State (C)
 
 console.log('Current state (latest):', store.get().messages); // Output: ['Second message']
 
@@ -703,7 +737,7 @@ if (timeTravel.canUndo()) {
 
 if (timeTravel.canUndo()) {
   await timeTravel.undo(); // Go back to State A
-  console.log('After undo 2:', store.get().messages); // Output: [] (original initial state)
+  console.log('After undo 2:', store.get().messages); // Output: [] (the state before 'First message' was added)
 }
 
 if (timeTravel.canRedo()) {
@@ -711,18 +745,35 @@ if (timeTravel.canRedo()) {
   console.log('After redo 1:', store.get().messages); // Output: ['First message']
 }
 
-console.log('Time-Travel history length:', timeTravel.getHistoryLength()); // Will be `maxStateHistory` (5 in this case) + any initial states.
+console.log('Time-Travel history length:', timeTravel.getHistoryLength()); // Reflects `maxStateHistory` + initial state
 
 // 5. Custom Debugging Middleware (provided by StoreObserver for convenience)
+// Example: A logging middleware that logs every update
 const loggingMiddleware = observer.createLoggingMiddleware({
-  logLevel: 'info', // 'debug', 'info', 'warn'
-  logUpdates: true,
+  logLevel: 'info', // Can be 'debug', 'info', 'warn'
+  logUpdates: true, // Whether to log the update payload itself
 });
 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' } }"
 
+// Example: A validation middleware (blocking)
+const validationMiddleware = observer.createValidationMiddleware((state, update) => {
+    if (update.messages && update.messages.length > 5) {
+        return { valid: false, reason: "Too many messages!" };
+    }
+    return true;
+});
+const validationMiddlewareId = store.use({ name: 'DebugValidation', block: true, action: validationMiddleware });
+
+try {
+    await store.set({ messages: ['m1','m2','m3','m4','m5','m6'] }); // This will be blocked
+} catch (e) {
+    console.warn(`Caught expected error from validation middleware: ${e.message}`);
+}
+console.log('Current messages after failed validation:', store.get().messages); // Should be the state before this set.
+
 // 6. Clear history
 observer.clearHistory();
 console.log('\nHistory cleared. Events:', observer.getEventHistory().length, 'State snapshots:', observer.getStateHistory().length);
@@ -737,10 +788,10 @@ await store.set({ messages: ['Final message after disconnect'] });
 
 ### Event System
 
-The store emits various events during its lifecycle, allowing for advanced monitoring, logging, and integration with external systems. You can subscribe to these events using `store.onStoreEvent()`.
+The store emits various events during its lifecycle, allowing for advanced monitoring, logging, and integration with external systems. You can subscribe to these events using `store.onStoreEvent(eventName, listener)`. The `StoreObserver` leverages this event system internally to provide its rich debugging capabilities.
 
 ```typescript
-import { ReactiveDataStore, StoreEvent } from '@asaidimu/utils-store';
+import { ReactiveDataStore, type StoreEvent } from '@asaidimu/utils-store';
 
 interface MyState {
   value: number;
@@ -749,12 +800,12 @@ interface MyState {
 
 const store = new ReactiveDataStore<MyState>({ value: 0, status: 'idle' });
 
-// Subscribe to 'update:start' event
+// Subscribe to 'update:start' event - triggered before an update begins processing.
 store.onStoreEvent('update:start', (data) => {
   console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ⚡ Update started.`);
 });
 
-// Subscribe to 'update:complete' event
+// Subscribe to 'update:complete' event - triggered after an update is fully applied or blocked.
 store.onStoreEvent('update:complete', (data) => {
   if (data.blocked) {
     console.warn(`[${new Date(data.timestamp).toLocaleTimeString()}] ✋ Update blocked. Error:`, data.error?.message);
@@ -763,7 +814,7 @@ store.onStoreEvent('update:complete', (data) => {
   }
 });
 
-// Subscribe to middleware events
+// Subscribe to middleware lifecycle events
 store.onStoreEvent('middleware:start', (data) => {
   console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ▶ Middleware "${data.name}" (${data.type}) started.`);
 });
@@ -781,11 +832,11 @@ store.onStoreEvent('middleware:blocked', (data) => {
 });
 
 store.onStoreEvent('middleware:executed', (data) => {
-  // This event captures detailed execution info for all middlewares
+  // This event captures detailed execution info for all middlewares, useful for aggregate metrics.
   console.debug(`[${new Date(data.timestamp).toLocaleTimeString()}] 📊 Middleware executed: "${data.name}" - Duration: ${data.duration?.toFixed(2)}ms, Blocked: ${data.blocked}`);
 });
 
-// Subscribe to transaction events
+// Subscribe to transaction lifecycle events
 store.onStoreEvent('transaction:start', (data) => {
   console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] 📦 Transaction started.`);
 });
@@ -804,7 +855,7 @@ store.onStoreEvent('persistence:ready', (data) => {
 });
 
 
-// Add a transform middleware to demonstrate
+// Add a transform middleware to demonstrate `middleware:start/complete/executed`
 store.use({
   name: 'ValueIncrementMiddleware',
   action: (state, update) => {
@@ -812,7 +863,7 @@ store.use({
   },
 });
 
-// Add a blocking middleware to demonstrate
+// Add a blocking middleware to demonstrate `middleware:error` and `update:complete` (blocked)
 store.use({
   name: 'StatusValidationMiddleware',
   block: true,
@@ -824,9 +875,9 @@ store.use({
   },
 });
 
-// Perform operations
+// Perform operations to trigger events
 console.log('\n--- Perform Initial Update ---');
-await store.set({ value: 5, status: 'active' }); // Will increment value by 5
+await store.set({ value: 5, status: 'active' }); // Will increment value by 5 (due to middleware)
 
 console.log('\n--- Perform Transactional Update (Success) ---');
 await store.transaction(async () => {
@@ -836,7 +887,7 @@ await store.transaction(async () => {
 
 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)
+  await store.set({ status: 'error' }); // This should be blocked by StatusValidationMiddleware (current value is 8, which is < 10)
 } catch (e: any) {
   console.log(`Caught expected error: ${e.message}`);
 }
@@ -848,55 +899,71 @@ console.log('Final value:', store.get().value, 'Final status:', store.get().stat
 
 ## Project Architecture
 
-The `@asaidimu/utils-store` library is built with a modular, component-based architecture to promote maintainability, testability, and extensibility.
+The `@asaidimu/utils-store` library is built with a modular, component-based architecture to promote maintainability, testability, and extensibility. Each core concern is encapsulated within its own class, with `ReactiveDataStore` acting as the central coordinator.
+
+```
+src/store/
+├── index.ts                # Main entry point (exports all public APIs)
+├── types.ts                # TypeScript interfaces and types for the store
+├── store.ts                # `ReactiveDataStore` - The main orchestrator
+├── state.ts                # `CoreStateManager` - Manages the immutable state and diffing
+├── merge.ts                # `createMerge` - Deep merging utility with deletion support
+├── diff.ts                 # `createDiff`, `createDerivePaths` - Change detection utilities
+├── middleware.ts           # `MiddlewareEngine` - Manages and executes middleware pipeline
+├── transactions.ts         # `TransactionManager` - Handles atomic state transactions
+├── persistence.ts          # `PersistenceHandler` - Integrates with `SimplePersistence` layer
+├── metrics.ts              # `MetricsCollector` - Gathers runtime performance metrics
+├── observability.ts        # `StoreObserver` - Debugging and introspection utilities
+└── ...                     # (Other test files like *.test.ts, internal helpers)
+```
 
 ### 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. 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. 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.
+*   **`ReactiveDataStore<T>` (`store.ts`)**: The public API and primary entry point. It orchestrates interactions between all other internal components. It manages the update queue, ensures sequential processing of `set` calls, and exposes public methods like `get`, `set`, `subscribe`, `transaction`, `use`, `unuse`, and `onStoreEvent`.
+*   **`CoreStateManager<T>` (`state.ts`)**: Responsible for the direct management of the immutable state (`cache`). It applies incoming state changes, performs efficient object `diff`ing to identify modified paths, and notifies internal listeners (via an `updateBus`) about granular state changes.
+*   **`MiddlewareEngine<T>` (`middleware.ts`)**: Manages the registration and execution of both `blocking` and `transform` middleware functions. It ensures middleware execution order, handles potential errors, and emits detailed lifecycle events for observability.
+*   **`PersistenceHandler<T>` (`persistence.ts`)**: Handles integration with an external persistence layer via the `SimplePersistence` interface. It loads initial state, saves subsequent changes, and listens for external updates from the persistence layer to keep the in-memory state synchronized across multiple instances (e.g., browser tabs).
+*   **`TransactionManager<T>` (`transactions.ts`)**: Provides atomic state operations. It creates a snapshot of the state before an `operation` begins and, if the operation fails, ensures the state is reverted to this snapshot, guaranteeing data integrity. It integrates closely with the store's event system for tracking transaction status.
+*   **`MetricsCollector` (`metrics.ts`)**: Observes the internal `eventBus` to gather and expose real-time performance metrics of the store, such as update counts, listener executions, average update times, and the largest update size.
+*   **`StoreObserver<T>` (`observability.ts`)**: An optional, yet highly valuable, debugging companion. It taps into the `ReactiveDataStore`'s extensive event stream and state changes to build a comprehensive history of events and state snapshots, enabling powerful features like time-travel debugging, detailed console logging, and performance monitoring.
+*   **`createMerge` (`merge.ts`)**: A factory function that returns a configurable deep merging utility (`MergeFunction`). This utility is crucial for immutably applying partial updates and specifically handles `Symbol.for("delete")` for explicit property removal.
+*   **`createDiff` / `createDerivePaths` (`diff.ts`)**: Factory functions returning utilities for efficient comparison between two objects (`diff`) to identify changed paths, and for deriving all parent paths from a set of changes (`derivePaths`). These are fundamental for optimizing listener notifications and internal change detection.
 
 ### Data Flow
 
-The `ReactiveDataStore` handles state updates in a robust, queued manner.
+The `ReactiveDataStore` handles state updates in a robust, queued, and event-driven manner:
 
 1.  **`store.set(update)` call**:
-    *   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.
+    *   If another update is already in progress (`isUpdating`), the new `update` is queued in `pendingUpdates`. This ensures sequential processing and prevents race conditions, and the `store.state().pendingChanges` reflects the queue.
+    *   An `update:start` event is immediately emitted.
 2.  **Middleware Execution**:
-    *   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.
+    *   The `MiddlewareEngine` first executes all `blocking` middlewares (registered via `store.use({ block: true, ... })`). If any blocking middleware returns `false` or throws an error, the update is immediately halted. An `update:complete` event with `blocked: true` is emitted, and the process stops, with the state remaining unchanged.
+    *   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 `DeepPartial<T>` that is then merged into the effective update payload.
+    *   Detailed lifecycle events (`middleware:start`, `middleware:complete`, `middleware:error`, `middleware:blocked`, `middleware:executed`) are emitted during this phase, providing granular insight into middleware behavior.
 3.  **State Application**:
     *   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`.
+    *   It internally uses the `createMerge` utility to immutably construct the new full state object.
+    *   It then performs a `createDiff` comparison between the *previous* state and the *new* state to precisely identify all `changedPaths` (an array of strings).
+    *   If changes are detected, the `CoreStateManager` updates its internal immutable `cache` to the `newState` and then emits an internal `update` event for each granular `changedPath` on its `updateBus`.
 4.  **Listener Notification**:
-    *   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`.
+    *   Any external subscribers (registered with `store.subscribe()`) whose registered paths match or are parent paths of the `changedPaths` are efficiently notified with the latest state. The `MetricsCollector` tracks `listenerExecutions` during this phase.
 5.  **Persistence Handling**:
     *   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` in the queue, the next update is immediately pulled and processed, ensuring sequential updates.
+    *   An `update:complete` event is emitted, containing crucial information about the update's duration, the `changedPaths`, and any blocking errors.
+    *   The `isUpdating` flag is reset. If there are any `pendingUpdates` in the queue, the next update is immediately pulled and processed, ensuring all queued updates are eventually applied in order.
 
 ### Extension Points
 
-*   **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.
+*   **Custom Middleware**: Developers can inject their own `Middleware` (for transformation) and `BlockingMiddleware` (for validation/prevention) functions using `store.use()`. This allows for highly customizable update logic, centralized logging, complex validation, authorization, or triggering specific side effects.
+*   **Custom Persistence**: The `SimplePersistence<T>` interface provides a clear contract for developers to integrate the store with any storage solution, whether it's local storage, IndexedDB, a backend API, or a WebSocket connection. This offers complete control over data durability and synchronization.
 
 ---
 
 ## Development & Contributing
 
-Contributions are welcome! Follow these guidelines to get started.
+Contributions are welcome! Follow these guidelines to get started with local development and contribute to the project.
 
 ### Development Setup
 
@@ -906,7 +973,7 @@ Contributions are welcome! Follow these guidelines to get started.
     cd erp-utils
     ```
 2.  **Install dependencies:**
-    The `@asaidimu/utils-store` module is part of a monorepo managed with `pnpm` workspaces.
+    The `@asaidimu/utils-store` module is part of a monorepo managed with `pnpm` workspaces. Ensure you have `pnpm` installed globally.
     ```bash
     pnpm install
     # If you don't have pnpm installed globally: npm install -g pnpm
@@ -914,25 +981,27 @@ Contributions are welcome! Follow these guidelines to get started.
 3.  **Build the project:**
     Navigate to the `store` package directory and run the build script, or build the entire monorepo from the root.
     ```bash
-    cd src/store # (from the monorepo root)
-    pnpm build # or npm run build
-    # Or, from the monorepo root:
-    # pnpm build
+    # From the monorepo root:
+    pnpm build # Builds all packages in the monorepo
+
+    # Or, from the `src/store` directory:
+    cd src/store
+    pnpm build
     ```
 
 ### Scripts
 
-From the `src/store` directory:
+From the `src/store` directory, the following `pnpm` scripts are available:
 
-*   `pnpm test`: Runs all unit tests using Vitest.
+*   `pnpm test`: Runs all unit tests using [Vitest](https://vitest.dev/).
 *   `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 and generates declaration files.
+*   `pnpm lint`: Lints the codebase using [ESLint](https://eslint.org/).
+*   `pnpm format`: Formats the code using [Prettier](https://prettier.io/).
+*   `pnpm build`: Compiles TypeScript to JavaScript (CommonJS and ES Modules) and generates declaration files (`.d.ts`).
 
 ### Testing
 
-All tests are written with [Vitest](https://vitest.dev/).
+All tests are written using [Vitest](https://vitest.dev/), a fast unit test framework powered by Vite.
 
 To run tests:
 
@@ -948,21 +1017,21 @@ cd src/store
 pnpm test:watch
 ```
 
-Ensure all new features have comprehensive test coverage and existing tests pass.
+Please ensure all new features have comprehensive test coverage and all existing tests pass before submitting a pull request.
 
 ### Contributing Guidelines
 
 1.  **Fork the repository** and create your branch from `main`.
-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 of the `erp-utils` repository. Describe your changes clearly and link to any relevant issues.
+2.  **Ensure code quality**: Write clean, readable, and maintainable code. Adhere to existing coding styles, which are enforced by ESLint and Prettier.
+3.  **Tests**: Add comprehensive 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`, `chore: update dependencies`).
+5.  **Pull Requests**: Open a pull request to the `main` branch of the `asaidimu/erp-utils` repository. Clearly describe your changes, provide context, 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/erp-utils/issues).
-*   For bugs, include steps to reproduce, expected behavior, and actual behavior.
-*   For feature requests, describe the use case and proposed solution.
+*   For **bug reports**, include steps to reproduce, expected behavior, and actual behavior. Provide relevant code snippets or a minimal reproducible example.
+*   For **feature requests**, describe the use case, the problem it solves, and your proposed solution or ideas.
 
 ---
 
@@ -971,44 +1040,45 @@ 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` (unless you also subscribe to `user` or the root `''`).
+    *   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 `''` path).
     *   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 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.
+    *   Ensure the error is thrown *within* the `transaction` callback function. Errors caught and handled inside the callback, or thrown outside of it, will not trigger the rollback mechanism.
+    *   Promises within the transaction *must* be `await`ed so the `TransactionManager` can capture potential rejections and manage the atomic operation correctly.
 *   **"Middleware not being applied"**:
-    *   Verify the middleware is registered with `store.use()` *before* the `set` operation it should affect.
-    *   Check middleware `name` in console logs (if `StoreObserver` is enabled) to ensure it's being hit.
+    *   Verify the middleware is registered with `store.use()` *before* the `set` operation it should affect. Middleware functions are applied in the order they are registered.
+    *   Check middleware `name` in console logs (if `StoreObserver` is enabled with `enableConsoleLogging: true`) to confirm 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 `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.
+    *   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 in your application.
 
 ### FAQ
 
 **Q: How are arrays handled during updates?**
-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.
+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 with the new array, not merged element-by-element. This ensures predictable behavior and avoids complex, potentially ambiguous partial array merging logic.
 
 **Q: What is `Symbol.for("delete")`?**
-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.
+A: `Symbol.for("delete")` is a special global 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 resulting state object. This provides a clear semantic for deletion.
 
 **Q: How do I debug my store's state changes?**
-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.
+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, showing update lifecycles, middleware execution, and transaction events.
 
 **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. An example can be found in the `InMemoryPersistence` example above.
+A: It's a minimal interface that defines the contract for any persistence layer you wish to integrate. It requires `get()`, `set(instanceId, state)`, and `subscribe(instanceId, listener)` methods. You need to provide an implementation of this interface to enable state saving and loading. An example `InMemoryPersistence` implementation is provided in the [Persistence Integration](#persistence-integration) section.
 
-**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, `onMounted` in Vue) to react to state changes and update your UI components.
+**Q: Can I use this with React/Vue/Angular or other UI frameworks?**
+A: Yes, absolutely. 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. The library's reactivity model is independent of any specific framework.
 
 ### Changelog / Roadmap
 
-*   **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:
-    *   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).
+*   **Changelog**: For detailed version history, including new features, bug fixes, and breaking changes, please refer to the project's [CHANGELOG.md](https://github.com/asaidimu/erp-utils/blob/main/src/store/CHANGELOG.md) file.
+*   **Roadmap**: Future plans for `@asaidimu/utils-store` may include:
+    *   Official framework-specific integrations (e.g., React hooks library for easier consumption).
+    *   More advanced query/selector capabilities with built-in memoization for derived state.
+    *   Built-in serialization/deserialization options for persistence, perhaps with schema validation.
+    *   Higher-order middlewares for common patterns (e.g., async data fetching, debouncing updates).
+    *   Further performance optimizations for very large states or high update frequencies.
 
 ### License
 
@@ -1016,6 +1086,6 @@ This project is licensed under the [MIT License](https://github.com/asaidimu/erp
 
 ### Acknowledgments
 
-*   Inspired by modern state management patterns and principles of immutability.
-*   Uses `@asaidimu/events` for the internal event bus.
-*   Utilizes `uuid` for unique instance IDs.
+*   Inspired by modern state management patterns such as Redux, Zustand, and Vuex, emphasizing immutability and explicit state changes.
+*   Leverages the `@asaidimu/events` package for robust internal event bus capabilities.
+*   Utilizes the `uuid` library for generating unique instance IDs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asaidimu/utils-store",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "A reactive data store",
   "main": "index.js",
   "module": "index.mjs",