CaseKeyPaths¶
KPaths’ CaseKeyPaths are inspired by Point-Free’s CasePaths. A CaseKeyPath<Root, Value> is a reusable, hashable value that matches one sealed case and focuses a value associated with it. It makes extraction, construction, composition, and generic APIs possible without repeating local when expressions.
interface CaseKeyPath<Root, Value> {
fun match(root: Root): CaseMatch<Value>
fun extract(root: Root): Value?
fun embed(value: Value): Root
}
embed always constructs a root, independent of any existing root—just like Swift CasePaths:
@Pathable
sealed interface Event {
data object Started : Event
data class Message(val text: String) : Event
data class Navigate(val id: String, val destination: String) : Event
data class Replace(
val id: String,
val destination: String,
val animated: Boolean,
) : Event
}
val message = caseKeyPath<Event, Event.Message>()
message.embed(Event.Message("Hello")) // Event.Message("Hello")
Event.Started[message] // null
There is no WritableCaseKeyPath: a genuine CaseKeyPath always embeds a complete case. val/var capability distinctions belong to ordinary Kotlin KeyPaths.
Choose a CaseKeyPath factory¶
For a source-owned sealed hierarchy used repeatedly, @Pathable is the preferred choice. The
annotated Event above gets canonical CaseKeyPaths without runtime shape discovery:
EventPaths.Message.text
// CaseKeyPath<Event, String>
EventPaths.Navigate.destinationFor(id = "settings")
// CaseKeyPath<Event, String>
For one-off and external hierarchies, choose the smallest manual factory that fully describes the case:
| Need | Factory | Use it when |
|---|---|---|
| Reuse a source-owned case | generated EventPaths.Message.text |
Preferred: canonical, discoverable, no reflection. |
| Match and embed the complete concrete case | caseKeyPath<Root, Case>() |
The case object itself is the desired focus. |
| Match one enum entry | caseKeyPath(Entry) |
A Kotlin enum entry has no associated payload. |
| Reflect a conventional data-class constructor (JVM) | casePathsOf<Root>().pathFor(::Case) |
Add kpaths-reflection-jvm; a one-off data case has one to three stored constructor properties. |
| Match and embed one payload property | caseKeyPath(extract, embed) |
A KProperty1 and one-argument constructor or embedder describe the case. |
| Match and embed two or three payload properties | caseKeyPath(extract1, extract2[, extract3], embed) |
A Pair or Triple is an acceptable focus. |
| Define a nonstandard case algorithm | caseKeyPath(id, valueType, match, embed) |
A library needs full control of identity, matching, and embedding. |
Whole cases and enum entries¶
The whole-case factory has no reflection and no constructor requirement:
val message: CaseKeyPath<Event, Event.Message> =
caseKeyPath<Event, Event.Message>()
message.embed(Event.Message("Hello"))
For a Kotlin enum, the focused value is Unit because the entry itself is already fully known:
enum class Compass { NORTH, SOUTH }
val north: CaseKeyPath<Compass, Unit> = caseKeyPath(Compass.NORTH)
north.embed(Unit) // Compass.NORTH
Reflection-backed constructor factories¶
casePathsOf<Root>().pathFor(::Case) is the short manual factory for a conventional data-class
case. It is a JVM-only convenience that needs the separate artifact. This isolates runtime case
shape discovery from the core API; the remaining Kotlin Multiplatform work is tracked separately:
Import a nested case so Kotlin can use its constructor reference directly:
import example.Event.Message
import example.Event.Navigate
val text: CaseKeyPath<Event, String> =
casePathsOf<Event>().pathFor(::Message)
val navigate: CaseKeyPath<Event, Pair<String, String>> =
casePathsOf<Event>().pathFor(::Navigate)
It reflects and validates the constructor shape once. Unary cases focus their one property; binary
and ternary cases focus Pair and Triple. Prefer a generated catalog when this CaseKeyPath is
on a hot or repeated path, and use an explicit factory for non-data cases, computed extraction,
or more than three constructor values.
Explicit payload factories¶
The explicit factory avoids reflection while retaining property names in the PathId:
import example.Event.Message
import example.Event.Navigate
import example.Event.Replace
val text: CaseKeyPath<Event, String> = caseKeyPath(
extract = Event.Message::text,
embed = ::Message,
)
val navigate: CaseKeyPath<Event, Pair<String, String>> = caseKeyPath(
extract1 = Event.Navigate::id,
extract2 = Event.Navigate::destination,
embed = ::Navigate,
)
The three-property overload is the same shape and focuses Triple<First, Second, Third>:
val replace: CaseKeyPath<Event, Triple<String, String, Boolean>> = caseKeyPath(
extract1 = Event.Replace::id,
extract2 = Event.Replace::destination,
extract3 = Event.Replace::animated,
embed = ::Replace,
)
For a case with four or more primary-constructor values, use the whole-case CaseKeyPath, create a
named payload data class, or write a focused custom CaseKeyPath. KPaths intentionally does not
invent an anonymous tuple type beyond Triple.
Fully custom CaseKeyPaths¶
The low-level factory is for library-defined matching and embedding behavior. It is not the normal
application API, because it requires an explicit stable PathId and TypeId:
sealed interface Signal {
data object Ping : Signal
}
val ping: CaseKeyPath<Signal, Unit> = caseKeyPath(
id = PathId.case(TypeId.of<Signal>(), "Ping"),
valueType = TypeId.of<Unit>(),
match = { signal ->
if (signal is Signal.Ping) CaseMatch.Matched(Unit) else CaseMatch.NoMatch
},
embed = { Signal.Ping },
)
When the root and focus types are reified, the overload without valueType captures that token
automatically. Generated catalogs and the higher-level factories should remain the default.
Extract, embed, compose¶
CaseKeyPaths are callable as their intentionally lossy (Root) -> Value? extraction:
Use match to preserve a matched null payload; see the API reference for its related operations:
when (val result = status.match(StatusPaths.Note.text)) {
CaseMatch.NoMatch -> Unit
is CaseMatch.Matched -> println(result.value) // may be null
}
Composition retains independent embedding through every enclosing case:
val renameText = AppEventPaths.Profile.action
.then(ProfileActionPaths.Editor.action)
.then(EditorActionPaths.Rename.text)
renameText.embed("Jr.")
// AppEvent.Profile(ProfileAction.Editor(EditorAction.Rename("Jr.")))
Multi-value cases and bound CaseKeyPaths¶
KSP generates a named context-bound CaseKeyPath factory for every property of a two- or three-value case:
@Pathable
sealed interface Request {
data class Navigate(val id: String, val destination: String) : Request
}
val destination = RequestPaths.Navigate.destinationFor(id = "settings")
destination.embed("privacy") // Request.Navigate("settings", "privacy")
Request.Navigate("profile", "privacy")[destination] // null
propertyFor(...) binds the remaining one or two constructor values, matches only that context, and independently embeds the focused value. This is useful for identifier-plus-action envelopes.
Generic roots and identity¶
On the JVM, casePathsOf<Root>() retains complete reified generic metadata:
val loaded: CaseKeyPath<Loadable<String>, String> =
casePathsOf<Loadable<String>>().pathFor(::Loaded)
Generated LoadablePaths<String>().Loaded.value carries the same concrete identity. Both manual and generated CaseKeyPaths compare and hash structurally by PathId; generated catalogs remain the most ergonomic no-reflection form. Read Generated catalogs for static versus generic catalog rules, Identity and type metadata for the equality model, and recipes for collection and nested-case patterns.