Clarify the documentation on the TRequest Handle(TRequest)

[IlSocio]

Is your feature request related to a problem? Please describe.
It is not clear to me why the signature of the IHandleRequest interface returns TRequest.

Describe the solution you'd like
Can't it just return void?

Describe alternatives you've considered
I looked within the code comments and within the documentation, but wasn't able to find an answer to this very basic doubt.
But the framework/library seems pretty solid to me, so, I'm wondering what am I missing.

I would make totally sense to me if we could return a different type:
"TResponse IHandleRequest(TRequest)"

Additional context

[DevJonny]

Hey @IlSocio. I just moved this over to "Discussions" as it feels more appropriate as a Q&A type thing.

One reason (the may be others intended) is so that you can access properties on the Command that might have been mutated as part of the handler. For example you have a Id property on your command that is initially null or have a default value. Then as part of the handling of the command you persist a new entity, and you set the Id property to Id of your newly persisted entity. Then (usually in the a Controller) when the Send method finishes executing you have the newly populated Id property to use to query the object to return it on a response (we normally use Darker for this).

I would make totally sense to me if we could return a different type:
"TResponse IHandleRequest(TRequest)"

This is actually how Darker works, and is more suited to the query side of CQRS.

[IlSocio]

Thanks @DevJonny, the use-case you mentioned makes sense.
Is there any particular reason to force the return type to exactly match the type given in input?
Would you accept a pull request to allow the return type to be different, which will give us the flexibility to accommodate other use-cases?
TResponse IHandleRequest(TRequest)
like MediatR interface essentially.

[DevJonny]

Is there any particular reason to force the return type to exactly match the type given in input?

I can't speak to the original design, that would be a question for @iancooper or @holytshirt as they built Brighter.

Would you accept a pull request to allow the return type to be different, which will give us the flexibility to accommodate other use-cases?

Also probably one for @iancooper, but as this would be a breaking change if accepted and would have to be included in Brighter v10. On the point of MediatR, that acts as both the Command & Query side whereas we have Brighter and Darker to handle each side.

@IlSocio I am curious though as to what use case you're after with TResponse Handle(TRequest request);?

[iancooper]

Brighter does two things:

• It is a Command Dispatcher => it routes requests to handlers to allow separation of call site from domain code and knowledge of recipient from the caller
• It is a Command Processor => it allows common orthogonal operations to be lifted out of the domain code that executes the request, such as logging, and into middleware that runs before the handler.

What Brighter is not is a mediator => which is a collaborator between colleagues, for example within a domain: (see https://softwareengineering.stackexchange.com/questions/364139/what-is-the-difference-between-the-command-and-mediator-patterns)

As we can have a number of orthogonal elements that run before the domain code, and may wish to re-use them, we use the pipes-and-filters approach to middleware.

In pipes and filters we have a source - in our case the command processor putting the request into the pipeline and a sink - the domain code. In between you can insert filter steps - middleware. As with most implementations of the filter pattern, to allow arbitrary composition, where you have an input and an output, and want to allow arbitrary composition of filter chains - both in order and in type - you need to make the input and output the same. Once input and output are the same, you can make the input of one filter, the output of another filter, allowing them to be chained together. This is not true if the input is not the output.

Incidentally, because the request being sent down the chain - the information packet - is both output and input we are comfortable with having fields on it that are filled by some part of the chain, not by the source.

A typical usage here is when the source cannot decide the id of any entity that will be created, but we want to access it after the pipeline runs. By putting id on the request, we can read it afterwards.

A reasonable question might be why Send and Publish don't return TRequest? That might be a change that we could make. Now of course by the time the pipeline terminates, the pass-by-reference approach of C# means that the original request already has all of the modifications, so we don't need to. But arguably this is true throughout the pipeline but we included a return value to make it clearer that mutation was possible. So if it was clearer to have TRequest as the return type, perhaps in v10.

We don't really want to modify this to change TRequest into TResponse here for this reason.

Now Darker does do TRequest to TRespone. Why the difference?

Because Brighter is the "command" operation i.e. how we mutate state and Darker is the "query" operation, how we read state. Apart from "get of jail" uses such as "what is the id of the newly created entity" we don't recommend using Brighter to return state in its TRequest to the caller. What happens in the pipeline stays in the pipeline. Instead we recommend using Brighter to change it and Darker to read it.

This separation is Command Query Separation (CQS): https://en.wikipedia.org/wiki/Command%E2%80%93query_separation

Does that help at all? We have a fundamental difference of approach here to Mediatr (its not a mediator and it mixes commands and queries)

[DevJonny]

Thank you @iancooper, far more eloquently put than I could have done.

[iancooper]

PS Technically we can run middleware after your domain code. Because of the Russian doll model you mostly don't need to do that explicitly very often as you just run your code after calling the next handler in the chain not before. But if, for whatever reason, you really want to run the middleware after the domain handler, you can. It's just about flexibility, but its not usually a recommendation.

[IlSocio]

thank you a lot for the detailed explaination @iancooper.
You provided a lot of valuable information, it will take me some time to digest, to learn and to put all the pieces together .
I'll came back on this topic at some point :)
keep up the good work!