Lightweight coroutine-based startup orchestrator offering a declarative DSL for initialization tasks, dependency graph with cycle detection, retry/backoff policies, importance levels, timing metrics and lifecycle events.
InitSpark is a lightweight, Kotlin Multiplatform (KMP) coroutine-based startup orchestration library. It provides a structured way to declare, sequence, and execute initialization tasks (called sparks) during your app's startup phase across JVM, Android, and iOS natively.
InitSpark is published to Maven Central.
Add the dependency to your build.gradle.kts:
sourceSets {
commonMain.dependencies {
implementation("io.github.ktomek:initspark:1.0.0") // Replace with latest version
}
}
For JVM or Android-only projects:
dependencies {
implementation("io.github.ktomek:initspark:1.0.0")
}
Add to your build.gradle:
repositories {
maven("https://jitpack.io")
}
dependencies {
implementation("com.github.ktomek:initspark:<version>")
}
Sparkclass DatabaseSpark @Inject constructor(...) : Spark {
override suspend fun execute() { /* initialize database */ }
}
val sparks = setOf(
DatabaseSpark(),
NotificationSpark(),
AnalyticsSpark(),
/* ... */
)
val config = buildSparks(sparks) {
// Sequential, must complete before next spark starts
await { System.loadLibrary("crypto-lib") }
await<LoggerSpark>()
await<ActivityLifecycleSpark>()
ioContext = Dispatchers.IO
coreDeps = setOf(Key())
async<DatabaseSpark>(
key = .asKey(),
context = ioContext
)
async<NotificationSpark>(
context = ioContext,
needs = coreDeps,
policy = SparkPolicy(importance = SparkImportance.OPTIONAL)
)
async<AnalyticsSpark>(
context = ioContext,
needs = coreDeps,
policy = SparkPolicy(
retry = RetryPolicy(
retryCount = ,
backoff = Backoff.Exponential(initialDelayMillis = )
)
)
)
spark<ConsentManagerSpark>(context = ioContext, needs = coreDeps)
}
val initSpark = InitSpark(config, CoroutineScope(Dispatchers.Default))
// Suspending version (preferred)
initSpark.initialize()
// Blocking version (for Java interop or legacy code)
initSpark.initializeBlocking()
Each builder function accepts:
Key is an interface, letting you use any type with proper equality — data object, enum entry, or a plain string:
// String-backed key (default)
"Database".asKey() // or Key("Database")
// Custom key type (recommended for robustness)
data object DatabaseKey : Key
enum class AppKey : Key { DATABASE, ANALYTICS }
Control how failures propagate using SparkPolicy:
// CRITICAL (default): failure throws and halts initialization
async<DatabaseSpark>(policy = SparkPolicy(importance = SparkImportance.CRITICAL))
// OPTIONAL: failure is logged and emitted as a SparkEvent.Failed, but other sparks continue
async<AnalyticsSpark>(policy = SparkPolicy(importance = SparkImportance.OPTIONAL))
Attach a RetryPolicy to automatically retry failing sparks:
val policy = SparkPolicy(
retry = RetryPolicy(
retryCount = 3,
backoff = Backoff.Exponential(initialDelayMillis = 100L, factor = 2.0)
)
)
| Strategy | Description |
|---|---|
Backoff.None | No delay between retries (default) |
Backoff.Fixed(delayMillis) |
Use the events flow to receive real-time lifecycle updates from the orchestrator:
launch {
initSpark.events.collect { event ->
when (event) {
is SparkEvent.Started -> log("▶ ${event.key} started")
is SparkEvent.Completed -> log("✅ ${event.key} done in ${event.duration}")
is SparkEvent.Failed -> log("❌ ${event.key} failed: ${event.error}")
is SparkEvent.Retry -> log()
}
}
}
// Suspend until all TRACKABLE sparks are done
initSpark.waitUntilTrackableInitialized()
// Suspend until ALL sparks (including fire-and-forget) are done
initSpark.waitUntilInitialized()
// Or observe via StateFlow
initSpark.isTrackableInitialized.collect { ready -> if (ready) onReady() }
initSpark.isInitialized.collect { ready -> if (ready) onFullyReady() }
Access detailed performance metrics after initialization:
initSpark.waitUntilInitialized()
with(initSpark.timing) {
// Per-spark durations
allDurations().forEach { (declaration, duration) ->
Timber.d("Spark '${declaration.key}' [${declaration.type}] took $duration")
}
// Cumulative total (sum of all individual durations)
Timber.d("Sum of all durations: ${sumOfDurations()}")
Timber.d("Sum by type: ${sumOfDurationsByType()}")
Timber.d()
Timber.d()
}
Contributions are welcome!
Please review our CONTRIBUTING.md for details on code style, testing, and how to submit pull requests.
This project is licensed under the MIT License.
await, async, and sparkCRITICAL (fail-fast) and OPTIONAL (failure-tolerant)None, Fixed, and Exponential backoffSparkEvent stream for lifecycle monitoringKey interface for spark identificationSparkTimingInfo| Builder function | Execution | Tracked | Default key |
|---|
await { } / await<T>() | Sequential | ✅ | Class simple name |
async { } / async<T>() | Parallel | ✅ | Class simple name |
spark { } / spark<T>() | Parallel | ❌ | Class simple name |
| Parameter | Type | Description |
|---|
key | Key? | Optional unique identifier (defaults to class name) |
needs | Set<Key> | Keys of sparks that must complete first |
context | CoroutineContext | Coroutine dispatcher |
policy | SparkPolicy | Importance and retry configuration |
| Constant delay |
Backoff.Exponential(initialDelayMillis, factor) | Delay × factor on each attempt |
| Method | Returns |
|---|
durationOf(declaration) | Duration for one spark, or null |
allDurations() | Map<SparkDeclaration, Duration> |
sumOfDurations() | Cumulative sum of all measured durations |
sumOfDurationsByType() | Cumulative sum grouped by SparkType |
executionDelta() | Wall-clock window (first start → last stop) |
executionDeltaByType() | Wall-clock window grouped by SparkType |
MIT License
Copyright (c) 2023 ktomek
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Surfaced from shared tags and platforms — no rankings paid for.