IronAlpine.Framework.Kernel 3.1.1

IronAlpine.Framework.Kernel

Domain and application primitives for the IronAlpine stack: entities, aggregates, projections, domain events, Result / Error, smart enumerations, value objects, strongly typed ids, guards, specifications, paging and time.

• Package id: IronAlpine.Framework.Kernel (3.1.1, net10.0)
• Root namespace: IronAlpine.Kernel
• Dependencies: none beyond the BCL. Safe to reference from every layer, including the domain layer.

The Kernel only defines types. Behaviour attached to them (audit stamping, soft delete, versioning, domain event dispatch, exception-to-HTTP mapping) is implemented by other packages; the tables below say which one.

Installation

<PackageReference Include="IronAlpine.Framework.Kernel" Version="3.1.1" />

There is nothing to register. IClock is registered (as SystemClock) by IronAlpine.Framework.Data; register it yourself if you use the Kernel without the Data package:

services.AddSingleton<IClock, SystemClock>();

Namespaces

Result and Error

Handlers return Result / Result<T> instead of throwing for expected failures.

using IronAlpine.Kernel.Results;

public static class OrderErrors
{
    public static readonly Error NotFound = Error.NotFound("Order.NotFound", "Order was not found.");
    public static readonly Error AlreadyShipped = Error.Conflict("Order.AlreadyShipped", "Order is already shipped.");
}

public Result<decimal> CalculateDiscount(Order order)
{
    if (order.IsShipped)
    {
        return Result.Failure<decimal>(OrderErrors.AlreadyShipped);
    }

    return Result.Success(order.Total * 0.1m);
}

Result / Result<T>

Constructing a success with an error (or a failure with Error.None) throws.

Result implements ITransactionalResult (IsSuccess). The Data package's result-aware transaction behaviour uses it to roll back a transaction when a handler returns a failure.

Functional helpers (ResultExtensions)

Result<OrderDto> dto = GetOrder(id)
    .Map(order => new OrderDto(order.Id, order.Total))   // transform value
    .Tap(d => logger.LogDebug("Loaded {Id}", d.Id));      // side effect on success

Result<Invoice> invoice = GetOrder(id).Bind(order => order.CreateInvoice()); // chain Result-returning calls

string text = GetOrder(id).Match(
    onSuccess: order => $"Order {order.Id}",
    onFailure: error => error.Message);

Error

Error is a record: Error(string Code, string Message, ErrorType Type = ErrorType.Unexpected, IReadOnlyList<ValidationError>? ValidationErrors = null, IReadOnlyDictionary<string, string?>? Metadata = null).

ValidationError(string PropertyName, string Message, string? Code = null) carries field level errors. TechnicalErrors contains ready-made errors: General.NotFound/NullValue/Unexpected, Auth.Unauthorized/Forbidden/InvalidToken, Network.Timeout/Unavailable, Concurrency.Conflict.

ErrorType is not mapped to HTTP status codes by any IronAlpine package; map it in your API layer, for example:

protected IActionResult ToActionResult(Result result) => result.IsSuccess
    ? Ok()
    : result.Error.Type switch
    {
        ErrorType.Validation => BadRequest(result.Error),
        ErrorType.NotFound => NotFound(result.Error),
        ErrorType.Conflict => Conflict(result.Error),
        ErrorType.Unauthorized => Unauthorized(result.Error),
        ErrorType.Forbidden => StatusCode(StatusCodes.Status403Forbidden, result.Error),
        _ => StatusCode(StatusCodes.Status500InternalServerError, result.Error)
    };

Entities, aggregates and projections

using IronAlpine.Kernel.Primitives;

public sealed class Order : AggregateRoot, ISoftDeletable
{
    private readonly List<OrderLine> _lines = [];

    private Order() { }                       // for EF Core

    private Order(Guid id, Guid customerId) : base(id)
    {
        CustomerId = customerId;
    }

    public Guid CustomerId { get; private set; }
    public bool IsDeleted { get; private set; }
    public IReadOnlyCollection<OrderLine> Lines => _lines;

    public static Order Create(Guid customerId)
    {
        var order = new Order(Guid.NewGuid(), customerId);
        order.AddDomainEvent(new OrderCreatedDomainEvent(order.Id, customerId));
        return order;
    }
}

public sealed record OrderCreatedDomainEvent(Guid OrderId, Guid CustomerId) : DomainEvent;

Marker interfaces and who acts on them

Smart enumerations (Enumeration<TEnum>)

public sealed class OrderStatus : Enumeration<OrderStatus>
{
    public static readonly OrderStatus Draft = new(1, "Draft");
    public static readonly OrderStatus Paid = new(2, "Paid");
    public static readonly OrderStatus Shipped = new(3, "Shipped");

    private OrderStatus(int id, string name) : base(id, name) { }
}

var paid = OrderStatus.FromValue(2);              // throws KeyNotFoundException if unknown
var maybe = OrderStatus.FromNameOrDefault("paid"); // case-insensitive, null if unknown
bool ok = OrderStatus.TryFromValue(9, out var none);
IReadOnlyCollection<OrderStatus> all = OrderStatus.GetValues();

• Values are discovered once (lazy, thread safe) from public static fields of type TEnum; duplicate ids throw.
• Equality is by type and Id; ToString() returns Name.
• Persist with the Data package's HasEnumerationConversion() (stores Id). In EF queries compare whole values (x.Status == OrderStatus.Paid); members such as Name are not translatable.

Value objects

public sealed class Money : ValueObject
{
    public Money(decimal amount, string currency)
    {
        Amount = Guard.AgainstNegative(amount);
        Currency = Guard.NotNullOrWhiteSpace(currency);
    }

    public decimal Amount { get; }
    public string Currency { get; }

    protected override IEnumerable<object?> GetEqualityComponents()
    {
        yield return Amount;
        yield return Currency;
    }
}

== / != and GetHashCode use the equality components; values of different types are never equal.

Strongly typed ids

using IronAlpine.Kernel.Identifiers;

public sealed record OrderId(Guid Value) : StronglyTypedId<Guid>(Value);

var id = new OrderId(Guid.NewGuid());   // a default value (Guid.Empty, 0, ...) throws ArgumentException

The Data repositories are keyed by TId : notnull; configure an EF value converter for strongly typed ids yourself.

Guard

using IronAlpine.Kernel.Guarding;

Name = Guard.NotNullOrWhiteSpace(name, nameof(name));
CustomerId = Guard.NotEmpty(customerId, nameof(customerId));
Quantity = Guard.AgainstNegativeOrZero(quantity, nameof(quantity));
Discount = Guard.AgainstOutOfRange(discount, 0m, 100m, nameof(discount));

Available: NotNull, NotNullOrWhiteSpace, NotEmpty(Guid), NotNullOrEmpty(IReadOnlyCollection<T>), AgainstDefault, AgainstNegative, AgainstNegativeOrZero, AgainstOutOfRange. Guards throw ArgumentException family exceptions; use them for programming errors, and Result for business rule violations.

Specifications

using IronAlpine.Kernel.Specifications;

public sealed class OpenOrdersSpecification : Specification<Order>
{
    public override Expression<Func<Order, bool>> ToExpression() => o => !o.IsDeleted && o.ShippedOnUtc == null;
}

var spec = new OpenOrdersSpecification()
    .And(Specification<Order>.Create(o => o.CustomerId == customerId));

IQueryable<Order> query = SpecificationEvaluator.Apply(dbContext.Orders, spec); // query.Where(spec.ToExpression())
bool matches = spec.IsSatisfiedBy(order);

And, Or and Not rewrite the expression parameters, so combined specifications stay translatable by EF Core. IReadRepository<T>.GetListAsync(ISpecification<T>) (Data) accepts specifications directly.

Paging

public sealed record GetOrdersQuery : PagedRequest;     // Page, Size, SortBy, SortDirection

var request = new GetOrdersQuery { Page = 2, Size = 500, SortBy = "createdOnUtc", SortDirection = "DESC" };
// request.Page == 2, request.Size == 100 (clamped), request.SortDirection == "desc", request.Descending == true

var page = PagedResult<OrderDto>.Create(items, page: 2, size: 20, totalCount: 135);
// page.TotalPages == 7, page.HasNextPage == true, page.HasPreviousPage == true

PagedResult<T> exposes Items, Page, Size (alias PageSize), TotalCount, TotalPages, HasNextPage, HasPreviousPage. A negative totalCount throws.

Time

public sealed class InvoiceDueDateCalculator(IClock clock)
{
    public DateTime DueDate() => clock.UtcNow.Date.AddDays(30);
}

Use IClock instead of DateTime.UtcNow in code you want to test with a fixed clock. The Data interceptors use IClock for every timestamp they write: they read it once per save and write that single save instant everywhere.

SaveInstantScope is the ambient (AsyncLocal) form of that instant. The Data package opens it around domain event dispatch; SaveInstantScope.Current is null elsewhere. IntegrationEventBase (EventBus package) uses it as the default OccurredOnUtc. SaveInstantScope.Begin(instant) returns an IDisposable; nested scopes restore the previous value when disposed.

Exceptions

ApplicationException has the same simple name as System.ApplicationException; qualify it when both namespaces are imported.

Pitfalls

• Result<T>.Value throws on failure; check IsFailure first or use Match / TryGetValue.
• Entity has audit properties but only AggregateRoot implements IAuditableEntity. Child entities stay unstamped (default values) unless they implement the interface.
• ProjectionEntity.OccurredOnUtc is the occurrence time of the last applied event; handlers must set it from the incoming event and can use it as a stale-event guard (existing.OccurredOnUtc >= e.OccurredOnUtc means skip). The Data package's OccurredOnInterceptor only fills it with the clock time when it is left null (since 3.0.5; earlier versions overwrote it on every save).
• Specification<T>.IsSatisfiedBy compiles the expression on every call; cache the compiled delegate in hot paths.
• DomainEvent.OccurredOnUtc uses DateTime.UtcNow, not IClock; pass both values to the protected constructor if you need deterministic timestamps.
• new Error(code, message) is ErrorType.Unexpected. Use the typed factories so API layers can map status codes.