Considerable Refactoring and EventListener implementations

- Unifying the Naming Conventions whereby `EventReceiver` will always be referred to as an Event Receiver.
- Introduced a new `EventListener` concept, which has been implemented and is pending suitable Unit Testing
- Reconsidering the `UIEventReceiver` entirely in favour of registering simple `EventListeners` instead.

Author: LK-Simon

Sources/EventDrivenSwift/Central/EventCentral.swift

@@ -21,7 +21,7 @@ final public class EventCentral: EventDispatcher, EventCentralable {
      - Author: Simon J. Stuart
      - Version: 1.0.0
      */
-    private static var _shared: EventDispatchable = EventCentral()
+    private static var _shared: EventCentral = EventCentral()
 
     /**
      Returns the Central Event Dispatcher
@@ -40,19 +40,16 @@ final public class EventCentral: EventDispatcher, EventCentralable {
         }
     }
 
-    /// This just makes it so that your code cannot initialise instances of `EventCentral`. It's a Singleton!
-    override private init() {}
-    
-    @inline(__always) public static func addListener(_ listener: EventReceivable, forEventType: Eventable.Type) {
-        _shared.addListener(listener, forEventType: forEventType)
+    @inline(__always) public static func addReceiver(_ receiver: EventReceivable, forEventType: Eventable.Type) {
+        _shared.addReceiver(receiver, forEventType: forEventType)
     }
 
-    @inline(__always) public static func removeListener(_ listener: EventReceivable, forEventType: Eventable.Type) {
-        _shared.removeListener(listener, forEventType: forEventType)
+    @inline(__always) public static func removeReceiver(_ receiver: EventReceivable, forEventType: Eventable.Type) {
+        _shared.removeReceiver(receiver, forEventType: forEventType)
     }
 
-    @inline(__always) public static func removeListener(_ listener: EventReceivable) {
-        _shared.removeListener(listener)
+    @inline(__always) public static func removeReceiver(_ receiver: EventReceivable) {
+        _shared.removeReceiver(receiver)
     }
 
     @inline(__always) public static func queueEvent(_ event: Eventable, priority: EventPriority) {
@@ -68,4 +65,21 @@ final public class EventCentral: EventDispatcher, EventCentralable {
             return _shared.eventCount
         }
     }
+    
+    internal var eventListener = EventListener()
+    
+    @inline(__always) public static func addListener<TEvent>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type) -> UUID where TEvent : Eventable {
+        return _shared.eventListener.addListener(requester, callback, forEventType: forEventType)
+    }
+    
+    @inline(__always) public static func removeListener(_ token: UUID) {
+        _shared.eventListener.removeListener(token)
+    }
+    
+    @inline(__always) public static func removeListener(_ token: UUID, typeOf: Eventable.Type) {
+        _shared.eventListener.removeListener(token, typeOf: typeOf)
+    }
+    
+    /// This just makes it so that your code cannot initialise instances of `EventCentral`. It's a Singleton!
+    override private init() {}
 }

Sources/EventDrivenSwift/Central/EventCentralable.swift

@@ -10,25 +10,25 @@ import Foundation
 
 public protocol EventCentralable {
     /**
-     Registers the given `listener` for the given `Eventable` Type with the Central Event Dispatcher
+     Registers the given `receiver` for the given `Eventable` Type with the Central Event Dispatcher
      - Author: Simon J. Stuart
      - Version: 1.0.0
      */
-    static func addListener(_ listener: any EventReceivable, forEventType: Eventable.Type)
+    static func addReceiver(_ receiver: any EventReceivable, forEventType: Eventable.Type)
 
     /**
-     Unregisters the given `listener` from the given `Eventable` Type for the Central Event Dispatcher
+     Unregisters the given `receiver` from the given `Eventable` Type for the Central Event Dispatcher
      - Author: Simon J. Stuart
      - Version: 1.0.0
      */
-    static func removeListener(_ listener: any EventReceivable, forEventType: Eventable.Type)
+    static func removeReceiver(_ receiver: any EventReceivable, forEventType: Eventable.Type)
 
     /**
-     Unregisters the given `listener` from all `Eventable` Types from the Central Event Dispatcher
+     Unregisters the given `receiver` from all `Eventable` Types from the Central Event Dispatcher
      - Author: Simon J. Stuart
      - Version: 1.0.0
      */
-    static func removeListener(_ listener: any EventReceivable)
+    static func removeReceiver(_ receiver: any EventReceivable)
 
     /**
      Adds the given `event` to the Central Event Queue with the given `priority`
@@ -57,4 +57,36 @@ public protocol EventCentralable {
      - Returns: The number of Events currently pending in the Queue and Stack combined
      */
     static var eventCount: Int { get }
+    
+    /**
+     Registers an Event Listner Callback for the given `Eventable` Type with the Central Event Listener
+     - Author: Simon J. Stuart
+     - Version: 3.0.0
+     - Parameters:
+        - requester: The Object owning the Callback Method
+        - callback: The code to invoke for the given `Eventable` Type
+        - forEventType: The `Eventable` Type for which to Register  the Callback
+     - Returns: A `UUID` value representing the `token` associated with this Event Callback
+     */
+    static func addListener<TEvent: Eventable>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type) -> UUID
+    
+    /**
+     Locates and removes the given Listener `token` (if it exists) from the Central Event Listener
+     - Author: Simon J. Stuart
+     - Version: 3.0.0
+     - Parameters:
+        - token: The Token of the Listener you wish to remove
+     - Note: Using this method is far slower than if you provide the `typeOf` Parameter to satisfy the more-specific overloaded version of this method
+     */
+    static func removeListener(_ token: UUID)
+    
+    /**
+     Locates and removes the given Listener `token` (if it exists) from the Central Event Listener
+     - Author: Simon J. Stuart
+     - Version: 3.0.0
+     - Parameters:
+        - token: The Token of the Listener you wish to remove
+        - typeOf: The Event Type for which the Listener identified by the given `token` is interested
+     */
+    static func removeListener(_ token: UUID, typeOf: Eventable.Type)
 }

Sources/EventDrivenSwift/EventDispatcher/EventDispatchable.swift

@@ -15,23 +15,23 @@ import Foundation
  */
 public protocol EventDispatchable: EventHandlable {
     /**
-     Registers the given `listener` for the given `Eventable` Type
+     Registers the given `receiver` for the given `Eventable` Type
      - Author: Simon J. Stuart
      - Version: 1.0.0
      */
-    func addListener(_ listener: any EventReceivable, forEventType: Eventable.Type)
+    func addReceiver(_ receiver: any EventReceivable, forEventType: Eventable.Type)
 
     /**
-     Unregisters the given `listener` from the given `Eventable` Type
+     Unregisters the given `receiver` from the given `Eventable` Type
      - Author: Simon J. Stuart
      - Version: 1.0.0
      */
-    func removeListener(_ listener: any EventReceivable, forEventType: Eventable.Type)
+    func removeReceiver(_ receiver: any EventReceivable, forEventType: Eventable.Type)
 
     /**
-     Unregisters the given `listener` from all `Eventable` Types
+     Unregisters the given `receiver` from all `Eventable` Types
      - Author: Simon J. Stuart
      - Version: 1.0.0
      */
-    func removeListener(_ listener: any EventReceivable)
+    func removeReceiver(_ receiver: any EventReceivable)
 }

Sources/EventDrivenSwift/EventDispatcher/EventDispatcher.swift

@@ -11,102 +11,102 @@ import ThreadSafeSwift
 import Observable
 
 /**
- An implementation of `EventHandler` designed to Queue/Stack outbound events, and Dispatch them to all registered `listeners`
+ An implementation of `EventHandler` designed to Queue/Stack outbound events, and Dispatch them to all registered `receivers`
  - Author: Simon J. Stuart
  - Version: 1.0.0
  - Note: While you can inherit from and even create instances of `EventDispatcher`, best practice would be to use `EventCentral.shared` as the central Event Dispatcher.
  */
 open class EventDispatcher: EventHandler, EventDispatchable {
-    struct ListenerContainer {
-        weak var listener: (any EventReceivable)?
+    struct ReceiverContainer {
+        weak var receiver: (any EventReceivable)?
     }
 
     /**
-    Stores all of the Listeners against the fully-qualified name of the corresponding `Eventable` Type
+    Stores all of the Receivers against the fully-qualified name of the corresponding `Eventable` Type
      - Author: Simon J. Stuart
      - Version: 1.0.0
      */
-    @ThreadSafeSemaphore private var listeners = [String:[ListenerContainer]]()
+    @ThreadSafeSemaphore private var receivers = [String:[ReceiverContainer]]()
 
-    public func addListener(_ listener: any EventReceivable, forEventType: Eventable.Type) {
+    public func addReceiver(_ receiver: any EventReceivable, forEventType: Eventable.Type) {
         let eventTypeName = String(reflecting: forEventType)
 
-        _listeners.withLock { listeners in
-            var bucket = listeners[eventTypeName]
+        _receivers.withLock { receivers in
+            var bucket = receivers[eventTypeName]
             let newBucket = bucket == nil
-            if newBucket { bucket = [ListenerContainer]() } /// If there's no Bucket for this Event Type, create one
+            if newBucket { bucket = [ReceiverContainer]() } /// If there's no Bucket for this Event Type, create one
 
-            /// If it's NOT a New Bucket, and the Bucket already contains this Listener...
-            if !newBucket && bucket!.contains(where: { listenerContainer in
-                listenerContainer.listener != nil && ObjectIdentifier(listenerContainer.listener!) == ObjectIdentifier(listener)
+            /// If it's NOT a New Bucket, and the Bucket already contains this Receiver...
+            if !newBucket && bucket!.contains(where: { receiverContainer in
+                receiverContainer.receiver != nil && ObjectIdentifier(receiverContainer.receiver!) == ObjectIdentifier(receiver)
             }) {
                 return // ... just Return!
             }
 
-            /// If we reach here, the Listener is not already in the Bucket, so let's add it!
-            bucket!.append(ListenerContainer(listener: listener))
-            listeners[eventTypeName] = bucket!
+            /// If we reach here, the Receiver is not already in the Bucket, so let's add it!
+            bucket!.append(ReceiverContainer(receiver: receiver))
+            receivers[eventTypeName] = bucket!
         }
     }
 
-    public func removeListener(_ listener: any EventReceivable, forEventType: Eventable.Type) {
+    public func removeReceiver(_ receiver: any EventReceivable, forEventType: Eventable.Type) {
         let eventTypeName = String(reflecting: forEventType)
 
-        _listeners.withLock { listeners in
-            var bucket = listeners[eventTypeName]
-            if bucket == nil { return } /// Can't remove a Listener if there isn't even a Bucket for hte Event Type
+        _receivers.withLock { receivers in
+            var bucket = receivers[eventTypeName]
+            if bucket == nil { return } /// Can't remove a Receiver if there isn't even a Bucket for hte Event Type
 
-            /// Remove any Listeners from this Event-Type Bucket for the given `listener` instance.
-            bucket!.removeAll { listenerContainer in
-                listenerContainer.listener != nil && ObjectIdentifier(listenerContainer.listener!) == ObjectIdentifier(listener)
+            /// Remove any Receivers from this Event-Type Bucket for the given `receiver` instance.
+            bucket!.removeAll { receiverContainer in
+                receiverContainer.receiver != nil && ObjectIdentifier(receiverContainer.receiver!) == ObjectIdentifier(receiver)
             }
         }
     }
 
-    public func removeListener(_ listener: any EventReceivable) {
-        _listeners.withLock { listeners in
-            for (eventTypeName, bucket) in listeners { /// Iterate every Event Type
+    public func removeReceiver(_ receiver: any EventReceivable) {
+        _receivers.withLock { receivers in
+            for (eventTypeName, bucket) in receivers { /// Iterate every Event Type
                 var newBucket = bucket // Copy the Bucket
-                newBucket.removeAll { listenerContainer in /// Remove any occurences of the given Listener from the Bucket
-                    listenerContainer.listener != nil && ObjectIdentifier(listenerContainer.listener!) == ObjectIdentifier(listener)
+                newBucket.removeAll { receiverContainer in /// Remove any occurences of the given Receiver from the Bucket
+                    receiverContainer.receiver != nil && ObjectIdentifier(receiverContainer.receiver!) == ObjectIdentifier(receiver)
                 }
-                listeners[eventTypeName] = newBucket /// Update the Bucket for this Event Type
+                receivers[eventTypeName] = newBucket /// Update the Bucket for this Event Type
             }
         }
     }
 
     /**
-     Dispatch the Event to all Subscribed Listeners
+     Dispatch the Event to all Subscribed Receivers
      - Author: Simon J. Stuart
      - Version: 1.0.0
      */
     override internal func processEvent(_ event: any Eventable, dispatchMethod: EventDispatchMethod, priority: EventPriority) {
         let eventTypeName = String(reflecting: type(of: event))
 
-        var snapListeners = [String:[ListenerContainer]]()
+        var snapReceivers = [String:[ReceiverContainer]]()
 
-        _listeners.withLock { listeners in
-            // We should take this opportunity to remove any nil listeners
-            listeners[eventTypeName]?.removeAll(where: { listenerContainer in
-                listenerContainer.listener == nil
+        _receivers.withLock { receivers in
+            // We should take this opportunity to remove any nil receivers
+            receivers[eventTypeName]?.removeAll(where: { receiverContainer in
+                receiverContainer.receiver == nil
             })
-            snapListeners = listeners
+            snapReceivers = receivers
         }
 
-        let bucket = snapListeners[eventTypeName]
-        if bucket == nil { return } /// No Listeners, so nothing more to do!
+        let bucket = snapReceivers[eventTypeName]
+        if bucket == nil { return } /// No Receivers, so nothing more to do!
 
-        for listener in bucket! {
-            if listener.listener == nil { /// If the Listener is `nil`...
+        for receiver in bucket! {
+            if receiver.receiver == nil { /// If the Recevier is `nil`...
                 continue
             }
 
-            // so, we have a listener... let's deal with it!
+            // so, we have a receiver... let's deal with it!
             switch dispatchMethod {
             case .stack:
-                listener.listener!.stackEvent(event, priority: priority)
+                receiver.receiver!.stackEvent(event, priority: priority)
             case .queue:
-                listener.listener!.queueEvent(event, priority: priority)
+                receiver.receiver!.queueEvent(event, priority: priority)
             }
         }
     }

Sources/EventDrivenSwift/EventListener/EventListenable.swift

@@ -0,0 +1,62 @@
+//
+// EventListenable.swift
+// Copyright (c) 2022, Flowduino
+// Authored by Simon J. Stuart on 11th August 2022
+//
+// Subject to terms, restrictions, and liability waiver of the MIT License
+//
+
+import Foundation
+
+/**
+ Convienience `typealias` used for Event Callbacks
+ - Author: Simon J. Stuart
+ - Version: 3.0.0
+ */
+typealias EventCallback = (_ event: any Eventable, _ priority: EventPriority) -> ()
+
+/**
+ Convienience `typealias` used for Typed Event Callbacks
+ - Author: Simon J. Stuart
+ - Version: 3.0.0
+ */
+public typealias TypedEventCallback<TEvent: Any> = (_ event: TEvent, _ priority: EventPriority) -> ()
+
+/**
+ Provides a simple means of Receiving Events and invoking appropriate Callbacks
+ - Author: Simon J. Stuart
+ - Version: 3.0.0
+ */
+public protocol EventListenable: AnyObject, EventReceivable {
+    /**
+     Registers an Event Callback for the given `Eventable` Type
+     - Author: Simon J. Stuart
+     - Version: 3.0.0
+     - Parameters:
+        - requester: The Object owning the Callback Method
+        - callback: The code to invoke for the given `Eventable` Type
+        - forEventType: The `Eventable` Type for which to Register  the Callback
+     - Returns: A `UUID` value representing the `token` associated with this Event Callback
+     */
+    func addListener<TEvent: Eventable>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type) -> UUID
+    
+    /**
+     Locates and removes the given Listener `token` (if it exists)
+     - Author: Simon J. Stuart
+     - Version: 3.0.0
+     - Parameters:
+        - token: The Token of the Listener you wish to remove
+     - Note: Using this method is far slower than if you provide the `typeOf` Parameter to satisfy the more-specific overloaded version of this method
+     */
+    func removeListener(_ token: UUID)
+    
+    /**
+     Locates and removes the given Listener `token` (if it exists)
+     - Author: Simon J. Stuart
+     - Version: 3.0.0
+     - Parameters:
+        - token: The Token of the Listener you wish to remove
+        - typeOf: The Event Type for which the Listener identified by the given `token` is interested
+     */
+    func removeListener(_ token: UUID, typeOf: Eventable.Type)
+}