feat: add assertion helpers, async primitives, and EFCore extensions

New features across multiple packages:
- Testing: assertion extensions for objects, booleans, comparables,
  strings, and exceptions (ShouldBeNull, ShouldBeTrue, ShouldThrow, etc.)
- Threading: AsyncLazy<T>, Debouncer, and Throttler
- Data.EFCore: soft-delete (ISoftDeletable) and audit trail
  (IAuditableEntity) with DbContext extensions
- Data.Validation: IAsyncValidator and AsyncValidatorCollection
- Networking: MultipartFormDataPostNetworkRequest and
  RetryDelegatingHandler with exponential backoff
- Web.Mvc: ForbiddenObjectResult (403) with controller extensions

Also adds CancellationToken support to async methods that were
missing it, and updates documentation for all new and existing
features.

Author: jamesmcroft

assets/Logo.afdesign

@@ -103,3 +103,81 @@ The `MADE.Data.EFCore.Extensions.QueryableExtensions` class provides helpers for
 
 - `Page<T>` - Applies skip and take pagination to a query based on page number and page size.
 - `OrderBy<T>` - Dynamically orders query results by a property name string, with optional descending sort.
+
+## Soft-delete support with ISoftDeletable
+
+The `MADE.Data.EFCore.ISoftDeletable` interface adds soft-delete support to your entities. Instead of permanently removing records, entities are marked as deleted and filtered out of queries by default.
+
+```csharp
+public class User : EntityBase, ISoftDeletable
+{
+    public string Name { get; set; }
+
+    public bool IsDeleted { get; set; }
+
+    public DateTime? DeletedDate { get; set; }
+}
+```
+
+### Applying a global query filter
+
+Use `ApplySoftDeleteFilter` in your model builder to automatically exclude soft-deleted entities from all queries:
+
+```csharp
+protected override void OnModelCreating(ModelBuilder modelBuilder)
+{
+    modelBuilder.ApplySoftDeleteFilter();
+}
+```
+
+To query soft-deleted entities, use `IgnoreQueryFilters()` on a specific query.
+
+### Automatic soft-delete interception
+
+Use `InterceptSoftDeletions` in your `SaveChangesAsync` override to automatically convert hard deletes to soft deletes:
+
+```csharp
+public override async Task<int> SaveChangesAsync(CancellationToken cancellationToken = default)
+{
+    this.InterceptSoftDeletions();
+    this.SetEntityDates();
+    return await base.SaveChangesAsync(cancellationToken);
+}
+```
+
+### Manual soft-delete and restore
+
+The `SoftDelete` and `Restore` extension methods allow you to explicitly manage the soft-delete state:
+
+```csharp
+user.SoftDelete();  // Sets IsDeleted = true and DeletedDate
+user.Restore();     // Clears IsDeleted and DeletedDate
+```
+
+## Audit trail support with IAuditableEntity
+
+The `MADE.Data.EFCore.IAuditableEntity` interface adds user tracking to your entities, recording who created and last updated each record.
+
+```csharp
+public class Order : EntityBase, IAuditableEntity
+{
+    public string Description { get; set; }
+
+    public string? CreatedBy { get; set; }
+
+    public string? UpdatedBy { get; set; }
+}
+```
+
+### Automatic audit info tracking
+
+Use `SetEntityAuditInfo` in your `SaveChangesAsync` override to automatically set audit fields:
+
+```csharp
+public override async Task<int> SaveChangesAsync(CancellationToken cancellationToken = default)
+{
+    this.SetEntityDates();
+    this.SetEntityAuditInfo(currentUserId);
+    return await base.SaveChangesAsync(cancellationToken);
+}
+```

assets/Logo.png

@@ -247,3 +247,57 @@ The `MADE.Data.Validation.FluentValidation` package provides an easy way to take
 Using the `MADE.Data.Validation.FluentValidatorCollection<T>` based on a `List` type, you can construct a collection of `AbstractValidator` instances which can be used to validate values.
 
 This way, you can bring FluentValidation's out-of-the-box validators or your own custom validators based on the `AbstractValidator` type and get all the benefits of using the existing MADE.NET validation framework. This is great for example with input validator controls that currently support the MADE.NET validation framework!
+
+## Asynchronous validation with IAsyncValidator
+
+For validation scenarios that require I/O operations (such as checking uniqueness against a database), the `IAsyncValidator` interface and `AsyncValidatorCollection` provide an asynchronous validation pipeline.
+
+### Creating an async validator
+
+Implement the `IAsyncValidator` interface for validators that need to perform asynchronous work:
+
+```csharp
+public class UniqueEmailValidator : IAsyncValidator
+{
+    private readonly IUserRepository repository;
+
+    public UniqueEmailValidator(IUserRepository repository)
+    {
+        this.repository = repository;
+    }
+
+    public string Key { get; set; } = nameof(UniqueEmailValidator);
+
+    public bool IsInvalid { get; set; }
+
+    public bool IsDirty { get; set; }
+
+    public string FeedbackMessage { get; set; } = "Email address is already in use.";
+
+    public async Task ValidateAsync(object value, CancellationToken cancellationToken = default)
+    {
+        var email = value?.ToString();
+        this.IsInvalid = !string.IsNullOrWhiteSpace(email)
+            && await this.repository.EmailExistsAsync(email, cancellationToken);
+        this.IsDirty = true;
+    }
+}
+```
+
+### Using the AsyncValidatorCollection
+
+The `AsyncValidatorCollection` works the same as the `ValidatorCollection` but executes each validator asynchronously:
+
+```csharp
+var validators = new AsyncValidatorCollection
+{
+    new UniqueEmailValidator(userRepository),
+};
+
+await validators.ValidateAsync(emailAddress);
+
+if (validators.IsInvalid)
+{
+    var messages = validators.FeedbackMessages;
+}
+```

assets/ProjectBanner.afdesign

@@ -85,3 +85,39 @@ public void UpdateProfileDetails(Profile profile)
 `NetworkRequest` objects have a `Guid` identifier also, so if you need to update a pending request with different data or a change in URL, you can do simply by recalling `NetworkManager.AddOrUpdate` passing in a network request with the same ID.
 
 The `AddOrUpdate` method has overloads for providing a success callback, as well as an error callback. This allows you to make decisions in your code to handle a successful or failed network request.
+
+## Uploading files with MultipartFormDataPostNetworkRequest
+
+The `MultipartFormDataPostNetworkRequest` allows you to upload files and form data using multipart/form-data encoding. It provides a fluent API for building the request content.
+
+```csharp
+public async Task<UploadResult> UploadFileAsync(Stream fileStream, string fileName, CancellationToken cancellationToken = default)
+{
+    var request = new MultipartFormDataPostNetworkRequest(new HttpClient(), "https://api.example.com/upload")
+        .AddStreamContent("file", fileStream, fileName, "image/png")
+        .AddStringContent("description", "Profile photo");
+
+    return await request.ExecuteAsync<UploadResult>(cancellationToken);
+}
+```
+
+You can add multiple types of content:
+
+- `AddStringContent` - Adds a string form field.
+- `AddStreamContent` - Adds a file stream with a file name and content type.
+- `AddByteArrayContent` - Adds byte array content with a file name and content type.
+
+## Adding retry support with RetryDelegatingHandler
+
+The `RetryDelegatingHandler` is a `DelegatingHandler` that automatically retries failed HTTP requests with exponential backoff. It handles transient failures including timeouts, server errors (500, 502, 503, 504), and rate limiting (429).
+
+```csharp
+var handler = new RetryDelegatingHandler(maxRetries: 3, initialDelay: TimeSpan.FromSeconds(1));
+var client = new HttpClient(handler);
+
+// All requests made with this client will automatically retry on transient failures
+var request = new JsonGetNetworkRequest(client, "https://api.example.com/data");
+var result = await request.ExecuteAsync<MyData>();
+```
+
+The handler uses exponential backoff, doubling the delay between each retry attempt. You can customize the maximum number of retries and the initial delay via the constructor parameters.

assets/ProjectBanner.png

@@ -38,3 +38,96 @@ public void InvalidTest()
 ```
 
 You can also perform the same check for scenarios where the collections are **not** equivalent.
+
+## Asserting null state with ObjectAssertExtensions
+
+The `ShouldBeNull` and `ShouldNotBeNull` extension methods for any object allow you to assert the null state of a value.
+
+```csharp
+[Test]
+public void ShouldBeNullTest()
+{
+    object? value = null;
+    value.ShouldBeNull();
+}
+
+[Test]
+public void ShouldNotBeNullTest()
+{
+    object value = new();
+    value.ShouldNotBeNull();
+}
+```
+
+## Asserting boolean values with BooleanAssertExtensions
+
+The `ShouldBeTrue` and `ShouldBeFalse` extension methods for `bool` values allow you to assert the expected state of a boolean.
+
+```csharp
+[Test]
+public void ShouldBeTrueTest()
+{
+    bool result = true;
+    result.ShouldBeTrue();
+}
+
+[Test]
+public void ShouldBeFalseTest()
+{
+    bool result = false;
+    result.ShouldBeFalse();
+}
+```
+
+## Comparing values with ComparableAssertExtensions
+
+The `ShouldBeGreaterThan`, `ShouldBeGreaterThanOrEqualTo`, `ShouldBeLessThan`, and `ShouldBeLessThanOrEqualTo` extension methods allow you to assert the comparison of `IComparable` values.
+
+```csharp
+[Test]
+public void ComparisonTest()
+{
+    int value = 10;
+    value.ShouldBeGreaterThan(5);
+    value.ShouldBeLessThan(20);
+    value.ShouldBeGreaterThanOrEqualTo(10);
+    value.ShouldBeLessThanOrEqualTo(10);
+}
+```
+
+## Asserting strings with StringAssertExtensions
+
+The `ShouldContain`, `ShouldNotContain`, `ShouldStartWith`, and `ShouldEndWith` extension methods allow you to assert the contents of strings.
+
+```csharp
+[Test]
+public void StringAssertionTest()
+{
+    string value = "Hello, World!";
+    value.ShouldContain("World");
+    value.ShouldNotContain("Goodbye");
+    value.ShouldStartWith("Hello");
+    value.ShouldEndWith("World!");
+}
+```
+
+## Asserting exceptions with ExceptionAssertExtensions
+
+The `ShouldThrow` and `ShouldNotThrow` extension methods allow you to assert that an action throws or does not throw an exception. Async variants `ShouldThrowAsync` and `ShouldNotThrowAsync` are also available.
+
+```csharp
+[Test]
+public void ShouldThrowTest()
+{
+    Action action = () => throw new InvalidOperationException("Oops");
+    var exception = action.ShouldThrow<InvalidOperationException>();
+    // exception.Message is "Oops"
+}
+
+[Test]
+public void ShouldNotThrowTest()
+{
+    Action action = () => { /* no error */ };
+    action.ShouldNotThrow();
+}
+```