Cache Helpers

IRENCacheService is a lightweight, extensible caching abstraction designed to provide consistent, predictable behavior across multiple cache providers (Redis and in-memory), while remaining explicit about responsibilities and boundaries.

The primary goal of this cache service is control and transparency — not hidden magic.

• Serialization is never enforced

• Storage and format concerns are explicitly separated

• Advanced capabilities are opt-in, not implicit

• Provider-specific features are clearly scoped

This design allows consumers to choose the right balance between simplicity, performance, and flexibility, depending on their use case and environment.

---

Core Design Principles

Provider-Agnostic Contract

The same API behaves identically for Redis and in-memory implementations wherever technically possible. Consumers do not need to change application code when switching providers.

Explicit Serialization

Typed caching uses JSON (System.Text.Json) for convenience, not as a requirement. Raw binary APIs allow external serializers such as MessagePack, Protobuf, compression, or encryption without coupling the cache layer to any format.

No Hidden Format Assumptions

Binary cache operations treat data as opaque payloads. The cache never interprets, modifies, wraps, or inspects raw binary data.

Predictable Expiration Semantics

• Absolute expiration is always enforced

• Sliding expiration is applied only when the cache format explicitly supports it

• No implicit TTL extension or background mutation occurs

Production-First Design

The API favors clarity, debuggability, and observability over convenience abstractions. All cache behavior is explicit and traceable, making production issues easier to diagnose.

---

When to Use This Cache Service

Use IRENCacheService when:

• You want the same cache code to run in local, test, and production environments

• You need high-performance caching without binding your domain to a specific serializer

• You prefer explicit control over cache keys, formats, TTLs, and eviction behavior

• You want to gradually migrate formats (e.g. JSON → MessagePack) without breaking consumers

• You need bulk operations and atomic counters for production workloads

---

What You Can Do with IRENCacheService

IRENCacheService provides a unified, provider-agnostic caching API that works consistently across in-memory and Redis implementations.

It supports:

• Typed object caching

• String-based access

• Raw binary payloads

• Bulk operations

• Atomic counters

• Redis hash-based structured caching

All while keeping serialization concerns optional and external.

---

1. Typed Object Caching (JSON-Based)

You can store and retrieve strongly-typed objects using generic methods. Serialization is handled internally using System.Text.Json.

cache.Set("stock:detail:AKBNK", dto, TimeSpan.FromMinutes(10));

var dto = cache.Get<StockDetailDto>("stock:detail:AKBNK");

Characteristics

• Strongly-typed access (Get<T>, Set<T>)

• Optional absolute and sliding expiration

• Safe deserialization (returns null on mismatch or failure)

• Identical behavior across Redis and in-memory providers

---

2. String Value Access

For debugging, interoperability, or legacy scenarios, you can access raw string values.

var value = cache.Get("some:key");

Useful When

• Inspecting cache entries manually

• Sharing keys with non-typed consumers

• Migrating legacy or external cache data

---

3. Raw Binary Cache Operations (Format-Agnostic)

For advanced or performance-critical scenarios, the cache supports raw binary payloads using byte[].

This enables external serializers such as MessagePack, Protobuf, compression, or encryption — without introducing dependencies into the cache library.

var bytes = MessagePackSerializer.Serialize(dto);

await cache.SetBytesAsync("stock:detail:AKBNK:bin", bytes);

var cachedBytes = await cache.GetBytesAsync("stock:detail:AKBNK:bin");
var dto = MessagePackSerializer.Deserialize<StockDetailDto>(cachedBytes);

Characteristics

• Format-agnostic (byte[] only)

• No internal serialization or envelopes

• Absolute expiration supported

• Ideal for high-throughput or low-allocation workloads

---

4. Bulk Binary Operations

For high-volume workloads, multiple binary entries can be retrieved or stored efficiently.

await cache.SetBytesManyAsync(items, TimeSpan.FromMinutes(5));

var values = await cache.GetBytesManyAsync(keys);

Benefits

• Reduced network round-trips (Redis)

• Consistent semantics across providers

• Missing keys are returned as null values

---

5. Get-Or-Create Pattern

You can atomically retrieve or populate a cache entry using a factory function.

var value = await cache.GetOrCreateAsync(
    "settings:global",
    ct => LoadFromDatabaseAsync(ct),
    TimeSpan.FromMinutes(30)
);

If the factory returns null, nothing is cached.

---

6. Atomic Counters

The cache provides atomic increment operations suitable for counters, rate-limiting, or metrics.

var count = await cache.IncrementAsync("api:requests", 1, TimeSpan.FromMinutes(1));

Notes

• Atomic in Redis (INCRBY)

• Best-effort atomicity in in-memory provider

• Optional TTL support

---

7. Redis Hash Operations (Structured Caching)

Redis hash structures allow grouping related values under a single key.

await cache.HashSetAsync("prices", "AKBNK", priceDto);

var price = await cache.HashGetAsync<PriceDto>("prices", "AKBNK");

Use Cases

• Symbol-based lookups

• Dictionary-style access patterns

• Reducing total key count in Redis

Important Notes

• Expiration applies to the hash key, not individual fields

• Hash operations are Redis-only

• In-memory provider explicitly does not support hashes

---

8. Raw Binary Hash Operations

Hash fields can also store raw binary payloads for high-performance grouped caching.

await cache.HashSetBytesAsync("prices:bin", "AKBNK", bytes);

var bytes = await cache.HashGetBytesAsync("prices:bin", "AKBNK");

Ideal For

• Large or frequently updated datasets

• MessagePack or other binary formats

• Avoiding repeated JSON serialization overhead

---

9. Cache Existence, Refresh, and Removal

You can explicitly manage cache lifecycle and eviction.

await cache.ExistsAsync("some:key");
await cache.RefreshAsync("some:key", TimeSpan.FromMinutes(10));
await cache.RemoveManyAsync(keys);

Clearing the Cache

await cache.ClearAsync();

⚠️ Warning In Redis, Clear() flushes the entire selected database. Use with extreme caution.

---

Design Philosophy Summary

• Serialization is optional and external

• Binary payloads are opaque

• Same contract, multiple providers

• Bulk and atomic operations for production workloads

• Performance without coupling

• Explicit behavior over implicit magic