@fjell/cache 4.7.35 → 4.7.36

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fjell/cache",
   "description": "Cache for Fjell",
-  "version": "4.7.35",
+  "version": "4.7.36",
   "keywords": [
     "cache",
     "fjell"
@@ -37,11 +37,11 @@
     "docs:test": "cd docs && npm run test"
   },
   "dependencies": {
-    "@fjell/client-api": "^4.4.46",
-    "@fjell/core": "^4.4.50",
-    "@fjell/http-api": "^4.4.42",
-    "@fjell/logging": "^4.4.49",
-    "@fjell/registry": "^4.4.52",
+    "@fjell/client-api": "^4.4.47",
+    "@fjell/core": "^4.4.51",
+    "@fjell/http-api": "^4.4.43",
+    "@fjell/logging": "^4.4.50",
+    "@fjell/registry": "^4.4.53",
     "fast-safe-stringify": "^2.1.1",
     "flatted": "^3.3.3",
     "yocto-queue": "^1.2.1"
@@ -49,7 +49,7 @@
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.33.0",
-    "@fjell/eslint-config": "^1.1.25",
+    "@fjell/eslint-config": "^1.1.28",
     "@swc/core": "^1.13.3",
     "@tsconfig/recommended": "^1.0.10",
     "@types/multer": "^2.0.0",

package/CACHE_EVENTS.md

@@ -1,306 +0,0 @@
-# Cache Event System
-
-The fjell-cache event system provides real-time notifications when cache operations occur. This enables reactive patterns where components can subscribe to cache changes and update automatically.
-
-## Overview
-
-The event system is built into the core Cache interface and provides:
-
-- **Event emission** for all cache operations (create, update, remove, query, etc.)
-- **Subscription management** with filtering options
-- **Event types** covering all cache state changes
-- **Debouncing** support for high-frequency updates
-- **Type safety** with full TypeScript support
-
-## Basic Usage
-
-### Subscribing to Events
-
-```typescript
-import { createCache, CacheEventListener } from '@fjell/cache';
-
-// Create cache
-const cache = createCache(api, coordinate, registry);
-
-// Subscribe to all events
-const listener: CacheEventListener<MyItem, 'myType'> = (event) => {
-  console.log('Cache event:', event.type, event);
-};
-
-const subscription = cache.subscribe(listener);
-
-// Later: unsubscribe
-subscription.unsubscribe();
-```
-
-### Filtering Events
-
-```typescript
-// Subscribe only to item creation events
-const subscription = cache.subscribe(listener, {
-  eventTypes: ['item_created', 'item_updated']
-});
-
-// Subscribe only to events for specific keys
-const subscription = cache.subscribe(listener, {
-  keys: [{ pk: 'user-123' }]
-});
-
-// Subscribe only to events in specific locations
-const subscription = cache.subscribe(listener, {
-  locations: [{ lk: 'container-1' }]
-});
-
-// Subscribe with debouncing (useful for UI updates)
-const subscription = cache.subscribe(listener, {
-  debounceMs: 100  // Debounce events by 100ms
-});
-```
-
-## Event Types
-
-### Item Events
-
-These events are emitted when individual items are affected:
-
-- **`item_created`** - Item was created via API and cached
-- **`item_updated`** - Item was updated via API and cache updated
-- **`item_removed`** - Item was removed via API and from cache
-- **`item_retrieved`** - Item was retrieved from API and cached
-- **`item_set`** - Item was set directly in cache (no API call)
-
-```typescript
-interface ItemEvent<V, S, L1, L2, L3, L4, L5> {
-  type: 'item_created' | 'item_updated' | 'item_removed' | 'item_retrieved' | 'item_set';
-  key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>;
-  item: V | null;  // null for removed items
-  previousItem?: V | null;  // Previous state before change
-  affectedLocations?: LocKeyArray<L1, L2, L3, L4, L5> | [];
-  timestamp: number;
-  source: 'api' | 'cache' | 'operation';
-}
-```
-
-### Query Events
-
-These events are emitted when multiple items are queried:
-
-- **`items_queried`** - Multiple items were queried and cached
-
-```typescript
-interface QueryEvent<V, S, L1, L2, L3, L4, L5> {
-  type: 'items_queried';
-  query: ItemQuery;
-  locations: LocKeyArray<L1, L2, L3, L4, L5> | [];
-  items: V[];
-  affectedKeys: (ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>)[];
-  timestamp: number;
-  source: 'api' | 'cache' | 'operation';
-}
-```
-
-### Cache Management Events
-
-These events are emitted for cache-wide operations:
-
-- **`cache_cleared`** - Entire cache was cleared
-- **`location_invalidated`** - Specific location(s) were invalidated
-- **`query_invalidated`** - Cached query results were invalidated
-
-## Advanced Usage
-
-### React Integration Example
-
-```typescript
-import { useEffect, useState } from 'react';
-import { Cache, CacheSubscription } from '@fjell/cache';
-
-function useItem<T>(cache: Cache<T, any>, key: any): T | null {
-  const [item, setItem] = useState<T | null>(() =>
-    cache.cacheMap.get(key)
-  );
-
-  useEffect(() => {
-    const subscription = cache.subscribe((event) => {
-      if (event.type === 'item_changed' &&
-          JSON.stringify(event.key) === JSON.stringify(key)) {
-        setItem(event.item);
-      } else if (event.type === 'item_removed' &&
-                 JSON.stringify(event.key) === JSON.stringify(key)) {
-        setItem(null);
-      }
-    }, {
-      keys: [key],
-      eventTypes: ['item_updated', 'item_removed', 'item_set']
-    });
-
-    return () => subscription.unsubscribe();
-  }, [cache, key]);
-
-  return item;
-}
-```
-
-### Listening to Multiple Caches
-
-```typescript
-class CacheEventHub {
-  private subscriptions: CacheSubscription[] = [];
-
-  subscribeTo<T>(cache: Cache<T, any>, listener: CacheEventListener<T, any>) {
-    const subscription = cache.subscribe(listener);
-    this.subscriptions.push(subscription);
-    return subscription;
-  }
-
-  unsubscribeAll() {
-    this.subscriptions.forEach(sub => sub.unsubscribe());
-    this.subscriptions = [];
-  }
-}
-
-const hub = new CacheEventHub();
-
-// Subscribe to multiple caches
-hub.subscribeTo(userCache, (event) => console.log('User event:', event));
-hub.subscribeTo(orderCache, (event) => console.log('Order event:', event));
-
-// Later: clean up all subscriptions
-hub.unsubscribeAll();
-```
-
-### Event Logging and Debugging
-
-```typescript
-// Log all cache events for debugging
-const debugSubscription = cache.subscribe((event) => {
-  console.log(`[${new Date(event.timestamp).toISOString()}] ${event.type}:`, {
-    source: event.source,
-    ...('key' in event ? { key: event.key } : {}),
-    ...('query' in event ? { query: event.query } : {}),
-  });
-});
-
-// Performance monitoring
-let eventCounts = new Map<string, number>();
-
-cache.subscribe((event) => {
-  const count = eventCounts.get(event.type) || 0;
-  eventCounts.set(event.type, count + 1);
-});
-
-setInterval(() => {
-  console.log('Event counts:', Object.fromEntries(eventCounts));
-  eventCounts.clear();
-}, 10000);
-```
-
-## Best Practices
-
-### 1. Use Specific Event Filters
-
-```typescript
-// Good: Filter by specific event types and keys
-cache.subscribe(listener, {
-  eventTypes: ['item_updated'],
-  keys: [userKey]
-});
-
-// Avoid: Subscribing to all events when you only need specific ones
-cache.subscribe(listener); // Too broad
-```
-
-### 2. Debounce High-Frequency Updates
-
-```typescript
-// Good: Debounce UI updates
-cache.subscribe(updateUI, {
-  debounceMs: 100
-});
-
-// Good: Don't debounce critical business logic
-cache.subscribe(saveToDisk, {
-  // No debouncing for critical operations
-});
-```
-
-### 3. Clean Up Subscriptions
-
-```typescript
-useEffect(() => {
-  const subscription = cache.subscribe(listener);
-
-  // Always clean up
-  return () => subscription.unsubscribe();
-}, []);
-```
-
-### 4. Handle Errors in Listeners
-
-```typescript
-cache.subscribe((event) => {
-  try {
-    // Your event handling logic
-    handleEvent(event);
-  } catch (error) {
-    console.error('Error handling cache event:', error);
-    // Don't let errors break other listeners
-  }
-});
-```
-
-## Event Sources
-
-Events include a `source` field indicating where they originated:
-
-- **`api`** - Event from API operation (create, update, remove, etc.)
-- **`cache`** - Event from direct cache operation (set, invalidate)
-- **`operation`** - Event from internal cache operation
-
-## Performance Considerations
-
-- **Subscription count**: Each subscription has minimal overhead, but avoid creating unnecessary subscriptions
-- **Event frequency**: Use debouncing for high-frequency UI updates
-- **Memory leaks**: Always unsubscribe when components unmount
-- **Event filtering**: Use specific filters to reduce unnecessary event processing
-
-## Error Handling
-
-The event system is designed to be resilient:
-
-- Listener errors don't affect other listeners or cache operations
-- Failed subscriptions are automatically cleaned up
-- Event emission continues even if some listeners fail
-
-## Migration from Manual State Management
-
-If you're currently using manual state management patterns:
-
-```typescript
-// Before: Manual state management
-const [items, setItems] = useState([]);
-
-const addItem = async (item) => {
-  const newItem = await cache.operations.create(item);
-  setItems(prev => [...prev, newItem]);  // Manual update
-};
-
-// After: Event-driven updates
-const [items, setItems] = useState([]);
-
-useEffect(() => {
-  const subscription = cache.subscribe((event) => {
-    if (event.type === 'item_created') {
-      setItems(prev => [...prev, event.item]);
-    }
-  }, { eventTypes: ['item_created'] });
-
-  return () => subscription.unsubscribe();
-}, []);
-
-const addItem = async (item) => {
-  await cache.operations.create(item);  // Event automatically updates state
-};
-```
-
-This approach eliminates the need for manual state synchronization and ensures your UI always reflects the current cache state.

package/CACHE_IMPLEMENTATIONS.md

@@ -1,315 +0,0 @@
-# Cache Implementations Guide
-
-The `@fjell/cache` package now provides multiple cache implementations to suit different environments and persistence requirements.
-
-## Available Implementations
-
-### 1. MemoryCacheMap (Default)
-**Location**: `src/memory/MemoryCacheMap.ts`
-**Use case**: Server-side or Node.js applications
-
-```typescript
-import { MemoryCacheMap } from '@fjell/cache';
-
-const cache = new MemoryCacheMap<YourItem, 'item-type'>(keyTypeArray);
-```
-
-**Characteristics:**
-- Fast, in-memory storage
-- Data lost when application restarts
-- No persistence across sessions
-- Thread-safe for single process
-- Best performance for frequent read/write operations
-
-### 2. LocalStorageCacheMap
-**Location**: `src/browser/LocalStorageCacheMap.ts`
-**Use case**: Browser applications requiring persistent storage
-
-```typescript
-import { LocalStorageCacheMap } from '@fjell/cache';
-
-const cache = new LocalStorageCacheMap<YourItem, 'item-type'>(
-  keyTypeArray,
-  'my-app-cache' // optional prefix
-);
-```
-
-**Characteristics:**
-- ~5-10MB storage limit
-- Data persists across browser sessions and restarts
-- Synchronous operations
-- Shared across all tabs for the same origin
-- Stores data as JSON strings
-
-### 3. SessionStorageCacheMap
-**Location**: `src/browser/SessionStorageCacheMap.ts`
-**Use case**: Browser applications requiring tab-scoped temporary storage
-
-```typescript
-import { SessionStorageCacheMap } from '@fjell/cache';
-
-const cache = new SessionStorageCacheMap<YourItem, 'item-type'>(
-  keyTypeArray,
-  'my-session-cache' // optional prefix
-);
-```
-
-**Characteristics:**
-- ~5MB storage limit
-- Data lost when browser tab is closed
-- Synchronous operations
-- Tab-specific storage (not shared between tabs)
-- Stores data as JSON strings
-
-### 4. AsyncIndexDBCacheMap
-**Location**: `src/browser/AsyncIndexDBCacheMap.ts`
-**Use case**: Browser applications requiring large, structured data storage
-
-```typescript
-import { AsyncIndexDBCacheMap } from '@fjell/cache';
-
-const cache = new AsyncIndexDBCacheMap<YourItem, 'item-type'>(
-  keyTypeArray,
-  'my-database',    // database name
-  'cache-store',    // object store name
-  1                 // version
-);
-
-// All operations are async
-const item = await cache.get(key);
-await cache.set(key, value);
-const items = await cache.allIn(locations);
-```
-
-**Characteristics:**
-- Hundreds of MB+ storage capacity
-- Asynchronous operations (returns Promises)
-- Long-term persistence
-- Can store complex objects natively
-- Better performance for large datasets
-- Supports transactions and indexing
-
-### 5. IndexDBCacheMap (Synchronous Wrapper)
-**Location**: `src/browser/IndexDBCacheMap.ts`
-**Use case**: Browser applications needing synchronous API with IndexedDB persistence
-
-```typescript
-import { IndexDBCacheMap } from '@fjell/cache';
-
-const cache = new IndexDBCacheMap<YourItem, 'item-type'>(
-  keyTypeArray,
-  'my-database',    // database name
-  'cache-store',    // object store name
-  1                 // version
-);
-
-// Synchronous operations work immediately
-cache.set(key, value);          // Sets in memory cache immediately
-const item = cache.get(key);    // Gets from memory cache immediately
-const items = cache.allIn(locations);
-
-// Background sync to IndexedDB happens automatically
-// For explicit async operations, use:
-await cache.asyncCache.set(key, value);
-const item = await cache.asyncCache.get(key);
-```
-
-**Characteristics:**
-- Synchronous API compatible with other CacheMap implementations
-- Memory cache for immediate operations
-- Background IndexedDB sync for persistence
-- Higher memory usage (dual storage)
-- Best for apps migrating from synchronous cache implementations
-- Provides access to async cache via `asyncCache` property
-
-**When to use IndexDBCacheMap vs AsyncIndexDBCacheMap:**
-- **IndexDBCacheMap**: When you need synchronous compatibility or are migrating from MemoryCacheMap
-- **AsyncIndexDBCacheMap**: When you can work with async/await and want direct IndexedDB control
-
-## Migration Guide
-
-### From Old CacheMap
-If you were previously using `CacheMap` directly:
-
-```typescript
-// OLD
-import { CacheMap } from '@fjell/cache';
-const cache = new CacheMap(keyTypeArray);
-
-// NEW
-import { MemoryCacheMap } from '@fjell/cache';
-const cache = new MemoryCacheMap(keyTypeArray);
-```
-
-### Choosing the Right Implementation
-
-**For Node.js/Server applications:**
-- Use `MemoryCacheMap`
-
-**For Browser applications:**
-- **Small data, session-only**: `SessionStorageCacheMap`
-- **Small data, persistent**: `LocalStorageCacheMap`
-- **Large data, complex queries**: `AsyncIndexDBCacheMap`
-
-## Cache Information and Capabilities
-
-All cache instances expose metadata about their configuration and capabilities through the `getCacheInfo()` method at the Cache level. This provides client applications with visibility into the cache's behavior and limitations.
-
-### CacheInfo Interface
-
-```typescript
-interface CacheInfo {
-  /** The implementation type in format "<category>/<implementation>" */
-  implementationType: string;
-  /** The eviction policy being used (if any) */
-  evictionPolicy?: string;
-  /** Default TTL in milliseconds (if configured) */
-  defaultTTL?: number;
-  /** Whether TTL is supported by this implementation */
-  supportsTTL: boolean;
-  /** Whether eviction is supported by this implementation */
-  supportsEviction: boolean;
-}
-```
-
-### Getting Cache Information
-
-```typescript
-import { MemoryCacheMap, EnhancedMemoryCacheMap } from '@fjell/cache';
-
-// Create cache instance
-const cache = createCache(api, createCoordinate('item'), registry);
-const cacheInfo = cache.getCacheInfo();
-console.log(cacheInfo);
-// Output: {
-//   implementationType: "memory/memory",
-//   supportsTTL: true,
-//   supportsEviction: false
-// }
-
-// Enhanced memory cache with eviction
-const enhancedCache = createCache(api, createCoordinate('item'), registry, {
-  cacheType: 'memory',
-  memoryConfig: {
-    size: {
-      maxItems: 1000,
-      evictionPolicy: 'lru'
-    }
-  }
-});
-const enhancedInfo = enhancedCache.getCacheInfo();
-console.log(enhancedInfo);
-// Output: {
-//   implementationType: "memory/enhanced",
-//   evictionPolicy: "lru",
-//   supportsTTL: true,
-//   supportsEviction: true
-// }
-```
-
-### Implementation Types
-
-Each cache implementation has a unique type identifier:
-
-- `memory/memory` - Basic MemoryCacheMap
-- `memory/enhanced` - EnhancedMemoryCacheMap with eviction support
-- `browser/localStorage` - LocalStorageCacheMap
-- `browser/sessionStorage` - SessionStorageCacheMap
-- `browser/indexedDB` - IndexDBCacheMap
-
-### Capability Detection
-
-Use the capability flags to adapt your application behavior:
-
-```typescript
-function configureCache<V extends Item<S>, S extends string>(
-  cache: Cache<V, S>
-) {
-  const info = cache.getCacheInfo();
-
-  // Adjust TTL strategy based on support
-  if (info.supportsTTL) {
-    console.log(`TTL operations supported for ${info.implementationType}`);
-  }
-
-  // Show eviction policy if supported
-  if (info.supportsEviction && info.evictionPolicy) {
-    console.log(`Using ${info.evictionPolicy} eviction policy`);
-  }
-
-  // Log implementation details
-  console.log(`Cache implementation: ${info.implementationType}`);
-}
-```
-
-### Display Information for Debugging
-
-The cache info is particularly useful for debugging and monitoring:
-
-```typescript
-function debugCacheStatus<V extends Item<S>, S extends string>(
-  cacheName: string,
-  cache: Cache<V, S>
-) {
-  const info = cache.getCacheInfo();
-
-  console.log(`[${cacheName}] Cache Configuration:`);
-  console.log(`  Type: ${info.implementationType}`);
-  console.log(`  TTL Support: ${info.supportsTTL ? 'Yes' : 'No'}`);
-  console.log(`  Eviction Support: ${info.supportsEviction ? 'Yes' : 'No'}`);
-
-  if (info.evictionPolicy) {
-    console.log(`  Eviction Policy: ${info.evictionPolicy}`);
-  }
-
-  if (info.defaultTTL) {
-    console.log(`  Default TTL: ${info.defaultTTL}ms`);
-  }
-}
-```
-
-## Common Patterns
-
-### Factory Pattern
-```typescript
-import { CacheMap, MemoryCacheMap, LocalStorageCacheMap } from '@fjell/cache';
-
-function createCacheMap<V extends Item<S>, S extends string>(
-  keyTypeArray: AllItemTypeArrays<S>,
-  environment: 'node' | 'browser-persistent' | 'browser-session' = 'node'
-): CacheMap<V, S> {
-  switch (environment) {
-    case 'node':
-      return new MemoryCacheMap<V, S>(keyTypeArray);
-    case 'browser-persistent':
-      return new LocalStorageCacheMap<V, S>(keyTypeArray);
-    case 'browser-session':
-      return new SessionStorageCacheMap<V, S>(keyTypeArray);
-    default:
-      return new MemoryCacheMap<V, S>(keyTypeArray);
-  }
-}
-```
-
-### Error Handling for Storage
-```typescript
-try {
-  await cache.set(key, value);
-} catch (error) {
-  if (error.message.includes('quota')) {
-    // Handle storage quota exceeded
-    cache.clear(); // Clear old data
-    await cache.set(key, value); // Retry
-  }
-  throw error;
-}
-```
-
-## Key Normalization
-
-All implementations use the same key normalization logic:
-- String and number primary/location keys are normalized to strings
-- Ensures consistent behavior across different implementations
-- Prevents issues with mixed key types (e.g., '123' vs 123)
-
-This refactoring maintains full backward compatibility while providing flexible storage options for different environments and use cases.