Clywell.Primitives

Generic Result pattern and functional primitives for .NET. Provides railway-oriented programming extensions, typed error handling, and pattern matching support with zero dependencies and zero business logic — can be used in any .NET application.

Features

Result<T> & Result — Type-safe success/failure for value-returning and void-like operations
Typed Error Hierarchy — Error, ErrorCode, ValidationError, ValidationFailure with metadata, inner errors, and field-level details
Railway-Oriented Programming — Map, Bind, Match, Tap, Ensure, MapError, TapError for composable pipelines
Implicit Conversions — Ergonomic syntax: assign values or errors directly to Result<T> / Result
Async Pipeline Support — Full async extensions for Task<Result<T>> and Task<Result> composition
Pattern Matching — Match (with return) and Switch (side-effects) for exhaustive handling
Collection Operations — Collect to aggregate IEnumerable<Result<T>> and Combine for tuples
Try/Catch Wrapping — Result.Try() / Result.TryAsync() to convert exception-based code to Results
Nullable Bridging — Result.FromNullable() for reference types and nullable value types
Deconstruct & Bridging — Deconstruct for tuple-style consumption, ToResult() / Map<T> / Bind<T> to bridge between Result and Result<T>
Zero Dependencies — 100% standalone, no external NuGet packages
.NET 10.0+ / C# 14 — Modern language features including extension members
Source Link Enabled — Step into source code when debugging NuGet package
211+ Unit Tests — Comprehensive coverage across all types and operations

Installation

dotnet add package Clywell.Primitives

Quick Start

using Clywell.Primitives;

// ── Value-returning operations: Result<T> ──────────────────────

// Implicit conversions — no factory needed
Result<int> success = 42;
Result<int> failure = Error.NotFound("User not found.");

// Factory methods
var ok   = Result.Success(42);
var fail = Result.Failure<int>(Error.Conflict("Already exists"));

// ── Void-like operations: Result ───────────────────────────────

Result deleted   = Result.Success();
Result notFound  = Result.Failure(Error.NotFound("Item not found"));
Result fromError = Error.Forbidden("Not allowed");  // implicit conversion

// ── Pattern matching ───────────────────────────────────────────

string message = ok.Match(
    onSuccess: value => $"Got: {value}",
    onFailure: error => $"Failed: {error.Description}");

deleted.Switch(
    onSuccess: () => Console.WriteLine("Done"),
    onFailure: error => Console.WriteLine($"Error: {error}"));

// ── Railway-oriented pipeline ──────────────────────────────────

var result = Result.Success("42")
    .Map(int.Parse)                                    // string → int
    .Ensure(v => v > 0, Error.Failure("Must be > 0"))  // validate
    .Bind(v => LookupUser(v))                          // int → Result<User>
    .Tap(user => Console.WriteLine(user.Name))         // side effect
    .MapError(e => Error.Unexpected(e.Description))    // remap error
    .Map(user => user.Email);                          // User → string

Core Types

`ErrorCode`

A readonly record struct classifying error categories. Supports implicit conversion to/from string for extensibility.

Code	Value	Usage
`ErrorCode.Failure`	`"General.Failure"`	General/unspecified failure
`ErrorCode.Validation`	`"General.Validation"`	Validation rule violations
`ErrorCode.NotFound`	`"General.NotFound"`	Resource not found
`ErrorCode.Conflict`	`"General.Conflict"`	Duplicate/conflict scenarios
`ErrorCode.Unauthorized`	`"General.Unauthorized"`	Authentication failures
`ErrorCode.Forbidden`	`"General.Forbidden"`	Authorization/permission failures
`ErrorCode.Unexpected`	`"General.Unexpected"`	Internal/unexpected errors
`ErrorCode.Unavailable`	`"General.Unavailable"`	Service/resource unavailable

// Custom error codes via implicit conversion
ErrorCode custom = "Billing.PaymentDeclined";

// String comparison
string code = ErrorCode.NotFound; // "General.NotFound"

`Error`

A record with Code, Description, optional InnerError, and Metadata. Immutable — builder methods return new instances.

Factory Methods

Error.Failure("Something went wrong")
Error.NotFound("User not found")
Error.Conflict("Email already registered")
Error.Unauthorized("Invalid credentials")
Error.Forbidden("Insufficient permissions")
Error.Unexpected("Unhandled exception occurred")
Error.Unavailable("Service temporarily down")
Error.Validation("Email", "Email is required")          // single field
Error.Validation(                                        // multiple fields
    new ValidationFailure("Email", "Required"),
    new ValidationFailure("Age", "Must be ≥ 18"))

Builder Methods (Immutable)

var error = Error.NotFound("Order not found")
    .WithMetadata("OrderId", orderId)
    .WithMetadata("RequestId", correlationId)
    .WithInnerError(originalError);

// Bulk metadata
var enriched = error.WithMetadata(new Dictionary<string, object>
{
    ["Timestamp"] = DateTime.UtcNow,
    ["Retry"] = 3
});

Properties

Property	Type	Description
`Code`	`ErrorCode`	Categorized error code
`Description`	`string`	Human-readable error message
`InnerError`	`Error?`	Optional causal error (error chain)
`Metadata`	`ImmutableDictionary<string,object>`	Key-value pairs for context

`ValidationFailure`

A readonly record struct representing a single field-level validation failure.

var failure = new ValidationFailure("Email", "Email is required");
failure.FieldName; // "Email"
failure.Message;   // "Email is required"
failure.ToString(); // "Email: Email is required"

`ValidationError`

A sealed record extending Error with structured validation details. Always has ErrorCode.Validation.

var error = Error.Validation(
    new ValidationFailure("Email", "Required"),
    new ValidationFailure("Name", "Too long"));

error.Failures;                     // ImmutableArray<ValidationFailure>
error.FailureCount;                 // 2
error.HasFailureForField("Email");  // true
error.GetFailuresForField("Email"); // IEnumerable<ValidationFailure>

// Append failures (returns new instance)
var combined = error.AddFailures(
    new ValidationFailure("Age", "Must be positive"));

`Result<T>` — Value-Returning Operations

A readonly struct representing success with a TValue or failure with an Error. Implicit conversions allow assigning values and errors directly.

Creating

// Implicit conversions
Result<User> success = user;
Result<User> failure = Error.NotFound("User not found");

// Factory methods
Result.Success(user);
Result.Failure<User>(error);
Result.Failure<User>("Something went wrong"); // shorthand for Error.Failure(...)

Properties

Property	Type	Description
`IsSuccess`	`bool`	`true` if the result contains a value
`IsFailure`	`bool`	`true` if the result contains an error
`Value`	`T`	The success value (throws if failure)
`Error`	`Error`	The error (throws if success)

Instance Methods

Method	Returns	Description
`Match(onSuccess, onFailure)`	`TOut`	Pattern match with return value
`Switch(onSuccess, onFailure)`	`void`	Pattern match with side effects
`Map(fn)`	`Result<TOut>`	Transform success value
`Bind(fn)`	`Result<TOut>`	Chain result-producing function (flatMap)
`Tap(action)`	`Result<T>`	Side effect on success
`OnSuccess(action)`	`Result<T>`	Execute action on success
`OnFailure(action)`	`Result<T>`	Execute action on failure
`ValueOr(fallback)`	`T`	Get value or fallback
`ValueOr(fn)`	`T`	Get value or compute fallback from error
`ToResult()`	`Result`	Discard value, preserve success/failure
`Deconstruct`	`(bool, T?, Error?)`	Tuple-style: `var (ok, val, err) = result`
`MapAsync(fn)`	`Task<Result<TOut>>`	Transform with async function
`BindAsync(fn)`	`Task<Result<TOut>>`	Chain with async result-producing function
`TapAsync(fn)`	`Task<Result<T>>`	Async side effect on success
`TapErrorAsync(fn)`	`Task<Result<T>>`	Async side effect on failure
`MatchAsync(onSuccess, onFailure)`	`Task<TOut>`	Pattern match with async functions

Extension Methods

Method	Returns	Description
`Ensure(predicate, error)`	`Result<T>`	Validate with predicate
`Ensure(predicate, errorFactory)`	`Result<T>`	Validate with lazy error from value
`MapError(fn)`	`Result<T>`	Transform the error
`TapError(action)`	`Result<T>`	Side effect on failure

Async Pipeline Extensions (on `Task<Result<T>>`)

These allow chaining directly off async operations without await:

Method	Returns	Description
`.Map(fn)`	`Task<Result<TOut>>`	Transform success value
`.Bind(fn)`	`Task<Result<TOut>>`	Chain sync result-producing function
`.BindAsync(fn)`	`Task<Result<TOut>>`	Chain async result-producing function
`.Match(onSuccess, onFailure)`	`Task<TOut>`	Pattern match
`.Ensure(predicate, error)`	`Task<Result<T>>`	Validate
`.Ensure(pred, errorFactory)`	`Task<Result<T>>`	Validate with lazy error from value
`.Tap(action)`	`Task<Result<T>>`	Side effect on success
`.TapError(action)`	`Task<Result<T>>`	Side effect on failure

var email = await GetUserAsync(id)       // Task<Result<User>>
    .Ensure(u => u.IsActive, Error.Failure("Inactive"))
    .Map(u => u.Email)
    .TapError(e => logger.LogWarning("Failed: {Error}", e));

`Result` — Void-Like Operations

A readonly struct for operations that succeed or fail but carry no value (e.g., Delete, SendEmail).

Creating

Result success = Result.Success();
Result failure = Result.Failure(Error.NotFound("Item not found"));
Result quick   = Result.Failure("Something went wrong");
Result fromErr = Error.Forbidden("Not allowed"); // implicit conversion

Properties

Property	Type	Description
`IsSuccess`	`bool`	`true` if the operation succeeded
`IsFailure`	`bool`	`true` if the operation failed
`Error`	`Error`	The error (throws if success)

Instance Methods

Method	Returns	Description
`Match(onSuccess, onFailure)`	`TOut`	Pattern match with return value
`Switch(onSuccess, onFailure)`	`void`	Pattern match with side effects
`Tap(action)`	`Result`	Side effect on success
`OnSuccess(action)`	`Result`	Execute action on success
`OnFailure(action)`	`Result`	Execute action on failure
`Map<T>(fn)`	`Result<T>`	Bridge to Result on success
`Bind<T>(fn)`	`Result<T>`	Chain to Result via binder
`Deconstruct`	`(bool, Error?)`	Tuple-style: `var (ok, err) = result`
`TapAsync(fn)`	`Task<Result>`	Async side effect on success
`TapErrorAsync(fn)`	`Task<Result>`	Async side effect on failure
`MatchAsync(onSuccess, onFailure)`	`Task<TOut>`	Pattern match with async functions

Extension Methods

Method	Returns	Description
`Ensure(predicate, error)`	`Result`	Validate with predicate
`MapError(fn)`	`Result`	Transform the error
`TapError(action)`	`Result`	Side effect on failure

Async Pipeline Extensions (on `Task<Result>`)

Method	Returns	Description
`.Match(onSuccess, onFailure)`	`Task<TOut>`	Pattern match
`.Ensure(predicate, error)`	`Task<Result>`	Validate with predicate
`.Map<T>(fn)`	`Task<Result<T>>`	Bridge to Result on success
`.Bind<T>(fn)`	`Task<Result<T>>`	Chain to Result via binder
`.Tap(action)`	`Task<Result>`	Side effect on success
`.TapError(action)`	`Task<Result>`	Side effect on failure

await Result.TryAsync(() => emailService.SendAsync(message))
    .Tap(() => logger.LogInformation("Email sent"))
    .TapError(e => logger.LogError("Send failed: {Error}", e));

Static Factory & Utility Methods

All accessible via Result.*:

Method	Returns	Description
`Result.Success()`	`Result`	Non-generic success
`Result.Failure(error)`	`Result`	Non-generic failure from error
`Result.Failure(description)`	`Result`	Non-generic failure from string
`Result.Success<T>(value)`	`Result<T>`	Generic success
`Result.Failure<T>(error)`	`Result<T>`	Generic failure from error
`Result.Failure<T>(description)`	`Result<T>`	Generic failure from string
`Result.Try(action)`	`Result`	Wrap void action in try/catch
`Result.Try<T>(func)`	`Result<T>`	Wrap function in try/catch
`Result.TryAsync(func)`	`Task<Result>`	Wrap async action in try/catch
`Result.TryAsync<T>(func)`	`Task<Result<T>>`	Wrap async function in try/catch
`Result.FromNullable<T>(value, msg)`	`Result<T>`	Null → NotFound failure (reference types)
`Result.FromNullable<T>(value?, msg)`	`Result<T>`	Null → NotFound failure (nullable value types)
`Result.Combine(r1, r2)`	`Result<(T1, T2)>`	Combine 2 results into tuple
`Result.Combine(r1, r2, r3)`	`Result<(T1,T2,T3)>`	Combine 3 results into tuple
`Result.Combine(r1, r2, r3, r4)`	`Result<(T1,T2,T3,T4)>`	Combine 4 results into tuple
`Result.Combine(r1, r2, r3, r4, r5)`	`Result<(T1,...,T5)>`	Combine 5 results into tuple

Collection Extensions

Method	Returns	Description
`results.Collect()`	`Result<IReadOnlyList<T>>`	Aggregate sequence; fail on first error

Real-World Examples

Service Method

public Result<User> CreateUser(CreateUserRequest request)
{
    return ValidateRequest(request)
        .Bind(req => CheckDuplicateEmail(req.Email))
        .Map(email => new User(request.Name, email))
        .Bind(user => repository.Save(user))
        .Tap(user => eventBus.Publish(new UserCreatedEvent(user.Id)));
}

Void-Like Service Method

public async Task<Result> DeleteOrderAsync(int orderId)
{
    return await FindOrder(orderId)
        .Map(order => order.Id)
        .BindAsync(id => repository.DeleteAsync(id))
        .Tap(() => logger.LogInformation("Deleted order {Id}", orderId))
        .TapError(e => logger.LogWarning("Delete failed: {Error}", e));
}

API Controller

[HttpPost]
public IActionResult Create(CreateUserRequest request)
{
    return userService.CreateUser(request).Match(
        onSuccess: user => CreatedAtAction(nameof(Get), new { id = user.Id }, user),
        onFailure: error => error.Code.Value switch
        {
            "General.Validation" => BadRequest(error),
            "General.Conflict"   => Conflict(error),
            "General.NotFound"   => NotFound(error),
            _                    => StatusCode(500, error)
        });
}

Combining Results

var combined = Result.Combine(
    GetUser(userId),
    GetOrder(orderId),
    GetPayment(paymentId));

return combined.Map(tuple =>
{
    var (user, order, payment) = tuple;
    return new OrderSummary(user.Name, order.Total, payment.Status);
});

// 4 & 5 result overloads available too
var all = Result.Combine(name, email, age, address);
var full = Result.Combine(name, email, age, address, phone);

Deconstructing Results

// Non-generic Result
var (ok, error) = Result.Success();
// ok = true, error = null

// Generic Result<T>
var (isSuccess, value, err) = Result.Success(42);
// isSuccess = true, value = 42, err = null

Bridging Result ↔ Result<T>

// Result → Result<T> via Map/Bind
Result deleted = DeleteOrder(id);
Result<string> message = deleted.Map(() => "Order deleted");
Result<Order> order = deleted.Bind(() => LoadOrder(id));

// Result<T> → Result via ToResult  (discards value)
Result<User> userResult = GetUser(id);
Result plain = userResult.ToResult();

Error Enrichment

var error = Error.NotFound("Order not found")
    .WithMetadata("OrderId", orderId)
    .WithInnerError(originalError);

// Validation with rich details
var validation = Error.Validation(
    new ValidationFailure("Email", "Required"),
    new ValidationFailure("Age", "Must be 18 or older"));

validation.Failures;                     // ImmutableArray<ValidationFailure>
validation.HasFailureForField("Email");  // true

// Combine validation errors
var merged = validation.AddFailures(
    new ValidationFailure("Name", "Too long"));

Collecting Sequences

var results = ids.Select(id => ParseId(id)); // IEnumerable<Result<int>>

Result<IReadOnlyList<int>> all = results.Collect();
// Success with all values, or first error encountered

Converting from Exceptions

// Sync — value-returning
var parsed = Result.Try(() => int.Parse(userInput));

// Sync — void
var written = Result.Try(() => File.WriteAllText(path, content));

// Async — value-returning
var data = await Result.TryAsync(() => httpClient.GetStringAsync(url));

// Async — void
var sent = await Result.TryAsync(() => emailService.SendAsync(msg));

Nullable Bridging

// Reference type
Result<User> user = Result.FromNullable(
    repository.FindById(id),
    "User not found");

// Nullable value type
Result<int> count = Result.FromNullable(
    GetOptionalCount(),  // int?
    "Count unavailable");

Contributing

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Commit changes: git commit -m 'feat: add my feature'
Push to branch: git push origin feature/my-feature
Create a Pull Request

Commit Convention

Follow Conventional Commits:

feat: — New feature
fix: — Bug fix
test: — Test additions/changes
docs: — Documentation only
chore: — Build/tooling changes

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.github		.github
sample/ScoreTracker		sample/ScoreTracker
src/Clywell.Primitives		src/Clywell.Primitives
tests/Clywell.Primitives.Tests		tests/Clywell.Primitives.Tests
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Clywell.Primitives.sln		Clywell.Primitives.sln
Directory.Build.props		Directory.Build.props
Directory.Packages.props		Directory.Packages.props
LICENSE		LICENSE
README.md		README.md
coverlet.runsettings		coverlet.runsettings
version.json		version.json

Folders and files

Latest commit

History

Repository files navigation

Clywell.Primitives

Features

Installation

Quick Start

Core Types

ErrorCode

Error

Factory Methods

Builder Methods (Immutable)

Properties

ValidationFailure

ValidationError

Result<T> — Value-Returning Operations

Creating

Properties

Instance Methods

Extension Methods

Async Pipeline Extensions (on Task<Result<T>>)

Result — Void-Like Operations

Creating

Properties

Instance Methods

Extension Methods

Async Pipeline Extensions (on Task<Result>)

Static Factory & Utility Methods

Collection Extensions

Real-World Examples

Service Method

Void-Like Service Method

API Controller

Combining Results

Deconstructing Results

Bridging Result ↔ Result<T>

Error Enrichment

Collecting Sequences

Converting from Exceptions

Nullable Bridging

Contributing

Commit Convention

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`ErrorCode`

`Error`

`ValidationFailure`

`ValidationError`

`Result<T>` — Value-Returning Operations

Async Pipeline Extensions (on `Task<Result<T>>`)

`Result` — Void-Like Operations

Async Pipeline Extensions (on `Task<Result>`)