Merge pull request #1 from simoneM93/feature/per-group-and-per-entry-cache-duration

simoneM93 · web-flow · commit 3f5e21bd466c · 2026-03-24T10:44:22.000+01:00
feat: add per-group and per-entry cache duration with priority chain
diff --git a/AspNetCoreCacheKit.csproj b/AspNetCoreCacheKit.csproj
@@ -7,16 +7,24 @@
 
 		<IsPackable>true</IsPackable>
 		<PackageId>AspNetCoreCacheKit</PackageId>
-		<Version>1.0.0</Version>
+		<Version>2.0.0</Version>
 		<Authors>Simone Marano</Authors>
-		<Description>Modern caching library for ASP.NET Core with group keys and validation</Description>
+		<Description>Lightweight caching toolkit for ASP.NET Core with group-based keys, per-entry and per-group duration, configurable via appsettings.json and DI-ready design.</Description>
 		<PackageLicenseExpression>MIT</PackageLicenseExpression>
-		<PackageTags>cache;aspnetcore;memorycache</PackageTags>
+		<PackageTags>caching;aspnetcore;dotnet;memorycache;dependency-injection;group-cache;cache-expiration;in-memory-cache</PackageTags>
 		<RepositoryUrl>https://github.com/simoneM93/AspNetCoreCacheKit</RepositoryUrl>
-		<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
+		<RepositoryType>git</RepositoryType>
+		<PackageProjectUrl>https://github.com/simoneM93/AspNetCoreCacheKit</PackageProjectUrl>
 		<PackageReadmeFile>README.md</PackageReadmeFile>
+		<PackageReleaseNotes>https://github.com/simoneM93/AspNetCoreCacheKit/blob/main/CHANGELOG.md</PackageReleaseNotes>
+		<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
 	</PropertyGroup>
 
+	<ItemGroup>
+		<None Include="README.md" Pack="true" PackagePath="\" />
+		<None Include="CHANGELOG.md" Pack="true" PackagePath="\" />
+	</ItemGroup>
+
 	<ItemGroup>
 		<PackageReference Include="Microsoft.Extensions.Caching.Memory" Version="9.0.0" />
 		<PackageReference Include="Microsoft.Extensions.Options.ConfigurationExtensions" Version="9.0.0" />
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,68 @@
+﻿# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+---
+
+## [2.0.0] - 2026-03-24
+
+### Added
+- Per-group cache duration via `GroupDurations` in `appsettings.json` — each group key can now have its own expiration independent of the global default
+- Per-entry duration override — all `Set`, `GetOrCreate` and `GetOrCreateAsync` methods now accept an optional `TimeSpan? duration` parameter
+- Duration resolution priority chain: per-entry → per-group → global default
+- `CancellationToken` support on all async methods
+- Validation on `GroupDurations` values — all entries must be greater than zero, enforced at startup via `ValidateOnStart`
+- `RepositoryType`, `PackageProjectUrl` and `PackageReleaseNotes` metadata in `.csproj`
+
+### Changed
+- `CacheOptions.Duration` renamed to `CacheOptions.DurationMinutes` for clarity — **breaking change**
+- `GetOrCreateAsync` now uses `IMemoryCache.GetOrCreateAsync` natively instead of wrapping the synchronous `GetOrCreate` — fixes potential cache stampede under concurrent requests
+- `ICacheService` registration changed from `Scoped` to `Singleton` in `AddAspNetCoreCacheKit` — aligns with `IOptions<T>` which is Singleton
+- Return types of `GetOrCreate<T>` and `GetOrCreateAsync<T>` corrected from `T` to `T?` — reflects the nullable contract of `IMemoryCache`
+- `GetFullKey` now returns the bare key when `groupKey` is empty, avoiding keys like `:mykey`
+- `PackageTags` expanded with `group-cache`, `cache-expiration`, `dotnet`, `dependency-injection`
+- `Description` updated to reflect new features
+
+### Fixed
+- Null checks in constructor moved before field assignments and applied to parameters, not fields
+- `IOptionsSnapshot<CacheOptions>` replaced with `IOptions<CacheOptions>` — `IOptionsSnapshot` was being recreated on every HTTP request, causing unnecessary allocations for a static configuration
+- Redundant `services.Configure<CacheOptions>()` call removed from `AddAspNetCoreCacheKit` — `AddOptions().Bind()` already covers this
+- Redundant `.PostConfigure()` removed — default value is now declared directly on `CacheOptions.DurationMinutes`
+
+### Breaking changes
+- `CacheOptions.Duration` (TimeSpan) → `CacheOptions.DurationMinutes` (int): update your `appsettings.json` accordingly
+  ```json
+  // before
+  "CacheOptions": { "Duration": "00:60:00" }
+
+  // after
+  "CacheOptions": { "DurationMinutes": 60 }
+  ```
+- `ICacheService` methods now return `T?` instead of `T` — callers may need to handle null returns
+- `GetOrCreateAsync` and `GetOrCreate` signatures now include `TimeSpan? duration = null` — source-compatible (optional parameter), but binary-incompatible if you were using the interface via reflection
+
+---
+
+## [1.0.0] - 2025-01-01
+
+### Added
+- Initial release
+- `ICacheService` interface with `Set`, `GetOrCreate`, `GetOrCreateAsync` and `Delete` methods
+- Group-based cache keys (`"group:key"` format)
+- `CacheOptions` with `IsEnabled` and `Duration` flags
+- `AddAspNetCoreCacheKit()` and `AddAspNetCoreCacheKit(IConfiguration)` DI extension methods
+- Configuration validation with DataAnnotations and `ValidateOnStart`
+- MIT license
+
+---
+
+[Unreleased]: https://github.com/simoneM93/AspNetCoreCacheKit/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/simoneM93/AspNetCoreCacheKit/compare/v1.0.0...v2.0.0
+[1.0.0]: https://github.com/simoneM93/AspNetCoreCacheKit/releases/tag/v1.0.0
diff --git a/CacheService.cs b/CacheService.cs
@@ -2,79 +2,119 @@
 using AspNetCoreCacheKit.Models;
 using Microsoft.Extensions.Caching.Memory;
 using Microsoft.Extensions.Options;
+using Microsoft.Extensions.Primitives;
 
 namespace AspNetCoreCacheKit
 {
     public class CacheService : ICacheService
     {
         private readonly IMemoryCache _memoryCache;
         private readonly CacheOptions _cacheOptions;
-        private readonly TimeSpan _expiration;
 
-        public CacheService(IMemoryCache memoryCache, IOptionsSnapshot<CacheOptions> cacheOptions)
+        public CacheService(IMemoryCache memoryCache, IOptions<CacheOptions> cacheOptions)
         {
+            ArgumentNullException.ThrowIfNull(memoryCache);
+            ArgumentNullException.ThrowIfNull(cacheOptions);
+
             _memoryCache = memoryCache;
             _cacheOptions = cacheOptions.Value;
-            _expiration = _cacheOptions.Duration;
-
-            ArgumentNullException.ThrowIfNull(_memoryCache);
-            ArgumentNullException.ThrowIfNull(_cacheOptions);
         }
 
-        public void Set(string groupKey, string key, object value)
+        public void Set(string groupKey, string key, object value, TimeSpan? duration = null)
         {
             if (_cacheOptions.IsEnabled)
             {
                 var fullKey = GetFullKey(key, groupKey);
                 _memoryCache.Set(fullKey, value, new MemoryCacheEntryOptions
                 {
-                    AbsoluteExpirationRelativeToNow = _expiration
+                    AbsoluteExpirationRelativeToNow = ResolveExpiration(groupKey, duration)
                 });
             }
         }
 
-        public async Task<T> GetOrCreateAsync<T>(string groupKey, string key, Func<Task<T>> createFunc)
+        public async Task<T?> GetOrCreateAsync<T>(
+            string groupKey,
+            string key,
+            Func<ICacheEntry, Task<T>> createFunc,
+            TimeSpan? duration = null,
+            CancellationToken cancellationToken = default)
         {
             if (!_cacheOptions.IsEnabled)
-                return await createFunc();
+                return await createFunc(new NullCacheEntry());
 
-            var fullKey = GetFullKey(key, groupKey);
+            cancellationToken.ThrowIfCancellationRequested();
 
-            return await _memoryCache.GetOrCreate(fullKey, entry =>
-            {
-                entry.AbsoluteExpirationRelativeToNow = _expiration;
-                return createFunc();
-            });
+            var expiration = ResolveExpiration(groupKey, duration);
+
+            return await _memoryCache.GetOrCreateAsync(
+                GetFullKey(groupKey, key),
+                entry =>
+                {
+                    entry.AbsoluteExpirationRelativeToNow = expiration;
+                    return createFunc(entry);
+                });
         }
 
-        public T GetOrCreate<T>(string groupKey, string key, Func<T> createFunc)
+        public T? GetOrCreate<T>(
+            string groupKey,
+            string key,
+            Func<T> createFunc,
+            TimeSpan? duration = null)
         {
             if (!_cacheOptions.IsEnabled)
                 return createFunc();
 
-            var fullKey = GetFullKey(key, groupKey);
+            var expiration = ResolveExpiration(groupKey, duration);
 
-            return _memoryCache.GetOrCreate(fullKey, entry =>
-            {
-                entry.AbsoluteExpirationRelativeToNow = _expiration;
-                return createFunc();
-            });
+            return _memoryCache.GetOrCreate(
+                GetFullKey(groupKey, key),
+                entry =>
+                {
+                    entry.AbsoluteExpirationRelativeToNow = expiration;
+                    return createFunc();
+                });
         }
 
         public void Delete(string groupKey, string key)
         {
             if (_cacheOptions.IsEnabled)
-                _memoryCache.Remove(GetFullKey(key, groupKey));
+                _memoryCache.Remove(GetFullKey(groupKey, key));
         }
 
-        public void Set(string key, object value) => Set(string.Empty, key, value);
+        public void Set(string key, object value, TimeSpan? duration = null)
+            => Set(string.Empty, key, value, duration);
+
+        public async Task<T?> GetOrCreateAsync<T>(
+            string key,
+            Func<ICacheEntry, Task<T>> createFunc,
+            TimeSpan? duration = null,
+            CancellationToken cancellationToken = default)
+            => await GetOrCreateAsync(string.Empty, key, createFunc, duration, cancellationToken);
 
-        public async Task<T> GetOrCreateAsync<T>(string key, Func<Task<T>> createFunc) => await GetOrCreateAsync(string.Empty, key, createFunc);
+        public T? GetOrCreate<T>(string key, Func<T> createFunc, TimeSpan? duration = null)
+            => GetOrCreate(string.Empty, key, createFunc, duration);
 
-        public T GetOrCreate<T>(string key, Func<T> createFunc) => GetOrCreate(string.Empty, key, createFunc);
+        public void Delete(string key)
+            => Delete(string.Empty, key);
 
-        public void Delete(string key) => Delete(string.Empty, key);
+        private static string GetFullKey(string groupKey, string key)
+            => string.IsNullOrEmpty(groupKey) ? key : $"{groupKey}:{key}";
 
-        private static string GetFullKey(string groupKey, string key) => $"{groupKey}:{key}";
+        private TimeSpan ResolveExpiration(string groupKey, TimeSpan? duration)
+            => duration ?? _cacheOptions.GetGroupDuration(groupKey) ?? _cacheOptions.Duration;
+
+        private sealed class NullCacheEntry : ICacheEntry
+        {
+            public object Key => string.Empty;
+            public object? Value { get; set; }
+            public DateTimeOffset? AbsoluteExpiration { get; set; }
+            public TimeSpan? AbsoluteExpirationRelativeToNow { get; set; }
+            public TimeSpan? SlidingExpiration { get; set; }
+            public IList<IChangeToken> ExpirationTokens { get; } = [];
+            public IList<PostEvictionCallbackRegistration> PostEvictionCallbacks { get; } = [];
+            public CacheItemPriority Priority { get; set; }
+            public long? Size { get; set; }
+            public void Dispose() { }
+        }
     }
 }
diff --git a/Extensions/CacheServiceExtensions.cs b/Extensions/CacheServiceExtensions.cs
@@ -10,28 +10,29 @@ namespace AspNetCoreCacheKit.Extensions
 {
     public static class CacheServiceExtensions
     {
-        public static IServiceCollection AddAspNetCoreCacheKit(this IServiceCollection services, IConfiguration configuration)
+        public static IServiceCollection AddAspNetCoreCacheKit(
+           this IServiceCollection services,
+           IConfiguration configuration)
         {
             ArgumentNullException.ThrowIfNull(services);
             ArgumentNullException.ThrowIfNull(configuration);
 
             services.AddMemoryCache();
 
             var cacheSection = configuration.GetSection("CacheOptions");
-            services.Configure<CacheOptions>(cacheSection);
 
             services.AddOptions<CacheOptions>()
                 .Bind(cacheSection)
                 .ValidateDataAnnotations()
-                .Validate(options => options.Duration > TimeSpan.Zero, "Duration must be greater than zero")
-                .PostConfigure(options =>
-                {
-                    options.Duration = options.Duration == TimeSpan.Zero ? TimeSpan.FromMinutes(60) : options.Duration;
-                })
+                .Validate(
+                    options => options.DurationMinutes > 0,
+                    "DurationMinutes must be greater than zero.")
+                .Validate(
+                    options => options.GroupDurations.Values.All(v => v > 0),
+                    "All GroupDurations values must be greater than zero.")
                 .ValidateOnStart();
 
-
-            services.AddScoped<ICacheService, CacheService>();
+            services.AddSingleton<ICacheService, CacheService>();
 
             return services;
         }
diff --git a/Interfaces/ICacheService.cs b/Interfaces/ICacheService.cs
@@ -1,18 +1,33 @@
-﻿namespace AspNetCoreCacheKit.Interfaces
+﻿using Microsoft.Extensions.Caching.Memory;
+
+namespace AspNetCoreCacheKit.Interfaces
 {
     public interface ICacheService
     {
-        void Set(string groupKey, string key, object value);
+        void Set(string groupKey, string key, object value, TimeSpan? duration = null);
 
-        void Set(string key, object value);
+        void Set(string key, object value, TimeSpan? duration = null);
 
-        Task<T> GetOrCreateAsync<T>(string groupKey, string key, Func<Task<T>> createFunc);
+        Task<T?> GetOrCreateAsync<T>(
+            string groupKey,
+            string key,
+            Func<ICacheEntry, Task<T>> createFunc,
+            TimeSpan? duration = null,
+            CancellationToken cancellationToken = default);
 
-        Task<T> GetOrCreateAsync<T>(string key, Func<Task<T>> createFunc);
+        Task<T?> GetOrCreateAsync<T>(
+           string key,
+           Func<ICacheEntry, Task<T>> createFunc,
+           TimeSpan? duration = null,
+           CancellationToken cancellationToken = default);
 
-        T GetOrCreate<T>(string groupKey, string key, Func<T> createFunc);
+        T? GetOrCreate<T>(string key, Func<T> createFunc, TimeSpan? duration = null);
 
-        T GetOrCreate<T>(string key, Func<T> createFunc);
+        T? GetOrCreate<T>(
+            string groupKey,
+            string key,
+            Func<T> createFunc,
+            TimeSpan? duration = null);
 
         void Delete(string groupKey, string key);
 
diff --git a/Models/CacheOptions.cs b/Models/CacheOptions.cs
@@ -6,7 +6,21 @@ public class CacheOptions
     {
         public bool IsEnabled { get; set; } = true;
 
-        [Range(typeof(TimeSpan), "00:00:01", "24:00:00", ErrorMessage = "Duration must be between 1 second and 24 hours")]
-        public TimeSpan Duration { get; set; } = TimeSpan.FromMinutes(60);
+        [Range(1, int.MaxValue, ErrorMessage = "Duration must be greater than 0.")]
+        public int DurationMinutes { get; set; } = 60;
+
+        internal TimeSpan Duration => TimeSpan.FromMinutes(DurationMinutes);
+
+        public Dictionary<string, int> GroupDurations { get; set; } = [];
+
+        internal TimeSpan? GetGroupDuration(string groupKey)
+        {
+            if (string.IsNullOrEmpty(groupKey))
+                return null;
+
+            return GroupDurations.TryGetValue(groupKey, out var minutes)
+                ? TimeSpan.FromMinutes(minutes)
+                : null;
+        }
     }
 }
diff --git a/README.md b/README.md
