@asaidimu/utils-cache 1.0.0

package/README.md

@@ -0,0 +1,753 @@
+# @asaidimu/utils-cache
+
+An intelligent, configurable in-memory cache library for Node.js and browser environments, designed for optimal performance, data consistency, and developer observability.
+
+[![npm version](https://img.shields.io/npm/v/@ausaidimu/utils.svg)](https://www.npmjs.com/package/@augustine/utils)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/ausaidimu/utils-ci.yml?branch=main)](https://github.com/augustine/utils-actions)
+[![TypeScript](https://img.shields.io/badge/Built%20with-TypeScript-blue.svg)](https://www.typescriptlang.org/)
+
+---
+
+## 🚀 Quick Links
+
+- [Overview & Features](#-overview--features)
+  - [Detailed Description](#detailed-description)
+  - [Key Features](#key-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
+
+### Detailed Description
+
+`Cache` provides a robust, in-memory caching solution designed for applications that require efficient data retrieval, resilience against network failures, and state persistence across sessions or processes. It implements common caching patterns like *stale-while-revalidate* and *Least Recently Used (LRU)* eviction, along with advanced features like automatic retries for failed fetches, extensible persistence mechanisms, and a comprehensive event system for real-time monitoring.
+
+Unlike simpler caches, `Cache` manages data freshness intelligently, allowing you to serve stale data while a fresh copy is being fetched in the background. Its pluggable persistence layer enables you to save and restore the cache state, making it ideal for client-side applications that need to maintain state offline or server-side applications that need rapid startup with pre-populated data. With built-in metrics and events, `SimpleCache` offers deep insights into cache performance and lifecycle.
+
+### Key Features
+
+*   **Configurable In-Memory Store**: Fast access to cached data.
+*   **Stale-While-Revalidate (SWR)**: Serve existing data immediately while fetching new data in the background, minimizing perceived latency.
+*   **Automatic Retries**: Configurable retry attempts and exponential backoff for `fetchFunction` failures.
+*   **Pluggable Persistence**: Integrates with any `SimplePersistence` implementation (e.g., LocalStorage, IndexedDB, custom backend) to save and restore cache state.
+    *   **Debounced Persistence Writes**: Optimizes write frequency to the underlying persistence layer.
+    *   **Remote Update Handling**: Synchronizes cache state when the persistence layer is updated externally.
+    *   **Custom Serialization/Deserialization**: Control how your data is prepared for persistence.
+*   **Configurable Eviction Policies**:
+    *   **Time-Based (TTL)**: Automatically evicts entries inactive for `cacheTime`.
+    *   **Size-Based (LRU)**: Evicts least recently used items when `maxSize` is exceeded.
+*   **Comprehensive Event System**: Subscribe to granular cache events (hit, miss, fetch, error, eviction, invalidation, persistence, set_data) for logging, debugging, and advanced reactivity.
+*   **Performance Metrics**: Built-in tracking for hits, misses, fetches, errors, evictions, and stale hits, with calculated hit rates.
+*   **Flexible Query Management**: Register `fetchFunction`s for specific keys, allowing `Cache` to manage their lifecycle.
+*   **Imperative Control**: Methods for manual `invalidate`, `prefetch`, `refresh`, `setData`, and `remove` operations.
+*   **TypeScript Support**: Fully typed API for enhanced developer experience.
+
+---
+
+## 🛠️ Installation & Setup
+
+### Prerequisites
+
+*   Node.js (v14.x or higher)
+*   npm or yarn
+
+### Installation Steps
+
+Install `Cache` using your preferred package manager:
+
+```bash
+bun add @ausaidimu/utils-cache
+```
+
+### Configuration
+
+`Cache` is initialized with a `CacheOptions` object, allowing you to customize its behavior globally. Individual queries can override these options.
+
+```typescript
+import { Cache } from '@ausaidimu/utils-cache';
+import { IndexedDBPersistence } from '@asaidimu/utils-persistence';
+
+
+const myCache = new Cache({
+  staleTime: 5 * 60 * 1000, // Data considered stale after 5 minutes
+  cacheTime: 30 * 60 * 1000, // Data evicted if not accessed for 30 minutes
+  retryAttempts: 2, // Retry fetch up to 2 times on failure
+  retryDelay: 2000, // 2-second initial delay between retries (doubles each attempt)
+  maxSize: 500, // Maximum 500 entries (LRU eviction)
+  enableMetrics: true,
+  persistence: new IndexedDBPersistence(), // Plug in your persistence layer
+  persistenceId: 'my-app-cache-v1', // Unique ID for this cache instance in persistence
+  persistenceDebounceTime: 1000, // Debounce persistence writes by 1 second
+  // Custom serializers/deserializers for non-JSON-serializable data
+  serializeValue: (value) => {
+    if (value instanceof Map) return { _type: 'Map', data: Array.from(value.entries()) };
+    return value;
+  },
+  deserializeValue: (value) => {
+    if (typeof value === 'object' && value !== null && value._type === 'Map') {
+      return new Map(value.data);
+    }
+    return value;
+  },
+});
+```
+
+### Verification
+
+To verify that `Cache` is installed and initialized correctly, you can run a simple test:
+
+```typescript
+import { Cache } from '@ausaidimu/utils-cache';
+
+const cache = new Cache();
+console.log('Cache initialized successfully!');
+
+// You can add a simple query and try to fetch:
+cache.registerQuery('hello', async () => 'world');
+cache.get('hello').then(data => {
+  console.log(`Fetched 'hello': ${data}`);
+});
+```
+
+---
+
+## 📖 Usage Documentation
+
+### Basic Usage
+
+The core of `Cache` involves registering queries and then retrieving data using those queries.
+
+```typescript
+import { Cache } from '@ausaidimu/utils-cache';
+
+const myCache = new Cache({
+  staleTime: 5000, // 5 seconds
+  cacheTime: 60000, // 1 minute
+});
+
+// 1. Register a query with a unique key and a function to fetch the data
+myCache.registerQuery('user/123', async () => {
+  console.log('Fetching user data...');
+  // Simulate network delay
+  await new Promise(resolve => setTimeout(resolve, 1000));
+  return { id: 123, name: 'Alice', email: 'alice@example.com' };
+});
+
+// 2. Retrieve data from the cache
+async function getUserData() {
+  const userData = await myCache.get('user/123');
+  console.log('User data:', userData);
+}
+
+// First call: Triggers fetch, data is fetched and cached
+getUserData();
+
+// Subsequent calls (within staleTime): Data is returned instantly from cache
+setTimeout(() => getUserData(), 500);
+
+// Call after staleTime: Data is returned instantly, but a background fetch is triggered
+setTimeout(() => getUserData(), 6000);
+
+// Example of waiting for fresh data
+async function getFreshUserData() {
+  console.log('\nRequesting fresh user data...');
+  const freshUserData = await myCache.get('user/123', { waitForFresh: true });
+  console.log('Fresh user data:', freshUserData);
+}
+
+setTimeout(() => getFreshUserData(), 7000);
+```
+
+### API Usage
+
+#### `new Cache(defaultOptions?: CacheOptions)`
+
+Creates a new `Cache` instance with global default options.
+
+```typescript
+import { Cache } from '@ausaidimu/utils-cache';
+
+const cache = new Cache({
+  staleTime: 5 * 60 * 1000, // 5 minutes
+  cacheTime: 30 * 60 * 1000, // 30 minutes
+  maxSize: 1000,
+});
+```
+
+#### `cache.registerQuery<T>(key: string, fetchFunction: () => Promise<T>, options?: CacheOptions): void`
+
+Registers a data fetching function associated with a `key`. This function will be called when data for the `key` is not in cache, is stale, or explicitly invalidated/refreshed.
+
+-   `key`: A unique string identifier for the data.
+-   `fetchFunction`: An `async` function that returns a `Promise` resolving to the data.
+-   `options`: Optional `CacheOptions` to override the instance's default options for this specific query.
+
+```typescript
+cache.registerQuery('products/featured', async () => {
+  const response = await fetch('/api/products/featured');
+  if (!response.ok) throw new Error('Failed to fetch featured products');
+  return response.json();
+}, {
+  staleTime: 60 * 1000, // This query's data is stale after 1 minute
+  retryAttempts: 5,
+});
+```
+
+#### `cache.get<T>(key: string, options?: { waitForFresh?: boolean; throwOnError?: boolean }): Promise<T | undefined>`
+
+Retrieves data for a given `key`.
+
+-   If data is fresh, returns it immediately.
+-   If data is stale, returns it immediately and triggers a background refetch (stale-while-revalidate).
+-   If data is not in cache (miss), triggers a fetch.
+-   `waitForFresh`: If `true`, the method will await the fetch function to complete and return fresh data. If `false` (default), it will return existing stale data immediately if available, otherwise `undefined` while a fetch is ongoing in the background.
+-   `throwOnError`: If `true`, and the fetch fails, the promise returned by `get` will reject with the error. If `false` (default), it will return `undefined` on fetch failure, or the last successfully fetched data if available.
+
+```typescript
+// Basic usage (stale-while-revalidate)
+const post = await cache.get('posts/latest');
+
+// Wait for fresh data, throw if fetch fails
+try {
+  const userProfile = await cache.get('user/profile', { waitForFresh: true, throwOnError: true });
+} catch (error) {
+  console.error('Could not get fresh user profile:', error);
+}
+```
+
+#### `cache.peek<T>(key: string): T | undefined`
+
+Retrieves data from the cache without triggering any fetches or updating `lastUpdated` time. Useful for quick synchronous checks.
+
+```typescript
+const cachedValue = cache.peek('some-key');
+if (cachedValue) {
+  console.log('Value is in cache:', cachedValue);
+} else {
+  console.log('Value not found in cache.');
+}
+```
+
+#### `cache.has(key: string): boolean`
+
+Checks if a non-stale, non-loading entry exists in the cache for the given `key`.
+
+```typescript
+if (cache.has('config/app')) {
+  console.log('App config is ready and fresh.');
+}
+```
+
+#### `cache.invalidate(key: string, refetch?: boolean): Promise<void>`
+
+Marks an entry as stale, forcing the next `get` call to trigger a refetch. Optionally triggers an immediate background refetch.
+
+-   `key`: The cache key to invalidate.
+-   `refetch`: If `true` (default), triggers an immediate background fetch for the invalidated key.
+
+```typescript
+// Invalidate a specific user's posts
+await cache.invalidate('user/123/posts');
+
+// Invalidate and don't refetch until `get` is called
+await cache.invalidate('admin/dashboard/stats', false);
+```
+
+#### `cache.invalidatePattern(pattern: RegExp, refetch?: boolean): Promise<void>`
+
+Invalidates all cache entries whose keys match the given regular expression.
+
+-   `pattern`: A `RegExp` to match cache keys.
+-   `refetch`: If `true` (default), triggers immediate background fetches for all matched keys.
+
+```typescript
+// Invalidate all product-related data
+await cache.invalidatePattern(/^products\//);
+```
+
+#### `cache.prefetch(key: string): Promise<void>`
+
+Triggers a background fetch for a `key` if it's not already in cache or is stale. Useful for loading data proactively.
+
+```typescript
+// On page load, prefetch common data
+cache.prefetch('static-content/footer');
+cache.prefetch('user/notifications/unread');
+```
+
+#### `cache.refresh<T>(key: string): Promise<T | undefined>`
+
+Forces a re-fetch of data for a given `key`, bypassing staleness checks and existing fetch promises. Returns the fresh data.
+
+```typescript
+// Force update user data after an API call changes it
+const updatedUser = await cache.refresh('user/current');
+console.log('User data refreshed:', updatedUser);
+```
+
+#### `cache.setData<T>(key: string, data: T): void`
+
+Manually sets or updates data in the cache for a given `key`. This immediately updates the cache entry, marks it as fresh, and triggers persistence if configured.
+
+```typescript
+// Manually update a shopping cart item count
+cache.setData('cart/item-count', 5);
+
+// Directly inject data fetched from another source
+const externalData = { /* ... */ };
+cache.setData('external-resource/id', externalData);
+```
+
+#### `cache.remove(key: string): boolean`
+
+Removes an entry from the cache. Returns `true` if an entry was found and removed, `false` otherwise.
+
+```typescript
+// When a user logs out, remove their specific session data
+cache.remove('user/session');
+```
+
+#### `cache.on<EType extends CacheEventType>(event: EType, listener: (ev: Extract<CacheEvent, { type: EType }>) => void): void`
+
+Subscribes to cache events.
+
+-   `event`: The type of event to listen for (e.g., `'hit'`, `'miss'`, `'error'`).
+-   `listener`: A callback function that receives the event payload.
+
+```typescript
+import { Cache, CacheEvent, CacheEventType } from '@ausaidimu/utils-cache';
+
+const myCache = new Cache();
+
+myCache.on('hit', (e) => {
+  console.log(`Cache HIT for ${e.key} (stale: ${e.isStale})`);
+});
+
+myCache.on('miss', (e) => {
+  console.log(`Cache MISS for ${e.key}`);
+});
+
+myCache.on('error', (e) => {
+  console.error(`Cache ERROR for ${e.key} (attempt ${e.attempt}):`, e.error.message);
+});
+
+myCache.on('persistence', (e) => {
+  if (e.event === 'save_success') {
+    console.log(`Cache state saved successfully for ID: ${e.key}`);
+  } else if (e.event === 'load_fail') {
+    console.error(`Failed to load cache state for ID: ${e.key}`, e.error);
+  }
+});
+```
+
+#### `cache.off<EType extends CacheEventType>(event: EType, listener: (ev: Extract<CacheEvent, { type: EType }>) => void): void`
+
+Unsubscribes a listener from a cache event.
+
+```typescript
+const myHitListener = (e: any) => console.log(`Hit: ${e.key}`);
+myCache.on('hit', myHitListener);
+// Later...
+myCache.off('hit', myHitListener);
+```
+
+#### `cache.getStats(): { size: number; metrics: CacheMetrics; hitRate: number; staleHitRate: number; entries: Array<CacheEntryInfo> }`
+
+Returns current cache statistics and metrics.
+
+-   `size`: Number of entries in the cache.
+-   `metrics`: Object containing `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).
+
+```typescript
+const stats = myCache.getStats();
+console.log('Cache Size:', stats.size);
+console.log('Metrics:', stats.metrics);
+console.log('Hit Rate:', (stats.hitRate * 100).toFixed(2) + '%');
+```
+
+#### `cache.clear(): Promise<void>`
+
+Clears all data from the in-memory cache and attempts to clear the persisted state.
+
+```typescript
+await myCache.clear();
+console.log('Cache cleared.');
+```
+
+#### `cache.destroy(): void`
+
+Shuts down the cache instance, clearing all data, stopping garbage collection, and unsubscribing from persistence. Call this when the cache instance is no longer needed.
+
+```typescript
+myCache.destroy();
+console.log('Cache instance destroyed.');
+```
+
+### Configuration Examples
+
+The `CacheOptions` interface provides extensive control:
+
+```typescript
+import { CacheOptions, SimplePersistence, SerializableCacheState } from '@ausaidimu/utils-cache';
+
+// A mock persistence layer for demonstration
+class MockPersistence implements SimplePersistence<SerializableCacheState> {
+    private store = new Map<string, SerializableCacheState>();
+    private subscribers = new Map<string, Array<(data: SerializableCacheState) => void>>();
+
+    async get(id: string): Promise<SerializableCacheState | undefined> {
+        console.log(`[MockPersistence] Getting state for ${id}`);
+        return this.store.get(id);
+    }
+    async set(id: string, data: SerializableCacheState): Promise<void> {
+        console.log(`[MockPersistence] Setting state for ${id}`);
+        this.store.set(id, data);
+        // Simulate remote update to subscribers
+        this.subscribers.get(id)?.forEach(cb => cb(data));
+    }
+    async clear(id?: string): Promise<void> {
+        console.log(`[MockPersistence] Clearing state ${id ? 'for ' + id : 'all'}`);
+        if (id) {
+            this.store.delete(id);
+        } else {
+            this.store.clear();
+        }
+    }
+    subscribe(id: string, callback: (data: SerializableCacheState) => void): () => void {
+        console.log(`[MockPersistence] Subscribing to ${id}`);
+        if (!this.subscribers.has(id)) {
+            this.subscribers.set(id, []);
+        }
+        this.subscribers.get(id)?.push(callback);
+        return () => {
+            const callbacks = this.subscribers.get(id);
+            if (callbacks) {
+                this.subscribers.set(id, callbacks.filter(cb => cb !== callback));
+            }
+        };
+    }
+}
+
+
+const fullOptions: CacheOptions = {
+  staleTime: 1000 * 60 * 5, // 5 minutes
+  cacheTime: 1000 * 60 * 60, // 1 hour (items idle for this long are garbage collected)
+  retryAttempts: 3, // Max 3 fetch attempts (initial + 2 retries)
+  retryDelay: 1000, // 1 second initial delay for retries (doubles each attempt)
+  maxSize: 2000, // Keep up to 2000 entries (LRU eviction kicks in beyond this)
+  enableMetrics: true, // Enable performance tracking
+  persistence: new MockPersistence(), // Provide an instance of your persistence layer
+  persistenceId: 'my-unique-cache-instance', // Specific ID for this cache in persistence
+  persistenceDebounceTime: 750, // Wait 750ms before writing to persistence
+  serializeValue: (value: any) => {
+    // Example: Convert Date objects to ISO strings for JSON serialization
+    if (value instanceof Date) {
+      return { _type: 'Date', data: value.toISOString() };
+    }
+    return value;
+  },
+  deserializeValue: (value: any) => {
+    // Example: Convert ISO strings back to Date objects
+    if (typeof value === 'object' && value !== null && value._type === 'Date') {
+      return new Date(value.data);
+    }
+    return value;
+  },
+};
+
+const configuredCache = new Cache(fullOptions);
+```
+
+### Common Use Cases
+
+#### Caching API Responses with SWR
+
+```typescript
+import { Cache } from '@ausaidimu/utils-cache';
+
+const apiCache = new Cache({
+  staleTime: 5 * 60 * 1000, // 5 min before data is considered stale
+  cacheTime: 30 * 60 * 1000, // 30 min before idle data is garbage collected
+  retryAttempts: 3,
+});
+
+apiCache.registerQuery('blog/posts', async () => {
+  console.log('Fetching ALL blog posts from API...');
+  const response = await fetch('https://api.example.com/blog/posts');
+  if (!response.ok) throw new Error('Failed to fetch blog posts');
+  return response.json();
+});
+
+// User opens blog page: get posts instantly, refresh if needed
+async function displayBlogPosts() {
+  const posts = await apiCache.get('blog/posts');
+  if (posts) {
+    console.log('Displaying posts (from cache or new fetch):', posts.slice(0, 2));
+  } else {
+    console.log('No posts yet, waiting for fetch...');
+  }
+}
+
+displayBlogPosts(); // First load
+setTimeout(() => displayBlogPosts(), 2000); // Subsequent fast load from cache
+setTimeout(() => displayBlogPosts(), 301000); // After staleTime, returns cached data, triggers background fetch
+```
+
+#### Using `waitForFresh` for Critical Data
+
+```typescript
+import { Cache } from '@ausaidimu/utils-cache';
+
+const criticalCache = new Cache({ retryAttempts: 5, retryDelay: 1000 });
+
+criticalCache.registerQuery('user/permissions', async () => {
+  console.log('Fetching user permissions...');
+  const response = await fetch('/api/user/permissions');
+  if (!response.ok) throw new Error('Failed to get permissions!');
+  return response.json();
+});
+
+async function checkPermissionsBeforeAction() {
+  try {
+    // We MUST have the latest permissions before proceeding
+    const permissions = await criticalCache.get('user/permissions', { waitForFresh: true, throwOnError: true });
+    console.log('User permissions:', permissions);
+    // Proceed with action based on permissions
+  } catch (error) {
+    console.error('Failed to load critical permissions:', error);
+    // Redirect to error page or show alert
+  }
+}
+
+checkPermissionsBeforeAction();
+```
+
+#### Real-time Monitoring with Events
+
+```typescript
+import { Cache } from '@ausaidimu/utils-cache';
+
+const monitorCache = new Cache({ enableMetrics: true });
+
+monitorCache.registerQuery('stock/AAPL', async () => {
+  const price = Math.random() * 100 + 150;
+  console.log(`Fetching AAPL price: $${price.toFixed(2)}`);
+  return { symbol: 'AAPL', price: parseFloat(price.toFixed(2)), timestamp: Date.now() };
+}, { staleTime: 1000 }); // Very short staleTime for frequent fetches
+
+monitorCache.on('fetch', (e) => {
+  console.log(`[EVENT] Fetching ${e.key} (attempt ${e.attempt})`);
+});
+monitorCache.on('hit', (e) => {
+  console.log(`[EVENT] Cache hit for ${e.key}. Stale: ${e.isStale}`);
+});
+monitorCache.on('miss', (e) => {
+  console.log(`[EVENT] Cache miss for ${e.key}`);
+});
+monitorCache.on('eviction', (e) => {
+  console.log(`[EVENT] Evicted ${e.key} due to ${e.reason}`);
+});
+monitorCache.on('set_data', (e) => {
+    console.log(`[EVENT] Data for ${e.key} manually set. Old: ${e.oldData?.price}, New: ${e.newData.price}`);
+});
+
+setInterval(() => {
+  monitorCache.get('stock/AAPL');
+}, 500); // Continuously try to get data
+
+setInterval(() => {
+  const stats = monitorCache.getStats();
+  console.log(`\n--- STATS ---`);
+  console.log(`Size: ${stats.size}, Hits: ${stats.metrics.hits}, Misses: ${stats.metrics.misses}, Fetches: ${stats.metrics.fetches}`);
+  console.log(`Hit Rate: ${(stats.hitRate * 100).toFixed(2)}%, Stale Hit Rate: ${(stats.staleHitRate * 100).toFixed(2)}%`);
+  console.log(`Active entries: ${stats.entries.map(e => `${e.key} (stale:${e.isStale})`).join(', ')}`);
+  console.log(`---\n`);
+}, 5000); // Log stats every 5 seconds
+```
+
+---
+
+## 🏗️ Project Architecture
+
+### Core Components
+
+*   **`Cache` Class (`index.ts`)**: The primary entry point. Manages the in-memory `Map` (`this.cache`), handles fetching, retries, staleness, garbage collection, persistence, and events.
+*   **`CacheOptions` (`types.ts`)**: Defines the configuration parameters for `Cache` instances and individual queries.
+*   **`CacheEntry` (`types.ts`)**: Represents a single item stored in the cache, including its data, timestamps, access count, and loading/error status.
+*   **`QueryConfig` (`types.ts`)**: Stores the `fetchFunction` and resolved options for each registered query.
+*   **`CacheMetrics` (`types.ts`)**: Defines the structure for tracking cache performance statistics.
+*   **`SimplePersistence<SerializableCacheState>` (from `@core/persistence/types`)**: An external interface that `Cache` uses for persistent storage. It requires `get()`, `set()`, `clear()`, and optionally `subscribe()` methods to handle data serialization and deserialization for the storage medium.
+*   **`CacheEvent` / `CacheEventType` (`types.ts`)**: Defines the union of all possible events emitted by the cache, enabling fine-grained observability.
+
+### Data Flow
+
+1.  **Initialization**: `Cache` constructor sets default options, initializes metrics, starts garbage collection, and attempts to load state from the configured `persistence` layer. It also subscribes to remote updates from persistence if available.
+2.  **`registerQuery`**: Stores a `fetchFunction` and its specific `CacheOptions` (merged with defaults) in a `queries` map.
+3.  **`get` Request**:
+    *   Checks `this.cache` for the key.
+    *   If found, updates `lastAccessed`, increments `accessCount`, emits `hit` event.
+    *   Checks `isStale` based on `staleTime`.
+    *   If `waitForFresh` is `true` OR if `isStale` / `cacheEntry` is loading/empty, it calls `fetchAndWait`.
+    *   Otherwise, if `isStale`, it triggers `fetch` in the background.
+    *   If no entry, emits `miss` event and creates a placeholder, then triggers `fetch`.
+    *   Returns cached data (if available and not `waitForFresh`) or `undefined` (if background fetch).
+4.  **`fetch` / `fetchAndWait`**:
+    *   Checks `this.fetching` to avoid concurrent fetches for the same key.
+    *   Calls `performFetchWithRetry`.
+5.  **`performFetchWithRetry`**:
+    *   Iteratively calls the registered `fetchFunction`.
+    *   Emits `fetch` event before each attempt.
+    *   On success: updates `cacheEntry` with `data`, `lastUpdated`, `isLoading: false`, `error: undefined`. Schedules `schedulePersistState`. Enforces `enforceSizeLimit`. Returns `data`.
+    *   On failure: emits `error` event. Retries after `retryDelay` (with exponential backoff). After all attempts, updates `cacheEntry` with `error` and `isLoading: false`. Schedules `schedulePersistState`. Returns `undefined`.
+6.  **`schedulePersistState`**: Debounces persistence writes. When triggered, `serializeCache` transforms the current cache state into a `SerializableCacheState` (applying `serializeValue`), which is then written to the `persistence` layer. Emits `persistence` events.
+7.  **`handleRemoteStateChange`**: When the `persistence` layer notifies of a remote update, this method deserializes the state (applying `deserializeValue`) and updates `this.cache`, ensuring local cache consistency with external changes.
+8.  **`garbageCollect`**: Periodically (via `gcTimer`) iterates through `this.cache` and removes entries that have not been accessed for `cacheTime`. Emits `eviction` events.
+9.  **`enforceSizeLimit`**: Triggered after successful fetches or `setData`. If `maxSize` is exceeded, evicts `LRU` entries. Emits `eviction` events.
+
+### Extension Points
+
+*   **`SimplePersistence` Interface**: The primary extension point for integrating `Cache` with various storage backends. Implement this interface to use `SimpleCache` with `localStorage`, `IndexedDB`, a database, or any other persistent storage.
+*   **`serializeValue` / `deserializeValue` Options**: Customize how cache entry data is converted to and from a serializable format (e.g., handling `Date` objects, `Map`s, custom classes) before interacting with the persistence layer.
+*   **Event Listeners (`on`/`off`)**: Integrate `Cache` events with your application's logging, analytics, UI reactivity, or debugging tools.
+
+---
+
+## 🤝 Development & Contributing
+
+### Development Setup
+
+To set up the development environment:
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/ausaidimu/utils.git
+    cd utils-src/cache
+    ```
+2.  **Install dependencies:**
+    ```bash
+    npm install
+    # or
+    yarn install
+    ```
+3.  **Build the project:**
+    ```bash
+    npm run build
+    # or
+    yarn build
+    ```
+
+### Scripts
+
+The following `npm` scripts are available:
+
+*   `npm run build`: Compiles TypeScript source files to JavaScript.
+*   `npm run test`: Runs the test suite.
+*   `npm run lint`: Runs ESLint to check for code style issues.
+*   `npm run format`: Formats code using Prettier.
+
+### Testing
+
+Tests are written using `[Your Testing Framework, e.g., Jest]`. To run tests:
+
+```bash
+npm test
+# or
+yarn test
+```
+
+We aim for high test coverage. Please ensure new features or bug fixes come with appropriate tests.
+
+### Contributing Guidelines
+
+We welcome contributions! Please follow these steps:
+
+1.  Fork the repository.
+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.
+4.  Write or update tests to cover your changes.
+5.  Ensure all tests pass (`npm test`).
+6.  Run lint and format checks (`npm run lint`, `npm run format`).
+7.  Write clear, concise commit messages following the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
+8.  Push your branch and open a Pull Request to the `main` branch.
+
+### Issue Reporting
+
+Found a bug or have a feature request? Please open an issue on our [GitHub Issues page](https://github.com/ausaidimu/utils-issues).
+When reporting a bug, please include:
+
+*   A clear and concise description of the issue.
+*   Steps to reproduce the behavior.
+*   Expected behavior.
+*   Screenshots or code snippets if applicable.
+*   Your environment details (Node.js version, OS, browser).
+
+---
+
+## 📚 Additional Information
+
+### Troubleshooting
+
+*   **"No query registered for key: [key]" Error**: This means you tried to `get`, `prefetch`, or `refresh` a key that was not previously registered using `registerQuery`. Ensure you register all keys you intend to use.
+*   **Data not persisting**:
+    *   Double-check that you passed a valid `persistence` instance to the `Cache` constructor.
+    *   Verify your `SimplePersistence` implementation correctly saves and loads data.
+    *   Ensure your data is properly serializable to JSON (or use `serializeValue`/`deserializeValue` options for complex types).
+    *   Check for `persistence` event errors in your console.
+*   **Cache not evicting data**:
+    *   Ensure `cacheTime` and `maxSize` are set to finite, non-zero values in `CacheOptions`. `Infinity` or `0` for `cacheTime` disables time-based GC.
+    *   Verify the garbage collection interval is not too long (it's `cacheTime / 4` or `5 minutes` max).
+*   **Listeners not firing**: Ensure you're subscribing to the correct `CacheEventType` and that the cache operation (e.g., a `hit` or `error`) is actually occurring. Check `enableMetrics` isn't `false` if expecting metric-related events/updates.
+
+### FAQ
+
+**Q: How does `staleTime` differ from `cacheTime`?**
+A: `staleTime` determines when data is considered "stale" and a background refetch should be triggered. You can still use stale data. `cacheTime` determines how long an item can remain unaccessed before it's eligible for garbage collection and removal from the cache. An item can be stale but still within its `cacheTime`.
+
+**Q: When should I use `waitForFresh`?**
+A: Use `waitForFresh: true` when your application absolutely needs the most up-to-date data before proceeding, and cannot tolerate serving stale or old data. This will block execution until the `fetchFunction` resolves. For most UI display purposes where latency is critical, `waitForFresh: false` (the default SWR behavior) is usually preferred.
+
+**Q: Can I use `Cache` in a web worker?**
+A: Yes, `Cache` is designed to be environment-agnostic. Its persistence mechanism is pluggable, so you can implement a `SimplePersistence` that works within a web worker (e.g., using IndexedDB directly or `postMessage` to the main thread).
+
+**Q: Is `Cache` thread-safe (or safe with concurrent access)?**
+A: `Cache` manages internal state with `Map`s and `Promise`s, which are atomic operations in JavaScript's single-threaded execution model. For concurrent `get` requests to the same key, it ensures only one `fetchFunction` runs via `this.fetching` map. It is safe for concurrent access within a single JavaScript runtime.
+
+### License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+### Acknowledgments
+
+*   Inspired by modern caching libraries like React Query and SWR.
+*   Uses `uuid` for generating unique cache IDs.