@asaidimu/react-store 1.4.11 → 1.5.0

package/README.md

@@ -3,75 +3,183 @@
 [![npm version](https://img.shields.io/npm/v/@asaidimu/react-store.svg)](https://www.npmjs.com/package/@asaidimu/react-store)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A performant, type-safe state management solution for React with built-in persistence, observability, and middleware support.
+A performant, type-safe state management solution for React with built-in persistence, extensive observability, and a robust middleware system.
 
 ⚠️ **Beta Warning**  
 This package is currently in **beta**. The API is subject to rapid changes and should not be considered stable. Breaking changes may occur frequently without notice as we iterate and improve. We’ll update this warning once the package reaches a stable release. Use at your own risk and share feedback or report issues to help us improve!
 
-## Features
+---
 
-- **Reactive State Management**: Automatically track dependencies and optimize renders.
-- **Type-Safe**: Full TypeScript support with strict type checking.
-- **Middleware Pipeline**: Transform or block updates with regular and blocking middleware.
-- **Transactions**: Atomic state updates with rollback capabilities.
-- **Persistence**: Seamless integration with IndexedDB or WebStorage (localStorage/sessionStorage), including cross-tab synchronization.
-- **Observability**: Built-in metrics, event logging, state history, and time-travel debugging.
-- **Remote Observability**: Send metrics to external systems like OpenTelemetry, Prometheus, or Grafana Cloud.
-- **Performance Optimized**: Smart selector caching and efficient update propagation.
-- **React 18+ Ready**: Built with modern React APIs for maximum compatibility.
+### Table of Contents
 
-## Installation
+*   [Overview & Features](#overview--features)
+*   [Installation & Setup](#installation--setup)
+*   [Usage Documentation](#usage-documentation)
+    *   [Creating a Store](#creating-a-store)
+    *   [Using in Components](#using-in-components)
+    *   [Handling Deletions](#handling-deletions)
+    *   [Persistence](#persistence)
+    *   [Middleware](#middleware)
+    *   [Observability](#observability)
+    *   [Remote Observability](#remote-observability)
+    *   [Transaction Support](#transaction-support)
+    *   [Event System](#event-system)
+    *   [Advanced Hook Properties](#advanced-hook-properties)
+*   [Project Architecture](#project-architecture)
+*   [Development & Contributing](#development--contributing)
+*   [Additional Information](#additional-information)
+    *   [Best Practices](#best-practices)
+    *   [API Reference](#api-reference)
+    *   [Comparison with Other State Management Solutions](#comparison-with-other-state-management-solutions)
+    *   [Changelog](#changelog)
+    *   [License](#license)
+    *   [Acknowledgments](#acknowledgments)
+
+---
+
+## Overview & Features
+
+`@asaidimu/react-store` provides an efficient and predictable way to manage complex application state in React applications. It goes beyond basic state management by integrating features typically found in separate libraries, such as data persistence and comprehensive observability tools, directly into its core. This allows developers to build robust, high-performance applications with deep insights into state changes and application behavior.
+
+Designed with modern React in mind, it leverages `useSyncExternalStore` for optimal performance and reactivity, ensuring components re-render only when relevant parts of the state change. Its flexible design supports a variety of use cases, from simple counter applications to complex data flows requiring atomic updates and cross-tab synchronization.
+
+### Key Features
+
+*   📊 **Reactive State Management**: Automatically tracks dependencies to optimize component renders and ensure efficient updates.
+*   🛡️ **Type-Safe**: Built with TypeScript from the ground up, providing strict type checking and a safer development experience.
+*   ⚙️ **Middleware Pipeline**: Implement custom logic to transform, validate, or log state changes before they are applied. Supports both transforming and blocking middleware.
+*   📦 **Transaction Support**: Group multiple state updates into a single atomic operation, with automatic rollback if any part of the transaction fails.
+*   💾 **Built-in Persistence**: Seamlessly integrate with web storage mechanisms like `IndexedDB` and `WebStorage` (localStorage/sessionStorage), including cross-tab synchronization.
+*   🔍 **Deep Observability**: Gain profound insights into your application's state with built-in metrics, detailed event logging, state history, and time-travel debugging capabilities.
+*   📈 **Remote Observability**: Extend monitoring by sending collected metrics and traces to external systems like OpenTelemetry, Prometheus, or Grafana Cloud.
+*   ⚡ **Performance Optimized**: Features intelligent selector caching and debounced actions to prevent rapid successive calls and ensure smooth application performance.
+*   ⚛️ **React 18+ Ready**: Fully compatible with the latest React versions, leveraging modern APIs for enhanced performance and development ergonomics.
+*   🗑️ **Explicit Deletions**: Use `Symbol.for("delete")` to explicitly remove properties from nested state objects.
+
+## Installation & Setup
+
+### Prerequisites
+
+*   Node.js (v18 or higher recommended)
+*   React (v18 or higher recommended)
+*   A package manager like `bun`, `npm`, or `yarn`.
+
+### Installation Steps
+
+To add `@asaidimu/react-store` to your project, run one of the following commands:
 
 ```bash
 bun install @asaidimu/react-store
+# or
+npm install @asaidimu/react-store
+# or
+yarn add @asaidimu/react-store
+```
+
+### Configuration
+
+No global configuration is required. All options are passed during store creation.
+
+### Verification
+
+You can verify the installation by importing `createStore` and setting up a basic store:
+
+```typescript
+import { createStore } from '@asaidimu/react-store';
+
+const myStore = createStore({
+  state: { value: 'hello' },
+  actions: {
+    setValue: (state, newValue: string) => ({ value: newValue }),
+  },
+});
+
+console.log(myStore().select(s => s.value)); // Should output 'hello'
 ```
 
-## Basic Usage
+If no errors are thrown, the package is correctly installed.
+
+## Usage Documentation
 
 ### Creating a Store
 
+Define your application state and actions, then create a store using `createStore`.
+
 ```tsx
+// src/stores/myStore.ts
 import { createStore } from '@asaidimu/react-store';
 
-const counterStore = createStore({
-  state: {
-    count: 0,
-    user: { name: 'Guest', loggedIn: false },
-  },
+interface AppState {
+  count: number;
+  user: { name: string; loggedIn: boolean; email?: string };
+  settings: { theme: 'light' | 'dark'; notifications: boolean };
+}
+
+const initialState: AppState = {
+  count: 0,
+  user: { name: 'Guest', loggedIn: false },
+  settings: { theme: 'light', notifications: true },
+};
+
+const myStore = createStore({
+  state: initialState,
   actions: {
     increment: (state, amount: number) => ({ count: state.count + amount }),
-    login: async (state, username: string) => {
-      await fetch('/api/login');
-      return { user: { name: username, loggedIn: true } };
+    login: async (state, username: string, email: string) => {
+      // Simulate an asynchronous API call
+      await new Promise(resolve => setTimeout(resolve, 500));
+      return { user: { name: username, loggedIn: true, email } };
     },
+    toggleTheme: (state) => ({
+      settings: { theme: state.settings.theme === 'light' ? 'dark' : 'light' },
+    }),
   },
+}, {
+  debounceTime: 100, // Debounce actions by 100ms
+  enableConsoleLogging: true, // Enable console logs for store events
+  logEvents: { updates: true, transactions: true, middleware: true },
+  performanceThresholds: { updateTime: 20, middlewareTime: 5 }, // Warn for slow operations
 });
 
-export const useCounter = counterStore;
+// Export the hook for use in components
+export const useMyStore = myStore;
 ```
 
 ### Using in Components
 
+Consume your store's state and actions within your React components using the exported hook.
+
 ```tsx
-function Counter() {
-  const { select, actions, isReady } = useCounter();
+// src/components/MyComponent.tsx
+import React from 'react';
+import { useMyStore } from '../stores/myStore';
+
+function MyComponent() {
+  const { select, actions, isReady } = useMyStore();
 
+  // Select specific parts of the state for granular re-renders
   const count = select((state) => state.count);
   const userName = select((state) => state.user.name);
+  const theme = select((state) => state.settings.theme);
 
+  // isReady indicates if persistence has loaded initial state
   if (!isReady) {
-    return <div>Loading persistence...</div>;
+    return <div>Loading store data...</div>;
   }
 
   return (
-    <div>
-      <p>Count: {count}</p>
-      <p>User: {userName}</p>
-      <button onClick={() => actions.increment(1)}>+</button>
-      <button onClick={() => actions.login('user123')}>Login</button>
+    <div style={{ background: theme === 'dark' ? '#333' : '#FFF', color: theme === 'dark' ? '#FFF' : '#333' }}>
+      <h1>Welcome, {userName}!</h1>
+      <p>Current Count: {count}</p>
+      <button onClick={() => actions.increment(1)}>Increment</button>
+      <button onClick={() => actions.increment(5)}>Increment by 5 (debounced)</button>
+      <button onClick={() => actions.login('Alice', 'alice@example.com')}>Login as Alice</button>
+      <button onClick={() => actions.toggleTheme()}>Toggle Theme</button>
     </div>
   );
 }
+
+export default MyComponent;
 ```
 
 ### Handling Deletions
@@ -79,75 +187,223 @@ function Counter() {
 To remove a property from the state, use the `Symbol.for("delete")` symbol in your action’s return value. The store’s internal `merge` function will remove the specified key from the state.
 
 #### Example
-```tsx
-const useStore = createStore({
-  state: { a: 1, b: 2 },
+
+```typescript
+import { createStore } from '@asaidimu/react-store';
+
+const deleteStore = createStore({
+  state: {
+    id: 'product-123',
+    name: 'Fancy Gadget',
+    details: {
+      color: 'blue',
+      weight: '1kg',
+      dimensions: { width: 10, height: 20 }
+    },
+    tags: ['electronics', 'new']
+  },
   actions: {
-    removeA: (state) => ({ a: Symbol.for("delete") }),
+    removeDetails: (state) => ({ details: Symbol.for("delete") }),
+    removeDimensions: (state) => ({ details: { dimensions: Symbol.for("delete") } }),
+    removeTag: (state, tagToRemove: string) => ({
+      tags: state.tags.filter(tag => tag !== tagToRemove)
+    }),
+    clearAllExceptId: (state) => ({
+      name: Symbol.for("delete"),
+      details: Symbol.for("delete"),
+      tags: Symbol.for("delete")
+    })
   },
 });
 
-const { actions } = useStore();
-actions.removeA(); // State becomes { b: 2 }
-```
+async function runDeleteExample() {
+  const { select, actions } = deleteStore();
+
+  console.log("Initial state:", select(s => s));
+  // Initial state: { id: 'product-123', name: 'Fancy Gadget', details: { color: 'blue', weight: '1kg', dimensions: { width: 10, height: 20 } }, tags: ['electronics', 'new'] }
+
+  await actions.removeDimensions();
+  console.log("After removing dimensions:", select(s => s));
+  // After removing dimensions: { id: 'product-123', name: 'Fancy Gadget', details: { color: 'blue', weight: '1kg' }, tags: ['electronics', 'new'] }
 
-## Advanced Features
+  await actions.removeDetails();
+  console.log("After removing details:", select(s => s));
+  // After removing details: { id: 'product-123', name: 'Fancy Gadget', tags: ['electronics', 'new'] }
+
+  await actions.removeTag('new');
+  console.log("After removing 'new' tag:", select(s => s));
+  // After removing 'new' tag: { id: 'product-123', name: 'Fancy Gadget', tags: ['electronics'] }
+
+  await actions.clearAllExceptId();
+  console.log("After clearing all except ID:", select(s => s));
+  // After clearing all except ID: { id: 'product-123' }
+}
+
+runDeleteExample();
+```
 
 ### Persistence
-Persist state across sessions or synchronize across tabs with built-in adapters.
+
+Persist your store's state across browser sessions or synchronize it across multiple tabs.
 
 ```tsx
 import { createStore, WebStoragePersistence, IndexedDBPersistence } from '@asaidimu/react-store';
 
-const persistence = new WebStoragePersistence('my-store'); // Uses localStorage by default
-const useStore = createStore(
+// 1. Using WebStoragePersistence (localStorage by default)
+// Data persists even if the browser tab is closed and reopened.
+const localStorePersistence = new WebStoragePersistence('my-app-state-key');
+const useLocalStore = createStore(
   {
-    state: { count: 0 },
+    state: { sessionCount: 0, lastVisited: new Date().toISOString() },
     actions: {
-      increment: (state) => ({ count: state.count + 1 }),
+      incrementSessionCount: (state) => ({ sessionCount: state.sessionCount + 1 }),
+      updateLastVisited: () => ({ lastVisited: new Date().toISOString() }),
     },
   },
-  { persistence },
+  { persistence: localStorePersistence },
 );
 
-function App() {
-  const { store, isReady } = useStore();
-  if (!isReady) return <div>Loading...</div>;
-  // Use store...
-}
-```
+// 2. Using WebStoragePersistence (sessionStorage)
+// Data only persists for the duration of the browser tab. Clears on tab close.
+const sessionStoragePersistence = new WebStoragePersistence('my-session-state-key', true);
+const useSessionStore = createStore(
+  {
+    state: { tabSpecificData: 'initial' },
+    actions: {
+      updateTabSpecificData: (state, newData: string) => ({ tabSpecificData: newData }),
+    },
+  },
+  { persistence: sessionStoragePersistence },
+);
 
-- **IndexedDBPersistence**: High-capacity storage with cross-tab sync.
-- **WebStoragePersistence**: Lightweight storage with optional sessionStorage support and cross-tab notifications for localStorage.
-- **LocalStoragePersistence** (Deprecated): Alias for `WebStoragePersistence`. Use `WebStoragePersistence` instead for future compatibility.
+// 3. Using IndexedDBPersistence
+// Ideal for larger amounts of data, offers robust cross-tab synchronization.
+const indexedDBPersistence = new IndexedDBPersistence('user-profile-data');
+const useUserProfileStore = createStore(
+  {
+    state: { userId: '', preferences: { language: 'en', darkMode: false } },
+    actions: {
+      setUserId: (state, id: string) => ({ userId: id }),
+      toggleDarkMode: (state) => ({ preferences: { darkMode: !state.preferences.darkMode } }),
+    },
+  },
+  { persistence: indexedDBPersistence },
+);
 
-#### Using sessionStorage
-```tsx
-const persistence = new WebStoragePersistence('my-store', true); // Uses sessionStorage
+function AppWithPersistence() {
+  const { select: selectLocal, actions: actionsLocal, isReady: localReady } = useLocalStore();
+  const { select: selectProfile, actions: actionsProfile, isReady: profileReady } = useUserProfileStore();
+
+  const sessionCount = selectLocal(s => s.sessionCount);
+  const darkMode = selectProfile(s => s.preferences.darkMode);
+
+  React.useEffect(() => {
+    if (localReady) {
+      actionsLocal.incrementSessionCount();
+      actionsLocal.updateLastVisited();
+    }
+    if (profileReady && !selectProfile(s => s.userId)) {
+      actionsProfile.setUserId('user-' + Math.random().toString(36).substring(2, 9));
+    }
+  }, [localReady, profileReady]);
+
+  if (!localReady || !profileReady) {
+    return <div>Loading persisted data...</div>;
+  }
+
+  return (
+    <div>
+      <h3>Local Store</h3>
+      <p>Session Count: {sessionCount}</p>
+      
+      <h3>User Profile Store (IndexedDB)</h3>
+      <p>Dark Mode: {darkMode ? 'Enabled' : 'Disabled'}</p>
+      <button onClick={() => actionsProfile.toggleDarkMode()}>Toggle Dark Mode</button>
+    </div>
+  );
+}
 ```
 
 ### Middleware
 
-```tsx
-const logger = (state, update) => {
-  console.log('Update:', update);
+Middleware functions can intercept and modify or block state updates. They are executed in the order they are added.
+
+```typescript
+import { createStore, Middleware, BlockingMiddleware } from '@asaidimu/react-store';
+
+interface CartState {
+  items: Array<{ id: string; name: string; quantity: number; price: number }>;
+  total: number;
+}
+
+const calculateTotalMiddleware: Middleware<CartState> = (state, update) => {
+  if (update.items) {
+    const newItems = update.items as CartState['items'];
+    const newTotal = newItems.reduce((sum, item) => sum + (item.quantity * item.price), 0);
+    return { ...update, total: newTotal };
+  }
   return update;
 };
 
-const validator = (state, update) => {
-  if (update.count > 100) {
-    console.warn('Count too high!');
-    return false;
+const validateItemMiddleware: BlockingMiddleware<CartState> = (state, update) => {
+  if (update.items) {
+    for (const item of update.items as CartState['items']) {
+      if (item.quantity < 0) {
+        console.warn('Blocked: Item quantity cannot be negative.');
+        return false; // Blocks the update
+      }
+    }
   }
-  return true;
+  return true; // Allows the update
 };
 
-const useStore = createStore({
-  state: { count: 0 },
-  actions: { increment: (state) => ({ count: state.count + 1 }) },
-  middleware: { logger },
-  blockingMiddleware: { validator },
+const useCartStore = createStore({
+  state: { items: [], total: 0 },
+  actions: {
+    addItem: (state, item: { id: string; name: string; price: number }) => {
+      const existingItem = state.items.find(i => i.id === item.id);
+      if (existingItem) {
+        return {
+          items: state.items.map(i =>
+            i.id === item.id ? { ...i, quantity: i.quantity + 1 } : i
+          ),
+        };
+      }
+      return {
+        items: [...state.items, { ...item, quantity: 1 }],
+      };
+    },
+    updateQuantity: (state, id: string, quantity: number) => ({
+      items: state.items.map(item => (item.id === id ? { ...item, quantity } : item)),
+    }),
+  },
+  middleware: { calculateTotal: calculateTotalMiddleware },
+  blockingMiddleware: { validateItem: validateItemMiddleware },
 });
+
+function CartComponent() {
+  const { select, actions } = useCartStore();
+  const items = select(s => s.items);
+  const total = select(s => s.total);
+
+  return (
+    <div>
+      <h2>Shopping Cart</h2>
+      <ul>
+        {items.map(item => (
+          <li key={item.id}>
+            {item.name} ({item.quantity}) - ${item.price} each
+            <button onClick={() => actions.updateQuantity(item.id, item.quantity - 1)}>-</button>
+            <button onClick={() => actions.updateQuantity(item.id, item.quantity + 1)}>+</button>
+          </li>
+        ))}
+      </ul>
+      <p>Total: ${total.toFixed(2)}</p>
+      <button onClick={() => actions.addItem({ id: 'apple', name: 'Apple', price: 1.50 })}>Add Apple</button>
+      <button onClick={() => actions.updateQuantity('apple', -1)}>Set Apple Quantity to -1 (Blocked)</button>
+    </div>
+  );
+}
 ```
 
 ### Observability
@@ -155,266 +411,633 @@ const useStore = createStore({
 Enable metrics and debugging via the `store` and `observer` objects:
 
 ```tsx
-const useStore = createStore(
+import { createStore } from '@asaidimu/react-store';
+
+const useObservedStore = createStore(
   {
-    state: { count: 0 },
-    actions: { increment: (state) => ({ count: state.count + 1 }) },
+    state: { task: '', completed: false },
+    actions: {
+      addTask: (state, taskName: string) => ({ task: taskName, completed: false }),
+      completeTask: (state) => ({ completed: true }),
+    },
   },
   {
-    enableMetrics: true,
-    enableConsoleLogging: true,
-    logEvents: { updates: true, middleware: false },
-    debounceTime: 500, // Debounce actions by 500ms
+    enableMetrics: true, // Crucial for enabling the 'observer' object
+    enableConsoleLogging: true, // Log events directly to browser console
+    logEvents: { updates: true, middleware: true, transactions: true }, // Which event types to log
+    performanceThresholds: {
+      updateTime: 50, // Warn if updates take longer than 50ms
+      middlewareTime: 20 // Warn if middleware takes longer than 20ms
+    },
+    maxEvents: 500, // Max number of events to keep in history
+    maxStateHistory: 50, // Max number of state snapshots for time travel
+    debounceTime: 300, // Debounce actions by 300ms to prevent rapid calls
   },
 );
 
 function DebugPanel() {
-  const { observer } = useStore();
-  const metrics = observer.getPerformanceMetrics();
-  const timeTravel = observer.createTimeTravel();
+  const { actions, observer, actionTracker } = useObservedStore();
+
+  // Access performance metrics
+  const metrics = observer?.getPerformanceMetrics();
+
+  // Access state history for time travel
+  const timeTravel = observer?.createTimeTravel();
+
+  // Access action execution history
+  const actionHistory = actionTracker.getExecutions();
 
   return (
     <div>
-      <p>Updates: {metrics.updateCount}</p>
-      <button onClick={() => timeTravel.undo()}>Undo</button>
-      <button onClick={() => timeTravel.redo()}>Redo</button>
+      <h2>Debug Panel</h2>
+      {observer && (
+        <>
+          <h3>Performance Metrics</h3>
+          <p>Update Count: {metrics?.updateCount}</p>
+          <p>Avg Update Time: {metrics?.averageUpdateTime?.toFixed(2)}ms</p>
+          <p>Largest Update Size (paths): {metrics?.largestUpdateSize}</p>
+
+          <h3>Time Travel</h3>
+          <button onClick={() => timeTravel?.undo()} disabled={!timeTravel?.canUndo()}>Undo</button>
+          <button onClick={() => timeTravel?.redo()} disabled={!timeTravel?.canRedo()}>Redo</button>
+          <p>State History: {timeTravel?.getHistoryLength()}</p>
+
+          <h3>Action History</h3>
+          <ul>
+            {actionHistory.slice(0, 5).map(exec => (
+              <li key={exec.id}>
+                <strong>{exec.name}</strong> ({exec.status}) - {exec.duration.toFixed(2)}ms
+              </li>
+            ))}
+          </ul>
+        </>
+      )}
+      <button onClick={() => actions.addTask('Learn React Store')}>Add Task</button>
+      <button onClick={() => actions.completeTask()}>Complete Task</button>
     </div>
   );
 }
 ```
 
-**Note**: The `debounceTime` option configures the debouncing applied to actions, preventing issues from rapid successive calls.
-
 ### Remote Observability
 
-Send metrics to external systems:
+Send collected metrics and traces to external systems like OpenTelemetry, Prometheus, or Grafana Cloud for centralized monitoring.
 
 ```tsx
 import { createStore, useRemoteObservability } from '@asaidimu/react-store';
+import React, { useEffect } from 'react';
+
+const useRemoteStore = createStore(
+  {
+    state: { apiCallsMade: 0, lastApiError: null },
+    actions: {
+      simulateApiCall: async (state) => {
+        // Simulate an error 10% of the time
+        if (Math.random() < 0.1) {
+          throw new Error('API request failed');
+        }
+        return { apiCallsMade: state.apiCallsMade + 1, lastApiError: null };
+      },
+      handleApiError: (state, error: string) => ({ lastApiError: error })
+    },
+  },
+  {
+    enableMetrics: true, // Required for RemoteObservability
+    enableConsoleLogging: false,
+    collectCategories: {
+      performance: true,
+      errors: true,
+      stateChanges: true,
+      middleware: true,
+    },
+    reportingInterval: 10000, // Send metrics every 10 seconds
+    batchSize: 10, // Send after 10 metrics or interval, whichever comes first
+    immediateReporting: false, // Don't send immediately after each metric
+  }
+);
 
-const useStore = createStore({ state: { count: 0 }, actions: {} });
-function Monitoring() {
-  const { store } = useStore();
-  const { remote, addOpenTelemetryDestination } = useRemoteObservability(store, {
-    serviceName: 'my-app',
-    environment: 'dev',
+function MonitoringIntegration() {
+  const { store, observer } = useRemoteStore();
+  const { remote, addOpenTelemetryDestination, addPrometheusDestination, addGrafanaCloudDestination } = useRemoteObservability(store, {
+    serviceName: 'my-react-app',
+    environment: 'development',
+    instanceId: `web-client-${Math.random().toString(36).substring(2, 9)}`,
   });
 
   useEffect(() => {
+    // Add OpenTelemetry Collector as a destination
     addOpenTelemetryDestination({
-      endpoint: 'https://otel-collector.example.com',
-      apiKey: 'your-api-key',
+      endpoint: 'http://localhost:4318', // Default OpenTelemetry HTTP endpoint
+      apiKey: 'your-otel-api-key',
+      resource: { 'app.version': '1.0.0', 'host.name': 'frontend-server' }
+    });
+
+    // Add Prometheus Pushgateway as a destination
+    addPrometheusDestination({
+      pushgatewayUrl: 'http://localhost:9091', // Default Prometheus Pushgateway
+      jobName: 'react-store-metrics',
+      username: 'promuser', // Optional basic auth
+      password: 'prompassword',
     });
+
+    // Add Grafana Cloud Loki as a destination (for logs/traces)
+    addGrafanaCloudDestination({
+      url: 'https://loki-prod-us-central1.grafana.net', // Example Loki endpoint
+      apiKey: 'your-grafana-cloud-api-key',
+    });
+
+    // Report current store metrics periodically (in addition to event-driven metrics)
+    const interval = setInterval(() => {
+      observer?.reportCurrentMetrics();
+    }, 5000); // Report every 5 seconds
+
+    return () => clearInterval(interval);
   }, []);
 
-  return null;
+  return null; // This component doesn't render anything visually
 }
+
+// In your App component:
+// <MonitoringIntegration />
+// <button onClick={() => useRemoteStore().actions.simulateApiCall().catch(e => useRemoteStore().actions.handleApiError(e.message))}>
+//   Simulate API Call
+// </button>
 ```
 
-## API Reference
+### Transaction Support
 
-### `createStore(definition, options)`
+Group related updates that should succeed or fail together. If an error occurs within the transaction, all changes made during that transaction are automatically rolled back.
 
 ```typescript
-type StoreDefinition<T, R extends Actions<T>> = {
-  state: T;
-  actions: R;
-  middleware?: Record<string, Middleware<T>>;
-  blockingMiddleware?: Record<string, BlockingMiddleware<T>>;
-};
+import { createStore } from '@asaidimu/react-store';
 
-interface StoreOptions<T> {
-  enableMetrics?: boolean;
-  enableConsoleLogging?: boolean;
-  maxEvents?: number;
-  maxStateHistory?: number;
-  logEvents?: { updates?: boolean; middleware?: boolean; transactions?: boolean };
-  performanceThresholds?: { updateTime?: number; middlewareTime?: number };
-  persistence?: DataStorePersistence<T>;
-  debounceTime?: number;
+interface BankState {
+  checking: number;
+  savings: number;
+  transactions: string[];
 }
 
-const useStore = createStore(definition, options);
+const useBankStore = createStore<BankState, any>({
+  state: { checking: 1000, savings: 500, transactions: [] },
+  actions: {
+    transferFunds: async (state, fromAccount: 'checking' | 'savings', toAccount: 'checking' | 'savings', amount: number) => {
+      if (amount <= 0) {
+        throw new Error('Transfer amount must be positive.');
+      }
+
+      const newChecking = fromAccount === 'checking' ? state.checking - amount : state.checking + amount;
+      const newSavings = fromAccount === 'savings' ? state.savings - amount : state.savings + amount;
+
+      if ((fromAccount === 'checking' && newChecking < 0) || (fromAccount === 'savings' && newSavings < 0)) {
+        throw new Error('Insufficient funds.');
+      }
+
+      // Simulate a complex operation that might fail
+      if (amount > 700 && fromAccount === 'checking') {
+        throw new Error('Large transfers from checking require additional verification.');
+      }
+
+      const newTransactions = [...state.transactions, `Transfer ${amount} from ${fromAccount} to ${toAccount}`];
+      return {
+        checking: newChecking,
+        savings: newSavings,
+        transactions: newTransactions,
+      };
+    },
+  },
+});
+
+function BankApp() {
+  const { select, actions } = useBankStore();
+  const checkingBalance = select(s => s.checking);
+  const savingsBalance = select(s => s.savings);
+  const transactions = select(s => s.transactions);
+
+  const handleTransfer = async (from: 'checking' | 'savings', to: 'checking' | 'savings', amount: number) => {
+    try {
+      await actions.transferFunds(from, to, amount);
+      alert(`Successfully transferred ${amount} from ${from} to ${to}.`);
+    } catch (error) {
+      alert(`Transfer failed: ${error instanceof Error ? error.message : String(error)}`);
+      // State is automatically rolled back if an error occurs within the transaction
+    }
+  };
+
+  return (
+    <div>
+      <h2>Bank Accounts</h2>
+      <p>Checking: ${checkingBalance.toFixed(2)}</p>
+      <p>Savings: ${savingsBalance.toFixed(2)}</p>
+      <h3>Recent Transactions</h3>
+      <ul>
+        {transactions.map((t, i) => <li key={i}>{t}</li>)}
+      </ul>
+      <button onClick={() => handleTransfer('checking', 'savings', 100)}>Transfer $100 (Checking to Savings)</button>
+      <button onClick={() => handleTransfer('savings', 'checking', 200)}>Transfer $200 (Savings to Checking)</button>
+      <button onClick={() => handleTransfer('checking', 'savings', 800)}>Transfer $800 (Will Fail)</button>
+      <button onClick={() => handleTransfer('checking', 'savings', 1500)}>Transfer $1500 (Insufficient Funds)</button>
+    </div>
+  );
+}
+```
+
+### Event System
+
+The store emits various events during its lifecycle, which you can subscribe to for logging, analytics, or custom side effects.
+
+```typescript
+import { createStore } from '@asaidimu/react-store';
+import React, { useEffect } from 'react';
+
+const useEventStore = createStore(
+  {
+    state: { data: 'initial', processedCount: 0 },
+    actions: {
+      processData: (state, newData: string) => ({ data: newData, processedCount: state.processedCount + 1 }),
+      triggerError: () => { throw new Error("Action failed intentionally"); }
+    },
+    middleware: {
+      myLoggingMiddleware: (state, update) => {
+        console.log('Middleware processing:', update);
+        return update;
+      }
+    }
+  }
+);
+
+function EventMonitor() {
+  const { store } = useEventStore();
+  const [eventLogs, setEventLogs] = React.useState<string[]>([]);
+
+  useEffect(() => {
+    const addLog = (message: string) => {
+      setEventLogs(prev => [`${new Date().toLocaleTimeString()}: ${message}`, ...prev].slice(0, 10));
+    };
+
+    // Subscribe to specific store events
+    const unsubscribeUpdateStart = store.onStoreEvent('update:start', (data) => {
+      addLog(`Update Started (timestamp: ${data.timestamp})`);
+    });
+
+    const unsubscribeUpdateComplete = store.onStoreEvent('update:complete', (data) => {
+      if (data.blocked) {
+        addLog(`Update BLOCKED by middleware or error. Error: ${data.error?.message || 'unknown'}`);
+      } else {
+        addLog(`Update Completed in ${data.duration?.toFixed(2)}ms. Paths changed: ${data.changedPaths?.join(', ')}`);
+      }
+    });
+
+    const unsubscribeMiddlewareStart = store.onStoreEvent('middleware:start', (data) => {
+      addLog(`Middleware '${data.name}' started (${data.type})`);
+    });
+
+    const unsubscribeMiddlewareError = store.onStoreEvent('middleware:error', (data) => {
+      addLog(`Middleware '${data.name}' encountered an error: ${data.error.message}`);
+    });
+
+    const unsubscribeTransactionStart = store.onStoreEvent('transaction:start', () => {
+      addLog(`Transaction Started`);
+    });
+
+    const unsubscribeTransactionError = store.onStoreEvent('transaction:error', (data) => {
+      addLog(`Transaction Failed: ${data.error.message}`);
+    });
+
+    const unsubscribePersistenceReady = store.onStoreEvent('persistence:ready', () => {
+      addLog(`Persistence is READY.`);
+    });
+
+    // Cleanup subscriptions on component unmount
+    return () => {
+      unsubscribeUpdateStart();
+      unsubscribeUpdateComplete();
+      unsubscribeMiddlewareStart();
+      unsubscribeMiddlewareError();
+      unsubscribeTransactionStart();
+      unsubscribeTransactionError();
+      unsubscribePersistenceReady();
+    };
+  }, [store]); // Re-subscribe if store instance changes (unlikely)
+
+  const { actions } = useEventStore();
+
+  return (
+    <div>
+      <h3>Store Event Log</h3>
+      <button onClick={() => actions.processData('new data')}>Process Data</button>
+      <button onClick={() => actions.triggerError().catch(() => {})}>Trigger Action Error</button>
+      <button onClick={() => store.transaction(() => { actions.processData('transaction data'); throw new Error('Transaction error'); }).catch(() => {})}>
+        Simulate Transaction Error
+      </button>
+      <ul style={{ maxHeight: '200px', overflowY: 'auto', border: '1px solid #ccc', padding: '10px' }}>
+        {eventLogs.map((log, index) => <li key={index} style={{ whiteSpace: 'pre-wrap', wordBreak: 'break-all' }}>{log}</li>)}
+      </ul>
+    </div>
+  );
+}
 ```
 
-**Returns**: A `useStore` hook with:
-- `store`: `ReactiveDataStore` instance.
-- `observer`: `StoreObservability` instance (if `enableMetrics` is true).
-- `select`: Memoized selector for state slices.
-- `actions`: Action dispatchers.
-- `actionTracker`: Tracks action executions.
-- `state`: Getter for full state.
-- `isReady`: Boolean indicating persistence initialization completion.
-
-### `ReactiveDataStore` (via `store`)
-
-- `get(): T`
-- `set(update: StateUpdater<T>): Promise<void>`
-- `subscribe(path: string | string[], listener: (state: T) => void): () => void`
-- `transaction<R>(operation: () => R | Promise<R>): Promise<R>`
-- `use(middleware: Middleware<T>, name?: string)`
-- `useBlockingMiddleware(middleware: BlockingMiddleware<T>, name?: string)`
-- `isReady(): boolean`
-- `onStoreEvent(event: StoreEvent, listener): () => void`
-
-### `StoreObservability` (via `observer`)
-
-- `getEventHistory(): DebugEvent[]`
-- `getStateHistory(): T[]`
-- `getRecentChanges(limit?: number): { timestamp, changedPaths, from, to }[]`
-- `getPerformanceMetrics(): StoreMetrics`
-- `createTimeTravel(): { undo, redo, canUndo, canRedo }`
-- `createLoggingMiddleware(options)`
-- `createValidationMiddleware(validator)`
-
-### `RemoteObservability`
-
-- Extend `StoreObservability` with `useRemoteObservability(store, options)`:
-  - `addDestination(destination: RemoteDestination)`
-  - `beginTrace(name: string)`
-  - `beginSpan(traceId, name, labels)`
-  - `endSpan(traceId, spanName)`
-  - `endTrace(traceId)`
-
-### Persistence Adapters
-
-- **`IndexedDBPersistence(storeId: string)`**
-- **`WebStoragePersistence(storageKey: string, session?: boolean)`**
-  - Methods: `set(id, state)`, `get()`, `subscribe(id, callback)`, `clear()`
-- **`LocalStoragePersistence(storageKey: string)`** (Deprecated)
-  - Alias for `WebStoragePersistence`. Use `WebStoragePersistence` instead.
-
-## Advanced Hook Properties
-
-The hook returned by `createStore` (e.g., `useCounter()` in examples) provides several properties for advanced usage and debugging, beyond the commonly used `select`, `actions`, and `isReady`:
+### Advanced Hook Properties
+
+The hook returned by `createStore` provides several properties for advanced usage and debugging, beyond the commonly used `select`, `actions`, and `isReady`:
 
 ```tsx
-function MyComponent() {
+function MyAdvancedComponent() {
   const {
-    select,        // Function to select state parts
-    actions,       // Object containing your defined actions
+    select,        // Function to select state parts (memoized)
+    actions,       // Object containing your defined actions (debounced)
     isReady,       // Boolean indicating if persistence is ready
     store,         // Direct access to the ReactiveDataStore instance
     observer,      // StoreObservability instance (if `enableMetrics` was true)
     actionTracker, // Instance of ActionTracker for monitoring action executions
     state,         // A hook `() => T` to get the entire reactive state object
-  } = useCounter();
+  } = useMyStore(); // Assuming useMyStore is defined from createStore
 
-  // Example: Accessing the full state (use with caution for performance)
+  // Example: Accessing the full state (use with caution for performance, `select` is preferred)
   const fullCurrentState = state();
+  console.log("Full reactive state:", fullCurrentState);
+
+  // Example: Accessing observer methods (if enabled)
+  if (observer) {
+    console.log("Performance metrics:", observer.getPerformanceMetrics());
+    console.log("Recent state changes:", observer.getRecentChanges(3));
+  }
+
+  // Example: Accessing action history
+  console.log("Action executions:", actionTracker.getExecutions());
 
-  // Example: Accessing observer methods or action history
-  // if (observer) console.log(observer.getPerformanceMetrics());
-  // console.log(actionTracker.getHistory());
+  return (
+    <div>
+      {/* ... your component content ... */}
+    </div>
+  );
 }
 ```
 
--   `store`: Provides direct access to the underlying `ReactiveDataStore` instance. This can be useful for advanced control or accessing methods not directly exposed by other parts of the hook (e.g., `store.getPerformanceMetrics()` if `observer` is not enabled).
--   `observer`: If `enableMetrics` was true during store creation, this is the `StoreObservability` instance. It offers methods like `getPerformanceMetrics()`, `getStateHistory()`, and `createTimeTravel()` for time-travel debugging.
--   `actionTracker`: An `ActionTracker` instance that records information about dispatched actions, including their parameters, status (success/error), and duration. Its history can be valuable for debugging action flows.
--   `state`: A hook that, when called (e.g., `state()`), returns the entire current state object. Be mindful that using this will cause your component to re-render on *any* change to the store, unlike the more granular `select` hook. Prefer `select` for optimal component performance.
-
-## Best Practices
-
-1. **Granular Selectors**:
-   ```tsx
-   const count = select((state) => state.count); // Good
-   const allState = select((state) => state); // Avoid
-   ```
-
-2. **Action Design**:
-   ```tsx
-   actions: {
-     fetchData: async (state, id: string) => {
-       const data = await fetch(`/api/${id}`).then((res) => res.json());
-       return { data };
-     },
-   }
-   ```
-
-3. **Persistence**:
-   - Use unique `storeId` or `storageKey` to avoid conflicts.
-   - Check `isReady` for UI dependent on persisted state:
-     ```tsx
-     if (!isReady) return <div>Loading...</div>;
-     ```
-
-4. **Middleware**:
-   ```tsx
-   const apiMonitor = (state, update) => {
-     if (update.apiCalls) telemetry.log(update.apiCalls);
-     return update;
-   };
-   ```
-
-## Example with Persistence and Observability
+## Project Architecture
 
-```tsx
-import { createStore, WebStoragePersistence } from '@asaidimu/react-store';
+`@asaidimu/react-store` is structured to provide a modular yet integrated state management solution.
 
-const persistence = new WebStoragePersistence('counter-store');
-const useCounter = createStore(
-  {
-    state: { count: 0 },
-    actions: {
-      increment: (state) => ({ count: state.count + 1 }),
-    },
-    middleware: {
-      log: (state, update) => {
-        console.log('Update:', update);
-        return update;
-      },
-    },
-  },
-  {
-    persistence,
-    enableMetrics: true,
-    enableConsoleLogging: true,
-  },
-);
+```
+.
+├── src/
+│   ├── hooks/
+│   │   └── observability.ts        # React hook for remote observability
+│   ├── persistence/
+│   │   ├── indexedb.ts             # IndexedDB persistence adapter
+│   │   ├── local-storage.ts        # WebStorage (localStorage/sessionStorage) persistence adapter
+│   │   └── types.ts                # Interface for persistence adapters
+│   ├── state/
+│   │   ├── diff.ts                 # Utility for deep diffing state objects
+│   │   ├── merge.ts                # Utility for immutable deep merging state objects
+│   │   ├── observability.ts        # Core observability logic for ReactiveDataStore
+│   │   └── store.ts                # Core ReactiveDataStore implementation (the state machine)
+│   ├── store/
+│   │   ├── compare.ts              # Utilities for fast comparison (e.g., array hashing)
+│   │   ├── execution.ts            # Action tracking interface and class
+│   │   ├── hash.ts                 # Utilities for hashing objects (e.g., for selectors)
+│   │   ├── index.ts                # Main `createStore` React hook
+│   │   ├── paths.ts                # Utility for building selector paths
+│   │   └── selector.ts             # Selector memoization manager
+│   ├── types.ts                    # Core TypeScript types for the library
+│   └── utils/
+│       ├── destinations.ts         # Concrete remote observability destinations (OTel, Prometheus, Grafana)
+│       └── remote-observability.ts # Remote observability extension for StoreObservability
+├── index.ts                        # Main entry point for the library
+├── package.json
+└── tsconfig.json
+```
 
-function App() {
-  const { select, actions, isReady, observer } = useCounter();
-  const count = select((state) => state.count);
+### Core Components
 
-  if (!isReady) return <div>Loading...</div>;
+*   **`ReactiveDataStore` (`src/state/store.ts`)**: The heart of the library. It manages the immutable state, processes updates (including debouncing), handles middleware, transactions, and interacts with persistence adapters. It also emits detailed internal events for observability.
+*   **`StoreObservability` (`src/state/observability.ts`)**: An extension built on top of `ReactiveDataStore`'s event system. It provides debugging features like event history, state snapshots for time-travel, performance metrics, and utilities to create logging/validation middleware.
+*   **`createStore` Hook (`src/store/index.ts`)**: The primary React-facing API. It instantiates `ReactiveDataStore` and `StoreObservability`, wraps actions with debouncing and tracking, and provides the `select` hook powered by `useSyncExternalStore` for efficient component updates.
+*   **Persistence Adapters (`src/persistence/`)**: Implement the `DataStorePersistence` interface. `WebStoragePersistence` (for localStorage/sessionStorage) and `IndexedDBPersistence` provide concrete storage solutions with cross-tab synchronization.
+*   **`RemoteObservability` (`src/utils/remote-observability.ts`)**: Extends `StoreObservability` to enable sending metrics, logs, and traces to external monitoring systems. It defines a pluggable `RemoteDestination` interface and provides out-of-the-box implementations.
 
-  return (
-    <div>
-      <p>Count: {count}</p>
-      <button onClick={() => actions.increment()}>+1</button>
-      <p>Updates: {observer.getPerformanceMetrics().updateCount}</p>
-    </div>
-  );
+### Data Flow
+
+1.  **Action Dispatch**: A React component calls an action (e.g., `actions.increment(1)`). Actions are debounced by default.
+2.  **Action Execution Tracking**: The `ActionTracker` records the action's details (name, params, start time).
+3.  **State Update Request**: The action, after potential debouncing, initiates a `store.set()` call with a partial state update or a function.
+4.  **Transaction Context**: If within a `store.transaction()`, the state is snapshotted for potential rollback.
+5.  **Blocking Middleware**: Updates first pass through `blockingMiddleware`. If any middleware returns `false` or throws, the update is halted, and the state is not modified.
+6.  **Transform Middleware**: If not blocked, updates then pass through transforming `middleware`. These functions can modify the partial update.
+7.  **State Merging**: The final transformed update is immutably merged into the current state using the `merge` utility. `Symbol.for("delete")` is handled here for property removal.
+8.  **Change Detection**: The `diff` utility identifies which paths in the state have truly changed.
+9.  **Persistence**: If changes occurred, the new state is saved via the configured `DataStorePersistence` adapter (e.g., `localStorage`, `IndexedDB`). External changes from persistence are also subscribed to and applied.
+10. **Listener Notification**: Only `React.useSyncExternalStore` subscribers whose selected paths have changed are notified, triggering re-renders of relevant components.
+11. **Observability Events**: Throughout this flow, the `ReactiveDataStore` emits fine-grained events (`update:start`, `middleware:complete`, `transaction:error`, etc.) that `StoreObservability` captures for debugging, metrics, and remote reporting.
+
+### Extension Points
+
+*   **Custom Middleware**: Easily add your own `Middleware` or `BlockingMiddleware` functions for custom logic.
+*   **Custom Persistence Adapters**: Implement the `DataStorePersistence<T>` interface to integrate with any storage solution (e.g., a backend API, WebSockets, or a custom in-memory store).
+*   **Remote Observability Destinations**: Create new `RemoteDestination` implementations to send metrics and traces to any external observability platform not already supported.
+
+## Development & Contributing
+
+We welcome contributions! Please follow the guidelines below.
+
+### Development Setup
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/asaidimu/react-store.git
+    cd react-store
+    ```
+2.  **Install dependencies:**
+    This project uses `bun` as the package manager.
+    ```bash
+    bun install
+    ```
+
+### Scripts
+
+*   `bun ci`: Installs dependencies (for CI/CD environments).
+*   `bun test`: Runs all unit tests using `Vitest`.
+*   `bun test:ci`: Runs tests in CI mode (single run).
+*   `bun clean`: Removes the `dist` directory.
+*   `bun prebuild`: Cleans `dist` and runs a sync script (internal).
+*   `bun build`: Compiles the TypeScript source into `dist/` for CJS and ESM formats, generates type definitions, and minifies.
+*   `bun dev`: Starts a development server (likely for a UI example).
+*   `bun postbuild`: Copies `README.md`, `LICENSE.md`, and `dist.package.json` into the `dist` folder.
+
+### Testing
+
+Tests are written using `Vitest` and `React Testing Library`.
+
+To run tests:
+
+```bash
+bun test
+# or to run in watch mode
+bun test --watch
+```
+
+### Contributing Guidelines
+
+1.  **Fork** the repository and create your branch from `main`.
+2.  **Code Standards**: Ensure your code adheres to existing coding styles (TypeScript, ESLint, Prettier are configured).
+3.  **Tests**: Add unit and integration tests for new features or bug fixes. Ensure all tests pass.
+4.  **Commits**: Follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages.
+5.  **Pull Requests**: Submit a pull request to the `main` branch. Provide a clear description of your changes.
+
+### Issue Reporting
+
+For bugs, feature requests, or questions, please open an issue on the [GitHub Issues page](https://github.com/asaidimu/react-store/issues).
+
+## Additional Information
+
+### Best Practices
+
+1.  **Granular Selectors**: Always use `select((state) => state.path.to.value)` instead of `select((state) => state)` to prevent unnecessary re-renders of components.
+2.  **Action Design**: Keep actions focused on a single responsibility. Use `async` actions for asynchronous operations and return partial updates upon completion.
+3.  **Persistence**:
+    *   Use unique `storeId` or `storageKey` for each distinct store to avoid data conflicts.
+    *   Always check the `isReady` flag for UI elements that depend on the initial state loaded from persistence.
+4.  **Middleware**: Leverage middleware for cross-cutting concerns like logging, analytics, or complex validation logic.
+5.  **`Symbol.for("delete")`**: Use this explicit symbol for property removal to maintain clarity and avoid accidental data mutations.
+
+### API Reference
+
+#### `createStore(definition, options)`
+
+The main entry point for creating a store.
+
+```typescript
+type StoreDefinition<T, R extends Actions<T>> = {
+  state: T; // Initial state object
+  actions: R; // Object mapping action names to action functions
+  middleware?: Record<string, Middleware<T>>; // Optional transforming middleware
+  blockingMiddleware?: Record<string, BlockingMiddleware<T>>; // Optional blocking middleware
+};
+
+interface StoreOptions<T> {
+  enableMetrics?: boolean; // Enable StoreObservability features (default: false)
+  enableConsoleLogging?: boolean; // Log store events to console (default: false)
+  maxEvents?: number; // Maximum number of events to keep in history (default: 500)
+  maxStateHistory?: number; // Maximum number of state snapshots for time travel (default: 20)
+  logEvents?: { // Which event categories to log (defaults to all true if enableConsoleLogging is true)
+    updates?: boolean;
+    middleware?: boolean;
+    transactions?: boolean;
+  };
+  performanceThresholds?: { // Thresholds for logging slow operations (in ms)
+    updateTime?: number; // default: 50ms
+    middlewareTime?: number; // default: 20ms
+  };
+  persistence?: DataStorePersistence<T>; // Optional persistence adapter instance
+  debounceTime?: number; // Time in milliseconds to debounce actions (default: 250ms)
 }
+
+const useStore = createStore(definition, options);
 ```
 
-## Comparison with Other State Management Solutions
+**Returns**: A `useStore` hook which, when called in a component, returns an object with:
+*   `store`: Direct access to the `ReactiveDataStore` instance.
+*   `observer`: The `StoreObservability` instance (available if `enableMetrics` is `true`). Provides debug and monitoring utilities.
+*   `select`: A memoized selector function to extract specific state slices. Re-renders components only when selected data changes.
+*   `actions`: An object containing your defined actions. These actions are debounced and tracked.
+*   `actionTracker`: An instance of `ActionTracker` for monitoring the execution history of your actions.
+*   `state`: A hook `() => T` that returns the entire current state object. Use sparingly as it will cause re-renders on *any* state change.
+*   `isReady`: A boolean indicating whether the store's persistence layer (if configured) has finished loading its initial state.
+
+#### `ReactiveDataStore` (accessed via `useStore().store`)
+
+*   `get(clone?: boolean): T`: Retrieves the current state. Pass `true` to get a deep clone (recommended for mutations outside of actions).
+*   `set(update: StateUpdater<T>): Promise<void>`: Updates the state with a partial object or a function returning a partial object.
+*   `subscribe(path: string | string[], listener: (state: T) => void): () => void`: Subscribes a listener to changes at a specific path or array of paths. Returns an unsubscribe function.
+*   `transaction<R>(operation: () => R | Promise<R>): Promise<R>`: Executes a function as an atomic transaction. Rolls back all changes if an error occurs.
+*   `use(middleware: Middleware<T>, name?: string): string`: Adds a transforming middleware. Returns its ID.
+*   `useBlockingMiddleware(middleware: BlockingMiddleware<T>, name?: string): string`: Adds a blocking middleware. Returns its ID.
+*   `removeMiddleware(id: string): boolean`: Removes a middleware by its ID.
+*   `isReady(): boolean`: Checks if the persistence layer has loaded its initial state.
+*   `onStoreEvent(event: StoreEvent, listener: (data: any) => void): () => void`: Subscribes to internal store events (e.g., `'update:complete'`, `'middleware:error'`).
+
+#### `StoreObservability` (accessed via `useStore().observer`)
+
+*   `getEventHistory(): DebugEvent[]`: Retrieves a history of all captured store events.
+*   `getStateHistory(): T[]`: Returns a history of state snapshots, enabling time-travel.
+*   `getRecentChanges(limit?: number): Array<{ timestamp: number; changedPaths: string[]; from: Partial<T>; to: Partial<T>; }>`: Provides a simplified view of recent state changes.
+*   `getPerformanceMetrics(): StoreMetrics`: Returns an object containing performance statistics (e.g., `updateCount`, `averageUpdateTime`).
+*   `createTimeTravel(): { canUndo: () => boolean; canRedo: () => boolean; undo: () => Promise<void>; redo: () => Promise<void>; getHistoryLength: () => number; clear: () => void; }`: Returns controls for time-travel debugging.
+*   `createLoggingMiddleware(options?: object): Middleware<T>`: A factory for a simple logging middleware.
+*   `createValidationMiddleware(validator: (state: T, update: DeepPartial<T>) => boolean | { valid: boolean; reason?: string }): BlockingMiddleware<T>`: A factory for a schema validation middleware.
+*   `clearHistory(): void`: Clears the event and state history.
+*   `disconnect(): void`: Cleans up all listeners and resources.
+
+#### `RemoteObservability` (accessed via `useRemoteObservability` hook)
+
+Extends `StoreObservability` with methods for sending metrics and traces externally.
 
-`@asaidimu/react-store` is a competitor in the React state management ecosystem, offering a unique blend of reactivity, persistence, and observability. Here’s how it stacks up against popular alternatives:
+*   `addDestination(destination: RemoteDestination): boolean`: Adds a remote destination for metrics.
+*   `removeDestination(id: string): boolean`: Removes a remote destination by ID.
+*   `getDestinations(): Array<{ id: string; name: string }> `: Gets a list of configured destinations.
+*   `testAllConnections(): Promise<Record<string, boolean>>`: Tests connectivity to all destinations.
+*   `beginTrace(name: string): string`: Starts a new performance trace, returning its ID.
+*   `beginSpan(traceId: string, name: string, labels?: Record<string, string>): string`: Starts a new span within a trace, returning its ID.
+*   `endSpan(traceId: string, spanName: string): void`: Ends a specific span within a trace.
+*   `endTrace(traceId: string): void`: Ends a performance trace and sends it to remote destinations.
+*   `trackMetric(metric: RemoteMetricsPayload['metrics'][0]): void`: Manually add a metric to the batch for reporting.
+
+#### Persistence Adapters
+
+All adapters implement `DataStorePersistence<T>`:
+
+*   `set(id:string, state: T): boolean | Promise<boolean>`: Persists data.
+*   `get(): T | null | Promise<T | null>`: Retrieves data.
+*   `subscribe(id:string, callback: (state:T) => void): () => void`: Subscribes to external changes.
+*   `clear(): boolean | Promise<boolean>`: Clears persisted data.
+
+##### `IndexedDBPersistence(storeId: string)`
+
+*   **`storeId`**: A unique identifier for the IndexedDB object store (e.g., `'user-data'`).
+
+##### `WebStoragePersistence(storageKey: string, session?: boolean)`
+
+*   **`storageKey`**: The key under which data is stored (e.g., `'app-config'`).
+*   **`session`**: Optional. If `true`, uses `sessionStorage`; otherwise, uses `localStorage` (default: `false`).
+
+##### `LocalStoragePersistence(storageKey: string)` (Deprecated)
+
+*   This is an alias for `WebStoragePersistence`. Use `WebStoragePersistence` instead.
+
+### Comparison with Other State Management Solutions
+
+`@asaidimu/react-store` aims to provide a comprehensive, all-in-one solution for React state management. Here's a comparison to popular alternatives:
 
 | **Feature**            | **@asaidimu/react-store** | **Redux**          | **Zustand**        | **MobX**           | **Recoil**         |
-|-------------------------|---------------------------|--------------------|--------------------|--------------------|--------------------|
+| :--------------------- | :------------------------ | :----------------- | :----------------- | :----------------- | :----------------- |
 | **Dev Experience**     | Intuitive hook-based API with rich tooling. | Verbose setup with reducers and middleware. | Minimalist, hook-friendly API. | Reactive, class-based approach. | Atom-based, React-native feel. |
 | **Learning Curve**     | Moderate (middleware, observability add complexity). | Steep (boilerplate-heavy). | Low (simple API). | Moderate (reactive concepts). | Low to moderate (atom model). |
 | **API Complexity**     | Medium (rich feature set balanced with simplicity). | High (many concepts: actions, reducers, etc.). | Low (straightforward). | Medium (proxies, decorators). | Medium (atom/selectors). |
 | **Scalability**        | High (transactions, persistence, remote metrics). | High (structured but verbose). | High (small but flexible). | High (reactive scaling). | High (granular atoms). |
 | **Extensibility**      | Excellent (middleware, custom persistence, observability). | Good (middleware, enhancers). | Good (middleware-like). | Moderate (custom reactions). | Moderate (custom selectors). |
 | **Performance**        | Optimized (selectors, reactive updates). | Good (predictable but manual optimization). | Excellent (minimal overhead). | Good (reactive overhead). | Good (granular updates). |
-| **Bundle Size**        | Moderate (includes observability, persistence). | Large (core + toolkit). | Tiny (~1KB). | Moderate (~20KB). | Moderate (~10KB). |
+| **Bundle Size**        | Moderate (includes observability, persistence, remote observability). | Large (core + toolkit). | Tiny (~1KB). | Moderate (~20KB). | Moderate (~10KB). |
 | **Persistence**        | Built-in (IndexedDB, WebStorage, cross-tab). | Manual (via middleware). | Manual (via middleware). | Manual (custom). | Manual (custom). |
 | **Observability**      | Excellent (metrics, time-travel, remote). | Good (dev tools). | Basic (via plugins). | Good (reactive logs). | Basic (via plugins). |
-| **React Integration**  | Native (hooks) | Manual (React-Redux). | Native (hooks). | Native (observers). | Native (atoms). |
+| **React Integration**  | Native (hooks, `useSyncExternalStore`) | Manual (React-Redux). | Native (hooks). | Native (observers). | Native (atoms). |
+
+#### Where `@asaidimu/react-store` Shines
+*   **All-in-One**: It aims to be a single solution for state management, persistence, and observability, reducing the need for multiple external dependencies.
+*   **Flexibility**: The robust middleware system and transaction support make it highly adaptable to complex business logic and data flows.
+*   **Modern React**: It leverages `useSyncExternalStore` for direct integration with React's concurrency model, ensuring efficient and up-to-date component renders.
+
+#### Trade-Offs
+*   **Bundle Size**: While comprehensive, it naturally has a larger bundle size compared to minimalist alternatives like Zustand, as it includes a wider range of features out-of-the-box.
+*   **Learning Curve**: The rich feature set might present a slightly steeper learning curve for developers new to advanced state management concepts, though the API strives for simplicity.
+
+### Changelog
+
+For a detailed history of changes and new features, please refer to the [CHANGELOG.md](./CHANGELOG.md) file.
 
-### Where `@asaidimu/react-store` Shines
-- **All-in-One**: Combines state management, persistence, and observability without external dependencies.
-- **Flexibility**: Middleware and transactions make it adaptable to complex use cases.
-- **Modern React**: Leverages `useSyncExternalStore` for optimal performance and compatibility.
+### License
 
-### Trade-Offs
-- Larger bundle size compared to minimalist solutions like Zustand.
-- Slightly steeper learning curve due to advanced features.
+This project is licensed under the MIT License. See the [LICENSE.md](./LICENSE.md) file for full details.
 
-## License
+### Acknowledgments
 
-MIT © [Saidimu](https://github.com/asaidimu)
+Developed by [Saidimu](https://github.com/asaidimu).