Module data_cache 

High-performance data caching layer for Prax ORM.

This module provides a flexible, multi-tier caching system for query results with support for:

• In-memory caching using moka for high-performance concurrent access
• Redis caching for distributed cache across multiple instances
• Tiered caching combining L1 (memory) and L2 (Redis) for optimal performance
• Automatic invalidation based on TTL, entity changes, or custom patterns
• Cache-aside pattern with transparent integration into queries

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Application                               │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Prax Query Builder                          │
│                  .cache(CacheOptions::new())                    │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Cache Manager                               │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐ │
│  │ L1: Memory  │ -> │ L2: Redis   │ -> │   Database          │ │
│  │ (< 1ms)     │    │ (1-5ms)     │    │   (10-100ms)        │ │
│  └─────────────┘    └─────────────┘    └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Quick Start

use prax_query::data_cache::{CacheManager, MemoryCache, RedisCache, TieredCache};
use std::time::Duration;

// In-memory only (single instance)
let cache = MemoryCache::builder()
    .max_capacity(10_000)
    .time_to_live(Duration::from_secs(300))
    .build();

// Redis only (distributed)
let redis = RedisCache::new("redis://localhost:6379").await?;

// Tiered: Memory (L1) + Redis (L2)
let tiered = TieredCache::new(cache, redis);

// Use with queries
let users = client
    .user()
    .find_many()
    .cache(CacheOptions::ttl(Duration::from_secs(60)))
    .exec()
    .await?;

Cache Invalidation

use prax_query::data_cache::{InvalidationStrategy, EntityTag};

// Invalidate by entity type
cache.invalidate_entity("User").await?;

// Invalidate by specific record
cache.invalidate_record("User", &user_id).await?;

// Invalidate by pattern
cache.invalidate_pattern("user:*:profile").await?;

// Tag-based invalidation
cache.invalidate_tags(&[EntityTag::new("User"), EntityTag::new("tenant:123")]).await?;

Performance Characteristics

Backend	Latency	Capacity	Distribution	Best For
Memory	< 1ms	Limited by RAM	Single instance	Hot data, sessions
Redis	1-5ms	Large	Multi-instance	Shared state, large datasets
Tiered	< 1ms (L1 hit)	Both	Multi-instance	Production systems

Structs

CacheEntry

A cached entry with metadata.

CacheKey

A cache key that uniquely identifies a cached value.

CacheKeyBuilder

A builder for constructing complex cache keys.

CacheManager

The main cache manager that coordinates caching operations.

CacheManagerBuilder

Builder for creating cache managers with different configurations.

CacheMetrics

Thread-safe cache metrics collector.

CacheOptions

Options for caching a query result.

CacheStats

A snapshot of cache statistics.

EntityTag

A tag for categorizing and invalidating cache entries.

InvalidationEvent

An event that triggers cache invalidation.

KeyPattern

A pattern for matching cache keys.

MemoryCache

High-performance in-memory cache.

MemoryCacheBuilder

Builder for MemoryCache.

MemoryCacheConfig

Configuration for the in-memory cache.

RedisCache

Redis cache backend.

RedisCacheConfig

Configuration for Redis cache.

RedisConnection

Represents a Redis connection (placeholder for actual implementation).

TieredCache

A tiered cache with L1 (local) and L2 (distributed) layers.

TieredCacheConfig

Configuration for tiered cache.

Enums

CacheError

Errors that can occur during cache operations.

CachePolicy

Cache lookup/write policy.

InvalidationStrategy

Strategy for cache invalidation.

WritePolicy

When to write to the cache.

Traits

CacheBackend

The core trait for cache backends.

Type Aliases

CacheResult

Result type for cache operations.