An elegant, fluent, and intuitive way to handle operations that may succeed or fail, inspired by functional programming principles.
$ dotnet add package FluentCoder.Maybe
dotnet add package FluentCoder.Maybe
Loving it? Show your support by giving this project a star!
Maybe is more than just an error-handling library; it's a tool for writing clearer, more expressive, and more resilient code. It encourages you to think about the different outcomes of your operations, not just success or failure.
By using an elegant, fluent API, Maybe guides you to:
Write code that reads like a business process.
Handle both success and failure paths explicitly.
Eliminate unexpected runtime exceptions.
Seamlessly compose synchronous and asynchronous operations.
Maybe is designed to be simple for common cases, but powerful for advanced scenarios.
Maybe<TValue, TError>You can specify both a success type and an error type. For common scenarios, you can use the built-in Error class, which provides a rich, specialized error system.
// The error type defaults to the built-in Error class.
public Maybe<User, Error> FindUser(int id)
{
if (id > 0)
{
return new User(id, ""Alice"");
}
// Return a built-in, specialized error type.
return Error.NotFound(itemName: ""User"", identifier: id);
}When you need to return a custom, strongly-typed error with specific data, you can provide your own error type.
public class UserCreationError : GenericError { /* ... */ }
public Maybe<User, UserCreationError> CreateUser(string email)
{
if (string.IsNullOrEmpty(email))
{
return new UserCreationError(""Email cannot be empty."");
}
// ...
}IOutcomeWhen you need to communicate a more specific success state (like Created or Updated), you can return a value that implements the IOutcome interface. Maybe will automatically inspect the value and adopt its specific OutcomeType, enriching your return value.
// 'Created' implements IOutcome and has its own OutcomeType
public Maybe<Created, Error> CreateUser(string name)
{
// ... create user ...
return Outcomes.Created;
}
var result = CreateUser(""Bob"");
// result.Type is now 'OutcomeType.Created', not the default 'Success'.This 👇
public User GetUserById(int id)
{
var user = _db.Users.Find(id);
if (user is null)
{
throw new UserNotFoundException(""User not found"");
}
return user;
}Turns into this 👇, using the powerful Match method to handle both outcomes safely.
public Maybe<User, Error> GetUserById(int id)
{
var user = _db.Users.Find(id);
if (user is null)
{
return Error.NotFound(itemName: ""User"", identifier: id);
}
return user;
}
GetUserById(1)
.Match(
onSome: user => Console.WriteLine(user.Name),
onNone: error => Console.WriteLine(error.Message));The true power of Maybe lies in its fluent DSL. The API is designed to be intuitive, automatically handling the transition between synchronous and asynchronous contexts without needing different method names.
// This example finds a user, validates their status, gets their permissions, and transforms the result.
// Notice how .Select and .Ensure are used on an async source without needing an ""Async"" suffix.
var result = await Api.FindUserAsync(userId) // Start: Task<Maybe<User, Error>>
.Ensure(user => user.IsActive, Error.Failure(""User is inactive"")) // Then: Sync validation
.Select(user => user.Name.ToUpper()) // Then: Sync transformation
.ThenAsync(name => Api.GetPermissionsAsync(name)) // Then: Async chain
.Select(permissions => permissions.ToUpper()); // Finally: Sync transformationMaybe instanceCreating a Maybe is designed to be frictionless, primarily through implicit conversions.
public Maybe<User, Error> FindUser(int id)
{
if (id == 1)
{
return new User(1, ""Alice"", true); // Implicit conversion from User to Maybe<User, Error>
}
return Error.NotFound(itemName: ""User"", identifier: id); // Implicit conversion from Error to Maybe<User, Error>
}Maybe shines with its rich, specialized error system. Instead of returning generic errors, you can use the built-in factory methods on the Error class to create descriptive, structured errors.
ValidationErrorFor handling invalid input data, including field-specific details.
var fieldErrors = new Dictionary<string, string>
{
[""Email""] = ""Email address is already in use."",
[""Password""] = ""Password is too weak.""
};
var validationError = Error.Validation(fieldErrors, ""User registration failed."");
// You can access the specific field errors later:
// if (validationError is ValidationError v) { ... v.FieldErrors ... }NotFoundErrorFor when a requested resource cannot be found.
var notFoundError = Error.NotFound(itemName: ""Product"", identifier: ""SKU-12345"");
// notFoundError.EntityName -> ""Product""
// notFoundError.Identifier -> ""SKU-12345""ConflictErrorFor conflicts with the current state of a resource (e.g., duplicates, stale data).
var conflictingParams = new Dictionary<string, object> { [""Username""] = ""john.doe"" };
var conflictError = Error.Conflict(
ConflictType.Duplicate,
resourceType: ""User"",
conflictingParameters: conflictingParams);AuthorizationErrorFor authentication (Unauthorized) or permission (Forbidden) failures.
var authError = Error.Forbidden(
action: ""DeleteResource"",
resourceIdentifier: ""res-abc"",
userId: ""user-789"");UnexpectedErrorFor wrapping system exceptions while preserving the original context for logging.
try { /* ... */ }
catch (Exception ex)
{
return Error.Unexpected(ex, ""Failed to communicate with the payment gateway."");
}FailureErrorFor expected but significant process failures, with additional context for debugging.
var context = new Dictionary<string, object> { [""TransactionId""] = ""txn_54321"" };
var failure = Error.Failure(
message: ""The payment was declined by the gateway."",
code: ""Payment.GatewayDeclined"",
contextData: context);ToFullString()Every Error object, including its inner errors, can be formatted into a detailed, aligned, and readable string perfect for logging.
// Create a chain of errors
var dbError = Error.NotFound(""User"", 123);
var serviceError = Error.Failure(
message: ""Failed to process order"",
code: ""Order.Processing"",
innerError: dbError);
// Print the full, formatted error chain
Console.WriteLine(serviceError.ToFullString());Output:
[Failure] Order.Processing [2025-09-14 11:00:00] Failed to process order
[NotFound] NotFound.User [2025-09-14 11:00:00] User with identifier '123' was not found.
Purpose: To chain an operation that itself returns a Maybe. This is the primary method for sequencing operations that can fail.
// Finds a user, and if successful, gets their permissions.
Maybe<Permissions, PermissionsError> result = Api.FindUserInDb(1)
.Then(user => Api.GetPermissions(user));Purpose: To transform the value inside a successful Maybe into something else, without altering the Maybe's state.
// Finds a user, and if successful, selects their email address.
Maybe<string, UserNotFoundError> userEmail = Api.FindUserInDb(1)
.Select(user => user.Email);Purpose: To check if the value inside a successful Maybe meets a specific condition. If the condition is not met, the chain is switched to an error state.
The library provides two sets of Ensure overloads:
Ergonomic (Preserves Error Type): Used when the validation error is of the same type as the Maybe's error channel.
Maybe<User, PermissionsError> validatedUser = GetUser() // Returns Maybe<User, PermissionsError>
.Ensure(u => u.IsActive, new PermissionsError()); // Error is also PermissionsError
Unifying (Changes Error Type): Used when the validation introduces a new, potentially incompatible error type. The result is unified to a Maybe whose error channel is a common base type, typically Error.
// GetUser() returns Maybe<User, UserNotFoundError>
// The result is Maybe<User, Error> to accommodate both UserNotFoundError and ValidationError.
Maybe<User, Error> validatedUser = GetUser()
.Ensure(u => u.Age > 18, Error.Validation(new()));
Purpose: To handle a failure by executing a recovery function that can return a new Maybe.
// Try to find a user in the database. If not found, try the cache.
Maybe<User, CacheError> result = await Api.FindUserInDbAsync(1)
.RecoverAsync(error => Api.FindUserInCache(1));Purpose: To safely exit the Maybe context by providing functions for both success and error cases.
string message = maybeUser.Match(
onSome: user => $""Welcome, {user.Name}!"",
onNone: error => $""Error: {error.Message}""
);Purpose: To exit the Maybe context by providing a default value in case of an error.
string userName = maybeUser.Select(u => u.Name).Else(""Guest"");Purpose: To perform an action (like logging) without altering the Maybe. It returns the original Maybe, allowing the chain to continue.
Maybe<User, UserNotFoundError> finalResult = Api.FindUserInDb(1)
.IfSome(user => Console.WriteLine($""User found: {user.Id}""))
.IfNone(error => Console.WriteLine($""Failed to find user: {error.Code}""));Purpose: To perform a final action on success (ThenDo) or failure (ElseDo). These methods terminate the fluent chain.
// Example: Final logging after a chain of operations
await Api.FindUserInDbAsync(1)
.Then(Api.GetPermissions)
.ThenDoAsync(permissions => Log.Information($""Permissions granted: {permissions}""))
.ElseDoAsync(error => Log.Error($""Operation failed: {error.Code}""));As explained in the Core Concepts, you can use types that implement IOutcome to communicate richer success states. Maybe provides a set of built-in, stateless struct types for common ""void"" operations, accessible via the Outcomes static class:
Outcomes.Success
Outcomes.Created
Outcomes.Updated
Outcomes.Deleted
Outcomes.Accepted
Outcomes.Unchanged
new Cached<T>(value)
public Maybe<Deleted, Error> DeleteUser(int id)
{
if (UserExists(id))
{
_db.Users.Remove(id);
return Outcomes.Deleted; // More expressive than returning void or true
}
return Error.NotFound(itemName: ""User"", identifier: id);
}The Maybe<TValue, TError> struct requires TError to have a parameterless constructor via the where TError : Error, new() constraint. All specialized errors provided by this library fulfill this requirement.
If you create your own custom error classes, they must also provide a public parameterless constructor. It's recommended to inherit from GenericError for simplicity and to gain access to features like ToFullString().
// Your custom error must have a parameterless constructor.
public class MyCustomError : GenericError
{
public MyCustomError() { /* ... */ }
public MyCustomError(string message)
: base(OutcomeType.Failure, ""Custom.Code"", message) { }
}
// This allows it to be used in generic methods with the `new()` constraint.
public Maybe<T, TError> GenericOperation<T, TError>() where TError : Error, new()
{
// ...
if (someCondition)
{
// Now this is possible
return new TError();
}
// ...
}If you have any questions, comments, or suggestions, please open an issue or create a pull request 🙂
This project is licensed under the terms of the MIT license.