Decorator for explicitly-typed Event callbacks

- Implemented a decorator method called `callTypedEventCallback` to type-test and cast an `Eventable` to an explicit Event Type
- Updated README.MD to reflect the above change.

Author: LK-Simon

README.md

@@ -193,35 +193,31 @@ So, we have an *Event* type, and we are able to *Dispatch* it through a *Queue*
 class TemperatureProcessor: EventReceiver {
     /// Register our Event Listeners for this EventReceiver
     override func registerEventListeners() {
-        addEventCallback(onTemperatureEvent, forEventType: TemperatureEvent.self)
+        addEventCallback({ event, priority in
+            self.callTypedEventCallback(self.onTemperatureEvent, forEvent: event, priority: priority)
+        }, forEventType: TemperatureEvent.self)
     }
 
     /// Define our Callback Function to process received TemperatureEvent Events
-    func onTemperatureEvent(_ event: TestEventTypeOne, _ priority: EventPriority) {
-        /// At the moment, it is necessary to type check and cast the Event ourselves...
-        if let typedEvent = event as? TemperatureEvent { // If the Event conforms to TemperatureEvent...
-            processTemperatureEvent(typedEvent) // ... invoke our concrete method to process the Event data.
-        }
-    }
-    
-    /// Method to process our TemperatureEvent
-    func processTemperatureEvent(_ event: TemperatureEvent) {
-        
+    func onTemperatureEvent(_ event: TemperatureEvent, _ priority: EventPriority) {
+
     }
 }
 ```
-Before we dig into the implementation of `processTemperatureEvent`, which can basically do whatever we would want to do with the data provided in the `TemperatureEvent`, let's take a moment to understand what is happening in the above code.
+Before we dig into the implementation of `onTemperatureEvent`, which can basically do whatever we would want to do with the data provided in the `TemperatureEvent`, let's take a moment to understand what is happening in the above code.
 
 Firstly, `TemperatureProcessor` inherits from `EventReceiver`, which is where all of the magic happens to receive *Events* and register our *Listeners* (or *Callbacks* or *Handlers*).
 
 The function `registerEventListeners` will be called automatically when an instance of `TemperatureProcessor` is created. Within this method, we cal `addEventCallback` to register `onTemperatureEvent` so that it will be invoked every time an *Event* of type `TemperatureEvent` is *Dispatched*.
 
-Our *Callback* (or *Handler* or *Listener Event*) is called `onTemperatureEvent`, and all this does is first check that the `event` received is of the type `TemperatureEvent`, and - if it is - passes the now-typed `TemperatureEvent` along to `processTemperatureEvent`, which is where we will implement whatever *Operation* is to be performed against a `TemperatureEvent`.
+Notice that we use a *Closure* which invokes `self.callTypedEventCallback`. This is to address a fundamental limitation of Generics in the Swift language, and acts as a decorator to perform the Type Checking and Casting of the received `event` to the explicit *Event* type we expect. In this case, that is `TemperatureEvent`
+
+Our *Callback* (or *Handler* or *Listener Event*) is called `onTemperatureEvent`, which is where we will implement whatever *Operation* is to be performed against a `TemperatureEvent`.
 
 **Note**: The need to provide type checking and casting (in `onTemperatureEvent`) is intended to be a temporary requirement. We are looking at ways to decorate this internally within the library, so that we can reduce the amount of boilerplate code you have to produce in your implementations.
 For the moment, this solution works well, and enables you to begin using `EventDrivenSwift` in your applications immediately.
 
-Now, let's actually do something with our `TemperatureEvent` in the `processTemperatureEvent` method.
+Now, let's actually do something with our `TemperatureEvent` in the `onTemperatureEvent` method.
 ```swift
     /// An Enum to map a Temperature value onto a Rating
     enum TemperatureRating: String {
@@ -253,13 +249,13 @@ Now, let's actually do something with our `TemperatureEvent` in the `processTemp
     @ThreadSafeSemaphore public var temperatureInCelsius: Float = Float.zero
     @ThreadSafeSemaphore public var temperatureRating: TemperatureRating = .freezing
 
-    func processTemperatureEvent(_ event: TemperatureEvent) {
+    func onTemperatureEvent(_ event: TemperatureEvent, _ priority: EventPriority) {
         temperatureInCelsius = event.temperatureInCelsius
         temperatureRating = TemperatureRating.fromTemperature(event.temperatureInCelsius)
     }
 }
 ```
-The above code is intended to be illustrative, rather than *useful*. Our `processTemperatureEvent` passes *Event*'s encapsulated `temperatureInCelsius` to a public variable (which could then be read by other code as necessary) as part of our `EventReceiver`, and also pre-calculates a `TemperatureRating` based on the Temperature value received in the *Event*.
+The above code is intended to be illustrative, rather than *useful*. Our `onTemperatureEvent` passes *Event*'s encapsulated `temperatureInCelsius` to a public variable (which could then be read by other code as necessary) as part of our `EventReceiver`, and also pre-calculates a `TemperatureRating` based on the Temperature value received in the *Event*.
 
 Ultimately, your code can do whatever you wish with the *Event*'s *Payload* data!
 
@@ -304,9 +300,9 @@ protocol TemperatureProcessorObserver: AnyObject {
     func onTemperatureEvent(temperatureInCelsius: Float)
 }
 ```
-Now let's modify the `processTemperatureEvent` method we implemented in the previous example:
+Now let's modify the `onTemperatureEvent` method we implemented in the previous example:
 ```swift
-    func processTemperatureEvent(_ event: TemperatureEvent) {
+    func onTemperatureEvent(_ event: TemperatureEvent, _ priority: EventPriority) {
         temperatureInCelsius = event.temperatureInCelsius
         temperatureRating = TemperatureRating.fromTemperature(event.temperatureInCelsius)
 
@@ -332,9 +328,9 @@ enum TemperatureRatingEvent: Eventable {
     var temperatureRating: TemperatureRating
 }
 ```
-With the *Event* type defined, we can now once more expand our `processTemperatureEvent` to *Dispatch* our reciprocal `TemperatureRatingEvent`:
+With the *Event* type defined, we can now once more expand our `onTemperatureEvent` to *Dispatch* our reciprocal `TemperatureRatingEvent`:
 ```swift
-    func processTemperatureEvent(_ event: TemperatureEvent) {
+    func onTemperatureEvent(_ event: TemperatureEvent, _ priority: EventPriority) {
         temperatureInCelsius = event.temperatureInCelsius
         temperatureRating = TemperatureRating.fromTemperature(event.temperatureInCelsius)
 

Sources/EventDrivenSwift/EventReceiver/EventReceiver.swift

@@ -11,10 +11,30 @@ import ThreadSafeSwift
 import Observable
 
 public class EventReceiver: EventHandler, EventReceivable {
+    /**
+     Convienience `typealias` used for Event Callbacks
+     - Author: Simon J. Stuart
+     - Version: 1.0.0
+     */
     typealias EventCallback = (_ event: any Eventable, _ priority: EventPriority) -> ()
 
+    /**
+     Convienience `typealias` used for Typed Event Callbacks
+     - Author: Simon J. Stuart
+     - Version: 1.0.0
+     */
+    typealias TypedEventCallback<TEvent: Any> = (_ event: TEvent, _ priority: EventPriority) -> ()
+    
+    /**
+     Map of `Eventable` qualified Type Names against `EventCallback` methods.
+     - Author: Simon J. Stuart
+     - Version: 1.0.0
+     - Note: We use the Qualified Type Name as the Key because Types are not Hashable in Swift
+     */
     @ThreadSafeSemaphore private var eventCallbacks = [String:EventCallback]() //TODO: Make this a Revolving Door collection!
 
+//    @ThreadSafeSemaphore private var typedEventCallbacks = [String:Any]() //TODO: Find an implementation that works for strong-typed Event Callbacks (P.S. limitations of Swift Generics are very annoying!)
+    
     /**
      Invoke the appropriate Callback for the given Event
      - Author: Simon J. Stuart
@@ -23,16 +43,24 @@ public class EventReceiver: EventHandler, EventReceivable {
     override internal func processEvent(_ event: any Eventable, dispatchMethod: EventDispatchMethod, priority: EventPriority) {
         let eventTypeName = String(reflecting: type(of: event))
         var callback: EventCallback? = nil
-        
+
         _eventCallbacks.withLock { eventCallbacks in
             callback = eventCallbacks[eventTypeName]
         }
-        
+
         if callback == nil { return } // If there is no Callback, we will just return!
-        
+
         callback!(event, priority)
     }
 
+    /**
+     Registers an Event Callback for the given `Eventable` Type
+     - Author: Simon J. Stuart
+     - Version: 1.0.0
+     - Parameters:
+        - callback: The code to invoke for the given `Eventable` Type
+        - forEventType: The `Eventable` Type for which to Register  the Callback
+     */
     internal func addEventCallback(_ callback: @escaping EventCallback, forEventType: Eventable.Type) {
         let eventTypeName = String(reflecting: forEventType)
 
@@ -44,6 +72,31 @@ public class EventReceiver: EventHandler, EventReceivable {
         EventCentral.shared.addListener(self, forEventType: forEventType)
     }
 
+    internal func callTypedEventCallback<TEvent: Eventable>(_ callback: @escaping TypedEventCallback<TEvent>, forEvent: Eventable, priority: EventPriority) {
+        if let typedEvent = forEvent as? TEvent {
+            callback(typedEvent, priority)
+        }
+    }
+    
+    //TODO: Find an implementation that works for strong-typed Event Callbacks (P.S. limitations of Swift Generics are very annoying!)
+//    internal func addEventCallback<TEvent: Eventable>(_ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type) {
+//        let eventTypeName = String(reflecting: forEventType)
+//
+//        _typedEventCallbacks.withLock { typedEventCallbacks in
+//            typedEventCallbacks[eventTypeName] = callback
+//        }
+//
+//        /// We automatically register the Listener with the Central Event Dispatcher
+//        EventCentral.shared.addListener(self, forEventType: forEventType)
+//    }
+    
+    /**
+     Removes an Event Callback for the given `Eventable` Type
+     - Author: Simon J. Stuart
+     - Version: 1.0.0
+     - Parameters:
+        - forEventType: The `Eventable` Type for which to Remove the Callback
+     */
     internal func removeEventCallback(forEventType: any Eventable) {
         let eventTypeName = String(reflecting: forEventType)
 

Tests/EventDrivenSwiftTests/BasicTests.swift

@@ -19,19 +19,15 @@ final class BasicTests: XCTestCase {
         @ThreadSafeSemaphore var foo: Int = 0
         public var awaiter = DispatchSemaphore(value: 0)
 
-        internal func eventOneCallback(_ event: any Eventable, _ priority: EventPriority) {
-            if let eventOne = event as? TestEventTypeOne {
-                eventOneCallback(eventOne, priority)
-            }
-        }
-
         internal func eventOneCallback(_ event: TestEventTypeOne, _ priority: EventPriority) {
             foo = event.foo
             awaiter.signal()
         }
 
         override func registerEventListeners() {
-            addEventCallback(eventOneCallback, forEventType: TestEventTypeOne.self)
+            addEventCallback({ event, priority in
+                self.callTypedEventCallback(self.eventOneCallback, forEvent: event, priority: priority)
+            }, forEventType: TestEventTypeOne.self)
         }
     }