Module data_cache 

High-performance data caching layer for Prax ORM.

This module provides a flexible, standalone caching system for query results with support for:

• In-memory caching using moka for high-performance concurrent access
• Tiered caching layering any two CacheBackend implementations (e.g. memory L1 over a slower L2)
• Automatic invalidation based on TTL, entity changes, or custom patterns
• Cache-aside usage through the standalone CacheManager API

Not yet available:

• Transparent query integration — there is no .cache(...) method on query operations; wrap queries manually with CacheManager as shown below.
• The Redis backend (RedisCache) — construction and every operation return an error because no Redis client is compiled in.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Application                               │
│         (standalone CacheManager; no query integration yet)      │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Cache Manager                               │
│  ┌─────────────┐    ┌──────────────────┐    ┌─────────────────┐ │
│  │ L1: Memory  │ -> │ L2: CacheBackend │ -> │   Database      │ │
│  │ (< 1ms)     │    │ (e.g. NoopCache) │    │   (10-100ms)    │ │
│  └─────────────┘    └──────────────────┘    └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Quick Start

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

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

// Standalone cache-aside usage around your own data access
let key = CacheKey::new("User", "find_many:all");
let users: Vec<User> = cache
    .get_or_set(
        &key,
        || async { Ok(load_all_users().await) },
        None,
    )
    .await?;

Cache Invalidation

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

// 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(&KeyPattern::entity("User")).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
Tiered	< 1ms (L1 hit)	Both layers	Depends on L2	Layered setups

A Redis backend for distributed, multi-instance caching is planned but not yet implemented.

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.