NPv.CQS.Abstractions 3.0.0

NPv.CQS.Abstractions

Minimal, dependency-free contracts for applications following the Command-Query Separation (CQS) pattern.

📌 Breaking changes

v3.0.0

• Target framework updated to net10.0 (dropped net9.0 support).

This is a personal library that focuses on the latest .NET runtime to keep maintenance simple and enjoyable.

✨ Overview

NPv.CQS.Abstractions is a foundational library containing interfaces and contracts for building systems based on the Command‑Query Separation (CQS) principle.

It does not include any infrastructure or implementation — only the minimal building blocks that let infrastructure resolve and invoke handlers automatically.

Use this package in your domain, application, or core layers to define behaviors without pulling in any dependencies.

🔧 Interfaces Included

🟢 Commands

🔵 Queries

🚨 Breaking Changes in v2.0.0+

• All commands now return a Result or Result<TResult> instead of being void tasks.
• ICommandContext split into two flavors: ICommandContext (no result) and ICommandContext<TResult> (with typed result).
• Extension methods added for shorter syntax when executing commands.

Before (v1.x)

public class CreateOrderCommand : ICommand<CreateOrderCommandContext>
{
    public Task ExecuteAsync(CreateOrderCommandContext context)
    {
        // Domain logic
        return Task.CompletedTask;
    }
}

After (v2.x)

public class CreateOrderCommand : ICommand<CreateOrderCommandContext>
{
    public Task<Result> ExecuteAsync(CreateOrderCommandContext context)
    {
        if (context.Amount <= 0)
            return Task.FromResult(Result.Failure(new Error("Validation.Invalid", "Amount")));

        return Task.FromResult(Result.Success());
    }
}

Commands with results:

public record LoginUserCommandContext(string Email, string Password) : ICommandContext<LoginUserCommandResult>;

public record LoginUserCommandResult(string Email, string Token);

public class LoginUserCommand : ICommand<LoginUserCommandContext, LoginUserCommandResult>
{
    public Task<Result<LoginUserCommandResult>> ExecuteAsync(LoginUserCommandContext context, CancellationToken ct = default)
    {
        if (context.Password != "123")
            return Task.FromResult(Result<LoginUserCommandResult>.Failure(new Error("Auth.Invalid", "Bad password")));

        return Task.FromResult(new LoginUserCommandResult(context.Email, "jwt-token"));
    }
}

📦 Installation

dotnet add package NPv.CQS.Abstractions

💡 Examples

Define a command without result

public record BanUserCommandContext(Guid UserId) : ICommandContext;

public class BanUserCommand : ICommand<BanUserCommandContext>
{
    public Task<Result> ExecuteAsync(BanUserCommandContext context, CancellationToken ct = default)
    {
        // Domain logic (ban user)
        return Task.FromResult(Result.Success());
    }
}

Define a command with result

public record CreateUserContext(string Email, string Password) : ICommandContext<UserDto>;

public record UserDto(Guid Id, string Email);

public class CreateUserCommand : ICommand<CreateUserContext, UserDto>
{
    public Task<Result<UserDto>> ExecuteAsync(CreateUserContext context, CancellationToken ct = default)
    {
        if (string.IsNullOrWhiteSpace(context.Email))
            return Task.FromResult(Result<UserDto>.Failure(new Error("Validation.Invalid", "Email required")));

        return Task.FromResult(new UserDto(Guid.NewGuid(), context.Email));
    }
}

Define a query

public record FindById(Guid Id) : ICriterion;

public class FindOrderByIdQuery(IOrderService orders) : IQuery<FindById, Order>
{
    public Task<Order> AskAsync(FindById criterion) =>
        orders.GetAsync(criterion.Id);
}

Use in application code

public class OrdersController(ICommandExecutor exec, IQueryBuilder queries)
{
    public async Task<IActionResult> Create(Guid id, decimal amount)
    {
        var result = await exec.ExecuteAsync(new CreateOrderCommandContext(id, amount));
        return result.IsSuccess ? Ok() : BadRequest(result.Errors);
    }

    public async Task<IActionResult> Login(string email, string password)
    {
        var result = await exec.ExecuteAsync<LoginUserCommandResult>(
            new LoginUserCommandContext(email, password));
        return result.IsSuccess ? Ok(result.Value) : Unauthorized(result.Errors);
    }

    public Task<Order> Get(Guid id) =>
        queries.ForAsync<Order>().With(new FindById(id));
}

Note: ICommandExecutor is just a contract; infrastructure can provide an implementation that wraps execution in a Unit of Work (see NPv.Uow.Abstractions) or adds logging/telemetry/retries.

📚 Designed For Use With

• NPv.CQS.Infrastructure – runtime execution (dispatch via DI, Autofac/MS.DI modules)
• NPv.Uow.Abstractions – optional Unit of Work contract for transactional execution
• Any DI container or runtime

⚖️ License

MIT — you are free to use this in commercial and open-source software.