SplatDev.Cache 1.0.3

SplatDev.Cache

Generic caching abstractions for SplatDev packages — provider-agnostic interfaces for Redis, HybridCache, MemoryCache, and other backends.

Compatibility

Installation

dotnet add package SplatDev.Cache

This package has zero external dependencies — it defines only abstractions.

Interfaces

ICacheProvider

The core abstraction for pluggable cache backends:

public interface ICacheProvider
{
    T? Get<T>(string key);
    Task<T?> GetAsync<T>(string key, CancellationToken cancellationToken = default);

    void Set<T>(string key, T value, CacheEntryOptions? options = null);
    Task SetAsync<T>(string key, T value, CacheEntryOptions? options = null, CancellationToken cancellationToken = default);

    T? GetOrCreate<T>(string key, Func<T> factory, CacheEntryOptions? options = null);
    Task<T?> GetOrCreateAsync<T>(string key, Func<CancellationToken, Task<T>> factory,
        CacheEntryOptions? options = null, CancellationToken cancellationToken = default);

    void Remove(string key);
    Task RemoveAsync(string key, CancellationToken cancellationToken = default);

    Task<bool> ExistsAsync(string key, CancellationToken cancellationToken = default);
    Task<bool> RemoveByPatternAsync(string pattern, CancellationToken cancellationToken = default);
    Task<bool> RemoveByTagAsync(string tag, CancellationToken cancellationToken = default);
}

RemoveByPatternAsync and RemoveByTagAsync are optional — adapters that cannot support these operations may throw NotSupportedException.

ICacheKeyBuilder

Canonical key composition for cache entries:

public interface ICacheKeyBuilder
{
    string Build(params string[] segments);
    string BuildPattern(params string[] segments);
}

Default key format: {KeyPrefix}:segment1:segment2:...

IDistributedLock

Distributed lock abstraction for coordinated cache operations:

public interface IDistributedLock
{
    Task<LockResult> AcquireAsync(
        string resource,
        TimeSpan timeout,
        TimeSpan? autoRelease = null,
        CancellationToken cancellationToken = default);
}

ICacheSerializer

Pluggable serialization for cache values:

public interface ICacheSerializer
{
    byte[]? Serialize<T>(T? value);
    T? Deserialize<T>(byte[]? data);
}

Models

CacheOptions

public class CacheOptions
{
    public string KeyPrefix { get; set; } = "";
    public TimeSpan DefaultTtl { get; set; } = TimeSpan.FromMinutes(30);
    public string KeySeparator { get; set; } = ":";
}

Bound from IConfiguration section "SplatDev:Cache".

CacheEntryOptions

public class CacheEntryOptions
{
    public TimeSpan? AbsoluteExpiration { get; set; }
    public TimeSpan? SlidingExpiration { get; set; }

    public static CacheEntryOptions WithAbsoluteExpiration(TimeSpan duration);
    public static CacheEntryOptions WithSlidingExpiration(TimeSpan duration);
}

CacheEntry<T>

public record CacheEntry<T>(string Key, T Value, DateTimeOffset? ExpiresAt = null);

LockResult

public sealed class LockResult
{
    public bool Acquired { get; init; }
    public string Resource { get; init; }
    public IDisposable? Handle { get; init; }
}

Helpers

CacheKeyBuilder

Default implementation of ICacheKeyBuilder. Composes keys in "splatdev:<app>:<domain>:<id>" format using the configured KeyPrefix and KeySeparator.

PatternMatcher

Glob-to-regex utility for cache key pattern matching:

public static class PatternMatcher
{
    public static Regex GlobToRegex(string pattern, bool caseInsensitive = true);
    public static bool IsMatch(string input, string pattern, bool caseInsensitive = true);
}

SystemTextJsonCacheSerializer

Default implementation of ICacheSerializer using System.Text.Json with camelCase naming policy.

CacheStampedeGuard

Per-key SemaphoreSlim stampede protection for GetOrCreateAsync patterns. Registered as a singleton via the DI extension.

public sealed class CacheStampedeGuard
{
    public Task<T?> GetOrCreateWithStampedeProtectionAsync<T>(
        string key,
        Func<CancellationToken, Task<T>> factory,
        Func<string, CancellationToken, Task<T?>> getAsync,
        Func<string, T, CacheEntryOptions?, CancellationToken, Task> setAsync,
        CacheEntryOptions? options = null,
        CancellationToken cancellationToken = default);
}

Dependency Injection

Register all abstractions in one call:

services.AddSplatDevCacheAbstractions(configuration);

This binds CacheOptions from "SplatDev:Cache" config section and registers:

• CacheOptions (singleton)
• ICacheKeyBuilder → CacheKeyBuilder (singleton)
• ICacheSerializer → SystemTextJsonCacheSerializer (singleton)
• CacheStampedeGuard (singleton)

Note: ICacheProvider is NOT registered — you must add a provider package (e.g. SplatDev.Cache.Redis or SplatDev.Cache.Hybrid).

Configuration

{
  "SplatDev": {
    "Cache": {
      "KeyPrefix": "myapp",
      "DefaultTtl": "00:10:00",
      "KeySeparator": ":"
    }
  }
}

Available provider implementations

Design decisions

• Stampede protection: Built into the foundation layer via per-key SemaphoreSlim (CacheStampedeGuard). Provider adapters may override with distributed locking.
• Tag-based invalidation: First-class in ICacheProvider. Adapters that cannot support it throw NotSupportedException.
• Serializer scope: Global default (ICacheSerializer) with per-call override support.
• Cancellation semantics: Cancellation token cancels the running factory in GetOrCreateAsync.

Dependencies

None. This package has zero NuGet dependencies — it is pure interface and model definitions.

SplatDev.Cache — part of the SplatDev.Umbraco.Plugins suite. Licensed under MIT. © SplatDev Ltda.

Changelog

1.0.3 — 2026-08-24

Removes a dashboard screenshot that showed an error toast. It was captured against a site where this plugin's API was unreachable, so it advertised a broken dashboard. No screenshot is better than a misleading one; a replacement will be taken against a working install.

1.0.2 — 2026-08-24

Package metadata only: the listing now carries an icon and search tags, and the project and repository links point at the organisation that actually hosts this code. No code changes.

1.0.1 — 2026-08-24

This package now keeps a changelog. Earlier releases predate it and are not reconstructed here — consult the repository history for those. From this version on, every release records what changed for someone using it.