Merge pull request #1 from andrej-dyck/feature/check-expressions

Add check expressions

Author: andrej-dyck

DotNet.Extensions.Require.Test/ChecksTests.cs

@@ -0,0 +1,76 @@
+using NUnit.Framework;
+using NUnit.Framework.Internal;
+
+namespace DotNet.Extensions.Require.Test;
+
+public sealed class ChecksTests
+{
+    [Test]
+    public void Check_ThrowsCheckFailed_WhenRequirementIsNotSatisfied() =>
+        Assert.Throws<CheckFailed>(
+            () => 1.Check(v => v != 1, expectation: "message")
+        )?.WithMessage("message");
+
+    [Test]
+    public void Check_DoesNotThrow_WhenRequirementIsSatisfied() =>
+        Assert.DoesNotThrow(
+            () => 1.Check(v => v == 1, expectation: string.Empty)
+        );
+
+    [Test]
+    public void Check_ThrowsBuiltException_WhenRequirementIsNotSatisfied() =>
+        Assert.Throws<SomeExceptionType>(
+            () => 1.Check(v => v != 1, () => new SomeExceptionType("message"))
+        )?.WithMessage("message");
+
+    [Test]
+    public void Check_CanConstructException_WithTheValue() =>
+        Assert.Throws<SomeExceptionType>(
+            () => 1.Check(v => v != 1, v => new SomeExceptionType($"message with {v}"))
+        )?.WithMessage("message with 1");
+
+    [Test]
+    public void Check_DoesNotBuildException_WhenRequirementIsSatisfied() => Assert.Multiple(
+        () =>
+        {
+            Assert.DoesNotThrow(
+                () => 1.Check(v => v == 1, expectation: () => throw new NUnitException("must not be called"))
+            );
+            Assert.DoesNotThrow(
+                () => 1.Check(v => v == 1, exception: () => throw new NUnitException("must not be called"))
+            );
+        }
+    );
+
+    [Test]
+    public void Check_DoesNotConstructException_WhenRequirementIsSatisfied() => Assert.Multiple(
+        () =>
+        {
+            Assert.DoesNotThrow(
+                () => 1.Check(
+                    v => v == 1,
+                    expectation: v => throw new NUnitException($"must not be called for {v}"))
+            );
+            Assert.DoesNotThrow(
+                () => 1.Check(v => v == 1, exception: v => throw new NUnitException($"must not be called for {v}"))
+            );
+        }
+    );
+
+    [Test]
+    public void Check_ReturnsTheValueOnWhichItIsCalled_WhenRequirementIsSatisfied() => Assert.Multiple(
+        () =>
+        {
+            Assert.AreEqual(1, 1.Check(value => value == 1, string.Empty));
+            Assert.AreEqual(1, 1.Check(value => value == 1, () => string.Empty));
+            Assert.AreEqual(1, 1.Check(value => value == 1, value => $"{value}"));
+            Assert.AreEqual(1, 1.Check(value => value == 1, () => new CheckFailed(string.Empty)));
+            Assert.AreEqual(1, 1.Check(value => value == 1, value => new CheckFailed($"{value}")));
+        }
+    );
+}
+
+public sealed class SomeExceptionType : Exception
+{
+    public SomeExceptionType(string? message = null) : base(message) { }
+}

DotNet.Extensions.Require.Test/PreconditionsTests.cs

@@ -20,7 +20,7 @@ public void Require_DoesNotThrow_WhenConditionIsTrue() =>
         );
 
     [Test]
-    public void Require_Returns_TheValueOnWhichItIsCalled_WhenConditionIsTrue() =>
+    public void Require_ReturnsTheValueOnWhichItIsCalled_WhenConditionIsTrue() =>
         Assert.AreEqual(
             expected: 1,
             actual: Require(subject: 1, condition: true)
@@ -91,7 +91,7 @@ protected override T Require<T>(T subject, Predicate<T> requirement, string expe
         subject.Require(requirement, expectation: () => expectation);
 
     [Test]
-    public void Require_DoesNotCreateExpectationMessage_WhenRequirementYieldsTrue() =>
+    public void Require_DoesNotCreateExpectationMessage_WhenRequirementIsSatisfied() =>
         Assert.DoesNotThrow(
             () => 1.Require(requirement: _ => true, () => throw new NUnitException("must not be called"))
         );
@@ -109,7 +109,7 @@ public void Require_CanUseTheValue_ToConstructTheExpectation() =>
         )?.WithMessage("message with 1");
 
     [Test]
-    public void Require_DoesNotBuildExpectationMessage_WhenConditionIsTrue() =>
+    public void Require_DoesNotBuildExpectationMessage_WhenRequirementIsSatisfied() =>
         Assert.DoesNotThrow(
             () => 1.Require(requirement: _ => true, value => throw new NUnitException($"must not be called for {value}"))
         );

DotNet.Extensions.Require/Checks.cs

@@ -0,0 +1,24 @@
+namespace DotNet.Extensions.Require;
+
+public static class Checks
+{
+    public static T Check<T>(this T @this, Predicate<T> requirement, string expectation) =>
+        requirement(@this) ? @this : throw new CheckFailed(expectation);
+
+    public static T Check<T>(this T @this, Predicate<T> requirement, Func<string> expectation) =>
+        requirement(@this) ? @this : throw new CheckFailed(expectation());
+
+    public static T Check<T>(this T @this, Predicate<T> requirement, Func<T, string> expectation) =>
+        requirement(@this) ? @this : throw new CheckFailed(expectation(@this));
+
+    public static T Check<T>(this T @this, Predicate<T> requirement, Func<Exception> exception) =>
+        requirement(@this) ? @this : throw exception();
+
+    public static T Check<T>(this T @this, Predicate<T> requirement, Func<T, Exception> exception) =>
+        requirement(@this) ? @this : throw exception(@this);
+}
+
+public sealed class CheckFailed : Exception
+{
+    public CheckFailed(string? message) : base(message) { }
+}

DotNet.Extensions.Require/DotNet.Extensions.Require.csproj

@@ -5,7 +5,7 @@
         <Description>☑ Require Expressions - A pre-condition checks library 📦 for .Net via extensions methods on types.</Description>
         <PackageTags>preconditions;require;guard;code-contracts;argument-checks;extension-methods</PackageTags>
 
-        <Version>1.0.0</Version>
+        <Version>1.1.0</Version>
         <Authors>Andrej Dyck</Authors>
 
         <PackageReadmeFile>README.md</PackageReadmeFile>

README.md

@@ -21,17 +21,17 @@ Reservation Request(DateTime now, DateTime reservationDate, int seats) =>
 dotnet add package Require-Expressions
 ```
 
-## Examples
+## Examples for `Require`
 
-**Basic `Require` function**
+Basic `Require` function
 ```csharp
 var requestedSeats = seats.Require(
     condition: seats > 0,
     expectation: "expected: seats > 0"
-);
+); // throws ArgumentException with expectation as message when condition is not met
 ```
 
-**`Require` functions with lazily constructed expectation messages**
+`Require` functions with lazily constructed expectation messages
 ```csharp
 var requestedSeats = seats.Require(
     condition: seats > 0,
@@ -44,7 +44,7 @@ var requestedDate = reservationDate.Require(
 );
 ```
 
-**`Require` functions with predicate for convenience**
+`Require` functions with predicate for convenience
 ```csharp
 var requestedSeats = seats.Require(
     condition: s => s > 0,
@@ -57,6 +57,23 @@ var requestedDate = reservationDate.Require(
 );
 ```
 
+## Examples for `Check`
+
+For checks other than on arguments, the `Check` function can be used
+```csharp
+var reservationRequest = JsonSerializer.Deserialize<Reservation>(request)
+    .Check(requirement: r => r.Seats > 0, expectation: "expected: seats > 0")
+    .Check(r => r.Date > now, r => $"Reservation date {r.Date} must be in the future")
+    // throws CheckFailed with expectation as message when requirement is not satisfied
+```
+
+With `Check`, custom exceptions can be constructed
+```csharp
+var reservationRequest = JsonSerializer.Deserialize<Reservation>(request)
+    .Check(r => r.Seats > 0, exception: () => new SeatsMustBePositive())
+    .Check(r => r.Date > now, exception: r => new MustBeFutureDateReservateion(r.Date))
+```
+
 ## Q&A
 
 **Why yet another preconditions library?**