Implements several functional Monadic Types which enable clean API- and method-design.
You can find a NuGet-Package at www.nuget.org, containing binaries for different frameworks. There are no special dependencies.
Consider of your code's contracts, such as the fact that an operation could fail or that a required value might not be present. In traditional C#, these contracts are implicit, for example realized through an exception which might be thrown (immediately aborting the current execution path) or by null-values which are supposed to carry that semantic. In short, your programmers must always be aware and on the look-out for these implicitly agreed-upon contracts. Usage of null is particular problematic in this context, as this overloads its semantics! A null now means both not initialized yet and edge/exception-case.
Through the classes within this library, you can leverage the type system of C# to enforce the basic nature of such contracts, which means that you code does not compile until the programmer has ensured that he or she is dealing with e.g. the fact that this particular operation might fail (and what to do in this case).
Defining expressive method contracts, avoiding any usage of null-values in method calls, clearly expressing failure states and overall just writing better code by leveraging C#'s type system.
Contains a number of functional classes of three basic archetypes, intended to be used in a monadic manner. This lib contains:
A Maybe indicates that a value may be present, aka there is either a value or there is no value (but obviously never both). A Maybe is therefore either a Some(X) or a None of a type X.
Example: When querying a data-structure for the presence of some value that is associated with a key, that query-getter may return a Maybe, which is a Some of that value if an association exists.
A Validation indicates that an operation may have failed, aka there is either no value because everything was fine or there is a value signaling a failure (but obviously never both). A Validation is therefore either a Success or a Failure(X) of a type X.
Example: When triggering a write-operation on your file-system, the corresponding function may return a Validation, which is a Failure containing a description of the problem if the write was not successful (e.g. due to permission problems).
See here.
A Failable indicates that either a value is "present" or something went wrong and a different value of a different type is "present". A Failable is therefore either a Success(X) or a Failure(E) of a type X, with E usually being some exception. Note however that such an exception is not thrown, as such no code paths are erroneously skipped and our contract is clean.
Example: When parsing an XML-serialized data-structure, that method may return a Failable, which is a Success containing the deserialized DTO-object if your input was satisfactory. Otherwise, the Failure models what was wrong with the string.
See here.
An Option represents the combination of a Maybe and Failable, indicating that a value is present or not present or that something went wrong. That means, in contrast to the two other classes, this is a ternary instead of a binary result type. An Option is therefore either a Some(X) or None or a Failure(E) of a type X, with E typically being some exception.
Example: When asking some persistence-wrapper for a DTO identified by a specific id via an appropriate method, this wrapper may return an Option. That Option is a Some if your id matches a datapoint in the persistence wrapped by this class (like a database), a None if there is nothing present for that identifier and a Failure if the persistence-layer encountered a technical error (like the database-connection being closed).
See here.
Validation, Failable and Option exist in E-variants, namely EValidation, EFailable and EOption. These classes are basically similar to their regular counterparts, but with the right-side type fixed to Exception. Therefore, these three classes allow for shorter, more readable code and are the recommended way to employ these concepts, unless your use-cases differ significantly from "modelling the result of operations".
var maybeA = Maybe<int>.Some( 1 );
var maybeB = Maybe<int>.None;
var validationA = Validation<string>.Success();
var validationB = Validation<string>.Failure( "Oh no, something went wrong!" );
var failableA = Failable<float, string>.Success( 2.0f );
var failableB = Failable<float, string>.Failure( "Oh no, something went wrong!" );
var optionA = Option<long, string>.Some( 3 );
var optionB = Option<long, string>.None;
var optionC = Option<long, string>.Failure( "Oh no, something went wrong!" );
For the majority of usecases, you will probably employ the E-Variants, which ends up looking like this for example:
var efailableA = EFailable<float>.Success( 2.0f );
var efailableB = EFailable<float>.Failure( new Exception( "Oh no, something went wrong!" ) );
//if we assume this is our contract for some authentication storage...
public interface SessionManager
{
EFailable<UserSessionKey> CreateSession();
Maybe<UserSession> GetSession( UserSessionKey key ); //return type clearly expresses that such a session may be non-existent!
EValidation EndSession( UserSessionKey key );
}
//...we can for example leverage this when employing the monadic-based contract in e.g. REST-API endpoint to write very clean code:
[HttpPost( "usersession/{sessionId}/do_something" )]
[Produces( MediaTypeConstants.Application.Json )]
public ActionResult<ResultOfSomething> ExecuteForExistingUserSession( int sessionId, [FromBody] OtherParams otherParams ) =>
SessionManager.GetSession( new UserSessionKey( sessionId ) )
.Map( session => DoSomething( session, otherParams ) ) //returns a 'ResultOfSomething' containing the result
.Or( ResultOfSomething.MakeError( $" Session '{sessionId}' not found!" ) } );
public class ClockForTests
{
private Maybe<DateTime> _currentTime; //monadic object
//CTOR for real-time clock:
public ClockForTests() => _currentTime = Maybe<DateTime>.None;
//CTOR for fixed-time instance:
public ClockForTests( DateTime definedNow ) => _currentTime = Maybe<DateTime>.Some( definedNow );
//accessor-methods for all testsuites to obtain the currently canonical concept of "the current time"
public DateTime Now => _currentTime.Or( DateTime.Now );
public DateTime UtcNow => _currentTime.Map( d => d.AsUtc() ).Or( DateTime.UtcNow );
//setter-methods to set the currently canonical "current time", depending on the testcase's demands
public void SetCurrentTimeTo( DateTime d ) => _currentTime = Maybe<DateTime>.Some( d );
public void SetToRealTime() => _currentTime = Maybe<DateTime>.None;
}
var efailable = EFailable<MyObject>.Wrapping( () => MyFunctionThatEitherReturnsAnObjectOrThrows( ... ) );
var evalidation = EValidation.Wrapping( () => MyFunctionThatMayThrow( ... ) );
namespace Persistence.Layer.of.my.Application
{
public interface IUserProvider
{
/// <summary>Obtain data based on the <paramref name="id"/>.</summary>
/// <returns>
/// <para>* <see cref="EOption{UserData}.Some(UserData)"/> containing the data identified by <paramref name="id"/>.</para>
/// <para>* <see cref="EOption{UserData}.None"/> if no data exists on the database. </para>
/// <para>* <see cref="EOption{UserData}.Failure(System.Data.SqlClient.SqlException)"/> if any technical problem occurred (e.g. connection loss). </para>
/// </returns>
EOption<UserData> GetUserData( User id );
}
}