CSharpEssentials.Maybe 3.0.0

CSharpEssentials

CSharpEssentials is a comprehensive ecosystem of .NET libraries designed to modernize C# development. It bridges the gap between Object-Oriented and Functional Programming, providing robust tools for error handling, domain modeling, and enterprise application development.

Goal: Make C# code more expressive, safer, and easier to test without sacrificing performance.

📦 Ecosystem Overview

CSharpEssentials is modular. You can use the meta-package to get everything, or install specific modules to keep dependencies light.

Package	Description	NuGet
CSharpEssentials	The meta-package including all core functional modules and exclusive bridge extensions.
CSharpEssentials.Core	Foundational extensions, guard clauses, and utilities (Strings, Collections, GUIDs).
CSharpEssentials.Results	Railway-oriented programming with Result and Result<T> patterns.
CSharpEssentials.Maybe	Maybe<T> monad for null-safe optional value handling.
CSharpEssentials.Errors	Structured error handling with unique codes and standard types (NotFound, Validation, etc.).
CSharpEssentials.Rules	Composable business rule engine (And, Or, Linear, Conditional logic).
CSharpEssentials.Any	Discriminated Unions (Any<T1, T2, ...>) for type-safe polymorphic returns.
CSharpEssentials.Entity	Domain-Driven Design base classes (EntityBase, SoftDeletableEntityBase).
CSharpEssentials.EntityFrameworkCore	EF Core extensions, Audit/Domain-Event/Slow-Query interceptors, and Pagination (offset + cursor).
CSharpEssentials.AspNetCore	Web API utilities: Global Exception Handler, Problem Details, API Versioning.
CSharpEssentials.Json	Advanced JSON serialization: Polymorphism, String Enums, Multi-format Dates.
CSharpEssentials.Time	Testable IDateTimeProvider abstraction and extensions.
CSharpEssentials.RequestResponseLogging	Highly configurable HTTP traffic logging middleware.
CSharpEssentials.GcpSecretManager	Google Cloud Secret Manager integration for IConfiguration.
CSharpEssentials.Clone	Type-safe deep cloning interfaces and extensions.
CSharpEssentials.Enums	Attributes for controlling Enum serialization behavior.

🚀 Getting Started

Install the main package to get the core functional tools:

dotnet add package CSharpEssentials

Or pick individual packages as needed (e.g., dotnet add package CSharpEssentials.Results).

Target Framework Support

💡 Feature Highlights

1. Functional Error Handling (Results & Errors)

Stop throwing exceptions for flow control. Use Result<T> to express success or failure explicitly.

using CSharpEssentials.ResultPattern;
using CSharpEssentials.Errors;

public Result<User> RegisterUser(string email)
{
    if (string.IsNullOrEmpty(email))
        return Error.Validation("User.EmailRequired", "Email cannot be empty.");

    if (_repo.Exists(email))
        return Error.Conflict("User.Exists", "User already exists.");

    var user = new User(email);
    return user; // Implicit conversion to Result<User>
}

2. Safe Optionals (Maybe)

Eliminate NullReferenceException by explicitly modeling the absence of a value.

using CSharpEssentials.Maybe;

public Maybe<User> GetUserById(Guid id)
{
    var user = _repo.Find(id);
    return user; // Implicit conversion from User?
}

// Chaining with LINQ
var zipCode = GetUserById(id)
    .Map(u => u.Address)
    .Map(a => a.ZipCode)
    .GetValueOrDefault("00000");

3. Business Rules Engine

Compose complex logic from simple, reusable rules.

var rule = Rule.And(
    new MinimumAgeRule(18),
    new KycCompletedRule()
);

var result = RuleEngine.Evaluate(rule, userContext);

4. Robust Web APIs (AspNetCore)

Automatically convert Result failures into standard RFC 7807 Problem Details responses using the Global Exception Handler.

// Program.cs
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddEnhancedProblemDetails();

// Controller
[HttpPost]
public IActionResult Create(CreateUserRequest request)
{
    Result<User> result = _service.Create(request);
    
    // Returns 200 OK with data, or 400/404/409 ProblemDetails based on Error Type
    return result.ToActionResult(); 
}

5. Domain Modeling (Entity)

Build rich domain models with built-in Audit logs and Domain Events.

public class Order : EntityBase<Guid>
{
    public void MarkAsPaid()
    {
        Status = OrderStatus.Paid;
        Raise(new OrderPaidEvent(Id)); // Domain Event
        SetUpdatedInfo(DateTimeOffset.UtcNow, "System"); // Auditing
    }
}

🔮 Roadmap

CSharpEssentials is designed with future .NET versions in mind.

.NET 9 (Current Baseline)

Full support with all modern optimizations:

• lock objects
• OverloadResolutionPriority
• Inline arrays
• params ReadOnlySpan<T>
• Task.WhenEach

.NET 10 (Planned)

• Params collections expansion — cleaner APIs across Result, Maybe, Any factory methods.
• Extension types (if available) — static extension methods for IEnumerable<Result<T>> batch operations.
• Improved JSON serialization — leverage any new System.Text.Json source-generator features.

.NET 11 (Future-Proof)

• Native union types — The big one. All discriminated-union-style types (Result<T>, Maybe<T>, Any<...>, Error) are structured so they can be migrated to readonly union with zero breaking changes when the language feature arrives.
• Field keyword — Simplify property declarations in EntityBase and error types.

// Today (.NET 9)
public readonly struct Result<T> { /* ... */ }

// Tomorrow (.NET 11)
public readonly union Result<T>(T Value, Error Error);
// Your code: no changes needed!

Migration Strategy

We follow a conditional-compilation bridge pattern:

1. Keep the struct implementation as the fallback for all targets.
2. When .NET 11 ships, add a new target and gate the union syntax behind #if NET11_0_OR_GREATER.
3. The public API surface (IsSuccess, Value, Error, Match, Map, Bind) remains 100 % identical.
4. Consumers simply upgrade their TFM — no code changes required.

🛠️ Development & Publishing

This repository includes a smart build script (build-and-publish-nugets.sh) that manages dependency orders and versioning for all packages.

# Build and Test all packages
./build-and-publish-nugets.sh

# Publish to NuGet (requires API Key)
./build-and-publish-nugets.sh --parallel YOUR_API_KEY

🤝 Contributing

Contributions are welcome! Please read our CONTRIBUTING.md guide.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙏 Acknowledgments

Inspired by excellent community projects like ErrorOr, CSharpFunctionalExtensions, and OneOf.

Star History