Add cached sequence walker/reader implementation - Issue #96

[konard]

Summary

Implements Issue #96: Cached sequence walker or sequence reader or sequences index

This PR introduces a comprehensive caching system for sequence operations that provides significant performance improvements when reading data from Links storage. The implementation caches the relationship between arrays of subsequence elements and their addresses, allowing for much faster repeated sequence reads.

🚀 Key Features

• In-Memory Caching: Thread-safe concurrent cache with hit/miss statistics
• File-Based Persistence: Optional file cache with configurable expiration (default: 1 second)
• Automatic Invalidation: Cache automatically invalidates when underlying data is modified
• Easy Integration: Extension methods for seamless use with existing ILinks implementations
• Async Support: Both synchronous and asynchronous APIs available
• Performance Monitoring: Built-in cache statistics and hit ratio tracking

📦 New Components

SequenceCache<TLinkAddress>

• In-memory cache for sequence address-to-array mappings
• Thread-safe operations using ConcurrentDictionary
• Bidirectional lookup (address → sequence and sequence → address)
• Cache statistics tracking (hits, misses, hit ratio)

SequenceFileCache<TLinkAddress>

• File-based cache with JSON serialization
• Configurable expiration duration (default: 1 second)
• Automatic cleanup of expired files
• Asynchronous caching support

CachedSequenceWalker<TLinkAddress>

• Main decorator that combines both caching layers
• Inherits from LinksDisposableDecoratorBase following existing patterns
• Automatic cache invalidation on Update and Delete operations
• Fallback sequence walking when cache misses occur

CachedSequenceExtensions

• Extension methods for easy integration: WithSequenceCache(), GetCachedSequenceArray(), etc.
• Transparent usage - works with any ILinks implementation
• Supports both temporary and persistent cached walkers

💡 Usage Examples

// Basic usage with extension methods
using var links = new UnitedMemoryLinks<ulong>(memory);
var sequence = links.CreateSequence(element1, element2, element3);
var elements = links.GetCachedSequenceArray(sequence); // Uses temporary cache

// Advanced usage with persistent cache
using var cachedWalker = links.WithSequenceCache(
    enableFileCache: true,
    cacheDirectory: "/path/to/cache",
    fileCacheDuration: TimeSpan.FromSeconds(10)
);

var result1 = cachedWalker.GetSequenceArray(sequence); // Cache miss
var result2 = cachedWalker.GetSequenceArray(sequence); // Cache hit!

// Monitor performance
var (hits, misses, ratio) = cachedWalker.GetCacheStatistics();
Console.WriteLine($"Cache hit ratio: {ratio:P2}");

🎯 Performance Impact

The link is two subsequences, we can cache the relationship between each array of subsequence's elements and its address. So if need to convert the address to array of elements second time we can do it faster, because of cached arrays. This can have a significant impact on the speed of reading of data from Links storage.

• First read: Cache miss → walks sequence structure → populates cache
• Subsequent reads: Cache hit → immediate return of cached array
• Automatic invalidation: Ensures cache consistency when data changes
• File persistence: Cache survives between application restarts

✅ Testing

• Comprehensive test suite covering all components
• Memory cache operations (hit/miss scenarios)
• File cache operations (sync/async)
• Integration tests with actual Links storage
• Cache invalidation verification
• Extension methods testing

📋 Version Update

• Version bumped from 0.18.1 → 0.19.0 (minor version for new feature)
• Updated package release notes with feature description

🔄 Backwards Compatibility

• Fully backwards compatible - no breaking changes
• All new functionality is opt-in via extension methods or explicit usage
• Existing code continues to work unchanged

Test Plan

• Build succeeds without errors
• All new components compile correctly
• Memory cache basic operations work
• File cache operations work (sync and async)
• Cache invalidation works properly
• Extension methods provide easy access
• Integration with existing Links implementations
• Performance improvements verified through statistics
• Version and release notes updated

🤖 Generated with Claude Code

---

Resolves #96