README.md

kotlin-channel-event-bus 🔆

Multi-keys, multi-producers, single-consumer event bus backed by kotlinx.coroutines.channels.Channels.

• A Kotlin Multiplatform library that provides a simple event bus implementation using kotlinx.coroutines.channels.Channels. This is useful for UI applications where you want to send events to communicate between different parts / scope of your application (e.g. send results from one screen to another).

• This bus is thread-safe to be used by multiple threads. It is safe to send events from multiple threads without any synchronization.

• ChannelEvent.Key will be used to identify a bus for a specific type of events. Each bus has a Channel to send events to and a Flow to receive events from.

• The Channel is unbounded (Channel.UNLIMITED - default) or conflated Channel.CONFLATED. The Flow is cold and only one collector is allowed at a time. This makes sure all events are consumed.

Author: Petrus Nguyễn Thái Học

Like some of my work? Could you buy me a coffee (or more likely a beer)?

Docs

• 0.x release docs: https://kotlin-multiplatform-foundation.github.io/kotlin-channel-event-bus/docs/0.x
• Snapshot docs: https://kotlin-multiplatform-foundation.github.io/kotlin-channel-event-bus/docs/latest/

Installation

allprojects {
  repositories {
    [...]
    mavenCentral()
  }
}

implementation("io.github.hoc081098:channel-event-bus:0.1.0")

Snapshot

Snapshots of the development version are available in Sonatype's snapshots repository.

• Kotlin

allprojects {
  repositories {
    [...]
    maven(url = "https://s01.oss.sonatype.org/content/repositories/snapshots/")
  }
}

dependencies {
  implementation("io.github.hoc081098:channel-event-bus:0.1.1-SNAPSHOT")
}

• Groovy

allprojects {
  repositories {
    [...]
    maven { url "https://s01.oss.sonatype.org/content/repositories/snapshots/" }
  }
}

dependencies {
  implementation 'io.github.hoc081098:channel-event-bus:0.1.1-SNAPSHOT'
}

Basic usage

// Create your event type
data class AwesomeEvent(val payload: Int) : ChannelEvent<AwesomeEvent> {
  override val key get() = Key

  companion object Key : ChannelEventKey<AwesomeEvent>(AwesomeEvent::class)
}

// Create your bus instance
val bus = ChannelEventBus()

// Send events to the bus
bus.send(AwesomeEvent(1))
bus.send(AwesomeEvent(2))
bus.send(AwesomeEvent(3))

// Receive events from the bus
bus
  .receiveAsFlow(AwesomeEvent) // or bus.receiveAsFlow(AwesomeEvent.Key) if you want to be explicit
  .collect { e: AwesomeEvent -> println(e) }

Supported targets

• jvm / android.
• js (IR).
• wasmJs.
• Darwin targets:
  • iosArm64, iosX64, iosSimulatorArm64.
  • watchosArm32, watchosArm64, watchosX64, watchosSimulatorArm64, watchosDeviceArm64.
  • tvosX64, tvosSimulatorArm64, tvosArm64.
  • macosX64, macosArm64.
• mingwX64
• linuxX64, linuxArm64.
• androidNativeArm32, androidNativeArm64, androidNativeX86, androidNativeX64.

Sample

• Android Compose sample: an Android app using Compose UI to show how to use the library. It has two nested navigation graphs: Register and Home.

  • In Register, we have 3 steps (3 screens) to allow the user to input their information, step by step.

    • A RegisterSharedViewModel (bound to Register navigation graph scope) is used to hold the whole state of the registration process. It observes events from the ChannelEventBus and updates the state accordingly.

    • Each step screen has a ViewModel to hold the state of the screen and will send events to the ChannelEventBus, then the RegisterSharedViewModel will receive those events and update the state.

  • In the Home nav graph, we have 2 screens: Home and Detail.

    • The Home screen has a HomeViewModel to hold the results received from the Detail screen. Those result events are sent from the Detail screen to the ChannelEventBus, and the HomeViewModel will receive those events and update the state.

    • The Detail screen will send events to the ChannelEventBus when the user clicks on the button. The HomeViewModel will receive those events and update the state.

Screen_recording_20231203_155312.mp4

Roadmap

• Support more targets: wasm (depends on supported targets by kotlinx.coroutines) (since 0.1.0).
• More samples.
• More docs.
• More tests.

License

                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/