Module strategy 

Cache strategies and decision logic for fetch operations.

This module defines the different strategies for accessing cached data and provides contextual information about cache operations.

Overview

Cache-kit uses an enum-based strategy pattern to replace ad-hoc boolean flags. This makes cache behavior explicit and type-safe.

The Four Strategies

Every cache operation uses one of four strategies:

use cache_kit::strategy::CacheStrategy;

// 1. Fresh - Use cache only
let _s = CacheStrategy::Fresh;

// 2. Refresh - Cache-first with DB fallback (default)
let _s = CacheStrategy::Refresh;

// 3. Invalidate - Clear cache, always fetch fresh
let _s = CacheStrategy::Invalidate;

// 4. Bypass - Skip cache entirely
let _s = CacheStrategy::Bypass;

Decision Tree

Do you have data in cache?
    ├─ YES, and you trust it
    │  └─ Use: Fresh or Refresh
    │
    ├─ NO, or it's possibly stale
    │  └─ Use: Invalidate or Refresh
    │
    └─ You don't want caching now
       └─ Use: Bypass

When to Use Each Strategy

Strategy	Cache Hit	Cache Miss	Use Case
Fresh	Return	Return None	Assume data cached; miss is error
Refresh	Return	DB fallback	Default; prefer cache, ensure availability
Invalidate	Delete	Fetch DB	After mutations; need fresh data
Bypass	Ignore	DB always	Testing or temporary disable

Examples by Scenario

These examples show typical usage patterns for different strategies. See the module tests for complete runnable examples.

Trade-offs

• Refresh (default): Best for most cases. Balances performance and consistency.
• Fresh: Fastest if hit, but fails on cache miss.
• Invalidate: Ensures freshness but increases DB load after mutations.
• Bypass: Simplest for testing, but defeats caching benefits.

Structs

CacheContext

Context information for cache operations.

Enums

CacheStrategy

Strategy enum controlling cache fetch/invalidation behavior.