unify query and command handling under requestHandling (#452)

Author: osoykan

MIGRATION_GUIDE.md

@@ -15,15 +15,16 @@ Documentation is available at [https://trendyol.github.io/kediatR/](https://tren
 ## Show me the code
 
 ```kotlin
-class PingCommand : Command.Unit // or
-class PingQuery : Query<String> // or
+class PingCommand : Request.Unit // or
+class PingQuery : Request<String> // or
 class PingNotification : Notification
-class PingCommandHandler : CommandHandler.Unit<PingCommand> {
-  override suspend fun handle(command: PingCommand) {
+
+class PingCommandHandler : RequestHandler.Unit<PingCommand> {
+  override suspend fun handle(command: PingCommand) : Unit {
     println("Pong!")
   }
 }
-class PingQueryHandler : QueryHandler<PingQuery, String> {
+class PingQueryHandler : RequestHandler<PingQuery, String> {
   override suspend fun handle(query: PingQuery): String {
     return "Pong!"
   }

README.md

@@ -6,8 +6,7 @@ package com.trendyol.kediatr
  * This class extends Registrar and acts as a central registry that discovers and organizes
  * all handlers and behaviors from the dependency provider. It maintains separate collections
  * for different types of handlers:
- * - Query handlers (one-to-one mapping)
- * - Command handlers (one-to-one mapping)
+ * - Request handlers (one-to-one mapping for both queries and commands)
  * - Notification handlers (one-to-many mapping)
  * - Pipeline behaviors (set of unique behaviors)
  *
@@ -16,8 +15,7 @@ package com.trendyol.kediatr
  *
  * @param dependencyProvider The dependency provider used to discover and resolve handlers
  * @see Registrar
- * @see QueryProvider
- * @see CommandProvider
+ * @see RequestProvider
  * @see NotificationProvider
  * @see PipelineProvider
  */
@@ -26,10 +24,10 @@ internal class Container(
   dependencyProvider: DependencyProvider
 ) : Registrar() {
   /**
-   * Map storing query handlers where the key is the query class and the value is the query provider.
-   * Each query type should have exactly one handler.
+   * Map storing request handlers where the key is the request class and the value is the request provider.
+   * Each request type should have exactly one handler.
    */
-  val queryMap = HashMap<Class<*>, QueryProvider<QueryHandler<*, *>>>()
+  val requestHandlerMap = HashMap<Class<*>, RequestProvider<RequestHandler<Request<*>, *>>>()
 
   /**
    * Map storing notification handlers where the key is the notification class and the value is a list of providers.
@@ -42,25 +40,9 @@ internal class Container(
    */
   val pipelineSet = HashSet<PipelineProvider<*>>()
 
-  /**
-   * Map storing command handlers where the key is the command class and the value is the command provider.
-   * Each command type should have exactly one handler.
-   */
-  val commandMap = HashMap<Class<*>, CommandProvider<*>>()
-
   init {
-    // Register query handlers - one handler per query type
-    registerFor<QueryHandler<Query<*>, *>, Query<*>>(dependencyProvider) { key, value ->
-      queryMap[key] = QueryProvider(dependencyProvider, value as Class<QueryHandler<*, *>>)
-    }
-
-    // Register command handlers - one handler per command type
-    registerFor<CommandHandler<Command<*>, *>, Command<*>>(dependencyProvider) { key, value ->
-      commandMap[key] =
-        CommandProvider(
-          dependencyProvider,
-          value as Class<CommandHandler<*, *>>
-        )
+    registerFor<RequestHandler<Request<*>, *>, Request<*>>(dependencyProvider) { key, value ->
+      requestHandlerMap[key] = RequestProvider(dependencyProvider, value)
     }
 
     // Register notification handlers - multiple handlers per notification type allowed

projects/kediatr-core/src/main/kotlin/com/trendyol/kediatr/CommandHandler.kt

@@ -4,19 +4,18 @@ package com.trendyol.kediatr
  * Dependency provider interface for resolving handler instances and discovering subtypes.
  *
  * This interface abstracts the dependency injection mechanism used by the mediator
- * to resolve handlers for queries, commands, and notifications. Implementations
+ * to resolve handlers for requests and notifications. Implementations
  * should integrate with specific DI frameworks (Spring, Koin, etc.).
  *
  * @see Mediator
- * @see QueryHandler
- * @see CommandHandler
+ * @see RequestHandler
  * @see NotificationHandler
  */
 interface DependencyProvider {
   /**
    * Gets a single instance of the specified class.
    *
-   * This method is used to resolve handler instances for queries and commands,
+   * This method is used to resolve handler instances for requests,
    * which should have exactly one handler per type.
    *
    * @param T The type of instance to resolve

projects/kediatr-core/src/main/kotlin/com/trendyol/kediatr/Container.kt

@@ -15,8 +15,7 @@ import java.lang.reflect.ParameterizedType
  * Example usage:
  * ```kotlin
  * val handlers = listOf(
- *     MyQueryHandler(),
- *     MyCommandHandler(),
+ *     MyRequestHandler(),
  *     MyNotificationHandler(),
  *     LoggingPipelineBehavior()
  * )
@@ -62,7 +61,7 @@ class HandlerRegistryProvider(
    *
    * This method performs sophisticated type checking that handles:
    * - Direct class inheritance and interface implementation
-   * - Generic interface implementations (e.g., QueryHandler<MyQuery, String>)
+   * - Generic interface implementations (e.g., RequestHandler<MyRequest, String>)
    * - Inheritance chains with generic interfaces
    * - Complex type hierarchies
    *
@@ -106,16 +105,15 @@ class HandlerRegistryProvider(
      * a full dependency injection framework.
      *
      * The handlers list can contain:
-     * - QueryHandler implementations
-     * - CommandHandler implementations
+     * - RequestHandler implementations for queries and commands
      * - NotificationHandler implementations
      * - PipelineBehavior implementations
      *
      * Example:
      * ```kotlin
      * val handlers = listOf(
-     *     GetUserQueryHandler(),
-     *     CreateUserCommandHandler(),
+     *     GetUserRequestHandler(),
+     *     CreateUserRequestHandler(),
      *     UserCreatedNotificationHandler(),
      *     LoggingPipelineBehavior()
      * )
@@ -128,10 +126,9 @@ class HandlerRegistryProvider(
      * ```
      *
      * @param handlers The handlers to be used by the mediator. Can include any combination of
-     *                 QueryHandler, CommandHandler, NotificationHandler, and PipelineBehavior instances
+     *                 RequestHandler, NotificationHandler, and PipelineBehavior instances
      * @return A configured mediator instance ready for use
-     * @see QueryHandler
-     * @see CommandHandler
+     * @see RequestHandler
      * @see NotificationHandler
      * @see PipelineBehavior
      */

projects/kediatr-core/src/main/kotlin/com/trendyol/kediatr/DependencyProvider.kt

@@ -1,63 +1,47 @@
 package com.trendyol.kediatr
 
 /**
- * Mediator interface for sending queries, commands, and notifications.
+ * Mediator interface for sending requests and publishing notifications.
  *
  * The Mediator pattern encapsulates how objects interact with each other, promoting loose coupling
  * by preventing objects from referring to each other explicitly. This implementation provides
  * a centralized way to handle:
- * - Queries: Request-response operations that return data
- * - Commands: Operations that modify state and may return results
+ * - Requests: Unified interface for both queries and commands that return responses
  * - Notifications: Fire-and-forget messages that can have multiple handlers
  *
- * @see Query
- * @see Command
+ * @see Request
  * @see Notification
  * @see PublishStrategy
  */
 interface Mediator {
   /**
-   * Sends a query and returns the response.
+   * Sends a request and returns the response.
    *
-   * Queries are typically used for read operations that return data without side effects.
-   * Each query type should have exactly one handler that processes it.
+   * Requests represent both queries and commands in a unified way. Each request type
+   * should have exactly one handler that processes it. Requests are typically used for:
+   * - Queries: Read operations that return data without side effects
+   * - Commands: Operations that modify state and may return results
    *
-   * @param TQuery The type of query that extends Query<TResponse>
-   * @param TResponse The type of response that the query handler will return
-   * @param query The query instance to send
-   * @return The response of the query as returned by its handler
-   * @throws IllegalStateException if no handler is found for the query type
-   * @throws Exception any exception thrown by the query handler
+   * @param TResponse The type of response that the request handler will return
+   * @param TRequest The type of request that extends Request<TResponse>
+   * @return The response of the request as returned by its handler
+   * @throws HandlerNotFoundException if no handler is found for the request type
+   * @throws Exception any exception thrown by the request handler
    */
-  suspend fun <TQuery : Query<TResponse>, TResponse> send(query: TQuery): TResponse
-
-  /**
-   * Sends a command and returns the result.
-   *
-   * Commands are typically used for write operations that modify state.
-   * Each command type should have exactly one handler that processes it.
-   *
-   * @param TCommand The type of command that extends Command<TResult>
-   * @param TResult The type of result that the command handler will return
-   * @param command The command instance to send
-   * @return The result of the command as returned by its handler
-   * @throws IllegalStateException if no handler is found for the command type
-   * @throws Exception any exception thrown by the command handler
-   */
-  suspend fun <TCommand : Command<TResult>, TResult> send(command: TCommand): TResult
+  suspend fun <TRequest : Request<TResponse>, TResponse> send(request: TRequest): TResponse
 
   /**
    * Publishes a notification using the specified publish strategy.
    *
    * Notifications are fire-and-forget messages that can have zero, one, or multiple handlers.
-   * The publish strategy determines how multiple handlers are executed (sequentially, in parallel, etc.)
+   * The publishing strategy determines how multiple handlers are executed (sequentially, in parallel, etc.)
    * and how exceptions are handled.
    *
    * @param T The type of notification that extends Notification
    * @param notification The notification instance to publish
    * @param publishStrategy The strategy to use for publishing the notification.
    *                       Defaults to [PublishStrategy.DEFAULT] which stops on first exception.
-   * @throws Exception depending on the publish strategy:
+   * @throws Exception depending on the publishing strategy:
    *                   - DEFAULT/StopOnException: throws the first exception encountered
    *                   - ContinueOnException: throws AggregateException if any handlers failed
    *                   - Parallel strategies: may throw exceptions from handlers
@@ -73,18 +57,17 @@ interface Mediator {
     /**
      * Creates a new Mediator instance with the provided dependency provider.
      *
-     * The dependency provider is used to resolve handlers for queries, commands, and notifications.
+     * The dependency provider is used to resolve handlers for requests and notifications.
      * It should be configured to provide instances of:
-     * - QueryHandler implementations for each query type
-     * - CommandHandler implementations for each command type
+     * - RequestHandler implementations for each request type (queries and commands)
      * - NotificationHandler implementations for each notification type
+     * - PipelineBehavior implementations for cross-cutting concerns
      *
      * @param dependencyProvider The dependency provider that will resolve handler instances
      * @return A configured Mediator instance ready for use
      *
      * @see DependencyProvider
-     * @see QueryHandler
-     * @see CommandHandler
+     * @see RequestHandler
      * @see NotificationHandler
      */
     fun build(dependencyProvider: DependencyProvider): Mediator = MediatorImpl(RegistryImpl(dependencyProvider))