Added new typesafe helper in Result object to get metadata 'TValue? GetMetadataValueOrDefault<TValue>(string key)'

Author: AlanBarber

docs/wiki/Error-Handling.md

@@ -219,6 +219,22 @@ public async ValueTask<Result<Order>> HandleAsync(
 }
 ```
 
+Retrieve metadata values with type safety using `GetMetadataValueOrDefault<TValue>`:
+
+```csharp
+if (result.IsFailure)
+{
+    // Type-safe retrieval - returns default if key missing or type mismatch
+    var customerId = result.GetMetadataValueOrDefault<int>("CustomerId");
+    var itemCount = result.GetMetadataValueOrDefault<int>("ItemCount");
+    var timestamp = result.GetMetadataValueOrDefault<DateTime>("Timestamp");
+    
+    _logger.LogError(
+        "Order creation failed for customer {CustomerId} with {ItemCount} items at {Timestamp}",
+        customerId, itemCount, timestamp);
+}
+```
+
 ## Logging Errors
 
 Use `AfterHandleAsync` for consistent error logging:

docs/wiki/The-Result-Type.md

@@ -94,8 +94,16 @@ var result = Result<User>.Success(user)
     .WithMetadata("Source", "API")
     .WithMetadata("RequestId", Guid.NewGuid());
 
-// Access metadata
-var createdAt = (DateTime)result.Metadata["CreatedAt"];
+// Access metadata with type-safe helper
+var createdAt = result.GetMetadataValueOrDefault<DateTime>("CreatedAt");
+var source = result.GetMetadataValueOrDefault<string>("Source");
+
+// Returns default if key doesn't exist or type doesn't match
+var missing = result.GetMetadataValueOrDefault<int>("NonExistent"); // Returns 0
+var wrongType = result.GetMetadataValueOrDefault<string>("CreatedAt"); // Returns null
+
+// Direct dictionary access is also available
+var requestId = (Guid)result.Metadata["RequestId"];
 ```
 
 ## Patterns

src/ResultR.Tests/ResultTests/ResultTests.cs

@@ -57,4 +57,53 @@ public void Metadata_ReturnsEmptyDictionary_WhenNoMetadataSet()
 
         Assert.Empty(result.Metadata);
     }
+
+    [Fact]
+    public void GetMetadataValueOrDefault_ReturnsValue_WhenKeyExistsAndTypeMatches()
+    {
+        var result = Result.Success()
+            .WithMetadata("StringKey", "TestValue")
+            .WithMetadata("IntKey", 42);
+
+        Assert.Equal("TestValue", result.GetMetadataValueOrDefault<string>("StringKey"));
+        Assert.Equal(42, result.GetMetadataValueOrDefault<int>("IntKey"));
+    }
+
+    [Fact]
+    public void GetMetadataValueOrDefault_ReturnsDefault_WhenKeyDoesNotExist()
+    {
+        var result = Result.Success();
+
+        Assert.Null(result.GetMetadataValueOrDefault<string>("NonExistentKey"));
+        Assert.Equal(0, result.GetMetadataValueOrDefault<int>("NonExistentKey"));
+    }
+
+    [Fact]
+    public void GetMetadataValueOrDefault_ReturnsDefault_WhenTypeMismatch()
+    {
+        var result = Result.Success()
+            .WithMetadata("IntKey", 42);
+
+        Assert.Null(result.GetMetadataValueOrDefault<string>("IntKey"));
+    }
+
+    [Fact]
+    public void GetMetadataValueOrDefault_ReturnsDefault_WhenNoMetadataSet()
+    {
+        var result = Result.Success();
+
+        Assert.Null(result.GetMetadataValueOrDefault<object>("AnyKey"));
+    }
+
+    [Fact]
+    public void GetMetadataValueOrDefault_WorksWithComplexTypes()
+    {
+        var complexObject = new List<int> { 1, 2, 3 };
+        var result = Result.Success()
+            .WithMetadata("ListKey", complexObject);
+
+        var retrieved = result.GetMetadataValueOrDefault<List<int>>("ListKey");
+
+        Assert.Same(complexObject, retrieved);
+    }
 }

src/ResultR/Result.cs

@@ -76,6 +76,23 @@ public Result WithMetadata(string key, object value)
         _metadata[key] = value;
         return this;
     }
+
+    /// <summary>
+    /// Retrieves a metadata value by key, cast to the specified type.
+    /// Returns the default value for the type if the key does not exist or the value cannot be cast.
+    /// </summary>
+    /// <typeparam name="TValue">The type to cast the metadata value to.</typeparam>
+    /// <param name="key">The metadata key.</param>
+    /// <returns>The metadata value cast to <typeparamref name="TValue"/>, or <c>default</c> if not found or cast fails.</returns>
+    public TValue? GetMetadataValueOrDefault<TValue>(string key)
+    {
+        if (_metadata is null || !_metadata.TryGetValue(key, out var value))
+        {
+            return default;
+        }
+
+        return value is TValue typedValue ? typedValue : default;
+    }
 }
 
 /// <summary>