feat(storage-kit): implement LocalCache for in-memory caching

[husamettinarabaci]

Is your feature request related to a problem?

The LocalCache skeleton class exists in packages/storage_kit/lib/cache/local_cache.dart but needs full implementation to provide an in-memory cache with TTL (time-to-live), LRU eviction, and automatic cleanup for temporary data caching.

Describe the solution you'd like

Implement a fully functional LocalCache service that provides in-memory caching with configurable TTL, LRU (Least Recently Used) eviction policy, size limits, and automatic expired entry cleanup.

What is LocalCache and why do we need it?

LocalCache is an in-memory cache for temporary data storage with automatic expiration and eviction, improving performance by reducing network calls and database queries.

Why it's important:

• Performance: Fast in-memory access without disk I/O
• Network Reduction: Cache API responses to reduce calls
• Resource Efficient: Automatic cleanup prevents memory bloat
• Configurable: TTL and size limits customizable
• Simple API: Easy to use for common caching scenarios

Common use cases:

• API response caching
• Image metadata caching
• User profile caching
• Search results caching
• Frequently accessed data
• Session-temporary data

Required Deliverables

1. LocalCache implementation with:

   • Set cache entry with TTL
   • Get cache entry
   • Remove cache entry
   • Clear all cache
   • LRU eviction policy
   • Size limit enforcement
   • Automatic expired entry cleanup
   • Cache statistics (hits, misses)
   • Type-safe generic methods

2. Widgetbook stories (6-8 use cases):

   • Set cache entry
   • Get cached entry
   • TTL expiration demo
   • LRU eviction demo
   • Size limit enforcement
   • Cache statistics display
   • Clear cache demo
   • Cache inspector UI

3. SPDX headers in all source files

Key Implementation Specs

• set(key, value, {Duration? ttl})
• get(key) returns T?
• remove(key)
• clear()
• contains(key) returns bool
• LRU eviction when size limit reached
• Default max entries: 100
• Default TTL: 5 minutes
• Periodic cleanup of expired entries
• Cache statistics (hits, misses, evictions)
• Generic type support

Acceptance Criteria

• LocalCache class implemented
• set() stores entries with TTL
• get() retrieves cached entries
• remove() deletes entries
• clear() removes all entries
• contains() checks existence
• TTL expiration works
• LRU eviction when size limit reached
• Size limit configurable
• Automatic expired entry cleanup
• Cache statistics tracked
• Generic type support
• All 6-8 Widgetbook stories created and functional
• SPDX headers present in all files
• Code follows STYLE_GUIDE.md standards
• Unit tests cover caching logic

Related Files

• packages/storage_kit/lib/cache/local_cache.dart (skeleton)
• packages/storage_kit/lib/cache/cache_keys.dart (cache key constants)
• widgetbook_kit/lib/stories/storage_kit/local_cache_story.dart (Widgetbook)

---

Impact: Improves app performance; reduces network and database calls

Priority: Medium