Pitasoft.Result 7.2.1

Pitasoft.Result

English | Castellano

English

Pitasoft.Result is a .NET library designed to standardize responses from REST services and internal application layers. It provides a robust set of classes to wrap data, status codes, and error collections, facilitating a unified communication contract between APIs, services, and clients.

Features

• Standardized Responses: Unify your API outputs using Result, ResultEntity<T>, ResultEntities<T>, ResultPaged<T>, and ResultBatch<T>.
• Fluent Error Handling: Easily add validation errors, exceptions, or business rule violations using a fluent interface. Includes Result.Try and Result.TryAsync for automatic exception handling.
• Rich Status Management: Built-in StatusResult enum covering common API scenarios (Success, Not Found, Validation Errors, Database Errors, etc.).
• Batch Operations: Specialized support for processing multiple items with ResultBatch<T> using IReadOnlyList<T> for efficient access.
• Pagination Support: ResultPaged<T> provides full paging metadata (TotalCount, Page, PageSize, TotalPages, etc.). Now includes a full set of static factory methods in the Result class (e.g., Result.ErrorPaged, Result.DatabaseErrorPaged).
• Async Support: Native support for IAsyncEnumerable<T> and Task<T> with MaterializeAsync and ToResultEntitiesAsync. Includes MapAsync and BindAsync extensions.
• Improved Serialization: Custom JSON converters for ResultEntities<T> and ResultPaged<T> ensure clean and predictable API outputs.
• Implicit Conversions: Convert StatusResult or entities directly to result types with zero boilerplate.
• Deconstruction: Use C# deconstruction to extract values and status easily: var (status, user) = result;.
• Extensions: Useful helper methods to check for success, specific errors, or state. Including ToOkResult(), ToAddedResult(), ToUpdatedResult(), and ToDeletedResult() for converting entities to results.
• Functional API: Match, Map, Tap, Bind, and Ensure for fluent result processing. Map and Bind now preserve full result state.
• Combine Results: Aggregate multiple results into one with Result.Combine().
• Performance: High-performance implementation with minimal allocations, AggressiveInlining, and efficient collection materialization using IReadOnlyList<T>.

Installation

dotnet add package Pitasoft.Result

Quick start

// 1) Simple result
Result r1 = Result.Ok();
Result r2 = Result.ValidationError().AddError("Email", "Invalid");

// 2) Entity
ResultEntity<User> u = Result.Ok(new User { Id = 1, Name = "John" });
var (status, user) = u; // deconstruction

// 3) Paged entities
var users = new List<User> { new() { Id = 1, Name = "John" } };
ResultPaged<User> paged = Result.OkPaged(users, totalCount: 100, page: 1, pageSize: 10);
foreach (var it in paged) { /* iterate directly */ }

// 4) Try/Catch automation
var result = Result.Try(() => DoWork());
var resultAsync = await Result.TryAsync(async () => await DoWorkAsync());

// 5) Functional extensions
var dto = u.Map(x => new UserDto(x!.Id, x.Name));
var okOrThrow = u.Match(
    onSuccess: () => dto,
    onFailure: res => throw new InvalidOperationException(res.Status.ToString()));

// 6) Combine results
var combined = Result.Combine(Result.Ok(), Result.Error().AddError("E", "err"));

Core Components

1. Simple Result (Result)

Used for operations that don't return data, only a completion status and optional errors.

public Result DeleteUser(int id)
{
    if (id <= 0)
        return Result.ValidationError().AddError("id", "Invalid ID");

    var deleted = _repository.Delete(id);
    if (!deleted) return Result.NotExists();

    return Result.Deleted();
}

// Deconstruction
var (status, errors) = DeleteUser(1);
if (status == StatusResult.Deleted) { /* ... */ }

2. Result with Entity (ResultEntity<T>)

Used for operations returning a single object.

public ResultEntity<User> GetUser(int id)
{
    var user = _repository.Find(id);
    if (user == null) return ResultEntity<User>.NotExists();

    return ResultEntity<User>.Ok(user);
}

Implicit conversions and fluent API:

public ResultEntity<User> GetUser(int id)
{
    var user = _repository.Find(id);
    // T implicitly converts to ResultEntity<T>.Ok(entity)
    return user ?? (ResultEntity<User>)StatusResult.NoExist;
}

// Deconstruction
var (status, user) = GetUser(1);
if (status == StatusResult.Ok) { /* ... */ }

// Fluent API
var result = ResultEntity<User>.Ok(user)
    .WithCode(200)
    .AddError("System", "Service throttled");

3. Result with Multiple Entities (ResultEntities<T>)

Used for lists of results. It uses IReadOnlyList<T> for the Entities property to ensure efficiency. Direct iteration is supported via foreach as it implements IEnumerable<T>.

public ResultEntities<User> GetActiveUsers()
{
    IEnumerable<User> users = _repository.GetActive();
    // Materializes the collection into IReadOnlyList
    return Result.OkEntities(users);
}

4. Paged Result (ResultPaged<T>)

Inherits from ResultEntities<T> and includes complete metadata for paginated results (TotalCount, Page, PageSize, TotalPages, HasNextPage, HasPreviousPage).

Create paged results easily using the Result static class:

public ResultPaged<User> GetUsers(PagingParameters paging)
{
    try 
    {
        var (users, total) = _repository.GetAll(paging);
        return Result.OkPaged(users, total, paging.Page, paging.PageSize);
    }
    catch (Exception ex)
    {
        return Result.DatabaseErrorPaged<User>(ex);
    }
}

// Deconstruction
var (status, users, total, page, pageSize) = result;

5. Batch Result (ResultBatch<T>)

Used for processing multiple items in a single request, providing a global status and individual results for each item using IReadOnlyList<ResultEntity<T>>.

public ResultBatch<User> ImportUsers(List<User> users)
{
    var results = users.Select(u => (ResultEntity<User>)Process(u));
    return ResultBatch<User>.Ok(results);
}

// Deconstruction
var (status, results) = importResult;

Error Handling

The library supports a fluent API for adding errors, which are stored in an ErrorCollection:

return Result.ValidationError()
    .AddError("Email", "Invalid format")
    .AddError("Password", "Too short")
    .AddError(new Exception("Inner system error"));

Associate a numeric code with any result using WithCode():

return Result.Error().WithCode(4001);

Status Codes (StatusResult)

Extensions

Import Pitasoft.Result.Extensions to use these helper methods on any IResult:

• result.IsSuccess(): Returns true if status is Ok, Added, Updated, or Deleted.
• result.IsError(): Returns true for most error-related statuses.
• result.IsFailure(): Returns true for any non-successful state, excluding None, NoExist, and Warning. Covers Unauthorized, Exception, CancelOperation, and more.
• result.IsNotExist(): Returns true if the resource was not found.
• result.HasErrors(): Returns true if there are any errors in the Errors collection.
• result.IsSuccessOrNotExist(): Useful for "Delete" operations where both cases are often handled similarly.
• Materialize() / MaterializeAsync(): Convert IEnumerable<T> or IAsyncEnumerable<T> to ResultEntities<T> or ResultPaged<T>.
• ToPaged(): Convert a result to a ResultPaged<T> preserving state.
• ToResultEntity() / ToResultEntities(): Convert between result types preserving metadata.

Functional API (Match, Map, Bind)

Import Pitasoft.Result.Extensions to use functional-style transformations:

Match — branch on success or failure

var dto = result.Match(
    onSuccess: () => mapper.ToDto(result.Entity),
    onFailure: r => throw new InvalidOperationException(r.Status.ToString())
);

Map — transform the entity if successful

ResultEntity<UserDto> dto = userResult.Map(user => mapper.ToDto(user));

Tap — execute an action without changing the result

result.Tap(() => _logger.LogInformation("Operation successful"))
      .Tap(user => _cache.Set(user));

Bind — chain operations that return results (FlatMap)

ResultEntity<Order> result = GetUser(id)
    .Bind(user => CreateOrder(user));

Ensure — validate a condition on the entity

ResultEntity<User> result = GetUser(id)
    .Ensure(u => u.Age >= 18, "User must be an adult", "Age");

MapAsync — chain async operations

var result = await GetUserAsync(id)
    .MapAsync(user => EnrichWithRolesAsync(user));

Pagination and Entity Parameters

Use PagingParameters to receive pagination input and EntityParameters for filtering, searching, and sorting:

public ResultPaged<User> GetUsers(EntityParameters parameters)
{
    // parameters.Page, parameters.PageSize, parameters.Search, parameters.Query, parameters.Order, parameters.Attrs
    var (users, total) = _repository.GetAll(parameters);
    return Result.OkPaged(users, total, parameters.Page, parameters.PageSize);
}

Batch Helper (Batch<T>)

Use Batch<T> to describe a set of entities and the action to perform on them:

var batch = Batch<User>.Append(newUsers);
var batch = Batch<User>.Update(modifiedUsers);
var batch = Batch<User>.Delete(removedUsers);

Performance

Performance tips

• Prefer using the provided static factories (e.g., Result.Ok(), Result.Added()) or the explicit extension methods (e.g., entity.ToOkResult()). They are very small and are annotated with AggressiveInlining to minimize overhead.
• ResultEntities<T> and ResultPaged<T> use IReadOnlyList<T> for the Entities property. Collections are materialized efficiently into a list only when necessary.
• Direct iteration is supported via foreach. Internally, its enumerator delegates to the underlying collection without using yield, avoiding extra state-machine allocations.
• When creating error results from exceptions, pass deep: false unless you explicitly need inner exception details. This reduces allocations in the ErrorCollection.
• Use Result.Try and Result.TryAsync to simplify your code while ensuring all exceptions are caught and wrapped in a Result or ResultEntity<T>.
• For JSON payload size, ResultPaged<T> automatically ignores calculated properties like TotalPages, HasNextPage, and HasPreviousPage during serialization.

Benchmark results for core operations (Mean time / Allocated memory):

The library is optimized to minimize allocations and maximize throughput. Benchmark results for core operations (Mean time / Allocated memory):

Note: Benchmarks performed on Apple M-series (Arm64).

Castellano

Pitasoft.Result es una librería .NET diseñada para estandarizar las respuestas de los servicios REST y las capas internas de la aplicación. Proporciona un conjunto robusto de clases para envolver datos, códigos de estado y colecciones de errores, facilitando un contrato de comunicación unificado entre APIs, servicios y clientes.

Características

• Respuestas Estandarizadas: Unifica las salidas de tu API usando Result, ResultEntity<T>, ResultEntities<T>, ResultPaged<T> y ResultBatch<T>.
• Gestión de Errores Fluida: Añade fácilmente errores de validación, excepciones o violaciones de reglas de negocio mediante una interfaz fluida. Incluye Result.Try y Result.TryAsync para la captura automática de excepciones.
• Gestión de Estados Enriquecida: Enumerado StatusResult integrado que cubre escenarios comunes (Éxito, No Encontrado, Errores de Validación, Errores de Base de Datos, etc.).
• Operaciones por Lote: Soporte especializado para procesar múltiples elementos con ResultBatch<T> usando IReadOnlyList<T> para un acceso eficiente.
• Soporte para Paginación: ResultPaged<T> proporciona metadatos completos de paginación (TotalCount, Page, PageSize, TotalPages, etc.). Ahora incluye un conjunto completo de métodos de factoría estáticos en la clase Result (ej., Result.ErrorPaged, Result.DatabaseErrorPaged).
• Soporte Async: Soporte nativo para IAsyncEnumerable<T> y Task<T> mediante MaterializeAsync y ToResultEntitiesAsync. Incluye las extensiones MapAsync y BindAsync.
• Serialización Mejorada: Conversores JSON personalizados para ResultEntities<T> y ResultPaged<T> garantizan salidas de API limpias y predecibles.
• Conversiones Implícitas: Convierte StatusResult o entidades directamente a tipos de resultado sin código repetitivo.
• Deconstrucción: Usa la deconstrucción de C# para extraer valores y estado fácilmente: var (status, user) = result;.
• Extensiones: Métodos de ayuda útiles para comprobar éxito, errores específicos o estado. Incluyendo ToOkResult(), ToAddedResult(), ToUpdatedResult() y ToDeletedResult() para convertir entidades en resultados.
• API Funcional: Match, Map, Tap, Bind y Ensure para el procesamiento fluido de resultados. Map y Bind ahora preservan el estado completo del resultado.
• Combinar Resultados: Agrega múltiples resultados en uno solo con Result.Combine().
• Rendimiento: Implementación de alto rendimiento con mínimas asignaciones, AggressiveInlining y materialización eficiente de colecciones mediante IReadOnlyList<T>.

Instalación

dotnet add package Pitasoft.Result

Inicio rápido

// 1) Resultado simple
Result r1 = Result.Ok();
Result r2 = Result.ValidationError().AddError("Email", "No válido");

// 2) Entidad
ResultEntity<User> u = Result.Ok(new User { Id = 1, Name = "John" });
var (status, user) = u; // deconstrucción

// 3) Colección paginada
var users = new List<User> { new() { Id = 1, Name = "John" } };
ResultPaged<User> paginado = Result.OkPaged(users, totalCount: 100, page: 1, pageSize: 10);
foreach (var it in paginado) { /* iteración directa */ }

// 4) Automatización Try/Catch
var resultado = Result.Try(() => HacerTrabajo());
var resultadoAsync = await Result.TryAsync(async () => await HacerTrabajoAsync());

// 5) Extensiones funcionales
var dto = u.Map(x => new UserDto(x!.Id, x.Name));
var okOTira = u.Match(
    onSuccess: () => dto,
    onFailure: res => throw new InvalidOperationException(res.Status.ToString()));

// 6) Combinar resultados
var combinado = Result.Combine(Result.Ok(), Result.Error().AddError("E", "err"));

Componentes Principales

1. Resultado Simple (Result)

Utilizado para operaciones que no devuelven datos, solo un estado de finalización y errores opcionales.

public Result DeleteUser(int id)
{
    if (id <= 0)
        return Result.ValidationError().AddError("id", "ID no válido");

    var deleted = _repository.Delete(id);
    if (!deleted) return Result.NotExists();

    return Result.Deleted();
}

// Deconstrucción
var (status, errors) = DeleteUser(1);
if (status == StatusResult.Deleted) { /* ... */ }

2. Resultado con Entidad (ResultEntity<T>)

Utilizado para operaciones que devuelven un único objeto.

public ResultEntity<User> GetUser(int id)
{
    var user = _repository.Find(id);
    if (user == null) return ResultEntity<User>.NotExists();

    return ResultEntity<User>.Ok(user);
}

Conversiones implícitas y API fluida:

public ResultEntity<User> GetUser(int id)
{
    var user = _repository.Find(id);
    // T se convierte implícitamente a ResultEntity<T>.Ok(entity)
    return user ?? (ResultEntity<User>)StatusResult.NoExist;
}

// Deconstrucción
var (status, user) = GetUser(1);
if (status == StatusResult.Ok) { /* ... */ }

// API Fluida
var result = ResultEntity<User>.Ok(user)
    .WithCode(200)
    .AddError("System", "Servicio saturado");

3. Resultado con Múltiples Entidades (ResultEntities<T>)

Utilizado para listas de resultados. Utiliza IReadOnlyList<T> para la propiedad Entities para garantizar la eficiencia. Se puede iterar directamente sobre el objeto mediante foreach, ya que implementa IEnumerable<T>.

public ResultEntities<User> GetActiveUsers()
{
    IEnumerable<User> users = _repository.GetActive();
    // Materializa la colección en IReadOnlyList
    return Result.OkEntities(users);
}

4. Resultado Paginado (ResultPaged<T>)

Hereda de ResultEntities<T> e incluye metadatos completos para resultados paginados (TotalCount, Page, PageSize, TotalPages, HasNextPage, HasPreviousPage).

Crea resultados paginados fácilmente usando la clase estática Result:

public ResultPaged<User> GetUsers(PagingParameters paging)
{
    try
    {
        var (users, total) = _repository.GetAll(paging);
        return Result.OkPaged(users, total, paging.Page, paging.PageSize);
    }
    catch (Exception ex)
    {
        return Result.DatabaseErrorPaged<User>(ex);
    }
}

// Deconstrucción
var (status, users, total, pagina, tamañoPagina) = result;

5. Resultado por Lote (ResultBatch<T>)

Utilizado para procesar múltiples elementos en una sola petición, proporcionando un estado global y resultados individuales para cada elemento usando IReadOnlyList<ResultEntity<T>>.

public ResultBatch<User> ImportUsers(List<User> users)
{
    var results = users.Select(u => (ResultEntity<User>)Process(u));
    return ResultBatch<User>.Ok(results);
}

// Deconstrucción
var (status, results) = importResult;

Gestión de Errores

La librería soporta una API fluida para añadir errores, que se almacenan en una ErrorCollection:

return Result.ValidationError()
    .AddError("Email", "Formato no válido")
    .AddError("Password", "Demasiado corta")
    .AddError(new Exception("Error interno del sistema"));

Asocia un código numérico a cualquier resultado con WithCode():

return Result.Error().WithCode(4001);

Códigos de Estado (StatusResult)

Extensiones

Importa Pitasoft.Result.Extensions para usar estos métodos de ayuda en cualquier IResult:

• result.IsSuccess(): Devuelve true si el estado es Ok, Added, Updated o Deleted.
• result.IsError(): Devuelve true para la mayoría de los estados relacionados con errores.
• result.IsFailure(): Devuelve true para cualquier estado no exitoso, excluyendo None, NoExist y Warning. Cubre Unauthorized, Exception, CancelOperation y más.
• result.IsNotExist(): Devuelve true si el recurso no fue encontrado.
• result.HasErrors(): Devuelve true si hay algún error en la colección Errors.
• result.IsSuccessOrNotExist(): Útil para operaciones "Delete" donde ambos casos suelen manejarse de forma similar.
• Materialize() / MaterializeAsync(): Convierte IEnumerable<T> o IAsyncEnumerable<T> a ResultEntities<T> o ResultPaged<T>.
• ToPaged(): Convierte un resultado a ResultPaged<T> preservando el estado.
• ToResultEntity() / ToResultEntities(): Convierte entre tipos de resultado preservando metadatos.

API Funcional (Match, Map, Bind)

Importa Pitasoft.Result.Extensions para usar transformaciones de estilo funcional:

Match — bifurcar según éxito o error

var dto = result.Match(
    onSuccess: () => mapper.ToDto(result.Entity),
    onFailure: r => throw new InvalidOperationException(r.Status.ToString())
);

Map — transformar la entidad si el resultado es exitoso

ResultEntity<UserDto> dto = userResult.Map(user => mapper.ToDto(user));

Tap — ejecutar una acción sin cambiar el resultado

result.Tap(() => _logger.LogInformation("Operación exitosa"))
      .Tap(user => _cache.Set(user));

Bind — encadenar operaciones que devuelven resultados (FlatMap)

ResultEntity<Order> result = GetUser(id)
    .Bind(user => CreateOrder(user));

Ensure — validar una condición sobre la entidad

ResultEntity<User> result = GetUser(id)
    .Ensure(u => u.Age >= 18, "El usuario debe ser mayor de edad", "Edad");

MapAsync — encadenar operaciones asíncronas

var result = await GetUserAsync(id)
    .MapAsync(user => EnrichWithRolesAsync(user));

Parámetros de Paginación y Entidad

Usa PagingParameters para recibir la entrada de paginación y EntityParameters para filtrado, búsqueda y ordenación:

public ResultPaged<User> GetUsers(EntityParameters parametros)
{
    // parametros.Page, parametros.PageSize, parametros.Search, parametros.Query, parametros.Order, parametros.Attrs
    var (users, total) = _repository.GetAll(parametros);
    return Result.OkPaged(users, total, parametros.Page, parametros.PageSize);
}

Helper de Lote (Batch<T>)

Usa Batch<T> para describir un conjunto de entidades y la acción a realizar sobre ellas:

var batch = Batch<User>.Append(newUsers);
var batch = Batch<User>.Update(modifiedUsers);
var batch = Batch<User>.Delete(removedUsers);

Rendimiento

Consejos de rendimiento

• Prefiere las factorías estáticas provistas (por ejemplo, Result.Ok(), Result.Added()) o los métodos de extensión explícitos (por ejemplo, entity.ToOkResult()). Son muy pequeñas y están anotadas con AggressiveInlining para minimizar el overhead.
• ResultEntities<T> y ResultPaged<T> utilizan IReadOnlyList<T> para la propiedad Entities. Las colecciones se materializan eficientemente en una lista solo cuando es necesario.
• La iteración directa con foreach está soportada. Internamente, su enumerador delega en la colección subyacente sin usar yield, evitando asignaciones extra de la máquina de estados.
• Al crear resultados de error desde excepciones, usa deep: false salvo que necesites explícitamente el detalle de inner exceptions. Esto reduce asignaciones en ErrorCollection.
• Usa Result.Try y Result.TryAsync para simplificar tu código asegurando que todas las excepciones sean capturadas y envueltas en un Result o ResultEntity<T>.
• Para el tamaño del payload JSON, ResultPaged<T> ignora automáticamente las propiedades calculadas como TotalPages, HasNextPage y HasPreviousPage durante la serialización.

Resultados de benchmarks para operaciones principales (Tiempo medio / Memoria asignada):

La librería está optimizada para minimizar asignaciones y maximizar el rendimiento. Resultados de benchmarks para operaciones principales (Tiempo medio / Memoria asignada):

Nota: Benchmarks realizados en Apple M-series (Arm64).

Autor

Sebastián Martínez Pérez

License

Copyright © 2019-2026 Pitasoft, S.L. Licensed under the LICENSE.txt provided in this repository.