Update readme

Author: ejsmith

README.md

@@ -1,142 +1,137 @@
 # Foundatio.Mediator
 
-**The fastest convention-based C# mediator library with source generators**
 
 [![NuGet](https://img.shields.io/nuget/v/Foundatio.Mediator.svg)](https://www.nuget.org/packages/Foundatio.Mediator/)
-[![Performance](https://img.shields.io/badge/performance-2x%20close%20to%20direct%20calls-brightgreen)](#performance-benchmarks)
-[![Memory](https://img.shields.io/badge/memory-zero%20allocation-blue)](#performance-benchmarks)
 
-Foundatio.Mediator is a high-performance, convention-based mediator library that leverages C# source generators and cutting-edge interceptors to achieve near-direct method call performance. No interfaces, no base classes, no reflection at runtime—just clean, simple code that flies.
+Blazingly fast, convention-based C# mediator powered by source generators and interceptors.
 
-## ✨ Why Choose Foundatio.Mediator?
+## High-Level Features
 
-- **🚀 Blazing Fast** - Nearly as fast as direct method calls, 3x faster than MediatR
-- **🎯 Convention-Based** - No interfaces or base classes required
-- **⚡ Source Generated** - Compile-time code generation for optimal performance
-- **🔧 Full DI Integration** - Works seamlessly with Microsoft.Extensions.DependencyInjection
-- **🎪 Middleware Pipeline** - Elegant middleware support
-- **� Cascading Messages** - Tuple returns automatically trigger follow-up events
-- **�📦 Auto Registration** - Handlers discovered and registered automatically
-- **🔒 Compile-Time Safety** - Rich diagnostics catch errors before runtime
-- **🔧 C# Interceptors** - Direct method calls using cutting-edge C# interceptor technology
-- **🎯 Built-in Result Type** - Comprehensive discriminated union for handling all operation outcomes
+- 🚀 Near-direct call performance, zero runtime reflection
+- ⚡ Convention-based handler discovery (no interfaces/base classes)
+- 🔧 Full DI support via Microsoft.Extensions.DependencyInjection
+- 🧩 Plain handler classes or static methods—just drop them in
+- 🎪 Middleware pipeline with Before/After/Finally hooks
+- 🎯 Built-in Result and Result\<T> types for rich status handling
+- 🔄 Automatic cascading messages via tuple returns
+- 🔒 Compile-time diagnostics and validation
+- 📦 Auto-registration with no boilerplate
 
-## 🚀 Quick Start
+## 1. Simple Handler
 
-### 1. Install the Package
+Just add any class ending with `Handler` or `Consumer`:
 
-```bash
-dotnet add package Foundatio.Mediator
+```csharp
+public record Ping(string Text);
+
+public static class PingHandler
+{
+    public static string Handle(Ping msg) => $"Pong: {msg.Text}";
+}
 ```
 
-### 2. Register the Mediator
+Call it:
 
 ```csharp
-services.AddMediator();
+var reply = mediator.Invoke<string>(new Ping("Hello"));
 ```
 
-### 3. Create Clean, Simple Handlers with Built-in Result Types
+## 2. Dependency Injection in Handlers
+
+Supports constructor and method injection:
 
 ```csharp
-// Messages (any class/record)
-public record CreateUserCommand
+public class EmailHandler
 {
-    [Required, StringLength(50, MinimumLength = 2)]
-    public string Name { get; set; } = string.Empty;
-
-    [Required, EmailAddress]
-    public string Email { get; set; } = string.Empty;
+    private readonly IEmailService _svc;
+    public EmailHandler(IEmailService svc) => _svc = svc;
 
-    [Range(18, 120)]
-    public int Age { get; set; }
+    public Task HandleAsync(SendEmail cmd, ILogger<EmailHandler> log, CancellationToken ct)
+    {
+        log.LogInformation("Sending to {To}", cmd.To);
+        return _svc.SendAsync(cmd.To, cmd.Subject, cmd.Body, ct);
+    }
 }
+```
 
-public record User(int Id, string Name, string Email, int Age, DateTime CreatedAt);
+## 3. Simple Middleware
 
-// Handlers return Result<T> for comprehensive status handling
-public class CreateUserCommandHandler
+Discovered by convention; static or instance with DI:
+
+```csharp
+public static class ValidationMiddleware
 {
-    public async Task<Result<User>> HandleAsync(CreateUserCommand command, CancellationToken cancellationToken = default)
-    {
-        // Business logic validation
-        if (command.Email == "existing@example.com")
-            return Result.Conflict("A user with this email already exists");
+    public static HandlerResult Before(object msg)
+        => MiniValidator.TryValidate(msg, out var errs)
+           ? HandlerResult.Continue()
+           : HandlerResult.ShortCircuit(Result.Invalid(errs));
+}
+```
 
-        // Create the user
-        var user = new User(
-            Id: Random.Shared.Next(1000, 9999),
-            Name: command.Name,
-            Email: command.Email,
-            Age: command.Age,
-            CreatedAt: DateTime.UtcNow
-        );
+## 4. Logging Middleware Example
 
-        return user; // Implicit conversion to Result<User>
+```csharp
+public class LoggingMiddleware
+{
+    public Stopwatch Before(object msg) => Stopwatch.StartNew();
+
+    public void Finally(object msg, Stopwatch sw, Exception? ex)
+    {
+        sw.Stop();
+        if (ex != null)
+            Console.WriteLine($"Error in {msg.GetType().Name}: {ex.Message}");
+        else
+            Console.WriteLine($"Handled {msg.GetType().Name} in {sw.ElapsedMilliseconds}ms");
     }
 }
 ```
 
-### 4. Use the Mediator with Result Pattern
+## 5. Using Result<T>
 
 ```csharp
-var mediator = serviceProvider.GetRequiredService<IMediator>();
-
-// Create a user with comprehensive result handling
-var result = await mediator.InvokeAsync<Result<User>>(new CreateUserCommand
-{
-    Name = "John Doe",
-    Email = "john@example.com",
-    Age = 30
-});
-
-// Handle different outcomes with pattern matching
-var response = result.Status switch
+public class GetUserHandler
 {
-    ResultStatus.Ok => $"User created successfully: {result.Value.Name}",
-    ResultStatus.Invalid => $"Validation failed: {string.Join(", ", result.Errors.Select(e => e.ErrorMessage))}",
-    ResultStatus.Conflict => $"Conflict: {result.ErrorMessage}",
-    _ => "Unexpected result"
-};
-
-Console.WriteLine(response);
+    public Task<Result<User>> HandleAsync(GetUser cmd)
+        => _repo.Find(cmd.Id) is { } user
+           ? Task.FromResult(Result.Ok(user))
+           : Task.FromResult(Result.NotFound($"User {cmd.Id} not found"));
+}
 ```
 
-## 🎯 Built-in Result Type - Essential for Message-Oriented Architecture
+## 6. Invocation API
 
-Foundatio.Mediator includes a comprehensive `Result` and `Result<T>` type that acts as a discriminated union, allowing handlers to return different operation outcomes without exceptions. This is crucial for message-oriented architectures where you need to handle various scenarios gracefully.
+```csharp
+// With response
+var user = await mediator.InvokeAsync<User>(new GetUser(id));
 
-### Why Result Types Matter
+// Without response
+await mediator.InvokeAsync(new Ping("Hi"));
+```
 
-In message-oriented systems, operations can have many outcomes beyond just success/failure:
+## 7. Tuple Returns & Cascading Messages
 
-- **Success** with data
-- **Validation errors** with detailed field-level messages
-- **Business rule violations** (conflicts, unauthorized access)
-- **Not found** scenarios
-- **Created** responses with location information
+Handlers can return tuples; one matches the response, the rest are published:
 
-The Result type captures all these scenarios in a type-safe way without throwing exceptions.
+```csharp
+public async Task<(User user, UserCreated evt)> HandleAsync(CreateUser cmd)
+{
+    var user = await _repo.Add(cmd);
+    return (user, new UserCreated(user.Id));
+}
 
-### Result Creation Methods
+// Usage
+var user = await mediator.InvokeAsync<User>(new CreateUser(...));
+// UserCreated is auto-published
+```
+
+## 8. Publish API
 
 ```csharp
-// Success results
-var user = new User(1, "John", "john@example.com", 30, DateTime.UtcNow);
-return user;                                    // Implicit conversion to Result<User>
-return Result.Ok(user);                        // Explicit success
-return Result.Created(user, "/api/users/1");   // Created with location
-
-// Error results
-return Result.NotFound("User not found");
-return Result.Invalid(validationErrors);
-return Result.Conflict("Email already exists");
-return Result.Unauthorized("Login required");
-
-// Generic results (non-generic Result class)
-return Result.Ok();           // Success with no return value
-return Result.NoContent();    // Success with no content
+await mediator.PublishAsync(new OrderShipped(orderId));
 ```
 
+All handlers run in parallel; if any fail, PublishAsync throws.
+
 ### Example: Complete CRUD with Result Types
 
 ```csharp
@@ -273,107 +268,6 @@ public class ComplexOrderHandler
 }
 ```
 
-## 🎪 Beautiful Middleware Pipeline
-
-Create elegant middleware that runs before, after, and finally around your handlers. Middleware works seamlessly with the Result type for comprehensive error handling:
-
-```csharp
-public class LoggingMiddleware
-{
-    private readonly ILogger<LoggingMiddleware> _logger;
-
-    public LoggingMiddleware(ILogger<LoggingMiddleware> logger)
-    {
-        _logger = logger;
-    }
-
-    public Stopwatch Before(object message)
-    {
-        _logger.LogInformation("Processing {MessageType}", message.GetType().Name);
-        return Stopwatch.StartNew();
-    }
-
-    public void Finally(object message, Stopwatch stopwatch, Exception? exception)
-    {
-        stopwatch.Stop();
-        if (exception != null)
-        {
-            _logger.LogError(exception, "Error processing {MessageType}", message.GetType().Name);
-        }
-        else
-        {
-            _logger.LogInformation("Completed {MessageType} in {ElapsedMs}ms",
-                message.GetType().Name, stopwatch.ElapsedMilliseconds);
-        }
-    }
-}
-
-public static class ValidationMiddleware
-{
-    public static HandlerResult Before(object message)
-    {
-        if (MiniValidator.TryValidate(message, out var errors))
-            return HandlerResult.Continue();
-
-        var validationErrors = errors.SelectMany(kvp =>
-            kvp.Value.Select(errorMessage => new ValidationError(kvp.Key, errorMessage))).ToList();
-
-        return HandlerResult.ShortCircuit(Result.Invalid(validationErrors));
-    }
-}
-```
-
-With this middleware, your handlers automatically get validation without any boilerplate:
-
-```csharp
-// This command will be automatically validated by ValidationMiddleware
-var result = await mediator.InvokeAsync<Result<User>>(new CreateUserCommand
-{
-    Name = "", // Invalid - too short
-    Email = "not-an-email", // Invalid - bad format
-    Age = 10 // Invalid - too young
-});
-
-if (result.Status == ResultStatus.Invalid)
-{
-    foreach (var error in result.Errors)
-        Console.WriteLine($"{error.PropertyName}: {error.ErrorMessage}");
-}
-```
-
-## 💉 Dependency Injection Made Simple
-
-Handlers support both constructor and method-level dependency injection:
-
-```csharp
-public class SendWelcomeEmailHandler
-{
-    private readonly IEmailService _emailService;
-    private readonly IGreetingService _greetingService;
-    private readonly ILogger<SendWelcomeEmailHandler> _logger;
-
-    public SendWelcomeEmailHandler(
-        IEmailService emailService,
-        IGreetingService greetingService,
-        ILogger<SendWelcomeEmailHandler> logger)
-    {
-        _emailService = emailService;
-        _greetingService = greetingService;
-        _logger = logger;
-    }
-
-    public async Task HandleAsync(
-        SendWelcomeEmailCommand command,
-        CancellationToken cancellationToken = default) // Provided by mediator
-    {
-        _logger.LogInformation("Sending welcome email to {Email}", command.Email);
-
-        var greeting = _greetingService.CreateGreeting(command.Name);
-        await _emailService.SendEmailAsync(command.Email, "Welcome!", greeting);
-    }
-}
-```
-
 ## 📊 Performance Benchmarks
 
 Foundatio.Mediator delivers exceptional performance, getting remarkably close to direct method calls while providing full mediator pattern benefits:
@@ -454,30 +348,9 @@ public interface IMediator
 
     // Publishing (multiple handlers)
     Task PublishAsync(object message, CancellationToken cancellationToken = default);
-    void Publish(object message, CancellationToken cancellationToken = default);
 }
 ```
 
-## 🎬 Sample Applications
-
-### ConsoleSample - Comprehensive Demonstration
-
-The `samples/ConsoleSample` project provides a complete demonstration of all Foundatio.Mediator features:
-
-- **Simple Commands & Queries** - Basic fire-and-forget and request/response patterns
-- **Dependency Injection** - Handler methods with injected services and logging
-- **Publish/Subscribe** - Multiple handlers for the same event
-- **Mixed Sync/Async** - Both synchronous and asynchronous handler examples
-- **Middleware Pipeline** - Global and message-specific middleware examples
-- **Service Integration** - Email, SMS, and audit service examples
-
-To run the comprehensive sample:
-
-```bash
-cd samples/ConsoleSample
-dotnet run
-```
-
 ## ⚙️ How It Works
 
 The source generator:
@@ -516,8 +389,6 @@ foreach (var handler in handlers)
 
 - **Interceptors First** - Same-assembly calls use interceptors for maximum performance
 - **DI Fallback** - Cross-assembly handlers and publish operations use DI registration
-- **Automatic Selection** - The generator chooses the optimal strategy per call site
-- **Keyed Services** - Handlers registered by fully qualified message type name
 - **Zero Runtime Overhead** - Interceptors bypass all runtime lookup completely
 
 **Benefits:**