Sondor.Results
0.3.0
Prefix Reserved
dotnet add package Sondor.Results --version 0.3.0
NuGet\Install-Package Sondor.Results -Version 0.3.0
<PackageReference Include="Sondor.Results" Version="0.3.0" />
<PackageVersion Include="Sondor.Results" Version="0.3.0" />
<PackageReference Include="Sondor.Results" />
paket add Sondor.Results --version 0.3.0
#r "nuget: Sondor.Results, 0.3.0"
#:package Sondor.Results@0.3.0
#addin nuget:?package=Sondor.Results&version=0.3.0
#tool nuget:?package=Sondor.Results&version=0.3.0
Sondor.Results
Failures as values. An operation that can fail in an expected way returns a Result instead of throwing, so the failure is
part of the method's signature and the caller has to deal with it. No dependencies.
dotnet add package Sondor.Results
The basics
using Sondor.Results;
public sealed class NodeService
{
private static readonly Error NotFound =
new("Node.NotFound", "There is no node with that id.", ErrorType.NotFound);
// Returns a value or an error. A value and an Error both convert implicitly, so there is nothing to wrap.
public Result<Node> Find(Guid id) =>
_nodes.TryGetValue(id, out var node) ? node : NotFound;
// Returns nothing, or an error.
public Result Remove(Guid id) =>
_nodes.Remove(id) ? Result.Success() : NotFound;
}
The caller decides what a failure means:
var result = service.Find(id);
if (result.IsFailure)
{
return Problem(result.Error); // Code: "Node.NotFound", Type: NotFound
}
var node = result.Value; // only valid on a success
Errors
An Error has three parts:
| Part | What it is |
|---|---|
Code |
A stable code in the form Area.Reason, such as Node.NotFound. Callers and clients depend on it, so it never changes once released, and it never contains data from the request. |
Description |
A message for a person, safe to show to the caller. |
Type |
The kind of failure (Validation, NotFound, Conflict, Unauthorized, Forbidden, RateLimited, FeatureDisabled, InternalServerError, Failure). It says how to treat the failure, not how it is transported. |
An error can also carry named arguments (the entity, the property, the action behind its message), which is what makes it translatable: see Common errors and templates.
Define your errors once, as static readonly fields, small factory methods or templates, so a code is spelled in one place.
Common errors and templates
The usual failures are one call each. The description is a plain English sentence built from named arguments, and the arguments stay on the error so a layer that translates can fill its own wording instead of parsing yours.
Error notFound = Error.NotFound("Order", "Id");
// Code: Resource.NotFound Type: NotFound
// Description: No Order was found for the given Id.
// Arguments: Entity = Order, Property = Id
return notFound; // converts to a failed Result or Result<T>, like any Error
| Factory | Code | Type |
|---|---|---|
Error.NotFound(entity, property) |
Resource.NotFound |
NotFound |
Error.Conflict(entity, property) |
Resource.Conflict |
Conflict |
Error.Invalid(entity, property) |
Resource.Invalid |
Validation |
Error.Unauthorized(action) |
Request.Unauthorized |
Unauthorized |
Error.Forbidden(action) |
Request.Forbidden |
Forbidden |
Error.RateLimited(action) |
Request.RateLimited |
RateLimited |
Error.FeatureDisabled(feature) |
Feature.Disabled |
FeatureDisabled |
Error.Internal(action) |
Error.Internal |
InternalServerError |
Error.Failed(action) |
Error.Failed |
Failure |
The built-in codes are generic: the entity is an argument, not part of the code. When clients should be able to tell one failure from another, give it a code of your own. It keeps the same words, and the error still names the general template it came from, so a translation layer with no wording for your code can fall back to the general one:
static readonly ErrorTemplate OrderNotFound = ErrorTemplates.NotFound.WithCode("Order.NotFound");
Error error = OrderNotFound.Create(
ErrorArgument.Term("Entity", "Order"),
ErrorArgument.Term("Property", "Id"));
// Code: Order.NotFound Arguments.Template: Resource.NotFound
Or declare a template with your own words. Placeholders are plain names in braces; there are no positions, formats or alignments, so nothing depends on the culture:
static readonly ErrorTemplate Overdrawn = new(
"Account.Overdrawn", ErrorType.Conflict, "The {Account} cannot go below the {Limit}.");
Error error = Overdrawn.Create(
ErrorArgument.Term("Account", "current account"),
ErrorArgument.Term("Limit", "overdraft limit"));
A template is immutable and safe to share. Declare it as a static readonly field; a mistake in its words (an unclosed
brace, {0}, a repeated placeholder) throws when it is declared, and a missing or unknown argument throws when the error is
created, so the first test that touches the code finds it.
What may be shown
Every argument is one of three kinds, and the kind decides whether it can ever reach a person:
| Kind | Made with | Meaning |
|---|---|---|
Term |
ErrorArgument.Term(name, text) |
A name you chose: an entity, a property, an action. Safe to show, and what a translation fills in. |
Data |
ErrorArgument.Data(name, value) |
A value that may have come from a caller (an id, an email, a search text). It travels with the error, but is not put in the description, and a layer showing errors should not show it by default. |
Sensitive |
ErrorArgument.Sensitive(name) |
Personal data or a secret. Only the name is kept; there is no way to attach the value, so it cannot leak from the error later. A template shows [redacted] in its place. |
Error.NotFound("Customer", "Email", email) keeps the looked-up value as Data and leaves it out of the description. A
template can name a Data placeholder only if it was declared with showData: true, and then the value is shown as one short
line (control characters replaced, 64 characters at most). ToString() on an error, an argument and the argument list
shows names only, never values.
What the package leaves to you: it does not translate and it does not scan free text for personal data. A translation layer
looks an error up by Code, then by Arguments.Template, and falls back to Description; only the human text is ever
translated, never the code.
Chaining
Result<Order> order = FindCustomer(id)
.Ensure(customer => customer.IsActive, Errors.CustomerInactive) // a success that fails a rule becomes a failure
.Bind(customer => CreateOrder(customer)) // the next step can fail too
.Map(order => order with { Reference = NextReference() }) // change the value
.Tap(order => log.Created(order.Id)); // a side effect, on success only
string message = order.Match(
value => $"Created {value.Reference}",
error => $"Could not create the order: {error.Code}");
A failure skips every step after it and comes out at the end unchanged.
| Method | Does |
|---|---|
Map |
Turns the value of a success into another value |
Bind |
Runs the next step, which returns a Result |
Tap |
Runs a side effect on success, and returns the same result |
Ensure |
Turns a success into a given failure when the value does not satisfy a rule |
Match |
Returns one thing for a success and another for a failure |
TryGetValue |
out the value of a success, for code that prefers the Try shape |
Things that behave in a specific way
- A success always has a value.
Result.Success<T>(null)throws; use the non-genericResult.Success()for "nothing to return". An implicit conversion of a null (Result<string> r = (string)null!;) and aMapthat returns null give the failureError.NullValueinstead of throwing. defaultis a failure, not a success. An uninitialisedResultorResult<T>has the errorError.Unspecified, so it cannot pass for a good one.- A failure needs a reason.
Result.Failure(Error.None)throws:Error.Noneis the error of a success. - Reading the value of a failure throws
InvalidOperationException, naming the failure's code. CheckIsSuccess, or useTryGetValueorMatch. ToString()shows only the code, never the value or the description, so logging a result cannot leak either.- Errors compare by value, arguments included: two errors made separately from the same template with the same arguments are equal.
ResultandResult<T>are structs, so passing them around does not allocate.
Reading a result without knowing its type
IResultState exposes IsSuccess and Error for both result types, so cross-cutting code (logging, tracing, a pipeline
behaviour) can look at any outcome:
if (response is IResultState { IsSuccess: false } failed)
{
logger.LogWarning("Request refused: {Code}", failed.Error.Code);
}
Not included
Async helpers (MapAsync, BindAsync), collecting several errors into one result, and exception-to-result conversion are
not part of this package yet. They can be added without breaking anything; open an issue if you need one.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net10.0
- No dependencies.
-
net11.0
- No dependencies.
NuGet packages (5)
Showing the top 5 NuGet packages that depend on Sondor.Results:
| Package | Downloads |
|---|---|
|
Sondor.Cqrs.Results
Sondor.Results support for Sondor.Cqrs: tracing, metrics and logging report a failed Result with its error code, and behaviours can refuse a request by returning one. |
|
|
Sondor.AspNetCore
One consistent RFC 9457 problem response for an ASP.NET Core API: a failed Sondor.Results Result, an exception and the framework's own 401 or 404 all leave the service with the same shape, a stable error code and a trace id. Built on the framework's own ProblemDetails, exception handler and status code pages, for minimal APIs and MVC. |
|
|
Sondor.AspNetCore.FluentValidation
FluentValidation for Sondor.AspNetCore: a ValidationException is answered with a 400 problem response whose errors member lists the messages of each property, named as the API names its JSON properties. |
|
|
Sondor.Http
Read the answer of another HTTP service as a value: a non-success status, a problem document, a timeout and an unreachable host become a failed Sondor.Results Result, never an exception. Reads the RFC 9457 problems of Sondor.AspNetCore back into an Error with its stable code, with bounded reads, a safe error model, per-call timeouts, an opt-in bearer token that only goes to allowed hosts, and a hook for other error formats. Built on HttpClient and IHttpClientFactory. |
|
|
Sondor.Results.Localization
Translated text for a Sondor.Results Error, from the application's own resources: the title and the message in the current culture, looked up by error code, then by the general template, then the English text. Works with any IStringLocalizer store (resx, JSON, a database) and never shows request data unless told to. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.3.0 | 139 | 11/16/2026 |
| 0.2.0 | 216 | 11/13/2026 |
| 0.1.1 | 175 | 11/13/2026 |
| 0.1.0 | 167 | 11/12/2026 |
| 0.1.0-preview.1 | 53 | 11/12/2026 |