LowCodeHub.MinimalEndpoints 0.0.2

LowCodeHub.MinimalEndpoints

LowCodeHub.MinimalEndpoints is a utility library for ASP.NET Core Minimal APIs that gives you:

• modular endpoint registration
• endpoint logging and validation filters
• language and timezone awareness middleware
• JSON-based localization (IStringLocalizer)
• lightweight event bus (in-memory or Redis-backed)
• mapping and result helpers

Installation

dotnet add package LowCodeHub.MinimalEndpoints

Features

1) Modular endpoint mapping

Define modules implementing IModule and map them automatically.

app.MapModules<Program>();
// or:
app.MapModules(typeof(Program).Assembly);

2) Endpoint filters

• AddLogging<TEndpoint>() for request timing/logging
• AddValidator<TRequest>() for sync/async request validation

app.MapPost("/orders", (CreateOrderRequest req) => Results.Ok())
   .AddValidator<CreateOrderRequest>();

3) Language awareness

Reads language from headers (Language, Accept-Language, X-Culture) and sets request language context.

builder.Services.AddLanguageAwareness(defaultLanguage: "en");
app.UseLanguageAwareness();

4) Timezone awareness

Reads timezone from configured headers and stores it in request context.

builder.Services.AddTimeZoneAwareness("TimeZone", "X-TimeZone");
app.UseTimeZoneAwareness();

5) JSON localization

Uses JSON resource files through native IStringLocalizer.

builder.Services.AddJsonLocalization(options =>
{
    options.ResourcesPath = "Resources";
});

app.UseJsonLocalization("en", "ar");

Example resource files:

• Resources/en.json
• Resources/ar.json

Supports nested keys with dot notation:

{
  "Errors": {
    "USER_NOT_FOUND": "User not found"
  }
}

Access key: Errors.USER_NOT_FOUND

6) Event bus (in-memory)

builder.Services.AddEventBus<Program>();

• bounded channel for backpressure
• hosted background processor
• handler auto-registration from scanned assemblies

7) Event bus (Redis-backed)

builder.Services.AddRedisEventBus(options =>
{
    options.ConnectionString = "localhost:6379";
    options.QueueKey = "domain-events";
    options.ProcessingQueueKey = "domain-events:processing";
    options.PopTimeoutSeconds = 5;
}, typeof(Program).Assembly);

Redis mode includes:

• reliable processing queue (BRPOPLPUSH)
• ack on success
• nack + requeue on failure

Domain events

public record OrderCreated(Guid OrderId) : IDomainEvent;

public sealed class OrderCreatedHandler : IDomainEventHandler<OrderCreated>
{
    public ValueTask Handle(OrderCreated domainEvent, CancellationToken cancellationToken)
    {
        // handle event
        return ValueTask.CompletedTask;
    }
}

Publish event:

await eventBus.Publish(new OrderCreated(orderId), cancellationToken);

Operations

The operations pattern provides a structured way to define units of work that return ErrorOr<TResult>. Each operation is a self-contained handler with single responsibility, dispatched through a single IOperation service.

Define a request and handler

// The request defines the return type via IOperationRequest<TResult>
public record CreateOrderRequest(string Name, List<Item> Items) : IOperationRequest<OrderDto>;

// One handler per operation
public class CreateOrderHandler(IOrderRepository repo) : IOperationHandler<CreateOrderRequest, OrderDto>
{
    public async Task<ErrorOr<OrderDto>> HandleAsync(CreateOrderRequest request, CancellationToken cancellationToken = default)
    {
        if (await repo.ExistsAsync(request.Name, cancellationToken))
            return Error.Conflict("Order.Duplicate", "Order already exists");

        var order = await repo.CreateAsync(request, cancellationToken);

        return new OrderDto(order.Id, order.Name);
    }
}

Register operations

// Single assembly
builder.Services.AddOperations<Program>();

// Multiple assemblies
builder.Services.AddOperations(typeof(Program).Assembly, typeof(SharedLib).Assembly);

Use in endpoints

app.MapPost("/orders", async (CreateOrderRequest req, IOperation operation, CancellationToken ct) =>
{
    var result = await operation.ExecuteAsync(req, ct); // returns ErrorOr<OrderDto> — inferred from request

    return result.IsError
        ? EndpointResult.Failure(result.FirstError).ToBusinessFailure()
        : EndpointResult<OrderDto>.Success(result.Value).ToCreated($"/orders/{result.Value.Id}");
});

Chain multiple operations (short-circuit on first error)

app.MapPost("/orders", async (CreateOrderRequest req, IOperation operation, CancellationToken ct) =>
{
    var result = await operation.ExecuteAsync(req, ct)
        .ThenAsync(order => operation.ExecuteAsync(new SendConfirmationRequest(order.Id), ct));

    return result.IsError
        ? EndpointResult.Failure(result.FirstError).ToBusinessFailure()
        : EndpointResult.Success().ToOk();
});

Best practices

1. Use MapModules to keep endpoint registration organized by feature.
2. Add AddValidator<TRequest>() to write-side endpoints.
3. Prefer Redis event bus for multi-instance deployments.
4. Keep event handlers idempotent.
5. Use short, stable event contract names and avoid breaking schema changes.
6. Keep localization JSON keys stable across languages.

Notes

• Request language/timezone contexts are cleaned after each request.
• Redis event bus requires StackExchange.Redis connectivity.
• If no event handlers are registered for an event, processing still completes safely.