Initial version

README.md

@@ -1,3 +1,125 @@
 # EonaCat.SmartRetry
 
-EonaCat.SmartRetry
+[![NuGet](https://img.shields.io/nuget/v/EonaCat.SmartRetry)](https://www.nuget.org/packages/EonaCat.SmartRetry)
+
+`EonaCat.SmartRetry` is a powerful and flexible .NET library for building resilient applications. 
+
+It provides **retry policies**, **circuit breakers**, **fallbacks**, **jittered backoff**, **async/sync support**, and more
+
+---
+
+## Features
+
+- Retry on **exceptions** or **result conditions**  
+- Configurable **retry count** and **max retry duration**  
+- **Exponential**, **linear**, or **custom backoff** strategies  
+- **Jitter** support to prevent thundering herd  
+- **Circuit breaker** with open, half-open, and closed states  
+- **Sync and async fallback actions**  
+- Retry **with cancellation tokens**  
+- Logging and async callbacks for retries and circuit breaker events  
+- Thread-safe for **multi-threaded operations**  
+- Named policies for reusable resilience configurations  
+
+---
+
+## Installation
+
+Install via NuGet:
+
+```bash
+dotnet add package EonaCat.SmartRetry
+```
+
+Or via Package Manager:
+```csharp
+Install-Package EonaCat.SmartRetry
+```
+
+# Usage Examples
+## Basic Retry with Fallback
+
+```csharp
+using EonaCat.SmartRetry;
+
+var policy = SmartRetryPolicy.Policy()
+    .Handle<TimeoutException>()
+    .Retry(3)
+    .WithExponentialBackoff(1, 2)
+    .WithFallbackAsync(async () =>
+    {
+        Console.WriteLine("Executing fallback...");
+        await Task.Delay(50);
+
+        // fallback value
+        return 42; 
+    });
+
+int result = await policy.ExecuteAsync<int>(async () =>
+{
+    Console.WriteLine("Attempting operation...");
+    await Task.Delay(50);
+    throw new TimeoutException("Simulated failure");
+});
+
+// Outputs: 42
+Console.WriteLine($"Result: {result}"); 
+```
+
+
+## Retry with Circuit Breaker, Jitter, and Logging
+
+```csharp
+var policy = SmartRetryPolicy.Policy()
+    .Handle<TimeoutException>()
+    .Retry(5)
+    .WithExponentialBackoff(1, 2)
+    .WithJitter(0.2)
+    .WithCircuitBreaker(failureThreshold: 3, openDuration: TimeSpan.FromSeconds(10))
+    .WithFallbackAsync(async () =>
+    {
+        Console.WriteLine("Executing fallback...");
+        await Task.Delay(50);
+        return -1;
+    })
+    .OnRetry((attempt, ex) => Console.WriteLine($"Retry {attempt}: {ex.Message}"))
+    .OnCircuitOpen(() => Console.WriteLine("Circuit breaker opened"))
+    .OnCircuitClose(() => Console.WriteLine("Circuit breaker closed"));
+
+int result = await policy.ExecuteAsync<int>(async (ct) =>
+{
+    Console.WriteLine("Attempting operation...");
+    await Task.Delay(50, ct);
+    throw new TimeoutException("Simulated failure");
+});
+
+Console.WriteLine($"Result: {result}");
+
+```
+
+## Retry Based on Result Condition
+```csharp
+var policy = SmartRetryPolicy.Policy()
+    .RetryIf<int>(value => value < 0) // retry if result is negative
+    .Retry(3)
+    .WithLinearBackoff(0.5)
+    .WithFallback(() => 0);
+
+int result = policy.Execute(() =>
+{
+    Console.WriteLine("Returning -1 to trigger retry...");
+    return -1;
+});
+
+// Outputs: 0 (fallback)
+Console.WriteLine($"Result: {result}"); 
+
+```
+
+# Advanced Features
+
+* Max Retry Duration: Stop retrying after a total duration.
+* CancellationToken Support: Cancel retry loops gracefully.
+* Custom Backoff Functions: Provide your own delay logic.
+* Async Logging Hooks: Integrate with metrics or monitoring systems.
+* Named Policies: Standardize retry/circuit-breaker behavior across your app.