
Typed, composable KeyPaths and CaseKeyPaths enabling structural property access, sealed-case matching/embedding, generated catalogs via annotations, composition, and optional reflection-backed factories for concise value/reference updates.
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 published 0.1.0 release.The main documentation includes:
@Pathable adds.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.
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 published 0.1.0 release.The main documentation includes:
@Pathable adds.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.