MonadicTypes.NET.AspNetCore 0.3.0-preview.2

MonadicTypes.NET.AspNetCore

NativeAOT-compatible typed HTTP results, RFC problem responses, validation conversion, and endpoint metadata for MonadicTypes.NET. This package includes MonadicTypes.NET.Errors and the core package transitively.

Requirements

• ASP.NET Core and .NET 10 or later
• Minimal APIs are the primary reflection-free path
• No runtime dependency on FluentValidation or an OpenAPI package

Install

dotnet add package MonadicTypes.NET.AspNetCore --prerelease

Quick Start

using Microsoft.AspNetCore.Http.HttpResults;
using MonadicTypes;
using MonadicTypes.AspNetCore;

public sealed record Customer(int Id);

static Results<Ok<Customer>, ProblemHttpResult> GetCustomer(int id)
{
    Result<Customer, Error> result = id > 0
        ? Result<Customer, Error>.Ok(new Customer(id))
        : Result<Customer, Error>.Fail(
            Error.NotFound("CUSTOMER_NOT_FOUND", "Customer was not found."));

    return result.ToHttpResult(static customer => TypedResults.Ok(customer));
}

app.MapGet("/customers/{id:int}", GetCustomer)
    .ProducesErrors(ErrorType.NotFound, ErrorType.Unexpected);

HTTP Contract

• Built-in Error categories map to bounded default status codes.
• Private messages and exception causes are not exposed by default.
• ValidationErrors maps to a typed validation problem response.
• Errors implementing IErrorConvertible<Error> can use the default policy.
• Error.Custom values from 400 through 599 retain that status at this boundary; other custom numeric categories map to the generic 500 response.
• Create, CreateExample, ToHttpResult, and error metadata accept explicit 400-through-599 overrides without changing the application error category.
• Two-callback and IHttpResultMapper overloads are escape hatches for custom domain errors, status policies, or ProblemDetails shapes.
• .ProducesErrors(...) adds Minimal API metadata; [ProducesError] provides controller metadata without requiring a runtime OpenAPI dependency.
• .ProducesErrorCatalog(...) and [ProducesErrorCatalog] attach stable public error codes without taking a dependency on an OpenAPI document engine. Add MonadicTypes.NET.AspNetCore.OpenApi only when document transformation is required.

ErrorCatalogEntry rejects an uninitialized or undefined category and blank public fields. ErrorCatalogMetadata requires at least one entry, copies the input, rejects duplicate codes ordinally, and exposes the owned data through a zero-allocation readonly span. Larger catalogs use a bounded validation table while small and collision-heavy catalogs use a bounded linear fallback. OpenAPI transformation rejects duplicate codes across all metadata attached to one endpoint, even when statuses differ. Inline Minimal API entries should use explicit new ErrorCatalogEntry(...) construction for stable package-consumer inference.

ErrorProblemDetails.CreateExample(error) applies the normal response policy without reading ambient activity or request trace data. Use it for deterministic documentation and tests; Create(error, context) retains normal trace behavior. Registered HTTP errors receive stable titles and every status in the 400-through- 599 range receives a deterministic urn:problem-type:http-{status} identity. Unassigned statuses use the generic HTTP error title. Status-specific headers remain application policy.

Minimal API adapters return strongly typed results and are NativeAOT tested. Controller applications can use the metadata attribute and own their MVC result adapter because controller serialization and action-result policy vary by app.

Install MonadicTypes.NET.Async and MonadicTypes.NET.Effects separately when the endpoint pipeline needs them; this package does not force unrelated features into an API.

Related Packages

Documentation

See ASP.NET Core usage and the compatibility contract.

Apache-2.0. Developed with AI assistance.

Complete API reference

Documented public members: 54