@asaidimu/utils-store 1.0.0

package/README.md

@@ -0,0 +1,900 @@
+# `@asaidimu/utils-store` - 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)
+
+---
+
+### Quick Links
+
+- [Overview & Features](#overview--features)
+- [Installation & Setup](#installation--setup)
+- [Usage Documentation](#usage-documentation)
+  - [Basic Usage](#basic-usage)
+  - [Persistence Integration](#persistence-integration)
+  - [Middleware System](#middleware-system)
+  - [Transaction Support](#transaction-support)
+  - [Store Observability](#store-observability)
+  - [Event System](#event-system)
+- [Project Architecture](#project-architecture)
+- [Development & Contributing](#development--contributing)
+- [Additional Information](#additional-information)
+
+---
+
+## Overview & Features
+
+`@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.
+
+### 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.
+*   🧠 **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 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.).
+    *   **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.
+
+---
+
+## 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.
+
+```bash
+# Using Bun
+bun add @asaidimu/utils-store
+```
+
+### Prerequisites
+
+*   Node.js (LTS version recommended)
+*   TypeScript (for type-safe development)
+
+### Verification
+
+To verify the installation, you can run a simple test script:
+
+```typescript
+// verify.ts
+import { ReactiveDataStore } from '@asaidimu/utils-store';
+
+interface MyState {
+  count: number;
+  message: string;
+}
+
+const store = new ReactiveDataStore<MyState>({ count: 0, message: "Hello" });
+
+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
+
+console.log("Current state:", store.get());
+
+// Expected Output:
+// Count changed to: 1
+// Current state: { count: 1, message: "World" }
+```
+
+Run this file:
+```bash
+npx ts-node verify.ts
+```
+
+---
+
+## Usage Documentation
+
+This section provides practical examples of how to use `@asaidimu/utils-store` to manage your application state.
+
+### Basic Usage
+
+Creating a store, getting state, and setting updates.
+
+```typescript
+import { ReactiveDataStore, DeepPartial } from '@asaidimu/utils-store';
+
+// 1. Define your state interface for type safety
+interface AppState {
+  user: {
+    id: string;
+    name: string;
+    email: string;
+    isActive: boolean;
+  };
+  products: Array<{ id: string; name: string; price: number }>;
+  settings: {
+    theme: 'light' | 'dark';
+    notificationsEnabled: boolean;
+  };
+  lastUpdated: number;
+}
+
+// 2. Initialize the store with an initial state
+const initialState: AppState = {
+  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: Date.now(),
+};
+
+const store = new ReactiveDataStore<AppState>(initialState);
+
+// 3. Get the current state
+const currentState = store.get();
+console.log('Initial state:', currentState);
+// Output: Initial state: { user: { ... }, products: [ ... ], ... }
+
+// 4. Update the state using a partial object
+// You can update deeply nested properties without affecting siblings
+await store.set({
+  user: {
+    name: 'Jane Smith',
+    isActive: false,
+  },
+  settings: {
+    theme: 'dark',
+  },
+});
+
+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.
+
+// 5. Update the state using a function (StateUpdater)
+// This is useful when the new state depends on the current state.
+await store.set((state) => ({
+  products: [
+    ...state.products, // Keep existing products
+    { id: 'p3', name: 'Keyboard', price: 75 }, // Add a new product
+  ],
+  lastUpdated: Date.now(),
+}));
+
+console.log('State after functional update:', store.get().products.length);
+// Output: State after functional update: 3
+
+// 6. Subscribing to state changes
+// You can subscribe to the entire state or specific paths.
+const unsubscribeUser = store.subscribe('user', (state) => {
+  console.log('User data changed:', state.user);
+});
+
+const unsubscribeNotifications = store.subscribe('settings.notificationsEnabled', (state) => {
+  console.log('Notifications setting changed:', state.settings.notificationsEnabled);
+});
+
+// Subscribe to multiple paths
+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
+const unsubscribeAll = store.subscribe('', (state) => {
+  console.log('Store updated (any path changed).');
+});
+
+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).
+
+await store.set({ settings: { notificationsEnabled: false } });
+// Output:
+// Notifications setting changed: false
+// Store updated (any path changed).
+
+// 7. Unsubscribe from changes
+unsubscribeUser();
+unsubscribeNotifications();
+unsubscribeMulti();
+unsubscribeAll();
+
+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.
+const deleteSymbol = Symbol.for("delete");
+await store.set({
+  user: {
+    email: deleteSymbol as DeepPartial<string> // Cast is needed for type inference
+  }
+});
+console.log('User email after deletion:', store.get().user.email);
+// Output: User email after deletion: undefined
+```
+
+### 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.
+
+```typescript
+import { ReactiveDataStore, StoreEvent } from '@asaidimu/utils-store';
+import { SimplePersistence } from '@core/persistence'; // Your persistence implementation
+
+// 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;
+  private subscribers: Map<string, (state: T) => void> = new Map();
+
+  async get(): Promise<T | null> {
+    console.log('Persistence: Loading state...');
+    return this.data;
+  }
+
+  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.subscribers.forEach((callback, subId) => {
+      if (subId !== instanceId) { // Don't notify the instance that just saved
+        callback(this.data!);
+      }
+    });
+    return true;
+  }
+
+  subscribe(instanceId: string, callback: (state: T) => void): () => void {
+    console.log(`Persistence: Subscribing to external changes for instance ${instanceId}`);
+    this.subscribers.set(instanceId, callback);
+    return () => {
+      console.log(`Persistence: Unsubscribing for instance ${instanceId}`);
+      this.subscribers.delete(instanceId);
+    };
+  }
+}
+
+interface UserConfig {
+  theme: 'light' | 'dark';
+  fontSize: number;
+}
+
+// Create a persistence instance
+const userConfigPersistence = new InMemoryPersistence<UserConfig>();
+
+// Optionally, listen for persistence readiness
+const storeReady = 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:', store.get()); // May reflect initial state if persistence is empty
+
+await storeReady; // Wait for persistence to load/initialize
+
+// Now update the state, which will trigger persistence.set()
+await store.set({ theme: 'dark' });
+console.log('Current theme:', store.get().theme);
+
+// 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.
+console.log('Current theme after external update:', store.get().theme);
+```
+
+### Middleware System
+
+Middleware functions allow you to intercept and modify state updates.
+
+#### 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.
+
+```typescript
+import { ReactiveDataStore, DeepPartial } from '@asaidimu/utils-store';
+
+interface MyState {
+  counter: number;
+  logs: string[];
+  lastAction: string | null;
+}
+
+const store = new ReactiveDataStore<MyState>({
+  counter: 0,
+  logs: [],
+  lastAction: null,
+});
+
+// Middleware 1: Logger
+// Logs the incoming update before it's processed
+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
+store.use({
+  name: 'TimestampActionMiddleware',
+  action: (state, update) => {
+    // This middleware transforms the update by adding `lastAction`
+    const actionDescription = JSON.stringify(update);
+    return {
+      lastAction: `Updated at ${new Date().toLocaleTimeString()} with ${actionDescription}`,
+      logs: [...state.logs, `Update processed: ${actionDescription}`],
+    };
+  },
+});
+
+// Middleware 3: Counter Incrementor
+// Increments the counter whenever a specific property is updated
+store.use({
+  name: 'CounterIncrementMiddleware',
+  action: (state, update) => {
+    if (update.counter !== undefined && typeof update.counter === 'number') {
+      return { counter: state.counter + update.counter };
+    }
+    // Return original update or void if no transformation needed
+    return update;
+  },
+});
+
+await store.set({ counter: 5 }); // Will increment counter by 5, not set to 5
+// Output:
+// 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' }
+console.log('State after manual action:', store.get());
+// Output: lastAction will be overwritten by TimestampActionMiddleware logic
+//         and a new log entry will be added.
+
+// Unuse a middleware by its ID
+const loggerId = store.use({ name: 'AnotherLogger', action: (s, u) => console.log('Another logger', u) });
+await store.set({ counter: 1 });
+store.unuse(loggerId);
+await store.set({ counter: 1 }); // AnotherLogger 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.
+
+```typescript
+import { ReactiveDataStore, DeepPartial } from '@asaidimu/utils-store';
+
+interface UserProfile {
+  name: string;
+  age: number;
+  isAdmin: boolean;
+}
+
+const store = new ReactiveDataStore<UserProfile>({
+  name: 'Guest',
+  age: 0,
+  isAdmin: false,
+});
+
+// Blocking middleware: Age validation
+store.use({
+  block: true, // Mark as a blocking middleware
+  name: 'AgeValidationMiddleware',
+  action: (state, update) => {
+    if (update.age !== undefined && update.age < 18) {
+      console.warn('Blocking update: Age must be 18 or older.');
+      return false; // Block the update
+    }
+    return true; // Allow the update
+  },
+});
+
+// Blocking middleware: Admin check
+store.use({
+  block: true,
+  name: 'AdminRestrictionMiddleware',
+  action: (state, update) => {
+    if (update.isAdmin === true && state.age < 21) {
+      console.warn('Blocking update: User must be 21+ to become admin.');
+      return false;
+    }
+    return true;
+  },
+});
+
+// Attempt to set a valid age
+await store.set({ age: 25 });
+console.log('User age after valid update:', store.get().age); // Output: 25
+
+// Attempt to set an invalid age
+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 });
+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
+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
+```
+
+### 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.
+
+```typescript
+import { ReactiveDataStore } from '@asaidimu/utils-store';
+
+interface BankAccount {
+  balance: number;
+  transactions: string[];
+}
+
+const store = new ReactiveDataStore<BankAccount>({
+  balance: 1000,
+  transactions: ['Initial deposit'],
+});
+
+async function transferFunds(
+  fromStore: ReactiveDataStore<BankAccount>,
+  toStore: ReactiveDataStore<BankAccount>,
+  amount: number,
+) {
+  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) {
+        throw new Error('Insufficient funds');
+      }
+      return {
+        balance: state.balance - amount,
+        transactions: [...state.transactions, `Debited ${amount}`],
+      };
+    });
+
+    // Simulate a delay or another async operation
+    await new Promise(resolve => setTimeout(resolve, 50));
+
+    // Add to receiver
+    await toStore.set((state) => ({
+      balance: state.balance + amount,
+      transactions: [...state.transactions, `Credited ${amount}`],
+    }));
+
+    console.log(`Transfer complete. From: ${fromStore.get().balance}, To: ${toStore.get().balance}`);
+  });
+}
+
+const accountA = new ReactiveDataStore<BankAccount>({ balance: 500, transactions: [] });
+const accountB = new ReactiveDataStore<BankAccount>({ balance: 200, transactions: [] });
+
+// Successful transfer
+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
+} catch (error: any) {
+  console.error('Transfer 1 failed:', error.message);
+}
+
+// Failed transfer (insufficient funds)
+try {
+  await transferFunds(accountA, accountB, 1000); // Account A only has 400
+} catch (error: any) {
+  console.error('Transfer 2 failed:', 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)
+}
+```
+
+### Store Observability
+
+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.
+
+```typescript
+import { ReactiveDataStore, StoreObservability } from '@asaidimu/utils-store';
+
+interface DebuggableState {
+  user: { name: string; status: 'online' | 'offline' };
+  messages: string[];
+  settings: { debugMode: boolean };
+}
+
+const store = new ReactiveDataStore<DebuggableState>({
+  user: { name: 'Debugger', status: 'online' },
+  messages: [],
+  settings: { debugMode: true },
+});
+
+// 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
+  enableConsoleLogging: true, // Log events to 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
+  },
+  performanceThresholds: {
+    updateTime: 50,          // Warn if an update takes > 50ms
+    middlewareTime: 20,      // Warn if a middleware takes > 20ms
+  },
+});
+
+// Perform some state updates
+await store.set({ user: { status: 'offline' } });
+await store.set({ messages: ['Hello World!'] });
+await store.set({ settings: { debugMode: false } });
+
+// 1. Get Event History
+console.log('\n--- Event History ---');
+const events = observability.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()}`));
+
+// 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));
+
+// 3. Get Recent Changes
+console.log('\n--- Recent State Changes (Diff) ---');
+const recentChanges = observability.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,
+  });
+});
+
+// 4. Time-Travel Debugging
+console.log('\n--- Time-Travel ---');
+const timeTravel = observability.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
+
+console.log('Current state (latest):', store.get().messages);
+
+if (timeTravel.canUndo()) {
+  await timeTravel.undo(); // Go back to State 3
+  console.log('After undo 1:', store.get().messages);
+}
+
+if (timeTravel.canUndo()) {
+  await timeTravel.undo(); // Go back to State 4
+  console.log('After undo 2:', store.get().messages);
+}
+
+if (timeTravel.canRedo()) {
+  await timeTravel.redo(); // Go forward to State 3
+  console.log('After redo 1:', store.get().messages);
+}
+
+// 5. Custom Debugging Middleware
+const loggingMiddleware = observability.createLoggingMiddleware({
+  logLevel: 'info',
+  logUpdates: true,
+});
+store.use({ name: 'DebugLogging', action: loggingMiddleware });
+
+await store.set({ user: { name: 'New User' } }); // This update will be logged by the created middleware.
+
+// 6. Disconnect observability when no longer needed to prevent memory leaks
+observability.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()`.
+
+```typescript
+import { ReactiveDataStore, StoreEvent } from '@asaidimu/utils-store';
+
+interface MyState {
+  value: number;
+}
+
+const store = new ReactiveDataStore<MyState>({ value: 0 });
+
+// Subscribe to 'update:start' event
+store.onStoreEvent('update:start', (data) => {
+  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);
+  } else {
+    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.`);
+});
+
+store.onStoreEvent('middleware:complete', (data) => {
+  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);
+});
+
+// Subscribe to transaction events
+store.onStoreEvent('transaction:start', (data) => {
+  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] Transaction started.`);
+});
+
+store.onStoreEvent('transaction:complete', (data) => {
+  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);
+});
+
+// Subscribe to persistence events
+store.onStoreEvent('persistence:ready', (data) => {
+  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] Persistence layer is ready.`);
+});
+
+
+// Add a middleware to demonstrate
+store.use({
+  name: 'SampleMiddleware',
+  action: (state, update) => {
+    return { value: state.value + (update.value || 0) };
+  },
+});
+
+// Perform operations
+await store.set({ value: 10 });
+
+await store.transaction(async () => {
+  await store.set({ value: 5 }); // Inside transaction
+  if (store.get().value > 15) {
+    throw new Error('Value too high!');
+  }
+});
+
+console.log('Final value:', store.get().value);
+```
+
+---
+
+## Project Architecture
+
+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.
+*   **`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.
+
+### 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`.
+    *   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.
+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`.
+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.
+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.
+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.
+
+### 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.
+
+---
+
+## Development & Contributing
+
+Contributions are welcome! Follow these guidelines to get started.
+
+### Development Setup
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/asaidimu/utils.git
+    cd utils
+    ```
+2.  **Install dependencies:**
+    The `@asaidimu/utils-store` module is part of a monorepo (likely `pnpm` workspaces).
+    ```bash
+    pnpm install
+    # Or if you don't have pnpm:
+    # npm install -g pnpm
+    # pnpm install
+    ```
+3.  **Build the project:**
+    Navigate to the `store` package directory and run the build script.
+    ```bash
+    cd packages/store # (Assuming the store package is in 'packages/store')
+    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)
+    ```
+
+### Scripts
+
+*   `pnpm test`: Runs all unit tests using Vitest.
+*   `pnpm test:watch`: Runs tests in watch mode.
+*   `pnpm lint`: Lints the codebase using ESLint.
+*   `pnpm format`: Formats the code using Prettier.
+*   `pnpm build`: Compiles TypeScript to JavaScript.
+
+### Testing
+
+All tests are written with [Vitest](https://vitest.dev/).
+
+To run tests:
+
+```bash
+pnpm test
+```
+
+To run tests and watch for changes during development:
+
+```bash
+pnpm test:watch
+```
+
+Ensure all new features have comprehensive test coverage and existing tests pass.
+
+### 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. 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).
+*   For bugs, include steps to reproduce, expected behavior, and actual behavior.
+*   For feature requests, describe the use case and proposed solution.
+
+---
+
+## Additional Information
+
+### 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.
+    *   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.
+*   **"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.
+*   **"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.
+
+### 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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+### Changelog / Roadmap
+
+*   **Changelog**: For detailed version history, please refer to the [CHANGELOG.md](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.
+
+### License
+
+This project is licensed under the [MIT License](LICENSE).
+
+### 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.