feat: ✨ Add bus listeners

Author: remimd

cq/__init__.py

@@ -12,9 +12,9 @@
     QueryBus,
     command_handler,
     event_handler,
-    find_command_bus,
-    find_event_bus,
-    find_query_bus,
+    get_command_bus,
+    get_event_bus,
+    get_query_bus,
     query_handler,
 )
 from ._core.middleware import Middleware, MiddlewareResult
@@ -35,8 +35,8 @@
     "QueryBus",
     "command_handler",
     "event_handler",
-    "find_command_bus",
-    "find_event_bus",
-    "find_query_bus",
+    "get_command_bus",
+    "get_event_bus",
+    "get_query_bus",
     "query_handler",
 )

cq/_core/dispatcher/bus.py

@@ -1,11 +1,11 @@
 import asyncio
-from abc import abstractmethod
+from abc import ABC, abstractmethod
 from collections import defaultdict
-from collections.abc import Callable
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 from inspect import isclass
 from types import GenericAlias
-from typing import Protocol, Self, TypeAliasType, runtime_checkable
+from typing import Any, Protocol, Self, TypeAliasType, runtime_checkable
 
 import injection
 
@@ -14,6 +14,8 @@
 type HandlerType[**P, T] = type[Handler[P, T]]
 type HandlerFactory[**P, T] = Callable[..., Handler[P, T]]
 
+type Listener[T] = Callable[[T], Awaitable[Any]]
+
 type BusType[I, O] = type[Bus[I, O]]
 
 
@@ -34,6 +36,10 @@ class Bus[I, O](Dispatcher[I, O], Protocol):
     def subscribe(self, input_type: type[I], factory: HandlerFactory[[I], O]) -> Self:
         raise NotImplementedError
 
+    @abstractmethod
+    def add_listeners(self, *listeners: Listener[I]) -> Self:
+        raise NotImplementedError
+
 
 @dataclass(eq=False, frozen=True, slots=True)
 class SubscriberDecorator[I, O]:
@@ -59,7 +65,24 @@ def __find_bus(self) -> Bus[I, O]:
         return self.injection_module.find_instance(self.bus_type)
 
 
-class SimpleBus[I, O](BaseDispatcher[I, O], Bus[I, O]):
+class BaseBus[I, O](BaseDispatcher[I, O], Bus[I, O], ABC):
+    __slots__ = ("__listeners",)
+
+    __listeners: list[Listener[I]]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.__listeners = []
+
+    def add_listeners(self, *listeners: Listener[I]) -> Self:
+        self.__listeners.extend(listeners)
+        return self
+
+    async def _trigger_listeners(self, input_value: I, /) -> None:
+        await asyncio.gather(*(listener(input_value) for listener in self.__listeners))
+
+
+class SimpleBus[I, O](BaseBus[I, O]):
     __slots__ = ("__handlers",)
 
     __handlers: dict[type[I], HandlerFactory[[I], O]]
@@ -69,6 +92,7 @@ def __init__(self) -> None:
         self.__handlers = {}
 
     async def dispatch(self, input_value: I, /) -> O:
+        await self._trigger_listeners(input_value)
         input_type = type(input_value)
 
         try:
@@ -91,7 +115,7 @@ def subscribe(self, input_type: type[I], factory: HandlerFactory[[I], O]) -> Sel
         return self
 
 
-class TaskBus[I](BaseDispatcher[I, None], Bus[I, None]):
+class TaskBus[I](BaseBus[I, None]):
     __slots__ = ("__handlers",)
 
     __handlers: dict[type[I], list[HandlerFactory[[I], None]]]
@@ -101,6 +125,7 @@ def __init__(self) -> None:
         self.__handlers = defaultdict(list)
 
     async def dispatch(self, input_value: I, /) -> None:
+        await self._trigger_listeners(input_value)
         handler_factories = self.__handlers.get(type(input_value))
 
         if not handler_factories:

cq/_core/message.py

@@ -39,13 +39,16 @@ class Query(Message, ABC):
 injection.set_constant(SimpleBus(), QueryBus, alias=True)
 
 
-def find_command_bus[T]() -> CommandBus[T]:
-    return injection.find_instance(CommandBus)
+@injection.inject
+def get_command_bus[T](bus: CommandBus[T] = NotImplemented, /) -> CommandBus[T]:
+    return bus
 
 
-def find_event_bus() -> EventBus:
-    return injection.find_instance(EventBus)
+@injection.inject
+def get_event_bus(bus: EventBus = NotImplemented, /) -> EventBus:
+    return bus
 
 
-def find_query_bus[T]() -> QueryBus[T]:
-    return injection.find_instance(QueryBus)
+@injection.inject
+def get_query_bus[T](bus: QueryBus[T] = NotImplemented, /) -> QueryBus[T]:
+    return bus

documentation/fastapi-example.md

@@ -4,7 +4,7 @@
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 
-from cq import Command, CommandBus, command_handler, find_command_bus
+from cq import Command, CommandBus, command_handler, get_command_bus
 from fastapi import FastAPI, status
 from injection import injectable
 from injection.integrations.fastapi import Inject
@@ -31,7 +31,7 @@ class ExampleHandler:
 
 @asynccontextmanager
 async def lifespan(_: FastAPI) -> AsyncIterator[None]:
-    find_command_bus().add_middlewares(...)  # Add middlewares here
+    get_command_bus().add_middlewares(...)  # Add middlewares here
     yield
 
 app = FastAPI(lifespan=lifespan)

poetry.lock

@@ -44,6 +44,20 @@ async def test_dispatch_with_unknown_input_type_return_not_implemented(
     ) -> None:
         assert await bus.dispatch("hello") is NotImplemented
 
+    async def test_dispatch_with_listeners_return_none(
+        self,
+        bus: SimpleBus[object, Any],
+    ) -> None:
+        called = False
+
+        async def listener(_: Any) -> None:
+            nonlocal called
+            called = True
+
+        bus.add_listeners(listener)
+        assert await bus.dispatch("hello") is NotImplemented
+        assert called
+
     async def test_dispatch_no_wait_with_success_return_none(
         self,
         bus: SimpleBus[Any, Any],