kotlin-throwable-policy

kotlin-throwable-policy provides Kotlin Multiplatform helpers for deciding which Throwable
instances must be propagated from broad catch blocks.
Use it at containment boundaries, cleanup paths, and callback adapters where code catches broadly but
still needs to preserve fatal platform errors, interruption, cancellation, non-local control flow,
and programmer-error signals.
🚀 Installation
commonMain.dependencies {
implementation("one.wabbit:kotlin-throwable-policy:0.0.1")
}
🚀 Usage
import one.wabbit.throwables.Throwables
fun runBoundary(block: () -> Unit): Boolean =
try {
block()
true
} catch (t: Throwable) {
Throwables.propagateIfNeeded(t)
false
}
propagateIfNeeded rethrows the first high-priority throwable selected by the active policy: fatal
platform errors, interruption or cancellation, non-fatal errors, non-cancellation control flow, or
contract violations. If nothing needs propagation, the caller can contain or translate the failure.
Policies
Throwables.defaultPolicy avoids allocation-heavy throwable graph traversal. It follows preferred
causes and unwraps common platform wrapper exceptions.
Throwables.strictPolicy enables suppressed-exception scanning, follows suppressed causes, uses
strict control-flow detection, and throws when traversal exceeds the configured maximum depth.
The rethrowControlFlow, rethrowCancellations, rethrowInterrupts, and
rethrowContractViolations flags decide which non-fatal categories mustPropagate returns. Fatal
platform errors always propagate.
Suppressed Failures
Cleanup code can preserve primary and secondary failures without burying abort signals:
try {
closeResource()
} catch (cleanup: Throwable) {
Throwables.handleSuppressed(primary, cleanup)
}
If cleanup must propagate, it is thrown after primary is added as suppressed on a best-effort
basis. Otherwise it is added to primary. When restoreInterrupt is enabled, handleSuppressed
also restores the interrupt flag if cleanup contains an interruption signal.
Status
This is an early 0.x policy library. The core API is small, but platform classifications may evolve
as more targets and foreign runtime integrations are validated.
Documentation
Generated API docs can be built locally with Dokka. See API reference notes
for the command.
Release Notes
Licensing
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) for open
source use.
For commercial use, contact Wabbit Consulting Corporation at wabbit@wabbit.one.
Contributing
Contributions are governed by the repository contribution policy and the Wabbit CLA. See
CONTRIBUTING.md and the files under legal/.