PlainOutcomes 1.0.0

PlainOutcomes

PlainOutcomes is a minimal library that provides explicit Outcome and OutcomeError value types for .NET.

It is designed for scenarios where success and failure should be explicit, predictable, and represented as values instead of exceptions.

Why PlainOutcomes

This library intentionally avoids overengineering and hidden magic.

PlainOutcomes focuses on:

• Explicit success / failure flow
• Immutable value objects
• No exceptions for expected failures
• No framework, HTTP, or infrastructure coupling
• Zero unnecessary allocations
• Simple and predictable APIs

If you are looking for a full functional framework, this library is not that. If you want a small, explicit building block, this might fit.

Core Types

Outcome<T>

Represents the result of an operation that can either succeed with a value or fail with an error.

Characteristics:

• Immutable
• Value type (readonly record struct)
• No identity
• No side effects
• Designed for frequent creation and disposal

OutcomeError

Represents an expected failure as part of the operation contract.

Characteristics:

• Immutable value object
• Stable error code
• Human-readable message
• Not an exception

Example

using PlainOutcomes;

var result = Outcome<User>.Failure(
    new OutcomeError("user_not_found", "User was not found")
);

if (result.TryGetError(out var error))
{
    Console.WriteLine(error.Code);    // user_not_found
    Console.WriteLine(error.Message); // User was not found
}

Or for a success case:

var result = Outcome<User>.Success(user);

if (result.TryGetValue(out var value))
{
    Console.WriteLine(value.Name);
}

Design Principles

• Errors are values, not exceptions
• Exceptions are reserved for unexpected or unrecoverable failures.
• No implicit behavior
• Consumers must explicitly check success or failure.
• Minimal surface area
• Only what is necessary to represent the outcome.
• Fail fast on misuse
• Invalid access patterns are detected immediately.

What PlainOutcomes Is Not

• Not a functional programming framework
• Not a validation library
• Not an HTTP result abstraction
• Not a replacement for exceptions in all scenarios

When to Use

PlainOutcomes is a good fit for:

• Application and domain layers -Use cases and services
• Business logic where failures are expected
• Codebases that prefer explicit control flow

When Not to Use

You may want something else if:

• You rely heavily on exception-based flow
• You want automatic error propagation or retries
• You need advanced functional combinators
• You expect rich error hierarchies