docs: Command/Query docs changes

Author: vp

docs/features-application-commands-queries.md

@@ -8,12 +8,12 @@
 
 ### Background
 
-The [Command Query Separation](https://en.wikipedia.org/wiki/Command%E2%80%93query_separation#:~:text=Command%2Dquery%20separation%20(CQS),the%20caller%2C%20but%20not%20both.) (CQS) principle, introduced by Bertrand Meyer, divides operations into commands, which modify system state and queries, which retrieve data without side effects. This separation enhances code clarity, predictability and maintainability by ensuring methods have distinct roles. By moving away from bloated application services that centralize all logic, commands and queries encapsulate specific business operations in smaller, focused units. This reduces the number of dependencies injected into each handler, improves testability by allowing isolated testing and promotes a cleaner architecture.
+The [Command Query Separation](https://en.wikipedia.org/wiki/Command%E2%80%93query_separation#:~:text=Command%2Dquery%20separation%20(CQS),the%20caller%2C%20but%20not%20both.) (CQS) principle, introduced by Bertrand Meyer, divides operations into commands, which modify system state, and queries, which retrieve data without side effects. This separation enhances code clarity, predictability and maintainability by ensuring methods have distinct roles. By moving away from bloated application services that centralize all logic, commands and queries encapsulate specific business operations in smaller, focused units. This reduces the number of dependencies injected into each handler, improves testability by allowing isolated testing and promotes a cleaner architecture.
 
-- **Commands**: Perform state-changing actions (e.g., creating a customer). They typically return `Result<Unit>` for actions with no meaningful return or `Result<T>` for minimal data like an ID.
-- **Queries**: Retrieve data without altering state (e.g., fetching a customer). They return `Result<T>` with the requested data and are idempotent.
+- **Commands**: Perform state-changing actions such as creating or updating data. They typically return `Result<Unit>` for actions with no meaningful return or `Result<T>` for minimal data such as an identifier or summary model.
+- **Queries**: Retrieve data without altering state. They return `Result<T>` with the requested data and are idempotent.
 
-In Domain-Driven Design (DDD), commands and queries align with application services, encapsulating business logic and data access. The `Requester` feature in bITDevKit implements CQS using a mediator-like pattern, dispatching requests to handlers with type-safe `Result<T>` outcomes and extensible pipeline behaviors (e.g., validation, retries). This reduces coupling, as callers are unaware of handler implementations, minimizes dependency injection in handlers, and enables consistent handling of cross-cutting concerns, making the codebase more modular and testable.
+In Domain-Driven Design (DDD), commands and queries align with application services, encapsulating business logic and data access. The `Requester` feature in bITDevKit implements CQS using a mediator-like pattern, dispatching requests to handlers with type-safe `Result<T>` outcomes and extensible pipeline behaviors such as validation, retries, and timeouts. This reduces coupling, as callers are unaware of handler implementations, minimizes dependency injection in handlers, and enables consistent handling of cross-cutting concerns, making the codebase more modular and testable.
 
 Many handlers also depend on the shared mapping abstraction to translate between request models, domain objects, and response DTOs; see [Common Mapping](./common-mapping.md).
 
@@ -28,11 +28,11 @@ Many handlers also depend on the shared mapping abstraction to translate between
 
 The `Requester` system provides:
 
-- **Requests**: Inherit from `RequestBase<TResponse>`, defining inputs and outputs.
-- **Handlers**: Implement `RequestHandlerBase<TRequest, TResponse>`, returning `Result<TResponse>`.
+- **Requests**: Source-generated command and query types authored as `partial` classes with `[Command]` or `[Query]`.
+- **Handlers**: Business logic written inline with a single instance `[Handle]` method.
 - **Dispatching**: Via `IRequester.SendAsync()`, routing requests through a pipeline of behaviors.
 
-Behaviors (e.g., `ValidationPipelineBehavior`, `RetryPipelineBehavior`) handle concerns without altering business logic.
+Behaviors such as `ValidationPipelineBehavior` and `RetryPipelineBehavior` handle concerns without altering business logic.
 
 ### Flow Diagram
 
@@ -61,118 +61,140 @@ sequenceDiagram
 
 ## Setup
 
-Register the `Requester` in the dependency injection (DI) container (e.g., in `CoreModule.cs`):
+Register the `Requester` in the dependency injection container:
 
 ```csharp
 services.AddRequester()
-    .AddHandlers()  // Scans for handlers
-    .WithBehavior<ValidationPipelineBehavior<,>>()  // Validates requests
-    .WithBehavior<RetryPipelineBehavior<,>>();      // Adds retries
+    .AddHandlers()
+    .WithBehavior<ValidationPipelineBehavior<,>>()
+    .WithBehavior<RetryPipelineBehavior<,>>();
+```
+
+Add the code generation package to the project that contains the commands and queries:
+
+```xml
+<PackageReference Include="BridgingIT.DevKit.Common.Utilities.CodeGen"
+                  Version="x.y.z"
+                  PrivateAssets="all" />
 ```
 
 ## Basic Usage
 
 ### Defining a Command
 
-Commands modify state and return `Result<T>` (e.g., a DTO or `Unit`).
+Commands modify state and return `Result<Unit>` or `Result<T>`.
 
 ```csharp
-public class CustomerCreateCommand(CustomerModel model) : RequestBase<CustomerModel>
+[Command]
+public partial class CustomerCreateCommand
 {
-    public CustomerModel Model { get; set; } = model;
+    public string FirstName { get; init; }
+
+    public string LastName { get; init; }
 
-    public class Validator : AbstractValidator<CustomerCreateCommand>
+    public string Email { get; init; }
+
+    [Handle]
+    private async Task<Result<CustomerModel>> HandleAsync(
+        IMapper mapper,
+        IGenericRepository<Customer> repository,
+        CancellationToken cancellationToken)
     {
-        public Validator()
-        {
-            this.RuleFor(c => c.Model).NotNull();
-            this.RuleFor(c => c.Model.FirstName).NotNull().NotEmpty().WithMessage("Must not be empty.");
-            this.RuleFor(c => c.Model.LastName).NotNull().NotEmpty().WithMessage("Must not be empty.");
-            this.RuleFor(c => c.Model.Email).NotNull().NotEmpty().WithMessage("Must not be empty.");
-        }
+        var customer = mapper.Map<CustomerCreateCommand, Customer>(this);
+        await repository.InsertAsync(customer, cancellationToken);
+
+        return Success(mapper.Map<Customer, CustomerModel>(customer));
     }
 }
 ```
 
-### Command Handler
+### Validating a Command
 
-Handlers implement business logic, often using repositories.
+For simple cases, place validation directly on the properties:
 
 ```csharp
-[HandlerRetry(2, 100)]   // Retry twice with 100ms delay
-[HandlerTimeout(500)]    // Timeout after 500ms
-public class CustomerCreateCommandHandler(
-    ILoggerFactory loggerFactory,
-    IMapper mapper,
-    IGenericRepository<Customer> repository)
-    : RequestHandlerBase<CustomerCreateCommand, CustomerModel>(loggerFactory)
+[Command]
+public partial class CustomerRenameCommand
 {
-    protected override async Task<Result<CustomerModel>> HandleAsync(
-        CustomerCreateCommand request,
-        SendOptions options,
-        CancellationToken cancellationToken)
+    [ValidateNotEmptyGuid("CustomerId is required.")]
+    public string CustomerId { get; init; }
+
+    [ValidateNotEmpty("Display name is required.")]
+    [ValidateLength(3, 100, "Display name must be between 3 and 100 characters.")]
+    public string DisplayName { get; init; }
+
+    [Handle]
+    private Result<Unit> Handle()
     {
-        var customer = mapper.Map<CustomerModel, Customer>(request.Model);
-        return await repository.InsertResultAsync(customer, cancellationToken: cancellationToken)
-            .Tap(_ => Console.WriteLine("AUDIT"))
-            .Map(mapper.Map<Customer, CustomerModel>);
+        return Success();
     }
 }
 ```
 
-### Defining a Query
-
-Queries retrieve data and return `Result<T>`.
+For more complex rules, the `[Validate]` marker can be used:
 
 ```csharp
-public class CustomerFindOneQuery(string customerId) : RequestBase<CustomerModel>
+[Command]
+public partial class CustomerImportCommand
 {
-    public string CustomerId { get; } = customerId;
+    [ValidateNotEmpty("At least one email address is required.")]
+    [ValidateEachNotEmpty("Email entries cannot be empty.")]
+    public List<string> Emails { get; init; }
 
-    public class Validator : AbstractValidator<CustomerFindOneQuery>
+    [Validate]
+    private static void Validate(InlineValidator<CustomerImportCommand> validator)
     {
-        public Validator()
-        {
-            this.RuleFor(c => c.CustomerId).NotNull().NotEmpty().WithMessage("Must not be empty.");
-        }
+        validator.RuleFor(x => x.Emails) // regular fluent validation
+            .Must(x => x.Count <= 100).WithMessage("A maximum of 100 email addresses is allowed.");
+    }
+
+    [Handle]
+    private Result<Unit> Handle()
+    {
+        return Success();
     }
 }
 ```
 
-### Query Handler
+### Defining a Query
+
+Queries retrieve data and return `Result<T>`.
 
 ```csharp
-[HandlerRetry(2, 100)]
-[HandlerTimeout(500)]
-public class CustomerFindOneQueryHandler(
-    IMapper mapper,
-    IGenericRepository<Customer> repository)
-    : RequestHandlerBase<CustomerFindOneQuery, CustomerModel>
+[Query]
+public partial class CustomerFindOneQuery
 {
-    protected override async Task<Result<CustomerModel>> HandleAsync(
-        CustomerFindOneQuery request,
-        SendOptions options,
-        CancellationToken cancellationToken) =>
-        await repository.FindOneResultAsync(CustomerId.Create(request.CustomerId), cancellationToken: cancellationToken)
-            .Tap(_ => Console.WriteLine("AUDIT"))
-            .Map(mapper.Map<Customer, CustomerModel>);
+    [ValidateNotEmptyGuid("CustomerId is required.")]
+    public string CustomerId { get; }
+
+    [Handle]
+    private async Task<Result<CustomerModel>> HandleAsync(
+        IMapper mapper,
+        IGenericRepository<Customer> repository,
+        CancellationToken cancellationToken)
+    {
+        var customer = await repository.FindOneAsync(CustomerId, cancellationToken: cancellationToken);
+
+        return customer != null
+            ? Success(mapper.Map<Customer, CustomerModel>(customer))
+            : Failure($"Customer with ID {CustomerId} was not found.");
+    }
 }
 ```
 
 ### Dispatching
 
-Inject and use the `IRequester`:
+Inject and use `IRequester`:
 
 ```csharp
 var requester = serviceProvider.GetRequiredService<IRequester>();
 
-// Command
-var command = new CustomerCreateCommand(new CustomerModel
+var command = new CustomerCreateCommand
 {
     FirstName = "John",
     LastName = "Doe",
     Email = "john.doe@example.com"
-});
+};
 
 var commandResult = await requester.SendAsync(command);
 if (commandResult.IsSuccess)
@@ -184,7 +206,6 @@ else
     Console.WriteLine($"Errors: {string.Join(", ", commandResult.Errors.Select(e => e.Message))}");
 }
 
-// Query
 var query = new CustomerFindOneQuery("some-guid");
 var queryResult = await requester.SendAsync(query);
 if (queryResult.IsSuccess)
@@ -193,4 +214,12 @@ if (queryResult.IsSuccess)
 }
 ```
 
-See [features-requester-notifier.md](./features-requester-notifier.md) for more details.
+### Notes
+
+- The response type is inferred from the `Result<T>` returned by `[Handle]`.
+- `Success(...)` and `Failure(...)` can be used directly inside `[Handle]`.
+- DI services can be declared as parameters on `[Handle]` and are resolved automatically.
+- `CancellationToken` and `SendOptions` can also be declared as `[Handle]` parameters when needed.
+- Handler policy attributes such as retry, timeout, authorization, and transactions can be applied at the command or query definition.
+
+See [features-requester-notifier.md](./features-requester-notifier.md) for more details (Appendix D: Source-Generated Commands and Queries).

docs/features-requester-notifier.md

@@ -1494,20 +1494,20 @@ The `Requester` and `Notifier` systems share similarities with the popular **Med
 
 ---
 
-# Appendix C: Generic Handlers in Requester and Notifier
+## Appendix C: Generic Handlers in Requester and Notifier
 
-## Overview
+### Overview
 
 Generic handlers in the `Requester` and `Notifier` systems enable handling of generic request/notification types (e.g., `GenericRequest<TData>`, `GenericNotification<TData>`) with a single handler, reducing code duplication. They are registered using `AddGenericHandlers`, which discovers open generic handlers, validates constraints, and registers closed handlers (e.g., `GenericDataProcessor<UserData>`).
 
-## Key Features
+### Key Features
 
 - **Automatic Discovery**: `AddGenericHandlers` scans assemblies for open generic handlers and discovers type arguments based on constraints.
 - **Constraint Validation**: Ensures type arguments meet constraints (e.g., `where TData : class, IDataItem`).
 
-## Setup with `AddGenericHandlers`
+### Setup with `AddGenericHandlers`
 
-### Requester
+#### Requester
 
 ```csharp
 services.AddRequester()
@@ -1516,7 +1516,7 @@ services.AddRequester()
     .WithBehavior<ValidationPipelineBehavior<,>>();
 ```
 
-### Notifier
+#### Notifier
 
 ```csharp
 services.AddNotifier()
@@ -1527,9 +1527,9 @@ services.AddNotifier()
 
 `AddGenericHandlers` discovers open generic handlers (e.g., `GenericDataProcessor<TData>`), finds type arguments (e.g., `UserData`, `OrderData`) that satisfy constraints, and registers closed handlers.
 
-## Examples
+### Examples
 
-### Generic Request Handler (Requester)
+#### Generic Request Handler (Requester)
 
 ```csharp
 public class ProcessDataRequest<TData> : RequestBase<string>
@@ -1566,7 +1566,7 @@ var userRequest = new ProcessDataRequest<UserData> { Data = new UserData { Id =
 var result = await requester.SendAsync(userRequest); // "Processed: user123"
 ```
 
-### Generic Notification Handler (Notifier)
+#### Generic Notification Handler (Notifier)
 
 ```csharp
 public class GenericNotification<TData> : NotificationBase
@@ -1601,6 +1601,8 @@ var userNotification = new GenericNotification<UserData> { Data = new UserData {
 var result = await notifier.PublishAsync(userNotification); // Logs: "Handled: user123"
 ```
 
+---
+
 ## Appendix D: Source-Generated Commands and Queries
 
 The source-generated authoring model lets you write a command or query as a single partial type. This is a convenient way to define simple requests without needing separate request and handler classes. The source generator creates the necessary boilerplate code, allowing you to focus on the business logic.