@asaidimu/utils-remote-store 1.0.0

package/README.md

@@ -0,0 +1,1475 @@
+# Reactive Remote Store
+
+An intelligent, reactive data management library for JavaScript/TypeScript applications, designed for optimal performance, real-time data synchronization, and seamless integration with any remote data source.
+
+[![npm version](https://img.shields.io/npm/v/@asaidimu/erp-utils-remote-store.svg)](https://www.npmjs.com/package/@asaidimu/erp-utils-remote-store)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/Built%20with-TypeScript-blue.svg)](https://www.typescriptlang.org/)
+
+---
+
+## 🚀 Quick Links
+
+- [Overview & Features](#-overview--features)
+- [Installation & Setup](#-installation--setup)
+  - [Prerequisites](#prerequisites)
+  - [Installation Steps](#installation-steps)
+  - [Configuration](#configuration)
+  - [Verification](#verification)
+- [Usage Documentation](#-usage-documentation)
+  - [Basic Usage](#basic-usage)
+  - [API Usage](#api-usage)
+  - [Configuration Examples](#configuration-examples)
+  - [Common Use Cases](#common-use-cases)
+- [Project Architecture](#-project-architecture)
+  - [Directory Structure](#directory-structure)
+  - [Core Components](#core-components)
+  - [Data Flow](#data-flow)
+  - [Extension Points](#extension-points)
+- [Development & Contributing](#-development--contributing)
+  - [Development Setup](#development-setup)
+  - [Scripts](#scripts)
+  - [Testing](#testing)
+  - [Contributing Guidelines](#contributing-guidelines)
+  - [Issue Reporting](#issue-reporting)
+- [Additional Information](#-additional-information)
+  - [Troubleshooting](#troubleshooting)
+  - [FAQ](#faq)
+  - [Changelog/Roadmap](#changelogroadmap)
+  - [License](#license)
+  - [Acknowledgments](#acknowledgments)
+
+---
+
+## 📦 Overview & Features
+
+`ReactiveRemoteStore` provides a robust, reactive data management solution for applications that interact with remote APIs. It intelligently handles data fetching, caching, and synchronization, ensuring your application always has access to up-to-date information while minimizing network overhead and improving user experience. By integrating with a `QueryCache` and a `BaseStore` (your API client), it abstracts away the complexities of data lifecycle management, allowing developers to focus on application logic.
+
+Key aspects of `ReactiveRemoteStore` include:
+
+*   **Reactive Queries**: Data is exposed through observable query results that automatically update when the underlying data changes, whether from local mutations or external server notifications.
+*   **Intelligent Caching**: It leverages a `QueryCache` to store data, reducing redundant API calls and providing instant access to previously fetched information.
+*   **Automatic Invalidation**: Mutations (create, update, delete, upload) automatically trigger intelligent cache invalidation, ensuring data consistency across your application.
+*   **Real-time Synchronization**: Through the `BaseStore`'s implementation of `subscribe` and `notify` (which can utilize technologies like Server-Sent Events, WebSockets, or other real-time protocols) and custom event correlators, `ReactiveRemoteStore` can react to external changes pushed from your backend, keeping your client-side data in sync with the server in real-time.
+*   **Pluggable `BaseStore`**: The library is agnostic to your specific API client. You provide an implementation of the `BaseStore` interface, allowing `ReactiveRemoteStore` to work with any REST, GraphQL, or custom API.
+*   **Data Streaming**: Supports consuming continuous data streams from your backend, ideal for dashboards, live feeds, or large datasets.
+
+### Key Features
+
+*   **Reactive Data Access**: Consume data through observable queries (`read`, `list`, `find`) that automatically update when data changes.
+*   **Query Caching**: Efficiently caches data from `read`, `list`, and `find` operations.
+*   **Automatic Invalidation**: Cache entries are intelligently invalidated upon `create`, `update`, `delete`, and `upload` mutations.
+*   **Real-time Event Integration**: Reacts to real-time data changes pushed from the `BaseStore` (via `subscribe` and `notify` methods, supporting various protocols like SSE or WebSockets).
+*   **Custom Invalidation Logic (Correlators)**: Define custom functions (`Correlator` and `StoreEventCorrelator`) to precisely control which cached queries are invalidated based on mutations or incoming store events.
+*   **Data Streaming**: Provides a robust mechanism for consuming real-time data streams from the `BaseStore` via an `AsyncIterable` interface.
+*   **Prefetching & Refreshing**: Imperative methods (`prefetch`, `refresh`) to proactively load data or force re-fetches, optimizing user experience.
+*   **Type-Safe**: Fully written in TypeScript, providing strong typing for enhanced developer experience, compile-time safety, and autocompletion.
+*   **Error Handling**: Centralized error handling for data operations.
+
+---
+
+## 🛠️ Installation & Setup
+
+### Prerequisites
+
+*   Node.js (v18.x or higher recommended)
+*   `bun`, `npm`, or `yarn` package manager
+*   A `QueryCache` implementation (e.g., `@core/cache` if available in your project, or a custom one).
+*   An implementation of the `BaseStore` interface that connects to your remote data source.
+
+### Installation Steps
+
+To install `ReactiveRemoteStore` and its peer dependencies, use your preferred package manager:
+
+```bash
+bun add @asaidimu/erp-utils-remote-store @core/cache
+# or
+npm install @asaidimu/erp-utils-remote-store @core/cache
+# or
+yarn add @asaidimu/erp-utils-remote-store @core/cache
+```
+
+### Configuration
+
+`ReactiveRemoteStore` is initialized with a `QueryCache` instance and an implementation of the `BaseStore` interface. Optionally, you can provide `correlator` and `storeEventCorrelator` functions for advanced invalidation logic.
+
+```typescript
+import { ReactiveRemoteStore } from '@asaidimu/erp-utils-remote-store';
+import { QueryCache } from '@core/cache'; // Your QueryCache implementation
+import { BaseStore, Record, Page, StoreEvent, ActiveQuery, MutationOperation } from '@asaidimu/erp-utils-remote-store/types';
+
+// --- Example: Define your data types ---
+interface Product extends Record {
+    name: string;
+    price: number;
+    inStock: boolean;
+}
+
+// --- Example: Implement your BaseStore (API client) ---
+// This would typically interact with your backend via fetch, axios, etc.
+class MyApiBaseStore implements BaseStore<Product> {
+    private baseUrl: string;
+    constructor(baseUrl: string) { this.baseUrl = baseUrl; }
+
+    async find(options: any): Promise<Page<Product>> { /* ... API call ... */ return { data: [], page: { number: 1, size: 0, count: 0, pages: 0 } }; }
+    async read(options: { id: string }): Promise<Product | undefined> { /* ... API call ... */ return undefined; }
+    async list(options: any): Promise<Page<Product>> { /* ... API call ... */ return { data: [], page: { number: 1, size: 0, count: 0, pages: 0 } }; }
+    async create(props: { data: Omit<Product, "id">; options?: any; }): Promise<Product | undefined> { /* ... API call ... */ return { id: 'new-id', ...props.data }; }
+    async update(props: { id: string; data: Partial<Omit<Product, "id">>; options?: any; }): Promise<Product | undefined> { /* ... API call ... */ return { id: props.id, ...props.data }; }
+    async delete(options: { id: string; }): Promise<void> { /* ... API call ... */ }
+    async upload(props: { file: File; options?: any; }): Promise<Product | undefined> { /* ... API call ... */ return { id: 'uploaded-id', name: 'uploaded', price: 0, inStock: true }; }
+
+    // For real-time updates, your `BaseStore` implementation would establish and manage
+    // a connection using technologies like Server-Sent Events (SSE), WebSockets, or polling.
+    // The `ReactiveRemoteStore` simply calls these methods on your `BaseStore`.
+    async subscribe(scope: string, callback: (event: StoreEvent) => void): Promise<() => void> {
+        console.log(`Subscribing to ${scope}`);
+        // Example: Connect to an SSE endpoint (as in test-server.ts)
+        // const eventSource = new EventSource(`${this.baseUrl}/events?scope=${scope}`);
+        // eventSource.onmessage = (e) => callback(JSON.parse(e.data));
+        // return () => eventSource.close();
+
+        // Example: Using WebSockets
+        // const ws = new WebSocket(`${this.baseUrl}/ws?scope=${scope}`);
+        // ws.onmessage = (e) => callback(JSON.parse(e.data));
+        // return () => ws.close();
+
+        return async () => { console.log(`Unsubscribed from ${scope}`); };
+    }
+    async notify(event: StoreEvent): Promise<void> {
+        console.log('Notifying base store:', event);
+        // Your implementation here to send the event to the backend
+        // e.g., via a POST request, WebSocket message, etc.
+        // await fetch(`${this.baseUrl}/notify`, { method: 'POST', body: JSON.stringify(event) });
+    }
+    stream(options: any): { stream: () => AsyncIterable<Product>; cancel: () => void; status: () => "active" | "cancelled" | "completed"; } {
+        console.log('Streaming with options:', options);
+        const mockStream = (async function* () {
+            yield { id: 'p1', name: 'Streamed Product 1', price: 10, inStock: true };
+            await new Promise(r => setTimeout(r, 100));
+            yield { id: 'p2', name: 'Streamed Product 2', price: 20, inStock: false };
+        })();
+        return { stream: () => mockStream, cancel: () => console.log('Stream cancelled'), status: () => 'completed' };
+    }
+}
+
+// --- Optional: Define custom correlators for invalidation ---
+const myCorrelator = (
+    mutation: { operation: MutationOperation; params: any },
+    activeQueries: ActiveQuery[]
+): string[] => {
+    // Example: Invalidate 'list' queries on any create/delete operation
+    if (mutation.operation === 'create' || mutation.operation === 'delete') {
+        return activeQueries.filter(q => q.operation === 'list').map(q => q.queryKey);
+    }
+    // Example: Invalidate specific 'read' query if its ID matches the updated item
+    if (mutation.operation === 'update' && mutation.params.id) {
+        return activeQueries
+            .filter(q => q.operation === 'read' && q.params.id === mutation.params.id)
+            .map(q => q.queryKey);
+    }
+    return [];
+};
+
+const myStoreEventCorrelator = (
+    event: StoreEvent, // { scope: string, payload?: any }
+    activeQueries: ActiveQuery[]
+): string[] => {
+    // Example: Invalidate 'read' query if an external event updates its ID
+    if (event.scope === 'product:updated:external' && event.payload?.id) {
+        return activeQueries
+            .filter(q => q.operation === 'read' && q.params.id === event.payload.id)
+            .map(q => q.queryKey);
+    }
+    return [];
+};
+
+// --- Initialize ReactiveRemoteStore ---
+const cache = new QueryCache();
+const baseStore = new MyApiBaseStore('https://api.example.com');
+
+const productStore = new ReactiveRemoteStore<Product>(
+    cache,
+    baseStore,
+    myCorrelator,          // Optional: for mutation-based invalidation
+    myStoreEventCorrelator // Optional: for store event-based invalidation
+);
+
+console.log('ReactiveRemoteStore initialized successfully!');
+```
+
+### Verification
+
+To verify that `ReactiveRemoteStore` is installed and initialized correctly, you can run a simple test:
+
+```typescript
+import { ReactiveRemoteStore } from '@asaidimu/erp-utils-remote-store';
+import { QueryCache } from '@core/cache';
+import { BaseStore, Record, Page, StoreEvent } from '@asaidimu/erp-utils-remote-store/types';
+
+// Minimal BaseStore for verification
+class MinimalBaseStore implements BaseStore<Record> {
+    async find(): Promise<Page<Record>> { return { data: [], page: { number: 1, size: 0, count: 0, pages: 0 } }; }
+    async read(): Promise<Record | undefined> { return undefined; }
+    async list(): Promise<Page<Record>> { return { data: [], page: { number: 1, size: 0, count: 0, pages: 0 } }; }
+    async create(props: any): Promise<Record | undefined> { return { id: '1', ...props.data }; }
+    async update(props: any): Promise<Record | undefined> { return { id: props.id, ...props.data }; }
+    async delete(): Promise<void> { }
+    async upload(): Promise<Record | undefined> { return undefined; }
+    async subscribe(): Promise<() => void> { return () => {}; }
+    async notify(): Promise<void> { }
+    stream(): { stream: () => AsyncIterable<Record>; cancel: () => void; status: () => "active" | "cancelled" | "completed"; } {
+        return { stream: async function*() {}, cancel: () => {}, status: () => 'completed' };
+    }
+}
+
+const cache = new QueryCache();
+const baseStore = new MinimalBaseStore();
+const store = new ReactiveRemoteStore(cache, baseStore);
+
+console.log('ReactiveRemoteStore instance:', store);
+console.log('Store initialized successfully!');
+
+// You can also run the project's tests to verify full functionality:
+// bun run vitest --run
+```
+
+---
+
+## A Developer's Guide to `BaseStore`
+
+The `BaseStore` interface is the heart of the `ReactiveRemoteStore`'s extensibility. It acts as a bridge between the reactive store and your backend, allowing you to use any API, protocol, or data source. This guide provides a comprehensive overview of how to implement it.
+
+### The Role of `BaseStore`
+
+The `BaseStore`'s responsibility is to handle the direct communication with your remote data source. `ReactiveRemoteStore` delegates all data operations (fetching, creating, updating, etc.) to your `BaseStore` implementation. This separation of concerns means `ReactiveRemoteStore` doesn't need to know anything about your API's specifics, such as URLs, headers, or authentication.
+
+### Getting Started
+
+First, define the data structure for the records your store will manage. This type must extend `StoreRecord`, which requires an `id: string` property.
+
+```typescript
+import type { BaseStore, StoreRecord, Page, StoreEvent } from '@asaidimu/erp-utils-remote-store/types';
+import { StoreError } from '@asaidimu/erp-utils-remote-store/error';
+
+// Your record type
+interface Product extends StoreRecord {
+    name: string;
+    price: number;
+    // ... any other fields
+}
+
+// Define the option types for your API
+// These are used for type-safety when calling the store's methods
+
+// Options for reading a single product (e.g., by ID)
+interface ProductReadOptions { id: string; }
+
+// Options for listing products (e.g., with pagination and sorting)
+interface ProductListOptions { page?: number; pageSize?: number; sortBy?: keyof Product; order?: 'asc' | 'desc'; }
+
+// Options for finding products (e.g., with a search query)
+interface ProductFindOptions extends ProductListOptions { query: string; }
+
+// Now, create your class that implements the BaseStore interface
+class ProductApiStore implements BaseStore<Product, ProductFindOptions, ProductReadOptions, ProductListOptions> {
+    private readonly baseUrl = 'https://api.example.com';
+
+    // Implementation of each method will go here...
+}
+```
+
+### Implementing the Methods
+
+Here is a detailed look at each method in the `BaseStore` interface.
+
+#### `read(options: TReadOptions): Promise<T | undefined>`
+
+**Purpose**: Fetch a single record by its identifier.
+
+-   **`options`**: The parameters for the read operation, typically containing the record's `id`.
+-   **Returns**: A `Promise` that resolves to the fetched record or `undefined` if it's not found.
+
+```typescript
+// Example implementation for `read` with error handling
+async read(options: ProductReadOptions): Promise<Product | undefined> {
+    try {
+        const response = await fetch(`${this.baseUrl}/products/${options.id}`);
+        if (response.status === 404) {
+            return undefined; // Handle not found gracefully
+        }
+        if (!response.ok) {
+            // Throw a generic error for non-404 issues
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        return await response.json();
+    } catch (error: any) {
+        // Convert any caught error into a standardized StoreError
+        throw StoreError.fromError(error, 'read');
+    }
+}
+```
+
+#### `list(options: TListOptions): Promise<Page<T>>`
+
+**Purpose**: Fetch a paginated list of records.
+
+-   **`options`**: Parameters for listing, such as `page`, `pageSize`, `sortBy`, etc.
+-   **Returns**: A `Promise` that resolves to a `Page<T>` object, which contains the `data` array and pagination details.
+
+```typescript
+// Example implementation for `list`
+async list(options: ProductListOptions): Promise<Page<Product>> {
+    const params = new URLSearchParams();
+    if (options.page) params.set('page', String(options.page));
+    if (options.pageSize) params.set('pageSize', String(options.pageSize));
+    if (options.sortBy) params.set('sortBy', options.sortBy);
+    if (options.order) params.set('order', options.order);
+
+    try {
+        const response = await fetch(`${this.baseUrl}/products?${params.toString()}`);
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        // Assume the API returns a body like: { data: [...], page: { number, size, count, pages } }
+        return await response.json();
+    } catch (error: any) {
+        throw StoreError.fromError(error, 'list');
+    }
+}
+```
+
+#### `find(options: TFindOptions): Promise<Page<T>>`
+
+**Purpose**: Fetch a paginated list of records based on search criteria.
+
+-   **`options`**: Parameters for finding, which might include a search `query` along with pagination and sorting.
+-   **Returns**: A `Promise` that resolves to a `Page<T>` object.
+
+```typescript
+// Example implementation for `find`
+async find(options: ProductFindOptions): Promise<Page<Product>> {
+    const params = new URLSearchParams({ query: options.query });
+    if (options.page) params.set('page', String(options.page));
+    // ... other params
+
+    try {
+        const response = await fetch(`${this.baseUrl}/products/search?${params.toString()}`);
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        return await response.json();
+    } catch (error: any) {
+        throw StoreError.fromError(error, 'find');
+    }
+}
+```
+
+#### `create(props: { data: Partial<T> }): Promise<T | undefined>`
+
+**Purpose**: Create a new record.
+
+-   **`props.data`**: The record to create.
+-   **Returns**: A `Promise` that resolves to the newly created record as returned by the server (including the server-generated `id`).
+
+```typescript
+// Example implementation for `create`
+async create(props: { data: Partial<Product> }): Promise<Product | undefined> {
+    try {
+        const response = await fetch(`${this.baseUrl}/products`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(props.data),
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        return await response.json(); // Important: return the server's response
+    } catch (error: any) {
+        throw StoreError.fromError(error, 'create');
+    }
+}
+```
+
+#### `update(props: { data: Partial<T> }): Promise<T | undefined>`
+
+**Purpose**: Update an existing record.
+
+-   **`props.data`**: A partial object of the fields to update, including the `id`.
+-   **Returns**: A `Promise` that resolves to the updated record.
+
+```typescript
+// Example implementation for `update`
+async update(props: { data: Partial<Product> }): Promise<Product | undefined> {
+    try {
+        const response = await fetch(`${this.baseUrl}/products/${props.data.id}`,
+        {
+            method: 'PATCH', // or 'PUT'
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(props.data),
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        return await response.json();
+    } catch (error: any) {
+        throw StoreError.fromError(error, 'update');
+    }
+}
+```
+
+#### `delete(options: TDeleteOptions): Promise<void>`
+
+**Purpose**: Delete a record.
+
+-   **`options`**: Parameters for deletion, typically `{ id: string }`.
+-   **Returns**: A `Promise` that resolves when the operation is complete.
+
+```typescript
+// Example implementation for `delete`
+async delete(options: { id: string }): Promise<void> {
+    try {
+        const response = await fetch(`${this.baseUrl}/products/${options.id}`, {
+            method: 'DELETE',
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+    } catch (error: any) {
+        throw StoreError.fromError(error, 'delete');
+    }
+}
+```
+
+### Implementing Real-Time Features
+
+`ReactiveRemoteStore` supports real-time updates through the `subscribe` and `notify` methods.
+
+#### `subscribe(scope: string, callback: (event: StoreEvent) => void): Promise<() => void>`
+
+**Purpose**: Establish a connection to your backend to receive real-time events.
+
+-   **`scope`**: A string indicating the event scope to subscribe to. `ReactiveRemoteStore` will call this with `'*'` to listen for all events.
+-   **`callback`**: A function that `ReactiveRemoteStore` provides. Your implementation must call this function whenever a `StoreEvent` is received from the backend.
+-   **Returns**: A `Promise` that resolves to an `unsubscribe` function. `ReactiveRemoteStore` will call this function when it's destroyed to clean up the connection.
+
+```typescript
+// Example implementation for `subscribe` using Server-Sent Events (SSE)
+async subscribe(scope: string, callback: (event: StoreEvent) => void): Promise<() => void> {
+    console.log(`Subscribing to event scope: ${scope}`);
+    const eventSource = new EventSource(`${this.baseUrl}/events?scope=${scope}`);
+
+    eventSource.onmessage = (event) => {
+        const storeEvent: StoreEvent = JSON.parse(event.data);
+        callback(storeEvent); // Pass the event to the ReactiveRemoteStore
+    };
+
+    eventSource.onerror = (error) => {
+        console.error('SSE Error:', error);
+        // You might want to add reconnection logic here
+    };
+
+    // Return a function that closes the connection
+    return () => {
+        console.log('Unsubscribing from events.');
+        eventSource.close();
+    };
+}
+```
+
+#### `notify(event: StoreEvent): Promise<void>`
+
+**Purpose**: Send an event from the client to the server. This is less common but can be used for client-initiated notifications.
+
+-   **`event`**: The `StoreEvent` to send.
+-   **Returns**: A `Promise` that resolves when the event has been sent.
+
+```typescript
+// Example implementation for `notify`
+async notify(event: StoreEvent): Promise<void> {
+    try {
+        const response = await fetch(`${this.baseUrl}/notify`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(event),
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+    } catch (error: any) {
+        throw StoreError.fromError(error, 'notify');
+    }
+}
+```
+
+### Error Handling
+
+For robust error handling, your `BaseStore` methods should wrap their logic in a `try...catch` block and convert any caught errors into a `StoreError`. This provides standardized, structured error information to the `ReactiveRemoteStore` and your application.
+
+The library provides a `StoreError.fromError(error, operation)` utility that intelligently converts various error types (network errors, HTTP errors, timeouts) into a consistent `StoreError` object.
+
+**Benefits of using `StoreError`**:
+- **Standardization**: All errors from the data layer have a consistent shape.
+- **Rich Information**: Includes `code`, `status`, `isRetryable`, and the `originalError`.
+- **Automatic Handling**: Correctly identifies common network and HTTP issues from `fetch` responses.
+
+Here is how you should structure your methods:
+
+```typescript
+import { StoreError } from '@asaidimu/erp-utils-remote-store/error';
+
+// Inside your BaseStore implementation...
+
+async read(options: ProductReadOptions): Promise<Product | undefined> {
+    try {
+        const response = await fetch(`${this.baseUrl}/products/${options.id}`);
+
+        if (response.status === 404) {
+            return undefined; // Not an error, just not found
+        }
+
+        // The `fromError` utility will automatically handle non-ok responses
+        // if you pass the response object to it, but throwing manually is also fine.
+        if (!response.ok) {
+            throw new Error(`HTTP Error: ${response.status}`);
+        }
+
+        return await response.json();
+
+    } catch (error: any) {
+        // The `fromError` factory will create the appropriate StoreError
+        // based on the type of error caught (e.g., network, timeout, HTTP).
+        console.error('Error in read operation:', error);
+        throw StoreError.fromError(error, 'read');
+    }
+}
+```
+
+
+
+## 📖 Usage Documentation
+
+### Basic Usage
+
+The `ReactiveRemoteStore` simplifies data interactions by providing reactive hooks into your data. Here's how to perform basic CRUD operations and observe data changes.
+
+```typescript
+import { ReactiveRemoteStore } from '@asaidimu/erp-utils-remote-store';
+import { QueryCache } from '@core/cache';
+import { BaseStore, Record, Page, StoreEvent } from '@asaidimu/erp-utils-remote-store/types';
+
+// Assume you have a Todo type and a TodoBaseStore implementation
+interface Todo extends Record {
+    title: string;
+    completed: boolean;
+}
+
+class TodoBaseStore implements BaseStore<Todo> {
+    // ... (implementation similar to MyApiBaseStore above)
+    // For simplicity, let's use a mock in-memory store for this example
+    private todos: Todo[] = [];
+    private nextId = 1;
+
+    async create(props: { data: Omit<Todo, "id">; options?: any; }): Promise<Todo | undefined> {
+        const newTodo = { id: String(this.nextId++), ...props.data };
+        this.todos.push(newTodo);
+        return newTodo;
+    }
+    async read(options: { id: string }): Promise<Todo | undefined> {
+        return this.todos.find(t => t.id === options.id);
+    }
+    async list(options: any): Promise<Page<Todo>> {
+        return { data: this.todos, page: { number: 1, size: this.todos.length, count: this.todos.length, pages: 1 } };
+    }
+    async update(props: { id: string; data: Partial<Omit<Todo, "id">>; options?: any; }): Promise<Todo | undefined> {
+        const todo = this.todos.find(t => t.id === props.id);
+        if (todo) {
+            Object.assign(todo, props.data);
+            return todo;
+        }
+        return undefined;
+    }
+    async delete(options: { id: string; }): Promise<void> {
+        this.todos = this.todos.filter(t => t.id !== options.id);
+    }
+    async upload(): Promise<Todo | undefined> { return undefined; }
+    async subscribe(): Promise<() => void> { return () => {}; }
+    async notify(): Promise<void> { }
+    stream(): { stream: () => AsyncIterable<Todo>; cancel: () => void; status: () => "active" | "cancelled" | "completed"; } {
+        return { stream: async function*() {}, cancel: () => {}, status: () => 'completed' };
+    }
+}
+
+const cache = new QueryCache();
+const todoBaseStore = new TodoBaseStore();
+const todoStore = new ReactiveRemoteStore<Todo>(cache, todoBaseStore);
+
+async function runBasicUsage() {
+    console.log('\n--- Basic Usage Examples ---');
+
+    // 1. Create a Todo
+    const createdTodo = await todoStore.create({ data: { title: 'Buy groceries', completed: false } });
+    console.log('Created Todo:', createdTodo);
+
+    // 2. Read a Todo and subscribe to changes
+    if (createdTodo) {
+        const { value: selectRead, onValueChange: subscribeRead } = todoStore.read({ id: createdTodo.id });
+        const unsubscribeRead = subscribeRead(() => {
+            const result = selectRead();
+            console.log('Read Todo (reactive update):', result.data, 'loading:', result.loading);
+        });
+
+        console.log('Initial Read:', selectRead().data);
+
+        // 3. List all Todos and subscribe to changes
+        const { value , onValueChange: subscribeToList } = todoStore.list({});
+        let result = value() 
+        const unsubscribeList = subscribeToList(() => {
+            result = value();
+            console.log('List Todos (reactive update):', result.page?.data, 'loading:', result.loading);
+        });
+
+        console.log('Initial List:', result.page?.data);
+
+        // 4. Update the Todo (this will trigger reactive updates in read and list queries)
+        await todoStore.update({ id: createdTodo.id, data: { completed: true } });
+        console.log('Updated Todo to completed.');
+
+        // 5. Delete the Todo (this will trigger reactive updates)
+        await todoStore.delete({ id: createdTodo.id });
+        console.log('Deleted Todo.');
+
+        // Clean up subscriptions
+        unsubscribeRead();
+        unsubscribeList();
+    }
+
+    // Don't forget to destroy the store when your application shuts down
+    todoStore.destroy();
+}
+
+runBasicUsage();
+```
+
+### API Usage
+
+`ReactiveRemoteStore` exposes a comprehensive API for managing your data. Below are detailed descriptions of its public methods.
+
+#### `constructor(cache: QueryCache, baseStore: BaseStore<T, ...>, correlator?: Correlator, storeEventCorrelator?: StoreEventCorrelator)`
+
+Creates a new instance of `ReactiveRemoteStore`.
+
+-   `cache`: An instance of `QueryCache` (or compatible interface) used for caching data.
+-   `baseStore`: Your implementation of the `BaseStore` interface, responsible for direct interaction with the remote API.
+-   `correlator` (optional): A function (`Correlator` type) that defines how mutations (create, update, delete, upload) should invalidate active queries in the `QueryCache`. If not provided, a default invalidation strategy (invalidating all `list` and `find` queries) is used.
+-   `storeEventCorrelator` (optional): A function (`StoreEventCorrelator` type) that defines how incoming `StoreEvent`s (e.g., from SSE) should invalidate active queries. If not provided, external events will be logged but won't trigger invalidation.
+
+#### `read(params: TReadOptions): ReactiveQueryResult<T>`
+
+Retrieves a single record from the store. This method returns an object containing a `selector` function and an `onValueChange` function, enabling reactive data access.
+
+-   `params`: Options specific to your `BaseStore`'s `read` operation (e.g., `{ id: string }`).
+
+**Returns:**
+
+-   `{ value, onValueChange }`: An object.
+    -   `value`: A function `() => QueryResult<T>` that returns the current state of the query, including `data`, `loading` status, `error`, `stale` status, and `updated` timestamp.
+    -   `onValueChange`: A function `(callback: () => void) => () => void` that allows you to register a callback to be notified when the query result changes. It returns an `unsubscribe` function.
+
+```typescript
+// Example: Reading a user profile
+interface UserProfile extends Record { name: string; email: string; }
+// Assume userStore is ReactiveRemoteStore<UserProfile>
+
+const { value: selectUser, onValueChange: subscribeUser } = userStore.read({ id: 'user-123' });
+
+// Initial access
+console.log('Initial User Data:', selectUser().data);
+
+// Subscribe to changes
+const unsubscribe = subscribeUser(() => {
+    const result = selectUser();
+    console.log('User Data Updated:', result.data, 'Loading:', result.loading, 'Stale:', result.stale);
+    if (result.error) console.error('Error fetching user:', result.error);
+});
+
+// Later, when no longer needed
+// unsubscribe();
+```
+
+#### `list(params: TListOptions): ReactivePagedQueryResult<T>`
+
+Retrieves a paginated list of records from the store. This method returns an object containing a `selector` function and an `onValueChange` function, enabling reactive data access and pagination controls.
+
+-   `params`: Options specific to your `BaseStore`'s `list` operation (e.g., `{ page: number, pageSize: number, filter?: string }`).
+
+**Returns:**
+
+-   `{ value, onValueChange }`: An object.
+    -   `value`: A function `() => PagedQueryResult<T>` that returns the current state of the paginated query, including `page` data, `loading` status, `error`, `stale` status, `updated` timestamp, and pagination helpers (`hasNext`, `hasPrevious`, `next()`, `previous()`, `fetch(page)`).
+    -   `onValueChange`: A function `(callback: () => void) => () => void` that allows you to register a callback to be notified when the query result changes. It returns an `unsubscribe` function.
+
+```typescript
+// Example: Listing products with pagination
+interface Product extends Record { name: string; price: number; }
+// Assume productStore is ReactiveRemoteStore<Product>
+
+const { value: selectProducts, onValueChange: subscribeProducts } = productStore.list({ page: 1, pageSize: 10 });
+
+const unsubscribeProducts = subscribeProducts(() => {
+    const result = selectProducts();
+    console.log('Products List Updated:', result.page?.data, 'Loading:', result.loading);
+    if (result.page) {
+        console.log(`Page ${result.page.page.number} of ${result.page.page.pages}`);
+    }
+});
+
+// Navigate to the next page
+const currentProducts = selectProducts();
+if (currentProducts.hasNext) {
+    await currentProducts.next();
+}
+
+// Fetch a specific page
+await selectProducts().fetch(3);
+
+// unsubscribeProducts();
+```
+
+#### `find(params: TFindOptions): ReactivePagedQueryResult<T>`
+
+Retrieves a paginated list of records based on search criteria. Similar to `list`, but typically used for more complex search queries.
+
+-   `params`: Options specific to your `BaseStore`'s `find` operation (e.g., `{ query: string, category: string }`).
+
+**Returns:**
+
+-   `{ value, onValueChange }`: An object identical in structure and behavior to the `list` method's return value.
+
+```typescript
+// Example: Finding orders by customer ID
+interface Order extends Record { customerId: string; amount: number; }
+// Assume orderStore is ReactiveRemoteStore<Order>
+
+const { value: selectOrders, onValueChange: subscribeOrders } = orderStore.find({ customerId: 'cust-456', status: 'pending' });
+
+const unsubscribeOrders = subscribeOrders(() => {
+    const result = selectOrders();
+    console.log('Orders Found Updated:', result.page?.data, 'Loading:', result.loading);
+});
+
+// unsubscribeOrders();
+```
+
+#### `create(params: { data: Omit<T, 'id'>, options?: TCreateOptions }): Promise<T | undefined>`
+
+Creates a new record in the remote store. This operation automatically invalidates relevant cached queries (e.g., `list` or `find` queries) to ensure data consistency.
+
+-   `params.data`: The data for the new record, excluding the `id` (which is typically generated by the backend).
+-   `params.options` (optional): Options specific to your `BaseStore`'s `create` operation.
+
+**Returns:** A promise that resolves to the newly created record (including its `id`) or `undefined` if creation failed.
+
+```typescript
+// Example: Creating a new task
+interface Task extends Record { description: string; dueDate: string; }
+// Assume taskStore is ReactiveRemoteStore<Task>
+
+const newTask = await taskStore.create({ data: { description: 'Write documentation', dueDate: '2025-12-31' } });
+console.log('New Task Created:', newTask);
+```
+
+#### `update(params: { id: string; data: Partial<Omit<T, 'id'>>; options?: TUpdateOptions }): Promise<T | undefined>`
+
+Updates an existing record in the remote store. This operation automatically invalidates relevant cached queries (e.g., the specific `read` query for the updated ID, or `list`/`find` queries).
+
+-   `params.id`: The `id` of the record to update.
+-   `params.data`: A partial object containing the fields to update.
+-   `params.options` (optional): Options specific to your `BaseStore`'s `update` operation.
+
+**Returns:** A promise that resolves to the updated record or `undefined` if the record was not found or the update failed.
+
+```typescript
+// Example: Marking a task as completed
+// Assume taskStore is ReactiveRemoteStore<Task> and taskId is known
+
+const updatedTask = await taskStore.update({ id: taskId, data: { completed: true } });
+console.log('Task Updated:', updatedTask);
+```
+
+#### `delete(params: TDeleteOptions): Promise<void>`
+
+Deletes a record from the remote store. This operation automatically invalidates relevant cached queries.
+
+-   `params`: Options specific to your `BaseStore`'s `delete` operation (e.g., `{ id: string }`).
+
+**Returns:** A promise that resolves when the deletion is complete.
+
+```typescript
+// Example: Deleting a task
+// Assume taskStore is ReactiveRemoteStore<Task> and taskId is known
+
+await taskStore.delete({ id: taskId });
+console.log('Task Deleted.');
+```
+
+#### `upload(params: { file: File; options?: TUploadOptions }): Promise<T | undefined>`
+
+Uploads a file associated with a record. This operation automatically invalidates relevant cached queries.
+
+-   `params.file`: The `File` object to upload.
+-   `params.options` (optional): Options specific to your `BaseStore`'s `upload` operation (e.g., `{ id: string, fieldName: string }`).
+
+**Returns:** A promise that resolves to the updated record (if the upload modifies the record) or `undefined` if upload failed.
+
+```typescript
+// Example: Uploading an avatar for a user
+interface User extends Record { name: string; avatarUrl?: string; }
+// Assume userStore is ReactiveRemoteStore<User> and userId is known
+
+const avatarFile = new File(['...'], 'avatar.png', { type: 'image/png' });
+const updatedUser = await userStore.upload({ file: avatarFile, options: { id: userId, fieldName: 'avatar' } });
+console.log('User Avatar Uploaded:', updatedUser?.avatarUrl);
+```
+
+#### `notify(event: StoreEvent): Promise<void>`
+
+Manually notifies the `ReactiveRemoteStore` of a `StoreEvent`. This can be used to simulate external events or trigger custom invalidation logic defined by `storeEventCorrelator`.
+
+-   `event`: The `StoreEvent` to process. It should have a `scope` and an optional `payload`.
+
+**Returns:** A promise that resolves when the notification has been processed.
+
+```typescript
+// Example: Notifying the store of an external product price change
+// Assume productStore is ReactiveRemoteStore<Product>
+
+await productStore.notify({
+    scope: 'product:price:changed',
+    payload: { id: 'prod-789', newPrice: 99.99 }
+});
+console.log('Notified store about product price change.');
+```
+
+#### `stream(options: TStreamOptions): Promise<{ stream: () => AsyncIterable<T>; cancel: () => void; status: () => 'active' | 'cancelled' | 'completed'; }>`
+
+Establishes a real-time data stream from the remote store. This method returns an object containing an `AsyncIterable` for consuming data, a `cancel` function to stop the stream, and a `status` getter to check the stream's current state.
+
+-   `options`: Options specific to your `BaseStore`'s `stream` operation (e.g., `{ filter: string, batchSize: number }`).
+
+**Returns:** An object with:
+
+-   `stream()`: A function that returns an `AsyncIterable<T>` which yields records as they arrive.
+-   `cancel()`: A function to call to terminate the stream.
+-   `status()`: A getter function that returns the current state of the stream (`'active'`, `'cancelled'`, or `'completed'`).
+
+```typescript
+// Example: Streaming live stock prices
+interface StockPrice extends Record { symbol: string; price: number; timestamp: number; }
+// Assume stockStore is ReactiveRemoteStore<StockPrice>
+
+async function consumeStockStream() {
+    console.log('Starting stock price stream...');
+    const { stream, cancel, status } = await stockStore.stream({ symbols: ['AAPL', 'GOOG'], interval: 1000 });
+
+    const streamInterval = setInterval(() => {
+        console.log('Stream Status:', status());
+    }, 500);
+
+    try {
+        for await (const priceUpdate of stream()) {
+            console.log(`Received: ${priceUpdate.symbol} - $${priceUpdate.price.toFixed(2)}`);
+        }
+        console.log('Stock stream completed.');
+    } catch (error) {
+        console.error('Stock stream error:', error);
+    } finally {
+        clearInterval(streamInterval);
+        cancel(); // Ensure stream is cancelled
+        console.log('Stock stream cleanup.');
+    }
+}
+
+// consumeStockStream();
+```
+
+#### `refresh(operation: 'read' | 'list' | 'find', params: TReadOptions | TListOptions | TFindOptions): Promise<T | Page<T> | undefined>`
+
+Forces a re-fetch of data for a specific query, bypassing staleness checks. This ensures you get the absolute latest data from the `BaseStore`.
+
+-   `operation`: The type of operation to refresh (`'read'`, `'list'`, or `'find'`).
+-   `params`: The parameters for the query to refresh.
+
+**Returns:** A promise that resolves to the refreshed data (single record or page) or `undefined` if the fetch fails.
+
+```typescript
+// Example: Refreshing a user's session data after an action
+// Assume userStore is ReactiveRemoteStore<UserProfile> and userId is known
+
+const freshUserData = await userStore.refresh('read', { id: userId });
+console.log('Refreshed User Data:', freshUserData);
+
+// Example: Refreshing a list of notifications
+// Assume notificationStore is ReactiveRemoteStore<Notification>
+
+const freshNotifications = await notificationStore.refresh('list', { status: 'unread' });
+console.log('Refreshed Notifications:', freshNotifications?.data);
+```
+
+#### `prefetch(operation: 'read' | 'list' | 'find', params: TReadOptions | TListOptions | TFindOptions): void`
+
+Triggers a background fetch for a specific query if it's not already in cache or is stale. Useful for loading data proactively before it's explicitly requested by the UI.
+
+-   `operation`: The type of operation to prefetch (`'read'`, `'list'`, or `'find'`).
+-   `params`: The parameters for the query to prefetch.
+
+**Returns:** `void` (the operation runs in the background).
+
+```typescript
+// Example: Prefetching related product details when a user hovers over a product card
+// Assume productStore is ReactiveRemoteStore<Product>
+
+productStore.prefetch('read', { id: 'prod-hovered-id' });
+console.log('Prefetched product details.');
+
+// Example: Prefetching the next page of a list
+// Assume currentListParams has page: 1, pageSize: 10
+
+const nextListPageParams = { ...currentListParams, page: currentListParams.page + 1 };
+productStore.prefetch('list', nextListPageParams);
+console.log('Prefetched next page of products.');
+```
+
+#### `invalidate(operation: string, params: any): Promise<void>`
+
+Manually invalidates a specific query in the cache, marking it as stale. The next time this query is accessed, it will trigger a re-fetch from the `BaseStore`.
+
+-   `operation`: The operation type of the query to invalidate (e.g., `'read'`, `'list'`, `'find'`).
+-   `params`: The parameters of the query to invalidate.
+
+**Returns:** A promise that resolves when the invalidation is complete.
+
+```typescript
+// Example: Invalidate a specific user's cached data after a direct API call outside the store
+// Assume userStore is ReactiveRemoteStore<UserProfile>
+
+await userStore.invalidate('read', { id: 'user-123' });
+console.log('User-123 data invalidated.');
+```
+
+#### `invalidateAll(): Promise<void>`
+
+Invalidates all active queries currently managed by the `ReactiveRemoteStore`.
+
+**Returns:** A promise that resolves when all active queries have been invalidated.
+
+```typescript
+// Example: Invalidate all cached data after a global data reset or logout
+// Assume anyStore is ReactiveRemoteStore<any>
+
+await anyStore.invalidateAll();
+console.log('All cached data invalidated.');
+```
+
+#### `getStats(): { size: number; metrics: CacheMetrics; hitRate: number; staleHitRate: number; entries: Array<{ key: string; lastAccessed: number; lastUpdated: number; accessCount: number; isStale: boolean; isLoading?: boolean; error?: boolean }> }`
+
+Retrieves current statistics about the underlying `QueryCache` and the number of active subscriptions within `ReactiveRemoteStore`.
+
+**Returns:** An object containing:
+
+-   `size`: Number of active entries in the cache.
+-   `metrics`: An object containing raw counts (`hits`, `misses`, `fetches`, `errors`, `evictions`, `staleHits`).
+-   `hitRate`: Ratio of hits to total requests (hits + misses).
+-   `staleHitRate`: Ratio of stale hits to total hits.
+-   `entries`: An array of objects providing details for each cached item (key, lastAccessed, lastUpdated, accessCount, isStale, isLoading, error status).
+-   `activeSubscriptions`: Number of currently active query subscriptions in `ReactiveRemoteStore`.
+
+```typescript
+// Example: Logging store statistics
+const stats = productStore.getStats();
+console.log('Store Stats:', stats);
+console.log('Active Subscriptions:', stats.activeSubscriptions);
+```
+
+#### `destroy(): void`
+
+Cleans up all active subscriptions, internal timers, and resources held by the `ReactiveRemoteStore` instance. This method should be called when the store instance is no longer needed (e.g., on application shutdown or component unmount) to prevent memory leaks.
+
+**Returns:** `void`.
+
+```typescript
+// Example: Cleaning up the store on application exit
+// Assume productStore is ReactiveRemoteStore<Product>
+
+productStore.destroy();
+console.log('ReactiveRemoteStore instance destroyed.');
+```
+
+### Configuration Examples
+
+#### Custom Correlators for Invalidation
+
+Correlators allow you to define precise rules for cache invalidation based on mutations or external events. This is crucial for maintaining data consistency in complex applications.
+
+```typescript
+import { ReactiveRemoteStore } from '@asaidimu/erp-utils-remote-store';
+import { QueryCache } from '@core/cache';
+import { BaseStore, Record, Page, StoreEvent, ActiveQuery, MutationOperation, Correlator, StoreEventCorrelator } from '@asaidimu/erp-utils-remote-store/types';
+
+interface Post extends Record { title: string; authorId: string; tags: string[]; }
+
+class PostBaseStore implements BaseStore<Post> { /* ... implementation ... */
+    async find(): Promise<Page<Post>> { return { data: [], page: { number: 1, size: 0, count: 0, pages: 0 } }; }
+    async read(): Promise<Post | undefined> { return undefined; }
+    async list(): Promise<Page<Post>> { return { data: [], page: { number: 1, size: 0, count: 0, pages: 0 } }; }
+    async create(props: any): Promise<Post | undefined> { return { id: 'new-post', ...props.data }; }
+    async update(props: any): Promise<Post | undefined> { return { id: props.id, ...props.data }; }
+    async delete(): Promise<void> { }
+    async upload(): Promise<Post | undefined> { return undefined; }
+    async subscribe(): Promise<() => void> { return () => {}; }
+    async notify(): Promise<void> { }
+    stream(): { stream: () => AsyncIterable<Post>; cancel: () => void; status: () => "active" | "cancelled" | "completed"; } {
+        return { stream: async function*() {}, cancel: () => {}, status: () => 'completed' };
+    }
+}
+
+// Correlator for mutations (create, update, delete, upload)
+const postMutationCorrelator: Correlator = (
+    mutation, // { operation: 'create' | 'update' | 'delete' | 'upload', params: any }
+    activeQueries // Array of { queryKey: string, operation: string, params: any }
+) => {
+    const invalidatedKeys: string[] = [];
+
+    // Invalidate all 'list' queries for posts on any post mutation
+    if (mutation.operation === 'create' || mutation.operation === 'delete') {
+        activeQueries.filter(q => q.operation === 'list').forEach(q => invalidatedKeys.push(q.queryKey));
+    }
+
+    // If a post is updated, invalidate its specific 'read' query
+    if (mutation.operation === 'update' && mutation.params.id) {
+        activeQueries
+            .filter(q => q.operation === 'read' && q.params.id === mutation.params.id)
+            .forEach(q => invalidatedKeys.push(q.queryKey));
+    }
+
+    // Example: Invalidate 'find' queries based on tags if a post's tags change
+    if (mutation.operation === 'update' && mutation.params.id && mutation.params.data?.tags) {
+        activeQueries
+            .filter(q => q.operation === 'find' && q.params.tags &&
+                          (mutation.params.data.tags as string[]).some(tag => q.params.tags.includes(tag)))
+            .forEach(q => invalidatedKeys.push(q.queryKey));
+    }
+
+    return invalidatedKeys;
+};
+
+// Correlator for external StoreEvents (e.g., from SSE)
+const postEventCorrelator: StoreEventCorrelator = (
+    event, // { scope: string, payload?: any }
+    activeQueries // Array of { queryKey: string, operation: string, params: any }
+) => {
+    const invalidatedKeys: string[] = [];
+
+    // If an external event indicates a specific post was updated, invalidate its 'read' query
+    if (event.scope === 'post:external:updated' && event.payload?.id) {
+        activeQueries
+            .filter(q => q.operation === 'read' && q.params.id === event.payload.id)
+            .forEach(q => invalidatedKeys.push(q.queryKey));
+    }
+
+    // If an external event indicates a new post was created, invalidate all 'list' queries
+    if (event.scope === 'post:external:created') {
+        activeQueries.filter(q => q.operation === 'list').forEach(q => invalidatedKeys.push(q.queryKey));
+    }
+
+    return invalidatedKeys;
+};
+
+const cache = new QueryCache();
+const postBaseStore = new PostBaseStore();
+
+const postStore = new ReactiveRemoteStore<Post>(
+    cache,
+    postBaseStore,
+    postMutationCorrelator, // Pass your custom mutation correlator
+    postEventCorrelator     // Pass your custom store event correlator
+);
+
+console.log('ReactiveRemoteStore with custom correlators initialized.');
+```
+
+### Common Use Cases
+
+#### Reactive UI Updates with `read` and `list`
+
+Automatically update your UI components when data changes, without manual re-fetching.
+
+```typescript
+import { ReactiveRemoteStore } from '@asaidimu/erp-utils-remote-store';
+import { QueryCache } from '@core/cache';
+import { BaseStore, Record, Page, StoreEvent } from '@asaidimu/erp-utils-remote-store/types';
+
+interface Item extends Record { name: string; status: 'active' | 'inactive'; }
+
+class ItemBaseStore implements BaseStore<Item> { /* ... mock implementation ... */
+    private items: Item[] = [];
+    private nextId = 1;
+
+    async create(props: { data: Omit<Item, "id">; options?: any; }): Promise<Item | undefined> {
+        const newItem = { id: String(this.nextId++), ...props.data };
+        this.items.push(newItem);
+        return newItem;
+    }
+    async read(options: { id: string }): Promise<Item | undefined> {
+        return this.items.find(i => i.id === options.id);
+    }
+    async list(options: any): Promise<Page<Item>> {
+        return { data: this.items, page: { number: 1, size: this.items.length, count: this.items.length, pages: 1 } };
+    }
+    async update(props: { id: string; data: Partial<Omit<Item, "id">>; options?: any; }): Promise<Item | undefined> {
+        const item = this.items.find(i => i.id === props.id);
+        if (item) {
+            Object.assign(item, props.data);
+            return item;
+        }
+        return undefined;
+    }
+    async delete(options: { id: string; }): Promise<void> {
+        this.items = this.items.filter(i => i.id !== options.id);
+    }
+    async upload(): Promise<Item | undefined> { return undefined; }
+    async subscribe(): Promise<() => void> { return () => {}; }
+    async notify(): Promise<void> { }
+    stream(): { stream: () => AsyncIterable<Item>; cancel: () => void; status: () => "active" | "cancelled" | "completed"; } {
+        return { stream: async function*() {}, cancel: () => {}, status: () => 'completed' };
+    }
+}
+
+const cache = new QueryCache();
+const itemBaseStore = new ItemBaseStore();
+const itemStore = new ReactiveRemoteStore<Item>(cache, itemBaseStore);
+
+async function runReactiveUIExample() {
+    console.log('\n--- Reactive UI Updates Example ---');
+
+    // Create some initial items
+    const item1 = await itemStore.create({ data: { name: 'Item A', status: 'active' } });
+    const item2 = await itemStore.create({ data: { name: 'Item B', status: 'inactive' } });
+
+    // Subscribe to a list of all items
+    const [subscribeAllItems, selectAllItems] = itemStore.list({});
+    const unsubscribeAllItems = subscribeAllItems(() => {
+        console.log('All Items (UI Update):', selectAllItems().page?.data.map(i => `${i.name} (${i.status})`));
+    });
+
+    // Subscribe to a single item
+    if (item1) {
+        const [subscribeItem1, selectItem1] = itemStore.read({ id: item1.id });
+        const unsubscribeItem1 = subscribeItem1(() => {
+            console.log('Item A (UI Update):', selectItem1().data ? `${selectItem1().data?.name} (${selectItem1().data?.status})` : 'Deleted');
+        });
+
+        // Simulate an update to Item A
+        await new Promise(r => setTimeout(r, 1000));
+        await itemStore.update({ id: item1.id, data: { status: 'inactive' } });
+        console.log('Simulated update to Item A.');
+
+        // Simulate deleting Item B
+        await new Promise(r => setTimeout(r, 1000));
+        if (item2) {
+            await itemStore.delete({ id: item2.id });
+            console.log('Simulated deletion of Item B.');
+        }
+
+        unsubscribeItem1();
+    }
+
+    unsubscribeAllItems();
+    itemStore.destroy();
+}
+
+// runReactiveUIExample();
+```
+
+#### Handling Real-time Data Streams
+
+Consume continuous data flows from your backend for live dashboards, chat applications, or sensor data.
+
+```typescript
+import { ReactiveRemoteStore } from '@asaidimu/erp-utils-remote-store';
+import { QueryCache } from '@core/cache';
+import { BaseStore, Record, Page, StoreEvent } from '@asaidimu/erp-utils-remote-store/types';
+
+interface SensorReading extends Record { temperature: number; humidity: number; timestamp: number; }
+
+class SensorBaseStore implements BaseStore<SensorReading> { /* ... mock implementation ... */
+    async find(): Promise<Page<SensorReading>> { return { data: [], page: { number: 1, size: 0, count: 0, pages: 0 } }; }
+    async read(): Promise<SensorReading | undefined> { return undefined; }
+    async list(): Promise<Page<SensorReading>> { return { data: [], page: { number: 1, size: 0, count: 0, pages: 0 } }; }
+    async create(props: any): Promise<SensorReading | undefined> { return undefined; }
+    async update(props: any): Promise<SensorReading | undefined> { return undefined; }
+    async delete(): Promise<void> { }
+    async upload(): Promise<SensorReading | undefined> { return undefined; }
+    async subscribe(): Promise<() => void> { return () => {}; }
+    async notify(): Promise<void> { }
+    stream(options: any): { stream: () => AsyncIterable<SensorReading>; cancel: () => void; status: () => "active" | "cancelled" | "completed"; } {
+        let counter = 0;
+        const intervalId = setInterval(() => {
+            // Simulate new readings every second
+            const newReading = { id: `s${counter++}`, temperature: Math.random() * 20 + 20, humidity: Math.random() * 30 + 50, timestamp: Date.now() };
+            // In a real scenario, this would push to an internal buffer consumed by the async generator
+            // For this example, we'll just yield directly.
+            // This mock doesn't perfectly simulate a real async generator being pushed to.
+            // A real implementation would involve a queue and a way to push items into it.
+            // For now, assume the BaseStore's stream method correctly provides the AsyncIterable.
+        }, 1000);
+
+        const mockAsyncIterable = (async function* () {
+            for (let i = 0; i < 5; i++) { // Yield 5 readings for example
+                await new Promise(r => setTimeout(r, 1000));
+                yield { id: `mock-${i}`, temperature: Math.random() * 10 + 20, humidity: Math.random() * 10 + 50, timestamp: Date.now() };
+            }
+        })();
+
+        return { 
+            stream: () => mockAsyncIterable, 
+            cancel: () => clearInterval(intervalId), 
+            status: () => 'completed' // Simplified status for mock
+        };
+    }
+}
+
+const cache = new QueryCache();
+const sensorBaseStore = new SensorBaseStore();
+const sensorStore = new ReactiveRemoteStore<SensorReading>(cache, sensorBaseStore);
+
+async function runStreamExample() {
+    console.log('\n--- Real-time Data Stream Example ---');
+
+    const { stream, cancel, status } = sensorStore.stream({});
+
+    const statusInterval = setInterval(() => {
+        console.log('Stream Status:', status());
+    }, 500);
+
+    try {
+        for await (const reading of stream()) {
+            console.log(`Sensor Reading: Temp=${reading.temperature.toFixed(2)}°C, Humidity=${reading.humidity.toFixed(2)}%`);
+        }
+        console.log('Sensor stream completed.');
+    } catch (error) {
+        console.error('Sensor stream error:', error);
+    } finally {
+        clearInterval(statusInterval);
+        cancel(); // Ensure stream is cancelled
+        console.log('Stream cleanup.');
+    }
+}
+
+// runStreamExample();
+```
+
+---
+
+## 🏗️ Project Architecture
+
+`ReactiveRemoteStore` is designed with modularity and extensibility in mind, separating concerns to allow for flexible integration with various caching strategies and backend communication methods.
+
+### Directory Structure
+
+```
+src/remote-store/
+├── error.ts            # Custom error classes for store operations.
+├── hash.ts             # Utility for hashing query parameters to create unique cache keys.
+├── store.ts            # The core ReactiveRemoteStore class implementation.
+├── types.ts            # TypeScript interfaces and types for the store, events, and options.
+├── test-server.ts      # A mock backend implementation used for e2e testing and examples.
+├── package.json        # Package metadata and dependencies for this specific module.
+├── README.md           # This documentation file.
+└── ...                 # Other related files (e.g., test files, build configs)
+```
+
+### Core Components
+
+*   **`ReactiveRemoteStore` (`store.ts`)**: The main class providing the reactive data access layer. It orchestrates data flow between the UI, the `QueryCache`, and the `BaseStore`. It manages query subscriptions, triggers fetches, handles invalidation, and processes real-time events.
+*   **`BaseStore<T>` (`types.ts`)**: An interface that defines the fundamental CRUD (Create, Read, Update, Delete), Upload, Subscribe, Notify, and Stream operations that your remote data source must implement. This makes `ReactiveRemoteStore` backend-agnostic.
+*   **`QueryCache` (from `@core/cache`)**: An external dependency responsible for the actual in-memory caching logic. `ReactiveRemoteStore` interacts with it to store, retrieve, and invalidate data. It handles cache policies like staleness, eviction, and background re-fetching.
+*   **`StoreEvent` (`types.ts`)**: Represents a data change event, typically originating from the `BaseStore` (e.g., via SSE) or triggered by local mutations. It has a `scope` (e.g., `product:created:success`) and an optional `payload`.
+*   **`Correlator` (`types.ts`)**: A function type that allows you to define custom logic for how local mutations (create, update, delete, upload) should affect the invalidation of active queries in the `QueryCache`.
+*   **`StoreEventCorrelator` (`types.ts`)**: A function type that allows you to define custom logic for how incoming `StoreEvent`s (e.g., from SSE) should affect the invalidation of active queries in the `QueryCache`.
+
+### Data Flow
+
+1.  **Query Initiation (e.g., `store.read()`, `store.list()`)**:
+    *   A component requests data via `ReactiveRemoteStore`'s reactive methods (`read`, `list`, `find`).
+    *   `ReactiveRemoteStore` generates a unique `queryKey` for the request.
+    *   It checks the `QueryCache` for existing data. If data is fresh, it's returned immediately.
+    *   If data is stale or not present, `ReactiveRemoteStore` registers a `fetchFunction` with the `QueryCache` (which then calls the appropriate `BaseStore` method) to fetch the data.
+    *   The `QueryCache` manages the actual fetching, retries, and updates its internal state.
+    *   `ReactiveRemoteStore` provides a `selector` function that components use to get the current state of the data (including `loading`, `stale`, `error`).
+    *   A `subscribe` function is also provided, allowing components to register callbacks that are notified whenever the query result changes in the cache.
+
+2.  **Mutations (e.g., `store.create()`, `store.update()`)**:
+    *   When a mutation operation is performed, `ReactiveRemoteStore` first calls the corresponding method on the `BaseStore` to update the remote data.
+    *   Upon successful completion, it uses the configured `Correlator` (or a default strategy) to identify which active queries in the `QueryCache` should be invalidated.
+    *   Invalidated queries are marked stale, ensuring that subsequent accesses will trigger a re-fetch (or background re-fetch if SWR is enabled by the `QueryCache`).
+
+3.  **Real-time Events (BaseStore-managed Connection)**:
+    *   `ReactiveRemoteStore` subscribes to a wildcard scope (`*`) on the `BaseStore`'s `subscribe` method, listening for all incoming `StoreEvent`s.
+    *   **Your `BaseStore` implementation is responsible for establishing and managing the actual real-time connection** (e.g., via Server-Sent Events, WebSockets, or other protocols) and pushing `StoreEvent`s to the `ReactiveRemoteStore` via the `callback` provided to `subscribe`.
+    *   When a `StoreEvent` is received, `ReactiveRemoteStore` uses the configured `StoreEventCorrelator` to determine which active queries should be invalidated based on the event's `scope` and `payload`.
+    *   This ensures that client-side data is automatically synchronized with server-side changes.
+
+4.  **Data Streaming (`store.stream()`)**:
+    *   When `store.stream()` is called, `ReactiveRemoteStore` delegates the request to the `BaseStore`'s `stream` method.
+    *   The `BaseStore` is responsible for establishing and managing the actual stream (e.g., HTTP streaming, WebSockets) and returning an `AsyncIterable`.
+    *   `ReactiveRemoteStore` provides this `AsyncIterable` directly to the consumer, along with `cancel` and `status` controls.
+
+### Extension Points
+
+`ReactiveRemoteStore` is designed to be highly extensible, allowing you to tailor its behavior to your specific application and backend needs:
+
+*   **Custom `BaseStore` Implementation**: The most significant extension point. By implementing the `BaseStore` interface, you can integrate `ReactiveRemoteStore` with any type of backend API (REST, GraphQL, custom RPC) and any communication library (Fetch API, Axios, gRPC clients).
+    *   Crucially, your `BaseStore` implementation also dictates the real-time communication method for `subscribe` and `notify` (e.g., Server-Sent Events, WebSockets, long polling, etc.), allowing you to choose the best fit for your backend and application needs.
+*   **Custom `QueryCache`**: While `@core/cache` is assumed, you can swap it out for any caching library that adheres to the expected `QueryCache` interface, allowing you to control caching policies, persistence, and memory management.
+*   **Custom `Correlator` and `StoreEventCorrelator`**: These functions provide powerful control over cache invalidation. You can implement complex logic to precisely invalidate only the necessary queries based on the specifics of your data model and backend events, optimizing performance and consistency.
+*   **Custom `TFindOptions`, `TReadOptions`, etc.**: The generic type parameters for options (`TFindOptions`, `TReadOptions`, etc.) allow you to define strongly-typed options objects that are specific to your API's query capabilities, enhancing type safety throughout your data layer.
+
+---
+
+## 🤝 Development & Contributing
+
+We welcome contributions to `ReactiveRemoteStore`! Whether it's a bug fix, a new feature, or an improvement to the documentation, your help is appreciated.
+
+### Development Setup
+
+To set up the development environment for `ReactiveRemoteStore`:
+
+1.  **Clone the monorepo** (assuming this is part of a larger `erp-utils` monorepo):
+    ```bash
+    git clone https://github.com/your-org/erp-utils.git # Replace with actual repo URL
+    cd erp-utils
+    ```
+2.  **Navigate to the `remote-store` package**:
+    ```bash
+    cd src/remote-store
+    ```
+3.  **Install dependencies**:
+    ```bash
+    bun install
+    # or
+    npm install
+    # or
+    yarn install
+    ```
+4.  **Build the project**:
+    ```bash
+    bun run build
+    # or
+    npm run build
+    # or
+    yarn build
+    ```
+
+### Scripts
+
+The following `bun`/`npm` scripts are available in this project:
+
+*   `bun run build`: Compiles TypeScript source files from `src/` to JavaScript output.
+*   `bun run test`: Runs the test suite using `Vitest`.
+*   `bun run test:watch`: Runs tests in watch mode for continuous feedback during development.
+*   `bun run test-server`: Starts a mock backend server used for e2e tests and examples.
+*   `bun run lint`: Runs ESLint to check for code style and potential errors.
+*   `bun run format`: Formats code using Prettier according to the project's style guidelines.
+
+### Testing
+
+This project includes comprehensive unit, integration, and end-to-end tests to ensure reliability and correctness.
+
+*   **Unit Tests**: Test individual functions and classes in isolation (e.g., `store.test.ts`).
+*   **Integration Tests**: Verify the interaction between `ReactiveRemoteStore` and a mock `BaseStore` (e.g., `store.integration.test.ts`).
+*   **End-to-End (e2e) Tests**: Test the entire system, including `ReactiveRemoteStore`, `QueryCache`, and the `test-server` mock backend, simulating real-world scenarios (e.g., `store.e2e.test.ts`).
+
+To run all tests:
+
+```bash
+bun run test
+```
+
+To run the mock test server (required for e2e tests):
+
+```bash
+bun run test-server
+```
+
+We aim for high test coverage. Please ensure that new features or bug fixes come with appropriate tests to maintain code quality and prevent regressions.
+
+### Contributing Guidelines
+
+Please follow these steps to contribute:
+
+1.  **Fork the repository** on GitHub.
+2.  **Create a new branch** for your feature or bug fix: `git checkout -b feature/my-new-feature` or `bugfix/fix-issue-123`.
+3.  **Make your changes**, ensuring they adhere to the existing code style and architecture.
+4.  **Write or update tests** to cover your changes and ensure existing functionality is not broken.
+5.  **Ensure all tests pass** locally by running `bun run test`.
+6.  **Run lint and format checks** (`bun run lint` and `bun run format`) and fix any reported issues.
+7.  **Write clear, concise commit messages** following the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification (e.g., `feat: add new streaming capability`, `fix: correct invalidation logic`).
+8.  **Push your branch** to your fork.
+9.  **Open a Pull Request** to the `main` branch of the original repository. Provide a detailed description of your changes and why they are necessary.
+
+### Issue Reporting
+
+Found a bug, have a feature request, or need clarification? Please open an issue on our [GitHub Issues page](https://github.com/your-org/erp-utils/issues). <!-- Placeholder: Replace with actual issues URL -->
+
+When reporting a bug, please include:
+
+*   A clear and concise description of the issue.
+*   Detailed steps to reproduce the behavior.
+*   The expected behavior.
+*   Any relevant screenshots or code snippets.
+*   Your environment details (Node.js version, OS, package manager, package version).
+
+---
+
+## 📚 Additional Information
+
+### Troubleshooting
+
+*   **Tests failing after changes in `test-server.ts`**: Ensure the `test-server` is restarted after any modifications to its code, as it runs as a separate process.
+    ```bash
+    bun run test-server # Stop and restart
+    ```
+*   **Data not updating reactively**: 
+    *   Verify that your `BaseStore` implementation correctly calls `notify` or that your backend is sending `StoreEvent`s via SSE.
+    *   Check your `correlator` and `storeEventCorrelator` functions to ensure they are correctly identifying and invalidating relevant queries.
+    *   Ensure your UI components are correctly subscribing to the `ReactiveRemoteStore`'s query results.
+*   **`TypeError: result.stream(...) is not a function`**: This typically occurs in unit tests if the mock for `baseStore.stream` does not return an object with a `stream` property that is a function returning an `AsyncIterable`. Ensure your mock matches the `BaseStore` interface precisely.
+
+### FAQ
+
+**Q: What is the difference between `read`, `list`, and `find`?**
+A: All three methods retrieve data, but they serve different purposes:
+    *   `read`: Designed for fetching a single, specific record (e.g., by ID).
+    *   `list`: Designed for fetching a paginated collection of records, typically without complex search criteria (e.g., all products, all users).
+    *   `find`: Designed for fetching a paginated collection of records based on specific search criteria or filters.
+
+**Q: How does `ReactiveRemoteStore` handle offline scenarios?**
+A: `ReactiveRemoteStore` itself does not directly handle offline persistence. Its caching capabilities (via `QueryCache`) provide in-memory caching. For true offline support, your `QueryCache` implementation would need to integrate with a persistent storage solution (e.g., IndexedDB, LocalStorage) and handle network connectivity changes.
+
+**Q: Can I use `ReactiveRemoteStore` with GraphQL?**
+A: Yes! `ReactiveRemoteStore` is backend-agnostic. You would implement the `BaseStore` interface using a GraphQL client (e.g., Apollo Client, Relay, or a simple `fetch`-based client) to make your GraphQL queries and mutations.
+
+### Changelog/Roadmap
+
+For a detailed history of changes, new features, and bug fixes, please refer to the [CHANGELOG.md](CHANGELOG.md) file in the repository root. Our future plans are outlined in the [ROADMAP.md](ROADMAP.md) (if available).
+
+### License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+### Acknowledgments
+
+*   Inspired by modern reactive data management patterns and libraries.
+*   Leverages `QueryCache` for robust caching capabilities.
+*   Uses `Vitest` for testing and `TypeScript` for type safety.