AxisCache 2.0.0

AxisCache — Documentation

🌐 Português (documentação navegável)

A tiny IAxisCache abstraction — five async operations (Get, Set, GetOrCreate, Remove, Exists), every one returning AxisResult, with cancellation flowing through AxisMediator. Two first-party adapter families ship in the box: a ready-made in-memory adapter (AxisMemoryCache) for single-process apps, and a two-tier SQL-backed adapter (AxisCache.Postgres / AxisCache.MySql) when cache state needs to survive a restart or be shared across instances. Drop in your own for Redis, Memcached or anything else.

public Task<AxisResult<Person>> GetByIdAsync(AxisEntityId personId)
    => cache.GetOrCreateAsync(
        key:        $"person:{personId}",
        factory:    () => repository.GetByIdAsync(personId),
        expiration: TimeSpan.FromMinutes(10));

Use this page as a map: read the trunk below (~5 min) and jump straight to the detail of the group you need — without reading hundreds of lines.

The trunk (read first)

The interface in 60 seconds

public interface IAxisCache
{
    Task<AxisResult<T?>>   GetAsync<T>(string key);
    Task<AxisResult>       SetAsync<T>(string key, T value, TimeSpan? expiration = null);
    Task<AxisResult<T>>    GetOrCreateAsync<T>(string key, Func<Task<AxisResult<T>>> factory, TimeSpan? expiration = null);
    Task<AxisResult>       RemoveAsync(string key);
    Task<AxisResult<bool>> ExistsAsync(string key);
}

Five methods. Every result is an AxisResult. Cancellation is implicit — the adapter pulls the CancellationToken from the current AxisMediator scope. Your application code never threads a token through cache calls. → The IAxisCache contract

GetOrCreateAsync — the most important operator

The cache-aside pattern, in one call. If the key is there, return it. If it isn't, run the factory, store its AxisResult<T> (only on success), return the value. If the factory fails, the failure flows through and nothing is cached. → Get-or-create pattern

In-memory adapter

AxisMemoryCache registers IAxisCache against Microsoft.Extensions.Caching.Memory:

services.AddAxisMemoryCache();   // wires IMemoryCache + IAxisCache → MemoryCacheAdapter

→ AxisMemoryCache adapter

SQL-backed adapter

Need the cache to survive a restart or be shared across instances? AxisCache.Postgres / AxisCache.MySql register the same IAxisCache, backed by a fast in-process L1 in front of a durable, shared L2 SQL table:

services.AddAxisCachePostgres(new AxisCacheRepositorySettings { ConnectionString = "Host=…" });

→ SQL adapter

Installation

dotnet add package AxisCache             # the abstraction (depends on AxisResult)
dotnet add package AxisMemoryCache       # the in-memory adapter
dotnet add package AxisCache.Postgres    # or AxisCache.MySql — the SQL-backed adapter

→ Full guide: Getting started

The map (jump to what you need)

Start here: Getting started · The IAxisCache contract · Why AxisCache?

Fundamentals: Get-or-create pattern · AxisMemoryCache adapter · SQL adapter

Reference & extras: Custom adapter · API reference

Design principles

1. Five methods, no more. A bigger surface invites micro-optimisations that leak the vendor's model. Keep callers honest.
2. Every result is an AxisResult. Cache failures are facts, not exceptions. The pipeline decides what to do with them.
3. Cancellation is implicit. The adapter pulls the token from IAxisMediatorAccessor, so no signature has to carry it.
4. The adapter is replaceable. services.AddAxisMemoryCache() is one line; swap it for AddAxisCachePostgres()/AddAxisCacheMySql() — or a custom AddAxisRedisCache() — and nothing in the application changes.
5. GetOrCreateAsync is the headline. The factory is allowed to fail — that failure is not cached.

License

Apache 2.0