Destroyable listener

Author: emyfops

common/src/main/kotlin/com/lambda/event/listener/SafeListener.kt

@@ -7,6 +7,7 @@ import com.lambda.event.Muteable
 import com.lambda.task.Task
 import com.lambda.threading.runConcurrent
 import com.lambda.threading.runSafe
+import com.lambda.util.selfReference
 
 
 /**
@@ -87,6 +88,54 @@ class SafeListener(
             return listener
         }
 
+        /**
+         * This function registers a new [SafeListener] for a generic [Event] type [T].
+         * The [function] is executed on the same thread where the [Event] was dispatched.
+         * The [function] will only be executed when the context satisfies certain safety conditions.
+         * These conditions are met when none of the following [SafeContext] properties are null:
+         * - [SafeContext.world]
+         * - [SafeContext.player]
+         * - [SafeContext.interaction]
+         * - [SafeContext.connection]
+         *
+         * This typically occurs when the user is in-game.
+         *
+         * After the [function] is executed once, the [SafeListener] will be automatically unsubscribed.
+         *
+         * Usage:
+         * ```kotlin
+         * listenerOnce<MyEvent> { event ->
+         *     player.sendMessage("Event received: $event")
+         * }
+         *
+         * listenerOnce<MyEvent>(priority = 1) { event ->
+         *     player.sendMessage("Event received before the previous listener: $event")
+         * }
+         * ```
+         *
+         * @param T The type of the event to listen for. This should be a subclass of Event.
+         * @param priority The priority of the listener. Listeners with higher priority will be executed first. The Default value is 0.
+         * @param alwaysListen If true, the listener will be executed even if it is muted. The Default value is false.
+         * @param function The function to be executed when the event is posted. This function should take a SafeContext and an event of type T as parameters.
+         * @return The newly created and registered [SafeListener].
+         */
+        inline fun <reified T : Event> Any.listenOnce(
+            priority: Int = 0,
+            alwaysListen: Boolean = false,
+            noinline function: SafeContext.(T) -> Unit,
+        ): SafeListener {
+            val destroyable by selfReference<SafeListener> {
+                SafeListener(priority, this@listenOnce, alwaysListen) { event ->
+                    function(event as T)
+                    EventFlow.syncListeners.unsubscribe(self)
+                }
+            }
+
+            EventFlow.syncListeners.subscribe<T>(destroyable)
+
+            return destroyable
+        }
+
         /**
          * Registers a new [SafeListener] for a generic [Event] type [T] within the context of a [Task].
          * The [function] is executed on the same thread where the [Event] was dispatched.

common/src/main/kotlin/com/lambda/event/listener/UnsafeListener.kt

@@ -5,7 +5,9 @@ import com.lambda.event.Event
 import com.lambda.event.EventFlow
 import com.lambda.event.Muteable
 import com.lambda.event.listener.SafeListener.Companion.concurrentListener
+import com.lambda.event.listener.SafeListener.Companion.listenOnce
 import com.lambda.event.listener.SafeListener.Companion.listener
+import com.lambda.util.selfReference
 
 /**
  * An [UnsafeListener] is a specialized type of [Listener] that operates without a [SafeContext].
@@ -79,6 +81,50 @@ class UnsafeListener(
             return listener
         }
 
+        /**
+         * Registers a new [UnsafeListener] for a generic [Event] type [T].
+         * The [function] is executed only once when the [Event] is dispatched.
+         * This function should only be used when the [function] performs read actions on the game data.
+         * For only in-game related contexts, use the [SafeListener.listenOnce] function instead.
+         * The listener will be automatically unsubscribed after the first execution.
+         * This function is useful for one-time event handling.
+         *
+         * Usage:
+         * ```kotlin
+         * unsafeListenOnce<MyEvent> { event ->
+         *     println("Unsafe event received only once: $event")
+         * }
+         *
+         * unsafeListenOnce<MyEvent>(priority = 1) { event ->
+         *     println("Unsafe event received only once before the previous listener: $event")
+         * }
+         * ```
+         *
+         * After the [function] is executed once, the [SafeListener] will be automatically unsubscribed.
+         *
+         * @param T The type of the event to listen for. This should be a subclass of Event.
+         * @param priority The priority of the listener. Listeners with higher priority will be executed first. The Default value is 0.
+         * @param alwaysListen If true, the listener will be executed even if it is muted. The Default value is false.
+         * @param function The function to be executed when the event is posted. This function should take an event of type T as a parameter.
+         * @return The newly created and registered [UnsafeListener].
+         */
+        inline fun <reified T : Event> Any.unsafeListenOnce(
+            priority: Int = 0,
+            alwaysListen: Boolean = false,
+            noinline function: (T) -> Unit,
+        ): UnsafeListener {
+            val destroyable by selfReference<UnsafeListener> {
+                UnsafeListener(priority, this@unsafeListenOnce, alwaysListen) { event ->
+                    function(event as T)
+                    EventFlow.syncListeners.unsubscribe(self)
+                }
+            }
+
+            EventFlow.syncListeners.subscribe<T>(destroyable)
+
+            return destroyable
+        }
+
         /**
          * Registers a new [UnsafeListener] for a generic [Event] type [T].
          * The [function] is executed on a new thread running asynchronously to the game thread.

common/src/main/kotlin/com/lambda/util/SelfReference.kt

@@ -0,0 +1,10 @@
+package com.lambda.util
+
+class SelfReference<T>(initializer: SelfReference<T>.() -> T)  {
+    val self: T by lazy { inner ?: throw IllegalStateException("Do not use `self` until initialized.") }
+
+    private val inner = initializer()
+    operator fun getValue(thisRef: Any?, property: Any?) = self
+}
+
+fun <T> selfReference(initializer: SelfReference<T>.() -> T): SelfReference<T> = SelfReference(initializer)