KPaths brings typed, composable, structurally identifiable KeyPaths and CaseKeyPaths to Kotlin. It is inspired by Swift KeyPaths and Point-Free’s CasePaths, while using Kotlin-native property references, sealed hierarchies, KSP, and reified type tokens.
kpaths-jvm: the default JVM and Android dependency; it re-exports core, annotations, and JVM reflection factories.kpaths-native: the default dependency for the supported iOS Kotlin/Native targets; it re-exports core and annotations.kpaths-core: KeyPath and CaseKeyPath types, explicit factories, composition, identity, and standard-library KeyPaths.kpaths-annotations:@Pathable.kpaths-ksp: generated catalogs.
An umbrella module only re-exports its dependencies: it adds no new KeyPath API. Use kpaths-jvm
for the JVM convenience surface and kpaths-native for the currently supported iOS Kotlin/Native
targets. kpaths-ksp remains a separate build-time processor because KSP uses a distinct Gradle
configuration. The reflection-backed casePathsOf(...).pathFor(...) shorthand remains JVM-only
because it depends on Kotlin reflection; generated catalogs and explicit factories work on Kotlin/Native.
For JVM or Android, one runtime dependency includes the core APIs, @Pathable, and reflection
factories:
implementation("io.github.brennanium:kpaths-jvm:<version>")For the supported iOS Kotlin/Native targets, add the Native umbrella from commonMain:
commonMain.dependencies {
implementation("io.github.brennanium:kpaths-native:<version>")
}If you use @Pathable, add kpaths-ksp to the KSP configuration for each source set or target
that compiles annotated models. See Generated catalogs
for the target-specific setup.
Use property references for any Kotlin type—no annotation is required:
data class Person(val name: String, var city: String)
val name = keyPath(Person::name)
val city = writableKeyPath(
get = Person::city,
set = { person, value -> person.copy(city = value) },
)KeyPath reads, WritableKeyPath returns a revised value for value-semantic models, and ReferenceWritableKeyPath is for intentional in-place class mutation. See the KeyPaths guide for factory selection, composition, nullable paths, and standard-library paths.
For a source-owned model with paths used repeatedly, annotate it to generate a canonical catalog:
@Pathable
data class Person(val name: String, var city: String)
PersonPaths.name
PersonPaths.cityThat top-level catalog is always the fallback for a valid annotated model; a companion is optional. For the most discoverable source-owned API, add a simple companion object:
@Pathable
data class Person(val name: String, var city: String) {
companion object
}
Person.Paths.name == PersonPaths.name // the same canonical KeyPath
Person.Paths.cityPerson.Paths keeps the vocabulary with its type in completion. It is a generated extension, so a
consumer in another package imports it normally; Kotlin IDEs generally offer that import
automatically. If the model has no companion, use PersonPaths instead—no generated behavior is
lost. See Generated catalogs for companion naming, imports, generic
construction forms, @PathsName, and generated-case naming options.
A CaseKeyPath<Root, Value> matches a sealed case, extracts its associated data, and independently constructs a root from that data:
sealed interface Event {
data object Started : Event
data class Message(val text: String) : Event
}
val message = caseKeyPath<Event, Event.Message>()
Event.Message("Hello")[message] // Event.Message("Hello")
Event.Started[message] // null
message.embed(Event.Message("Updated"))There is one CaseKeyPath type. Unlike KeyPaths, CaseKeyPaths reconstruct complete cases, so there is no read-only/writable hierarchy. The CaseKeyPaths guide explains whole-case, payload, JVM constructor, and generated factories.
For a conventional unannotated data-class case on the JVM, kpaths-jvm includes the constructor
shorthand:
implementation("io.github.brennanium:kpaths-jvm:<version>")import example.Event.Message
val text = casePathsOf<Event>().pathFor(::Message)
text.embed("Hello") // Event.Message("Hello")casePathsOf intentionally does not live in kpaths-core: it needs Kotlin/JVM's full runtime
shape discovery. Generated catalogs and explicit caseKeyPath factories do not need this optional
artifact.
For a non-reflective or custom CaseKeyPath, use the explicit factory:
val text = caseKeyPath<Event, Event.Message, String>(
extract = Event.Message::text,
embed = ::Message,
)For source-owned roots, generated CaseKeyPaths are the preferred repeated-use form:
@Pathable
sealed interface Request {
data class Navigate(val id: String, val destination: String) : Request
}
RequestPaths.Navigate.payload
RequestPaths.Navigate.destinationFor(id = "settings")
.embed("privacy")
// Request.Navigate("settings", "privacy")CaseKeyPaths compose and retain independent embedding:
val nested = AppEventPaths.Profile.action
.then(ProfileActionPaths.Editor.action)
.then(EditorActionPaths.Rename.text)
nested.embed("Jr.")Use match rather than nullable extraction whenever a matched null must remain distinguishable from a non-match.
main— documentation for the current development branch.0.1.0— documentation for the published0.1.0release.
The main documentation includes:
- KeyPaths covers the normal property-reference and writable-path APIs.
- CaseKeyPaths covers sealed-case matching, embedding, and composition.
- Generated catalogs explains what
@Pathableadds. - Recipes and API design show reusable patterns.
- Advanced KeyPath APIs and identity and type metadata cover library design and structural identity.
- The generated API reference is the source of truth for overloads and KDoc.
KPaths is strongly inspired by Swift’s KeyPath system and Point-Free’s CasePaths library. Their APIs demonstrate how first-class KeyPaths and CaseKeyPaths make generic algorithms and compositional application models substantially clearer.
KPaths is released under the MIT License.