Baubit.Caching.LiteDB 2026.2.2-prerelease

Baubit.Caching.LiteDB

<br/> <br/> <br/>

DI Extension: Baubit.Caching.LiteDB.DI
Distributed cache samples: Samples

LiteDB-backed L2 store implementation for Baubit.Caching with support for custom ID types.

Installation

dotnet add package Baubit.Caching.LiteDB

Features

• Generic ID Support: Use long, int, Guid, or any value type implementing IComparable<TId> and IEquatable<TId>
• Performance Optimized: Numeric IDs (long/int) deliver better performance than Guid - less memory, better cache locality
• Persistent Storage: File-based LiteDB storage for durable caching
• Automatic ID Generation: Built-in GuidV7 generation for StoreGuid<TValue> (backward compatible)
• Resumable Enumeration: Resume async enumeration sessions across application restarts with configurable persistence
• Thread-Safe: All public APIs are thread-safe
• Capacity Management: Support for bounded and unbounded stores

Backward Compatibility

The StoreGuid<TValue>, StoreLong<TValue>, and StoreInt<TValue> classes were added to maintain backward compatibility with code written against Baubit.Caching v2025.52+. These classes provide concrete implementations that handle ID generation internally, simplifying usage for common scenarios while the abstract Store<TId, TValue> base class enables custom ID type implementations.

Performance

Benchmarks show numeric IDs (long, int) deliver better performance than Guid:

Long IDs are faster due to:

• Smaller key size (8 bytes vs 16) improves cache locality and reduces index overhead
• Faster comparisons and hashing for numeric keys
• Especially noticeable on write-heavy and mixed workloads

Run benchmarks locally:

dotnet run -c Release --project Baubit.Caching.LiteDB.Benchmark

See Baubit.Caching.LiteDB.Benchmark/Results.md for detailed benchmarks.

Usage

Store with Custom ID Types

using Baubit.Caching.LiteDB;
using Microsoft.Extensions.Logging;

// Store with long IDs - recommended for best performance
var storeLong = new StoreLong<string>(
    "cache.db",
    "myCollection",
    loggerFactory);

storeLong.Add(1L, "value", out var entry);
storeLong.GetValueOrDefault(1L, out var value);

// Store with int IDs
var storeInt = new StoreInt<string>(
    "cache.db",
    "intCollection",
    loggerFactory);

storeInt.Add(42, "value", out var entry);

// Store with Guid IDs - uses automatic GuidV7 generation
var storeGuid = new StoreGuid<string>(
    "cache.db",
    "guidCollection",
    loggerFactory);

// Auto-generated ID
storeGuid.Add("value", out var entry1);

// Or provide explicit Guid
storeGuid.Add(Guid.NewGuid(), "value", out var entry2);

Resumable Enumeration

Enumeration sessions can be persisted to LiteDB and resumed after application restarts:

using Baubit.Caching.LiteDB;
using LiteDB;
using Microsoft.Extensions.Logging;

// Create database shared between store and enumerator factory
using var database = new LiteDatabase("cache.db");
var store = new StoreGuid<string>(database, "myCollection", loggerFactory);

// Configure resumable enumeration
var config = new Baubit.Caching.LiteDB.Configuration
{
    ResumeSession = true,
    PersistPositionEveryXMoves = 10,  // Persist every 10 moves (0 = disabled)
    PersistPositionBeforeMove = true  // Persist before move (crash recovery)
};

var factory = new CacheAsyncEnumeratorFactory<Guid, string>(database, config);
var cache = new OrderedCache<Guid, string>(store, factory, loggerFactory);

// First enumeration session
var enumerator = factory.CreateEnumerator(cache, _ => {}, "my-session", CancellationToken.None);
await enumerator.MoveNextAsync();  // First entry
await enumerator.MoveNextAsync();  // Second entry
await enumerator.DisposeAsync();   // Position persisted

// Resume from saved position (even after application restart)
var enumerator2 = factory.CreateEnumerator(cache, _ => {}, "my-session", CancellationToken.None);
await enumerator2.MoveNextAsync();  // Continues from third entry

Configuration Options:

• ResumeSession - Enable/disable session resumption (default: false)
• PersistPositionEveryXMoves - Persist every X moves, 0 to disable (default: 0)
• PersistPositionBeforeMove - Persist before move for crash recovery, false for after move (default: true)

Creating the Store

using Baubit.Caching.LiteDB;
using Microsoft.Extensions.Logging;

// Uncapped store with automatic Guid generation
var store = new StoreGuid<string>(
    "cache.db",
    "myCollection",
    loggerFactory);

// Capped store
var cappedStore = new StoreGuid<string>(
    "cache.db",
    "myCollection",
    minCap: 100,
    maxCap: 1000,
    loggerFactory);

// Store with custom ID type - long
var longStore = new StoreLong<string>(
    "cache.db",
    "longCollection",
    loggerFactory);

// Use with existing LiteDatabase instance
using var db = new LiteDatabase("cache.db");
var sharedStore = new StoreGuid<string>(db, "myCollection", loggerFactory);

Basic Store Operations

// Store with long IDs - explicit ID required
var storeLong = new StoreLong<string>("cache.db", "col", loggerFactory);
storeLong.Add(1L, "value", out var entry);
storeLong.GetValueOrDefault(1L, out var value);
storeLong.Update(1L, "new value");
storeLong.Remove(1L, out var removed);
storeLong.GetCount(out var count);

// Store with Guid IDs - auto-generates IDs
var storeGuid = new StoreGuid<string>("cache.db", "guidCol", loggerFactory);
storeGuid.Add("value", out var entryGuid);  // ID auto-generated
storeGuid.GetCount(out var countGuid);

License

MIT