Kanject.Core.CacheDb.Abstractions 3.9.0

Kanject.Core.CacheDb.Abstractions

Provider-agnostic contracts for a key/value cache store. The package defines the ICacheDb interface, the CacheDbModel<TPayload> storage envelope, trimming-safe serialization helpers, and the exception types that provider lock APIs throw. Your code depends only on ICacheDb. You pick the backing store (in-process memory, Amazon DynamoDB or Amazon S3 Express One Zone) by installing and registering a provider package.

Install it in libraries and services that use a cache without tying themselves to one store, or when you write your own provider.

Installation

dotnet add package Kanject.Core.CacheDb.Abstractions

Targets .NET 8, .NET 9 and .NET 10. It depends on Kanject.Core and Microsoft.Extensions.Caching.Abstractions. The package is marked trimming / Native AOT compatible. A few typed members use reflection; see Typed values for which ones.

Quick start

Register a provider in the composition root. For local development, use Kanject.Core.CacheDb.Provider.InMemory:

using Kanject.Core.CacheDb.Provider.InMemory.Extensions;

builder.Services.AddInMemoryCacheDb("catalog-api");

Everywhere else, depend only on ICacheDb:

using System.Text.Json.Serialization;
using Kanject.Core.CacheDb.Abstractions;
using Kanject.Core.CacheDb.Abstractions.Extensions;
using Kanject.Core.CacheDb.Abstractions.Models;

public sealed class ProductCache(ICacheDb cache)
{
    public Task StoreAsync(ProductSummary product) =>
        cache.CacheDataAsync(
            cache.FormatCacheKey("product", product.Sku),
            product,
            CatalogCacheJsonContext.Default,
            DateTime.UtcNow.AddMinutes(15)); // absolute UTC expiry, not a TimeSpan

    public Task<(bool exists, ProductSummary? value)> GetAsync(string sku) =>
        cache.TryGetCacheDataAsync<ProductSummary>(
            cache.FormatCacheKey("product", sku),
            CatalogCacheJsonContext.Default);

    public Task<bool> EvictAsync(string sku) =>
        cache.RemoveCachedDataAsync(cache.FormatCacheKey("product", sku));
}

public sealed class ProductSummary
{
    public string Sku { get; set; } = string.Empty;
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
}

// Typed values are stored inside a CacheDbModel<T> envelope, so the context must
// declare the envelope type, not only ProductSummary.
[JsonSerializable(typeof(CacheDbModel<ProductSummary>))]
internal sealed partial class CatalogCacheJsonContext : JsonSerializerContext
{
}

The ICacheDb contract

The interface documentation lays down these rules for every provider:

• Expiry is an absolute UTC DateTime. Every write takes a DateTime? duration, which is the instant the entry expires, not a length of time. Pass DateTime.UtcNow.AddMinutes(5). A value in the past counts as already expired.
• null expiry means no expiry. None of the shipped providers (InMemory, DynamoDB, S3 Express) applies a default: a null-expiry entry never expires on its own. For the shared default, pass ICacheDb.DefaultCacheDuration (now plus ICacheDb.DefaultCacheExpiryDurationMinutes, which is 10) explicitly.
• Misses don't throw. The TryGetCacheData* members return false or (false, …) for entries that are missing, expired or can't be deserialized, and also on transient store failures. Boolean-returning members report store failures as false instead of throwing provider-specific exceptions.
• Invalid input is ignored. A write with a null or empty key or payload is skipped. It does not throw.
• Thread safety. You can call one instance from many threads at the same time.
• Canonical keys. FormatCacheKey(params string[] keys) joins key fragments into the provider's key format. The result is deterministic, so the same fragments always give the same key. Build keys with it instead of concatenating strings.
• Cancellation. The overloads that take a CancellationToken are default interface methods. They check the token before they start and then call the overload without a token. A provider can override them to pass the token through to its store client. Otherwise, a token cancelled after the call starts has no effect.
• Removal. RemoveCachedData(params string[] keys) returns true when every key was removed or didn't exist, and false when at least one removal failed.

Typed values

You can store non-string values in three ways:

The JsonSerializerContext extensions wrap your value in CacheDbModel<T>, which has Payload and ExpiryDate. They serialize it with your context's metadata and store it through the string members. On read, they deserialize the envelope and handle problems like this:

• If ExpiryDate has passed, they remove the entry and report a miss.
• If the stored JSON can't be deserialized, they report a miss.
• If the context has no metadata for CacheDbModel<T>, they throw InvalidOperationException.

TryGetCacheData<T>(key, context, out value, out expiryDate) also returns the stored expiry. Use it when you want to refresh an entry before it expires.

Locks

Distributed locks aren't part of ICacheDb. Each provider package has its own DbLockExtensions class with AcquireLockAsync, ReleaseLockAsync and SeekLockAsync extension methods on ICacheDb. AcquireLockAsync and ReleaseLockAsync have the same signatures in every provider. A provider's lock extensions throw NotSupportedException when you call them on another provider's ICacheDb.

This package holds the exception types those APIs throw:

Public surface at a glance

Related packages

License

Licensed under the Kanject Code Libraries License Agreement (KCLLA); the full text ships in this package as LICENSE.md. Organizations whose trailing-twelve-month gross revenue and total funding raised are each below US$250,000 may use it at no cost under the Free Tier. At or above either threshold a commercial license is required — contact commercial@kanjectbusiness.com.