From 73f2a45152d4cad842872762f82e8686e65c4fe4 Mon Sep 17 00:00:00 2001
From: Fati Iseni <fati.iseni@pozitrongroup.com>
Date: Wed, 4 Jun 2025 10:45:29 +0200
Subject: [PATCH] Add WithCacheKey

---
 .../Builders/Builder_Cache.cs                 | 75 +++++++++++++++++++
 src/QuerySpecification/Internals/ItemType.cs  |  1 +
 src/QuerySpecification/Specification.cs       | 24 ++++++
 .../Builders/Builder_WithCacheKey.cs          | 61 +++++++++++++++
 4 files changed, 161 insertions(+)
 create mode 100644 src/QuerySpecification/Builders/Builder_Cache.cs
 create mode 100644 tests/QuerySpecification.Tests/Builders/Builder_WithCacheKey.cs

diff --git a/src/QuerySpecification/Builders/Builder_Cache.cs b/src/QuerySpecification/Builders/Builder_Cache.cs
new file mode 100644
index 00000000..94297dc9
--- /dev/null
+++ b/src/QuerySpecification/Builders/Builder_Cache.cs
@@ -0,0 +1,75 @@
+namespace Pozitron.QuerySpecification;
+
+public static partial class SpecificationBuilderExtensions
+{
+    /// <summary>
+    /// Sets the cache key for the specification.
+    /// </summary>
+    /// <typeparam name="T">The type of the entity.</typeparam>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
+    /// <param name="builder">The specification builder.</param>
+    /// <param name="cacheKey">The cache key to be used.</param>
+    /// <returns>The updated specification builder.</returns>
+    public static ISpecificationBuilder<T, TResult> WithCacheKey<T, TResult>(
+        this ISpecificationBuilder<T, TResult> builder,
+        string cacheKey) where T : class
+    {
+        WithCacheKey(builder, cacheKey, true);
+        return (SpecificationBuilder<T, TResult>)builder;
+    }
+
+    /// <summary>
+    /// Sets the cache key for the specification.
+    /// </summary>
+    /// <typeparam name="T">The type of the entity.</typeparam>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
+    /// <param name="builder">The specification builder.</param>
+    /// <param name="cacheKey">The cache key to be used.</param>
+    /// <param name="condition">The condition to evaluate.</param>
+    /// <returns>The updated specification builder.</returns>
+    public static ISpecificationBuilder<T, TResult> WithCacheKey<T, TResult>(
+        this ISpecificationBuilder<T, TResult> builder,
+        string cacheKey,
+        bool condition) where T : class
+    {
+        if (condition)
+        {
+            builder.Specification.AddOrUpdateInternal(ItemType.CacheKey, cacheKey);
+        }
+
+        return builder;
+    }
+
+    /// <summary>
+    /// Sets the cache key for the specification.
+    /// </summary>
+    /// <typeparam name="T">The type of the entity.</typeparam>
+    /// <param name="builder">The specification builder.</param>
+    /// <param name="cacheKey">The cache key to be used.</param>
+    /// <returns>The updated specification builder.</returns>
+    public static ISpecificationBuilder<T> WithCacheKey<T>(
+        this ISpecificationBuilder<T> builder,
+        string cacheKey) where T : class
+        => WithCacheKey(builder, cacheKey, true);
+
+    /// <summary>
+    /// Sets the cache key for the specification.
+    /// </summary>
+    /// <typeparam name="T">The type of the entity.</typeparam>
+    /// <param name="builder">The specification builder.</param>
+    /// <param name="cacheKey">The cache key to be used.</param>
+    /// <param name="condition">The condition to evaluate.</param>
+    /// <returns>The updated specification builder.</returns>
+    public static ISpecificationBuilder<T> WithCacheKey<T>(
+        this ISpecificationBuilder<T> builder,
+        string cacheKey,
+        bool condition) where T : class
+    {
+        if (condition)
+        {
+            builder.Specification.AddOrUpdateInternal(ItemType.CacheKey, cacheKey);
+        }
+
+        return builder;
+    }
+}
diff --git a/src/QuerySpecification/Internals/ItemType.cs b/src/QuerySpecification/Internals/ItemType.cs
index 07345ac5..69c9fe16 100644
--- a/src/QuerySpecification/Internals/ItemType.cs
+++ b/src/QuerySpecification/Internals/ItemType.cs
@@ -15,4 +15,5 @@ internal static class ItemType
     public const int Flags = -8; // Stored in the bag
 
     public const int QueryTag = -9;
+    public const int CacheKey = -10;
 }
diff --git a/src/QuerySpecification/Specification.cs b/src/QuerySpecification/Specification.cs
index 25db04a9..2a1e786a 100644
--- a/src/QuerySpecification/Specification.cs
+++ b/src/QuerySpecification/Specification.cs
@@ -183,6 +183,16 @@ public virtual bool IsSatisfiedBy(T entity)
         ? Enumerable.Empty<string>()
         : new SpecSelectIterator<string, string>(_items, ItemType.QueryTag, (x, bag) => x);
 
+    /// <summary>
+    /// Return whether or not a cache key is set.
+    /// </summary>
+    public bool HasCacheKey => Contains(ItemType.CacheKey);
+
+    /// <summary>
+    /// Gets the cache key.
+    /// </summary>
+    public string? CacheKey => FirstOrDefault<string>(ItemType.CacheKey);
+
     /// <summary>
     /// Gets the number of items to take.
     /// </summary>
@@ -306,6 +316,20 @@ public IEnumerable<TObject> OfType<TObject>(int type) => _items is null
 
     internal ReadOnlySpan<SpecItem> Items => _items ?? ReadOnlySpan<SpecItem>.Empty;
 
+    internal bool Contains(int type)
+    {
+        if (IsEmpty) return false;
+
+        foreach (var item in _items)
+        {
+            if (item.Type == type)
+            {
+                return true;
+            }
+        }
+        return false;
+    }
+
     [MemberNotNull(nameof(_items))]
     internal void AddInternal(int type, object value, int bag = 0)
     {
diff --git a/tests/QuerySpecification.Tests/Builders/Builder_WithCacheKey.cs b/tests/QuerySpecification.Tests/Builders/Builder_WithCacheKey.cs
new file mode 100644
index 00000000..cef83fcf
--- /dev/null
+++ b/tests/QuerySpecification.Tests/Builders/Builder_WithCacheKey.cs
@@ -0,0 +1,61 @@
+namespace Tests.Builders;
+
+public class Builder_WithCacheKey
+{
+    public record Customer(int Id, string Name);
+
+    [Fact]
+    public void DoesNothing_GivenNoWithCacheKey()
+    {
+        var spec1 = new Specification<Customer>();
+        var spec2 = new Specification<Customer, string>();
+
+        spec1.CacheKey.Should().BeNull();
+        spec1.HasCacheKey.Should().BeFalse();
+
+        spec2.CacheKey.Should().BeNull();
+        spec2.HasCacheKey.Should().BeFalse();
+    }
+
+    [Fact]
+    public void DoesNothing_GivenWithCacheKeyWithFalseCondition()
+    {
+        var key = "someKey";
+
+        var spec1 = new Specification<Customer>();
+        spec1.Query
+            .Where(x=> x.Id > 0)
+            .WithCacheKey(key, false);
+
+        var spec2 = new Specification<Customer, string>();
+        spec2.Query
+            .Where(x=> x.Id > 0)
+            .WithCacheKey(key, false);
+
+        spec1.CacheKey.Should().BeNull();
+        spec1.HasCacheKey.Should().BeFalse();
+
+        spec2.CacheKey.Should().BeNull();
+        spec2.HasCacheKey.Should().BeFalse();
+    }
+
+    [Fact]
+    public void SetsCacheKey_GivenWithCacheKey()
+    {
+        var key = "someKey";
+
+        var spec1 = new Specification<Customer>();
+        spec1.Query
+            .WithCacheKey(key);
+
+        var spec2 = new Specification<Customer, string>();
+        spec2.Query
+            .WithCacheKey(key);
+
+        spec1.CacheKey.Should().Be(key);
+        spec1.HasCacheKey.Should().BeTrue();
+
+        spec1.CacheKey.Should().Be(key);
+        spec2.HasCacheKey.Should().BeTrue();
+    }
+}