API Reference

Complete public API surface of com.cristianllanos.events and com.cristianllanos.events.coroutines.

Core Interfaces (events-core)

Event

Marker interface for all events. Implement as a data class.

kotlin
interface Event

Listener<T : Event>

Synchronous event handler. Resolved from the DI container on each emit.

kotlin
interface Listener<T : Event> {
    fun handle(event: T)
}

Emitter

Fires events to registered listeners.

kotlin
interface Emitter {
    fun <T : Event> emit(event: T)
    fun emit(first: Event, vararg rest: Event)
}

Subscriber

Manages listener registration, middleware, and the registration DSL.

kotlin
interface Subscriber {
    fun <E : Event, L : Listener<E>> subscribe(event: Class<E>, listener: Class<L>): Subscriber
    fun <E : Event> subscribe(event: Class<E>, vararg listeners: KClass<out Listener<E>>): Subscriber
    fun <E : Event, L : Listener<E>> unsubscribe(event: Class<E>, listener: Class<L>): Subscriber
    fun <E : Event> on(event: Class<E>, handler: (E) -> Unit): Subscription
    fun <E : Event, L : Listener<E>> once(event: Class<E>, listener: Class<L>): Subscriber
    fun <E : Event> once(event: Class<E>, handler: (E) -> Unit): Subscription
    fun onAny(handler: (Event) -> Unit): Subscription
    fun use(middleware: Middleware): Subscriber
    fun register(block: RegistrationDsl.() -> Unit): Subscriber
    fun clear()
}

Inspector

Introspection into registered listeners.

kotlin
interface Inspector {
    fun <E : Event> hasListeners(event: Class<E>): Boolean
    fun <E : Event> listenerCount(event: Class<E>): Int
}

EventBus

Combines Emitter, Subscriber, and Inspector.

kotlin
interface EventBus : Emitter, Subscriber, Inspector

Middleware

Intercepts event dispatch. Call next to continue or omit to short-circuit.

kotlin
fun interface Middleware {
    fun handle(event: Event, next: (Event) -> Unit)
}

Subscription

Handle returned by lambda registrations. Call cancel() to remove.

kotlin
fun interface Subscription {
    fun cancel()
}

Factory Functions

EventBus()

kotlin
fun EventBus(
    resolver: Resolver,
    onError: (Throwable) -> Unit = { throw it },
): EventBus

SuspendingEventBus()

kotlin
fun SuspendingEventBus(
    resolver: Resolver,
    onError: suspend (Throwable) -> Unit = { throw it },
): SuspendingEventBus

Extension Functions

Subscriber Extensions

kotlin
inline fun <reified E : Event, reified L : Listener<E>> Subscriber.subscribe(): Subscriber
inline fun <reified E : Event> Subscriber.subscribe(vararg listeners: KClass<out Listener<E>>): Subscriber
inline fun <reified E : Event, reified L : Listener<E>> Subscriber.unsubscribe(): Subscriber
inline fun <reified E : Event> Subscriber.on(noinline handler: (E) -> Unit): Subscription
inline fun <reified E : Event, reified L : Listener<E>> Subscriber.once(): Subscriber
inline fun <reified E : Event> Subscriber.once(noinline handler: (E) -> Unit): Subscription

Inspector Extensions

kotlin
inline fun <reified E : Event> Inspector.hasListeners(): Boolean
inline fun <reified E : Event> Inspector.listenerCount(): Int

Registration

RegistrationDsl

DSL for bulk-registering event-listener mappings.

kotlin
class RegistrationDsl {
    infix fun <E : Event> KClass<E>.mappedTo(listeners: List<KClass<out Listener<E>>>)
}

EventServiceProvider

Registers EventBus, Emitter, and Subscriber as singletons in a Container.

kotlin
class EventServiceProvider {
    fun register(container: Container)
}

Coroutines Interfaces (events-coroutines)

SuspendingListener<T : Event>

Suspending event handler for async operations.

kotlin
interface SuspendingListener<T : Event> {
    suspend fun handle(event: T)
}

SuspendingEmitter

kotlin
interface SuspendingEmitter {
    suspend fun <T : Event> emit(event: T)
    suspend fun emit(first: Event, vararg rest: Event)
}

SuspendingSubscriber

Accepts both Listener and SuspendingListener registrations.

kotlin
interface SuspendingSubscriber {
    fun <E : Event, L : Listener<E>> subscribe(event: Class<E>, listener: Class<L>): SuspendingSubscriber
    fun <E : Event> subscribe(event: Class<E>, vararg listeners: KClass<out Listener<E>>): SuspendingSubscriber
    fun <E : Event, L : Listener<E>> unsubscribe(event: Class<E>, listener: Class<L>): SuspendingSubscriber
    fun <E : Event, L : SuspendingListener<E>> subscribeSuspending(event: Class<E>, listener: Class<L>): SuspendingSubscriber
    fun <E : Event> subscribeSuspending(event: Class<E>, vararg listeners: KClass<out SuspendingListener<E>>): SuspendingSubscriber
    fun <E : Event, L : SuspendingListener<E>> unsubscribeSuspending(event: Class<E>, listener: Class<L>): SuspendingSubscriber
    fun <E : Event> on(event: Class<E>, handler: suspend (E) -> Unit): Subscription
    fun <E : Event> once(event: Class<E>, handler: suspend (E) -> Unit): Subscription
    fun <E : Event, L : Listener<E>> once(event: Class<E>, listener: Class<L>): SuspendingSubscriber
    fun <E : Event, L : SuspendingListener<E>> onceSuspending(event: Class<E>, listener: Class<L>): SuspendingSubscriber
    fun onAny(handler: suspend (Event) -> Unit): Subscription
    fun clear()
}

SuspendingEventBus

Combines SuspendingEmitter, SuspendingSubscriber, and Inspector.

kotlin
interface SuspendingEventBus : SuspendingEmitter, SuspendingSubscriber, Inspector

SuspendingSubscriber Extensions

kotlin
inline fun <reified E : Event, reified L : Listener<E>> SuspendingSubscriber.subscribe(): SuspendingSubscriber
inline fun <reified E : Event> SuspendingSubscriber.subscribe(vararg listeners: KClass<out Listener<E>>): SuspendingSubscriber
inline fun <reified E : Event, reified L : Listener<E>> SuspendingSubscriber.unsubscribe(): SuspendingSubscriber
inline fun <reified E : Event, reified L : SuspendingListener<E>> SuspendingSubscriber.subscribeSuspending(): SuspendingSubscriber
inline fun <reified E : Event> SuspendingSubscriber.subscribeSuspending(vararg listeners: KClass<out SuspendingListener<E>>): SuspendingSubscriber
inline fun <reified E : Event, reified L : SuspendingListener<E>> SuspendingSubscriber.unsubscribeSuspending(): SuspendingSubscriber
inline fun <reified E : Event> SuspendingSubscriber.on(noinline handler: suspend (E) -> Unit): Subscription
inline fun <reified E : Event> SuspendingSubscriber.once(noinline handler: suspend (E) -> Unit): Subscription
inline fun <reified E : Event, reified L : Listener<E>> SuspendingSubscriber.once(): SuspendingSubscriber
inline fun <reified E : Event, reified L : SuspendingListener<E>> SuspendingSubscriber.onceSuspending(): SuspendingSubscriber

SuspendingEventServiceProvider

Registers SuspendingEventBus, SuspendingEmitter, and SuspendingSubscriber as singletons.

kotlin
class SuspendingEventServiceProvider {
    fun register(container: Container)
}

Exceptions

CompositeEventException

Wraps multiple listener errors collected during a single emit. Thrown when more than one listener fails and no custom onError handler is provided.

kotlin
class CompositeEventException(val errors: List<Throwable>) : RuntimeException