Skip to content
BrennaniumPublic

About

Typed, composable KeyPaths and CaseKeyPaths for Kotlin.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

KPaths

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.

Modules

  • 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.

Installation

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.

KeyPaths

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.city

That 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.city

Person.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.

CaseKeyPaths

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.

Documentation

  • main — documentation for the current development branch.
  • 0.1.0 — documentation for the published 0.1.0 release.

The main documentation includes:

Acknowledgments

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.

License

KPaths is released under the MIT License.

About

Typed, composable KeyPaths and CaseKeyPaths for Kotlin.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages