ForgeSharp.Results 2.2.0

ForgeSharp.Results

A monadic Result type for .NET that replaces exceptions as flow control with explicit, composable success/failure values. All core types are readonly struct — zero heap allocations, zero GC pressure.

Install

dotnet add package ForgeSharp.Results

Get started

Return a Result from any operation. Check IsSuccess to branch on the outcome — no try/catch required.

Result<User> GetUser(int id)
{
    var user = db.Find(id);
    return user is not null
        ? Result.Ok(user)
        : Result.Fail<User>("User not found.");
}

var result = GetUser(42);
if (result.IsSuccess)
    Console.WriteLine(result.Value.Name);
else
    Console.WriteLine(result.Message);

Chain operations with Map and Bind. Failures propagate automatically — no manual error checking between steps.

var result = GetUser(42)
    .Bind(user => Validate(user))
    .Map(user => user.Profile);

Wrap code that throws into a Result with Capture:

Result result = Result.Capture(() => RiskyOperation());
Result<int> parsed = Result.Capture(() => int.Parse(input));

// Async
Result<Data> data = await Result.CaptureAsync(() => httpClient.GetFromJsonAsync<Data>(url));

Core types

Results distinguish three states: success, validation fault (with a message), and exception (with a captured Exception). The IsSuccess, IsValidationFault, and IsException properties let you branch accordingly.

Pipelines

Pipelines compose result-producing operations into discrete, reusable units. They come in sync (IPipeline<T>) and async (IAsyncPipeline<T>) variants and support LINQ query syntax.

var pipeline =
    from user in GetUserPipeline()
    where user.IsActive
    from profile in GetProfilePipeline(user.Id)
    select (user, profile);

Result<(User user, Profile profile)> result = pipeline.Execute();

Pipelines also support retry and timeout policies:

var resilient = Pipeline.Create(() => CallExternalService())
    .Retry(3, TimeSpan.FromSeconds(1))
    .Timeout(TimeSpan.FromSeconds(10));

Result result = resilient.Execute();

Use Repeat to execute a pipeline multiple times and collect the results:

EnumerableResult batch = pipeline.Repeat(100).ToEnumerableResult();
Console.WriteLine($"{batch.SuccessPercentage}% succeeded");

Extension methods

Every extension ships with an async counterpart (e.g. Map / MapAsync).

Chaining

var name = GetUser(42)
    .Bind(u => LoadSettings(u.Id))
    .Map(s => s.DisplayName)
    .GetOrDefault("Unknown");

Side effects

var result = GetUser(42)
    .Tap(user => Log.Info($"Found {user.Name}"))
    .TapError(err => Log.Warn($"Lookup failed: {err.Message}"));

Error transformation

Result<User, ApiError> apiResult = CallApi();
Result<User, string> friendly = apiResult.MapError(e => e.UserMessage);

Value extraction

Collections

Options interop

Convert freely between Options<T> and Result<T>:

// Result → Option
Options<User> maybeUser = GetUser(42).ToOption();

// Option → Result
Result<User> result = maybeUser.ToResult("No user found.");

// With a discriminated error type
Result<User, MyError> typed = maybeUser.ToResult(new MyError("missing"));

I/O integration

File, directory, and HTTP operations are wrapped as Result-returning extension methods so you never need a try/catch around I/O.

File & directory

Result<FileStream> stream = new FileInfo("data.bin").OpenReadAsResult();
Result deleted = File.DeleteAsResult("temp.log");

Result<DirectoryInfo> dir = Directory.CreateAsResult(@"C:\App\Logs");
Result removed = new DirectoryInfo(@"C:\App\Old").DeleteAsResult();

HttpClient

Every HTTP verb has an AsResult variant:

Result<HttpResponseMessage> response = await httpClient.GetAsResultAsync("https://api.example.com/items");

Result<Item[]> items = await httpClient
    .GetAsResultAsync("https://api.example.com/items")
    .ThenEnsureSuccessStatusCodeAsync(
        success: r => r.Content.ReadFromJsonAsync<Item[]>(),
        failure: r => $"API returned {r.StatusCode}");

API reference

Contributing

Contributions are welcome. Open an issue or submit a pull request on GitHub.

License

MIT