Fixes inconsistent SetIf*Async TTL behavior

Standardizes the behavior of the SetIfHigherAsync and SetIfLowerAsync methods regarding TTL handling.

Previously, these methods returned -1 when a zero or negative TimeSpan was provided, leading to inconsistent behavior. Now, they consistently return 0 and remove the key, aligning with other cache methods.

Author: niemyjski

docs/guide/caching.md

@@ -71,8 +71,8 @@ Different methods handle the `expiresIn` parameter slightly differently. The tab
 | `ReplaceAsync` | No TTL (removes existing) | Sets TTL | Removes key | `false` |
 | `ReplaceIfEqualAsync` | No TTL (removes existing) | Sets TTL | Removes key | `false` |
 | `IncrementAsync` | **Preserves existing TTL** | Sets/updates TTL | Removes key | `0` |
-| `SetIfHigherAsync` | No TTL (removes existing) | Sets TTL | Removes key | `-1` |
-| `SetIfLowerAsync` | No TTL (removes existing) | Sets TTL | Removes key | `-1` |
+| `SetIfHigherAsync` | No TTL (removes existing) | Sets TTL | Removes key | `0` |
+| `SetIfLowerAsync` | No TTL (removes existing) | Sets TTL | Removes key | `0` |
 | `ListAddAsync` | No TTL | Sets TTL | Removes key | `0` |
 | `ListRemoveAsync` | Preserves existing TTL | Sets TTL | Removes key | `0` |
 
@@ -137,8 +137,8 @@ await cache.SetIfHigherAsync("max-users", 150, null); // No TTL now!
 // Update with TTL - sets new TTL
 await cache.SetIfHigherAsync("max-users", 200, TimeSpan.FromHours(2)); // TTL = 2 hours
 
-// Zero/negative removes key, returns -1
-var diff = await cache.SetIfHigherAsync("max-users", 999, TimeSpan.Zero); // -1
+// Zero/negative removes key, returns 0
+var diff = await cache.SetIfHigherAsync("max-users", 999, TimeSpan.Zero); // 0
 ```
 
 ### Managing Expiration

src/Foundatio/Caching/ICacheClient.cs

@@ -17,7 +17,7 @@ namespace Foundatio.Caching;
 ///   When called on an existing key, passing null removes any existing expiration.</description></item>
 ///   <item><description><b>Positive value</b>: The entry will expire after the specified duration from now.</description></item>
 ///   <item><description><b>Zero or negative value</b>: The operation is treated as expired - any existing key is removed
-///   and the method returns a failure/default value (false, 0, -1, depending on the method).</description></item>
+///   and the method returns a failure/default value (false, 0, depending on the method).</description></item>
 ///   <item><description><b>TimeSpan.MaxValue</b>: The entry will not expire (treated as no expiration).</description></item>
 /// </list>
 /// <para>
@@ -325,13 +325,12 @@ public interface ICacheClient : IDisposable
     /// <list type="bullet">
     ///   <item><description><b>null</b>: Entry will not expire (removes any existing expiration).</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 -1.</description></item>
+    ///   <item><description><b>Zero or negative</b>: Any existing key is removed, returns 0.</description></item>
     /// </list>
     /// </param>
     /// <returns>
     /// The difference between the new value and the old value if the value was updated;
-    /// 0 if the current value was already higher or equal;
-    /// -1 if the operation failed due to invalid expiration.
+    /// 0 if the current value was already higher or equal or invalid expiration.
     /// For new keys, returns the value itself (difference from 0).
     /// </returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="key"/> is null.</exception>
@@ -350,13 +349,12 @@ public interface ICacheClient : IDisposable
     /// <list type="bullet">
     ///   <item><description><b>null</b>: Entry will not expire (removes any existing expiration).</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 -1.</description></item>
+    ///   <item><description><b>Zero or negative</b>: Any existing key is removed, returns 0.</description></item>
     /// </list>
     /// </param>
     /// <returns>
     /// The difference between the new value and the old value if the value was updated;
-    /// 0 if the current value was already higher or equal;
-    /// -1 if the operation failed due to invalid expiration.
+    /// 0 if the current value was already higher or equal or invalid expiration.
     /// For new keys, returns the value itself (difference from 0).
     /// </returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="key"/> is null.</exception>
@@ -375,13 +373,12 @@ public interface ICacheClient : IDisposable
     /// <list type="bullet">
     ///   <item><description><b>null</b>: Entry will not expire (removes any existing expiration).</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 -1.</description></item>
+    ///   <item><description><b>Zero or negative</b>: Any existing key is removed, returns 0.</description></item>
     /// </list>
     /// </param>
     /// <returns>
     /// The difference between the old value and the new value if the value was updated;
-    /// 0 if the current value was already lower or equal;
-    /// -1 if the operation failed due to invalid expiration.
+    /// 0 if the current value was already lower or equal or invalid expiration.
     /// For new keys, returns the value itself (difference from 0).
     /// </returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="key"/> is null.</exception>
@@ -400,13 +397,12 @@ public interface ICacheClient : IDisposable
     /// <list type="bullet">
     ///   <item><description><b>null</b>: Entry will not expire (removes any existing expiration).</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 -1.</description></item>
+    ///   <item><description><b>Zero or negative</b>: Any existing key is removed, returns 0.</description></item>
     /// </list>
     /// </param>
     /// <returns>
     /// The difference between the old value and the new value if the value was updated;
-    /// 0 if the current value was already lower or equal;
-    /// -1 if the operation failed due to invalid expiration.
+    /// 0 if the current value was already lower or equal or invalid expiration.
     /// For new keys, returns the value itself (difference from 0).
     /// </returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="key"/> is null.</exception>

tests/Foundatio.Tests/Caching/InMemoryCacheClientTests.cs

@@ -677,7 +677,7 @@ public async Task SetAsync_WithMaxItems_EnforcesLimit()
     [Fact]
     public async Task DoMaintenanceAsync_WithMaxTimeSpanExpiration_ShouldNotThrowException()
     {
-        // Arrange - use normal time, not DateTimeOffset.MaxValue which causes overflow issues
+        // Arrange - use a normal current time so using TimeSpan.MaxValue for expiration does not cause overflow issues
         var timeProvider = new FakeTimeProvider();
         timeProvider.SetUtcNow(new DateTimeOffset(2024, 1, 1, 0, 0, 0, TimeSpan.Zero));