Knight.Response 1.1.0

Knight.Response

Knight.Response is a lightweight, immutable, fluent result library for C# services, APIs, and applications. It provides a clean and consistent way to handle outcomes, success/failure states, messages, and functional chaining — making your code simpler, safer, and more expressive.

Features

• Immutable Result and Result<T> types
• Statuses: Completed, Cancelled, Failed, Error
• Rich Message with MessageType + optional structured Metadata
• Factory methods: Success, Failure, Error, Cancel, NotFound, FromCondition, Aggregate, Error(Exception)
• Functional extensions: OnSuccess, OnFailure, Map, Bind
• Advanced extensions: Ensure, Tap, Recover, WithMessage, WithMessages
• Pattern matching via deconstruction
• Zero runtime dependencies

Installation

dotnet add package Knight.Response

Quick Start

using Knight.Response;

var userResult = Results.Success(new User("Knight"))
    .Ensure(u => u!.IsActive, "User is not active")
    .Tap(u => _audit.LogLogin(u!));

if (userResult.IsSuccess)
{
    Console.WriteLine(userResult.Value!.Name);
}

Core Concepts

public class Result
{
    public Status Status { get; }
    public IReadOnlyList<Message> Messages { get; }
    public bool IsSuccess { get; } // Status == Completed
}

public class Result<T> : Result
{
    public T? Value { get; }
}

Status

• Completed
• Cancelled
• Failed
• Error

MessageType

• Information
• Warning
• Error

Metadata

Message supports optional Metadata as a read-only dictionary for structured context, e.g.:

var msg = new Message(
    MessageType.Warning,
    "Rate limit exceeded",
    new Dictionary<string, object?> { ["retryAfter"] = 30 }
);

Factory Methods

Core Extensions

result.OnSuccess(() => Console.WriteLine("All good"))
      .OnFailure(msgs => Console.WriteLine($"Failed: {string.Join(", ", msgs.Select(m => m.Content))}"));

var mapped = Results.Success(2).Map(x => x * 5); // Success(10)

var bound = Results.Success("abc").Bind(v => Results.Success(v.ToUpper()));

• OnSuccess – Runs an action if result is success
• OnFailure – Runs an action if result is failure/error/cancelled
• Map – Transforms the value if success
• Bind – Chains another Result operation if success

Advanced Extensions

• Ensure – Ensures a predicate holds for success; otherwise returns failure
• Tap – Executes an action for side effects, preserving the result
• Recover – Transforms a failure into a success with fallback value
• WithMessage – Adds a single message to a result
• WithMessages – Adds multiple messages to a result

var ensured = Results.Success(5).Ensure(x => x > 0, "Must be positive");
var tapped = ensured.Tap(v => Console.WriteLine($"Value: {v}"));
var recovered = Results.Failure<int>("bad").Recover(_ => 42);
var withMsg = recovered.WithMessage(new Message(MessageType.Information, "Recovered with default"));

Pattern Matching

You can deconstruct results directly:

var (status, messages) = Results.Failure("fail!");

var (status, messages, value) = Results.Success(42);

Or use C# pattern matching:

switch (result)
{
    case { Status: Status.Completed }:
        Console.WriteLine("Success!");
        break;
    case { Status: Status.Failed, Messages: var msgs }:
        Console.WriteLine($"Failed: {msgs[0].Content}");
        break;
}

Important: Result<T>.Value and default values

When T is a non-nullable value type, failed results will contain the default value of that type (0 for int, false for bool, etc.). This is a limitation of .NET generics, since value types always have a default.

var r1 = Results.Failure<int>("bad");
Console.WriteLine(r1.Value); // 0

var r2 = Results.Failure<int?>("bad");
Console.WriteLine(r2.Value); // null

Guidance

• Use nullable value types (e.g. int?, bool?) if you want null to represent "no value".
• Use non-nullable value types if a default like 0 or false makes sense in your domain.
• Reference types (e.g. string, User) will correctly return null when not Completed.

Status values

The Status enum indicates the outcome of an operation:

• Completed – success
• Cancelled – cancelled before completion
• Failed – failed due to a known issue
• Error – unexpected/unhandled error

Validation Support (new in 1.1.0)

You can now construct Result and Result<T> from System.ComponentModel.DataAnnotations.ValidationResult collections.

using System.ComponentModel.DataAnnotations;

var errors = new List<ValidationResult>
{
    new("Name is required", new[] { "Name" }),
    new("Amount must be greater than 0", new[] { "Amount" }),
    new("General rule failed")
};

// Produces Error result with prefixed messages:
// "Name: Name is required", "Amount: Amount must be greater than 0", "General rule failed"
var result = Results.Validation(errors);

For generics:

var result = Results.Validation<MyEntity>(errors);

Metadata Enricher Overloads

Use an enricher delegate to attach metadata (e.g., field name) without altering text:

var result = Results.Validation(
    errors,
    (msg, field) => string.IsNullOrEmpty(field)
        ? msg
        : msg.WithMeta("field", field) // your custom extension
);

Default behavior:

• Prefixed mapping: "Field: message"
• Enricher overload: raw message text, field passed separately

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md.