cache library

🗄️ JetLeaf Caching Library

This library provides a comprehensive caching system for JetLeaf applications, including annotations, storage, eviction policies, operations, metrics, and error handling.

It supports declarative caching with method interceptors, programmatic cache management, and extensible backends.

🔑 Key Concepts

• Cache Operations: define actions like put, evict, expire, and cacheable.
• Cache Storage: backends for storing cached data (in-memory, configurable stores, etc.).
• Eviction Policies: LRU, LFU, FIFO strategies for automatic cache pruning.
• Error Handling: robust handling of cache errors with pluggable handlers.
• Events & Metrics: observe cache activity and gather statistics.

📦 Exports Overview

⚙ Core

• CacheAnnotationMethodInterceptor — intercepts annotated methods for caching
• CacheComponentRegistrar — registers cache components
• CacheOperationContext / DefaultCacheOperationContext — runtime operation metadata

⚠ Error Handlers

• CacheErrorHandler — base interface
• CacheErrorHandlerRegistry — manages multiple handlers
• LoggableCacheErrorHandler — logs errors instead of throwing
• ThrowableCacheErrorHandler — propagates exceptions

🏷 Events

• CacheEvent — base class
• CacheHitEvent, CacheMissEvent, CachePutEvent, CacheEvictEvent, CacheExpireEvent, CacheClearEvent
  Allows observing cache lifecycle activities.

🗑 Eviction Policies

• CacheEvictionPolicy — base interface
• FifoEvictionPolicy, LfuEvictionPolicy, LruEvictionPolicy

🏗 Managers

• CacheManager — primary cache orchestrator
• CacheManagerRegistry — registry for multiple managers
• SimpleCacheManager — default implementation

📊 Metrics

• CacheMetrics — metrics collection interface
• SimpleCacheMetrics — basic implementation for monitoring

💾 Cache Operations

• CacheOperation — base interface for all operations
• CachePutOperation, CacheEvictOperation, CacheableOperation

🔍 Resolver

• CacheResolver — resolves cache targets dynamically
• CacheResolverRegistry — manages multiple resolvers
• SimpleCacheResolver — default implementation

🗄 Storage

• CacheStorage — interface for cache stores
• CacheStorageRegistry — manage multiple stores
• Cache / DefaultCache — standard cache abstraction
• ConfigurableCacheStorage — customizable backends
• CacheResource — resource abstraction
• DefaultCacheStorage — default in-memory storage

📝 Annotations & Config

• annotations.dart — declarative caching via method-level annotations
• CacheConfigurer — programmatic configuration of caches

🎯 Intended Usage

Import this library to enable full caching capabilities in JetLeaf:

import 'package:jetleaf_resource/cache.dart';

@Cacheable('myCache')
String fetchData(String key) {
  return computeData(key);
}

Supports pluggable storage, metrics, events, and error handling.

© 2025 Hapnium & JetLeaf Contributors