Allow enums to be used as event names, add proper template types (#34)

* Allow enums to be used as event names, add proper template types

* Fix code linting

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## v4.1.0
+
+#### Added 
+
+- Added the `Labrador\AsyncEvent\EventName` interface to allow for enums and other 
+objects to be used as event names when appropriate
+
+#### Changed
+
+- Updated the `Labrador\AsyncEvent\Emitter::register()` and `Emitter::listeners` 
+methods to accept a `non-empty-string|EventName`.
+- Added proper template types to the `Emitter::emit` and `Emitter::queue` methods
+
 ## v4.0.0
 
 #### Added

src/AmpEmitter.php

@@ -9,7 +9,6 @@
 use Labrador\AsyncEvent\Internal\ListenerInvocationContext;
 use Labrador\AsyncEvent\Internal\NotInvoked;
 use Labrador\CompositeFuture\CompositeFuture;
-use Random\RandomException;
 use Revolt\EventLoop;
 use Throwable;
 
@@ -23,11 +22,7 @@ final class AmpEmitter implements Emitter {
      */
     private array $listenerInvocationContexts = [];
 
-    /**
-     * @param non-empty-string $eventName
-     * @throws RandomException
-     */
-    public function register(string $eventName, Listener $listener) : ListenerRegistration {
+    public function register(string|EventName $eventName, Listener $listener) : ListenerRegistration {
         $listenerKey = random_bytes(16);
         $context = new ListenerInvocationContext(
             $listener,
@@ -94,10 +89,7 @@ public function finished(callable $callable) : void {
         };
     }
 
-    /**
-     * @inheritDoc
-     */
-    public function listeners(string $event) : array {
+    public function listeners(string|EventName $event) : array {
         return array_values(
             array_map(
                 static fn(ListenerInvocationContext $context) => $context->listener,

src/Emitter.php

@@ -3,6 +3,7 @@
 namespace Labrador\AsyncEvent;
 
 use Labrador\CompositeFuture\CompositeFuture;
+use Stringable;
 
 /**
  * Represents an object that allows listeners to respond to emitted events asynchronously.
@@ -15,11 +16,12 @@ interface Emitter {
      * Register a Listener to respond to emitted events; the ListenerRegistration returned can be used to remove the
      * Listener.
      *
-     * @param non-empty-string $eventName
-     * @param Listener $listener
+     * @template Payload of object
+     * @param non-empty-string|EventName $eventName
+     * @param Listener<Event<Payload>> $listener
      * @return ListenerRegistration
      */
-    public function register(string $eventName, Listener $listener) : ListenerRegistration;
+    public function register(string|EventName $eventName, Listener $listener) : ListenerRegistration;
 
     /**
      * Immediately invokes all registered listeners that can handle the given $event.
@@ -32,8 +34,8 @@ public function register(string $eventName, Listener $listener) : ListenerRegist
      * It is important that the CompositeFuture returned has a method invoked that awaits completion! If you don't
      * explicitly call a method on the CompositeFuture the behavior for how Listeners will behave is undefined.
      *
-     * @param Event $event
-     * @return CompositeFuture
+     * @template Payload of object
+     * @param Event<Payload> $event
      */
     public function emit(Event $event) : CompositeFuture;
 
@@ -43,14 +45,17 @@ public function emit(Event $event) : CompositeFuture;
      *
      * On the next tick of the loop, the $event will be passed to Emitter::emit. The CompositeFuture that results
      * will be handled by calling awaitAll. The Future returned from this method will
+     *
+     * @template Payload of object
+     * @param Event<Payload> $event
      */
     public function queue(Event $event) : FinishedNotifier;
 
     /**
      * Returns a list of Listener implementations that can handle the provided event name.
      *
-     * @param string $event
+     * @param non-empty-string|EventName $event
      * @return list<Listener>
      */
-    public function listeners(string $event) : array;
+    public function listeners(string|EventName $event) : array;
 }

src/EventName.php

@@ -0,0 +1,11 @@
+<?php declare(strict_types=1);
+
+namespace Labrador\AsyncEvent;
+
+interface EventName {
+
+    /**
+     * @return non-empty-string
+     */
+    public function name() : string;
+}

src/Internal/ListenerInvocationContext.php

@@ -4,6 +4,7 @@
 
 use Amp\Future;
 use Labrador\AsyncEvent\Event;
+use Labrador\AsyncEvent\EventName;
 use Labrador\AsyncEvent\ListenerRemovableBasedOnHandleCount;
 use Labrador\AsyncEvent\Listener;
 use Labrador\AsyncEvent\ListenerRegistration;
@@ -17,13 +18,21 @@ final class ListenerInvocationContext {
     private int $handledCount = 0;
 
     /**
-     * @param non-empty-string $registeredEvent
+     * @var non-empty-string
+     */
+    private readonly string $registeredEvent;
+
+    /**
+     * @template Payload of object
+     * @param Listener<Payload> $listener
+     * @param non-empty-string|EventName $registeredEvent
      */
     public function __construct(
         public readonly Listener             $listener,
         private readonly ListenerRegistration $registration,
-        private readonly string               $registeredEvent
+        string|EventName $registeredEvent
     ) {
+        $this->registeredEvent = $registeredEvent instanceof EventName ? $registeredEvent->name() : $registeredEvent;
     }
 
     public function handle(Event $event) : CompositeFuture|NotInvoked {
@@ -48,8 +57,12 @@ public function handle(Event $event) : CompositeFuture|NotInvoked {
         return $value;
     }
 
-    public function isRegisteredEventName(string $eventName) : bool {
-        return $eventName === $this->registeredEvent;
+    /**
+     * @param non-empty-string|EventName $eventName
+     * @return bool
+     */
+    public function isRegisteredEventName(string|EventName $eventName) : bool {
+        return ($eventName instanceof EventName ? $eventName->name() : $eventName) === $this->registeredEvent;
     }
 
     private function isHandleLimitReached() : bool {

test/Unit/AmpEventEmitterTest.php

@@ -10,6 +10,7 @@
 use Labrador\AsyncEvent\Event;
 use Labrador\AsyncEvent\ListenerRemovableBasedOnHandleCount;
 use Labrador\AsyncEvent\Listener;
+use Labrador\AsyncEvent\Test\Unit\Helper\MyEnum;
 use Labrador\CompositeFuture\CompositeFuture;
 use Mockery;
 use Mockery\Adapter\Phpunit\MockeryPHPUnitIntegration;
@@ -218,4 +219,24 @@ public function testQueueingFailure() : void {
         self::assertSame([], $data->values);
         self::assertSame([$exception], $data->exception->getReasons());
     }
+
+    public function testRegisterEventWithStringBackedEnumAddsToListeners() : void {
+        $subject = new AmpEmitter();
+
+        $a = Mockery::mock(Listener::class);
+
+        $subject->register(MyEnum::Foo, $a);
+
+        self::assertSame([$a], $subject->listeners('foo'));
+    }
+
+    public function testRetrieveListenersWithSameEnumUsedToRegister() : void {
+        $subject = new AmpEmitter();
+
+        $a = Mockery::mock(Listener::class);
+
+        $subject->register(MyEnum::Foo, $a);
+
+        self::assertSame([$a], $subject->listeners(MyEnum::Foo));
+    }
 }

test/Unit/Helper/MyEnum.php

@@ -0,0 +1,13 @@
+<?php declare(strict_types=1);
+
+namespace Labrador\AsyncEvent\Test\Unit\Helper;
+
+use Labrador\AsyncEvent\EventName;
+
+enum MyEnum : string implements EventName {
+    case Foo = 'foo';
+
+    public function name() : string {
+        return $this->value;
+    }
+}