Compze.Contracts 0.7.0

Compze.Contracts

Fluent, chainable runtime assertions for preconditions, invariants, and state checks — with CallerArgumentExpression support for clear failure messages.

Quick start

Fluent with static use. No wasted lines. The contract reads like part of the method declaration.

void Transfer(Account from, Account to, decimal amount) => 
    Argument.NotNull2(from, to).Assert(amount > 0).State.NotDisposed(_disposed, this).__(() => {
        //method implementation here
    });

Note, the __ method is from Compze.Underscore. You may want to check it out.

Classic style. Pretty verbose in our opinion

void Transfer(Account from, Account to, decimal amount)
{
    Contract.Argument.NotNull2(from, to);
    Contract.Argument.Assert(amount > 0);
    Contract.State.NotDisposed(_disposed, this);
    //method implementation here
}

All the assertion methods that do not take an explicit separate argument for the message use CallerArgumentExpression to ensure that you can know exactly what assertion failed

Mixing it up with Compze.Fluent

public OperationResult SomeBusinessMethod(Guid userId) =>
    userId
    ._assert().NotDefault()
    ._(LoadFromDatabase)
    ._tap(it => { /*log*/ })
    ._assert(MayExecuteThisOperation)
    ._(ActualOperationLogic)
    ._tap(it => { /*log*/ })
    ._assert(ResultIsWhatWeExpected);

Pipeline assertions

For inline assertions, avoiding the need for duplicate lines and breaking out of the fluent style:

var name = GetName()._assert(it => it.Length > 0);          // predicate with auto-generated message
var id   = GetId()._assert(it => it != Guid.Empty, it => $"Invalid id: {it}");      // predicate with custom message factory
var conn = GetConnection()._assert().NotNull(); 

Pipeline overloads:

• value._assert() — returns PipeAssertTarget<T> for .NotNull() / .NotDefault() chains
• value._assert(predicate) — throws AssertionFailedException("value._assert(predicate)") on failure
• value._assert(predicate, messageFactory) — throws AssertionFailedException with custom message
• value._assert(predicate, exceptionFactory) — throws custom exception

All the assertion methods that do not take an explicit separate argument for the message use CallerArgumentExpression to ensure that you can know exactly what assertion failed

Custom assertion extensions

Both ContractAsserter and PipeAssertTarget<T> are designed to be extended. All built-in assertions are themselves extension methods.

ContractAsserter extension

public static class MyContractExtensions
{
   extension(ContractAsserter @this)
   {
      public ContractAsserter IsValidEmail(string? value,
                                           [CallerArgumentExpression(nameof(value))] string expression = "")
      {
         if(!value.IsValidEmail()) @this.ThrowFailed(expression);
         return @this;
      }
   }
}

//throws: ArgumentAssertionFailedException("Argument.IsValidEmail(userEmail)") if invalid.
Contract.Argument.IsValidEmail(userEmail); 

PipeAssertTarget extension (pipeline)

public static class MyPipelineExtensions
{
   public static string IsValidEmail(this PipeAssertTarget<string?> target)
   {
      if(!target.Value.IsValidEmail()) target.ThrowAssertionFailed();
      return target.Value!;
   }
}

// throws:  AssertionFailedException("GetUserEmail()._assert().IsValidEmail()") if invalid.
var email = GetUserEmail()._assert().IsValidEmail();

License

Apache-2.0