Ensure consistent behavior with previous ListAddAsync expires in behavior.

Author: niemyjski

docs/guide/caching.md

@@ -353,23 +353,59 @@ await cache.SetIfLowerAsync("fastest-response-ms", responseTime);
 
 ### List Operations
 
-Store and manage lists:
+Foundatio lists support **per-value expiration**, where each item in the list can have its own independent TTL. This is different from standard cache keys where expiration applies to the entire key.
+
+#### Why Per-Value Expiration?
+
+Per-value expiration prevents unbounded list growth. Consider tracking recently deleted items:
+
+```csharp
+// Without per-value expiration (sliding expiration problem):
+// Adding ANY item resets the entire list's TTL, causing indefinite growth
+await cache.ListAddAsync("deleted-items", [itemId], TimeSpan.FromDays(7));
+// After months: list has 100,000+ items because TTL keeps resetting!
+
+// With per-value expiration (Foundatio's approach):
+// Each item expires independently after 7 days
+await cache.ListAddAsync("deleted-items", [itemId], TimeSpan.FromDays(7));
+// List stays bounded - old items expire even as new ones are added
+```
+
+**Real-world use cases:**
+- **Soft-delete tracking**: Track deleted document IDs that should be filtered from queries
+- **Recent activity feeds**: Each activity expires independently (e.g., "active in last 5 minutes")
+- **Rate limiting windows**: Track individual requests with their own expiration
+- **Session tracking**: Track user sessions where each session has its own timeout
+
+#### Basic List Usage
 
 ```csharp
-// Add to a list
-await cache.ListAddAsync("user:123:recent-searches", new[] { "query1" });
+// Add items with per-value expiration (each item expires in 1 hour)
+await cache.ListAddAsync("user:123:recent-searches", new[] { "query1" }, TimeSpan.FromHours(1));
+await cache.ListAddAsync("user:123:recent-searches", new[] { "query2" }, TimeSpan.FromHours(1));
+
+// Items expire independently - query1 expires 1 hour after it was added,
+// query2 expires 1 hour after IT was added (not when query1 was added)
 
-// Get paginated list
+// Get paginated list (expired items are automatically filtered)
 var searches = await cache.GetListAsync<string>(
     "user:123:recent-searches",
     page: 0,
     pageSize: 10
 );
 
-// Remove from list
+// Remove specific items from list
 await cache.ListRemoveAsync("user:123:recent-searches", new[] { "query1" });
 ```
 
+#### List Expiration Behavior
+
+| `expiresIn` Value | Behavior |
+|-------------------|----------|
+| `null` | Values will not expire. Key expiration is set to max of all item expirations. |
+| Positive `TimeSpan` | Each value expires independently after this duration. |
+| Zero or negative | The specified values are removed from the list (if present), returns 0. |
+
 ### Bulk Operations
 
 Efficiently work with multiple keys:

src/Foundatio.TestHarness/Caching/CacheClientTestsBase.cs

@@ -989,13 +989,40 @@ public virtual async Task ListAddAsync_WithExpiration_SetsExpirationCorrectly()
             Assert.False(await cache.ExistsAsync("list-past-exp-new"));
             Assert.False((await cache.GetListAsync<int>("list-past-exp-new")).HasValue);
 
-            // Past expiration on existing key: should return 0 and remove the key
+            // Past expiration on existing key: should return 0 and only remove the values being added (not the whole key)
             Assert.Equal(1, await cache.ListAddAsync("list-past-exp-existing", [1]));
             Assert.True(await cache.ExistsAsync("list-past-exp-existing"));
             result = await cache.ListAddAsync("list-past-exp-existing", [2], TimeSpan.FromSeconds(-1));
             Assert.Equal(0, result);
-            Assert.False(await cache.ExistsAsync("list-past-exp-existing"));
-            Assert.False((await cache.GetListAsync<int>("list-past-exp-existing")).HasValue);
+            Assert.True(await cache.ExistsAsync("list-past-exp-existing")); // Key still exists!
+            var existingList = await cache.GetListAsync<int>("list-past-exp-existing");
+            Assert.True(existingList.HasValue);
+            Assert.Single(existingList.Value);
+            Assert.Contains(1, existingList.Value); // Item 1 still present
+
+            // Past expiration on existing key with multiple items: should only remove the values being added
+            Assert.Equal(1, await cache.ListAddAsync("list-past-exp-multi", [1]));
+            Assert.Equal(1, await cache.ListAddAsync("list-past-exp-multi", [2]));
+            Assert.Equal(2, (await cache.GetListAsync<int>("list-past-exp-multi")).Value.Count);
+            // Add item 3 with negative expiration - should NOT delete existing items
+            result = await cache.ListAddAsync("list-past-exp-multi", [3], TimeSpan.FromSeconds(-1));
+            Assert.Equal(0, result);
+            Assert.True(await cache.ExistsAsync("list-past-exp-multi")); // Key still exists!
+            var multiList = await cache.GetListAsync<int>("list-past-exp-multi");
+            Assert.Equal(2, multiList.Value.Count); // Items 1 and 2 still present
+            Assert.Contains(1, multiList.Value);
+            Assert.Contains(2, multiList.Value);
+
+            // Past expiration removes existing item if it matches
+            Assert.Equal(1, await cache.ListAddAsync("list-past-exp-remove", [1]));
+            Assert.Equal(1, await cache.ListAddAsync("list-past-exp-remove", [2]));
+            result = await cache.ListAddAsync("list-past-exp-remove", [1], TimeSpan.FromSeconds(-1)); // Remove item 1
+            Assert.Equal(0, result);
+            Assert.True(await cache.ExistsAsync("list-past-exp-remove"));
+            var removeList = await cache.GetListAsync<int>("list-past-exp-remove");
+            Assert.Single(removeList.Value);
+            Assert.Contains(2, removeList.Value); // Only item 2 remains
+            Assert.DoesNotContain(1, removeList.Value); // Item 1 was removed
 
             // Zero expiration: should also be treated as expired
             result = await cache.ListAddAsync("list-zero-exp", [1], TimeSpan.Zero);
@@ -1039,6 +1066,7 @@ public virtual async Task ListAddAsync_WithExpiration_SetsExpirationCorrectly()
             Assert.True(cacheValue.HasValue);
             Assert.Single(cacheValue.Value);
             Assert.Contains(3, cacheValue.Value);
+            Assert.DoesNotContain(2, cacheValue.Value); // Explicit verification item 2 expired
 
             // Wait for second item to expire
             await Task.Delay(100);

src/Foundatio/Caching/ICacheClient.cs

@@ -418,14 +418,22 @@ public interface ICacheClient : IDisposable
     /// <param name="key">The unique identifier for the cache entry. Cannot be null or empty.</param>
     /// <param name="values">The values to add to the list. Cannot be null. Null values within the collection are ignored.</param>
     /// <param name="expiresIn">
-    /// Optional expiration time for the cache entry.
+    /// Optional expiration time for each value being added (per-value expiration, NOT per-key).
     /// <list type="bullet">
-    ///   <item><description><b>null</b>: Entry will not expire.</description></item>
-    ///   <item><description><b>Positive value</b>: Entry expires after this duration.</description></item>
-    ///   <item><description><b>Zero or negative</b>: Any existing key is removed, returns 0.</description></item>
+    ///   <item><description><b>null</b>: Values will not expire.</description></item>
+    ///   <item><description><b>Positive value</b>: Each value expires independently after this duration.</description></item>
+    ///   <item><description><b>Zero or negative</b>: The specified values are removed from the list if present, returns 0.</description></item>
     /// </list>
+    /// <para>
+    /// <b>Design Note:</b> Per-value expiration prevents unbounded list growth. Without it, adding any item
+    /// would reset the entire list's TTL (sliding expiration), causing lists to grow indefinitely in
+    /// scenarios like tracking deleted items or recent activity.
+    /// </para>
     /// </param>
     /// <returns>The number of values that were added to the list.</returns>
+    /// <remarks>
+    /// The key's overall expiration is automatically set to the maximum expiration of all items in the list.
+    /// </remarks>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="key"/> or <paramref name="values"/> is null.</exception>
     /// <exception cref="ArgumentException">Thrown when <paramref name="key"/> is empty.</exception>
     Task<long> ListAddAsync<T>(string key, IEnumerable<T> values, TimeSpan? expiresIn = null);

src/Foundatio/Caching/InMemoryCacheClient.cs

@@ -515,7 +515,7 @@ public async Task<long> ListAddAsync<T>(string key, IEnumerable<T> values, TimeS
 
         if (expiresIn is { Ticks: <= 0 })
         {
-            RemoveExpiredKey(key);
+            await ListRemoveAsync(key, values).AnyContext();
             return 0;
         }