API Reference IResult T - ulfbou/Zentient.Results GitHub Wiki
Namespace:
Zentient.ResultsAssembly:Zentient.Results.dllAvailable since:v0.1.0
Represents a generic result type that combines binary success/failure semantics with an optional typed value for successful outcomes, alongside structured errors, messages, and semantic status.
IResult<T>is the standard abstraction for returning value-rich results while preserving error-awareness, observability, and transport-agnostic semantics.
IResult<T> builds upon the IResult interface by introducing a typed success value (T). It enables pure functional result composition while allowing full propagation of structured error information and status metadata.
Key principles include:
- ๐งฐ Composability with Typed Values โ Enables fluent
Map,Bind, and monadic operations. - ๐ฆ Structured Failure Modeling โ Inherits all capabilities of
IResult. - ๐งช Observability-Ready โ Includes
Messagesfor diagnostics and telemetry pipelines. - ๐ Interoperability โ Compatible with transport adapters and protocol-mapped status models.
- ๐ Immutability by Contract โ Result objects are intended to be read-only after creation.
public interface IResult<T> : IResult-
Type:
T - Summary: The value returned by the operation if it succeeded.
-
Behavior: Only populated when
IsSuccessistrue. May throw if accessed whenIsFailureistrue. -
Remarks: Safe extraction should use
.Unwrap()or.GetValueOrDefault(...)extension methods.
Refer to IResult for:
-
IsSuccess(bool) -
IsFailure(bool) -
Errors(IReadOnlyList<ErrorInfo>) -
Messages(IReadOnlyList<string>) -
ErrorMessage(string?) -
Status(IResultStatus)
Extension methods available for IResult<T> (see ResultTransformationExtensions):
| Method | Description |
|---|---|
Map<TIn, TOut>(...) |
Transforms the value of a successful result to a new type. |
Bind<TIn, TOut>(...) |
Applies a result-returning function to a successful result. |
Then<TIn>(...) |
Executes an action if the result is successful; otherwise propagates failure. |
GetValueOrDefault(...) |
Returns the result's value or a fallback default. |
Unwrap() |
Extracts the value or throws if the result is a failure. |
IResult<User> result = userService.GetUserById(id);
if (result.IsSuccess)
{
var user = result.Value;
Console.WriteLine($"Welcome, {user.FullName}!");
}
else
{
logger.LogError("User fetch failed: {0}", result.ErrorMessage);
}Composition example:
var userDisplayResult = userService.GetUserById(id)
.Map(user => user.FullName)
.Bind(name => emailService.SendWelcomeEmail(name));| Layer | Member(s) | Purpose |
|---|---|---|
| Outcome Flag |
IsSuccess, IsFailure
|
Primary success/failure indicator. |
| Value |
Value, Map, Bind
|
Access and transformation of typed results. |
| Error Context |
Errors, ErrorMessage
|
Structured diagnostics and failure analysis. |
| Semantic Status | Status |
Status-driven protocol interoperability (e.g., HTTP, gRPC). |
| Trace Messages | Messages |
Hints, logs, and audit trail data. |
| Type | Description |
|---|---|
Result<T> |
Default generic result implementation. |
HttpResult<T> |
HTTP-specific typed result using ProblemDetails. |
GrpcResult<T> |
Typed result with gRPC code and trailer metadata. |
- Always check
IsSuccessbefore accessingValue. - Use
.Unwrap()with caution: it throws on failure. - Supports fluent error-aware pipelines in CQRS, service layers, and adapters.
- Suitable for async-first design using
Task<IResult<T>>orValueTask<IResult<T>>.
| Layer | Role |
|---|---|
| CQRS Handlers | Used as a return type for queries and commands with typed outputs. |
| Adapters | Adapted via HttpResultAdapter<T>, GrpcResultAdapter<T>. |
| Observability | Messages enriched by Zentient.Telemetry.ITelemetryEnricher. |
| Functional APIs | Consumed by Map, Bind, Then, and other transformation methods. |
IResultResult<T>ErrorInfoResultTransformationExtensionsIResultStatus
#API #GenericResult #FunctionalCore #Immutable #FluentAPI #ErrorHandling #TypedResults #ZentientCore
Last Updated: 2025-06-21 Version: 0.4.0