KeyPaths¶
KPaths is inspired by Swift key-path expressions.
In Swift, \Person.name is a compiler-recognized expression that creates a typed KeyPath<Person, String>.
Kotlin has property references rather than key-path expressions, so KPaths uses a factory as the equivalent construction syntax:
This factory-first style is the normal way to create a KeyPath. It works for any accessible Kotlin property, including one declared in another module. For source-owned models whose KeyPaths are used repeatedly, @Pathable generates canonical KeyPaths; see Generated catalogs.
Choose a KeyPath factory¶
Use a property-reference factory by default. It preserves Kotlin’s own property name and lets KPaths derive stable identity and complete type metadata:
For a source-owned type with a public, frequently used KeyPath vocabulary, prefer a generated catalog instead:
@Pathable
data class Person(val name: String, var address: Address)
PersonPaths.name // KeyPath<Person, String>
PersonPaths.address // WritableKeyPath<Person, Address>
The remaining factories are deliberate escape hatches:
| Need | Factory | Use it when |
|---|---|---|
| Read an accessible property | keyPath(Person::name) |
Default choice, including third-party types. |
| Reuse source-owned KeyPaths | PersonPaths.name |
The model is annotated and the KeyPath is part of its normal vocabulary. |
| Read a computed or derived value | keyPath(name, get) |
No property reference represents the read. |
| Replace part of an immutable value | writableKeyPath(get, set) |
You can state how a new focus produces a new root. |
| Set a mutable computed property on a copied root | writableKeyPath(property, copy) |
A KMutableProperty1 exists and copying first is the desired value semantics. |
| Mutate an intentionally shared class | referenceWritableKeyPath(property) |
The root is reference-owned and in-place mutation is intentional. |
| Bind an index or map key | indexed/keyed keyPath or writableKeyPath factories |
The selector is a Kotlin get/set operation rather than a property. |
| Define library-level identity explicitly | the PathId and TypeId overloads |
A library must control every identity segment or lacks reified type information. |
asKeyPath() and asReferenceWritableKeyPath() are equivalent extension spellings for the
property-reference factories. They are conveniences, not a separate KeyPath model. The generated
API reference lists every overload.
Derived KeyPaths¶
Use the named keyPath factory when a derived value has no KProperty1:
val normalizedName: KeyPath<Person, String> = keyPath("normalizedName") { person ->
person.name.trim().lowercase()
}
The name is part of the KeyPath’s PathId. Use a stable, root-local name; two separately-created
KeyPaths with the same root type and name compare equal.
The PathId overload is lower level. It is for library authors who need a custom multi-segment
identity or who must pass an explicit TypeId:
val normalizedName: KeyPath<Person, String> = keyPath(
id = PathId.custom(TypeId.of<Person>(), "normalizedName"),
valueType = TypeId.of<String>(),
get = { person -> person.name.trim().lowercase() },
)
Application code should normally use the named factory instead.
A KeyPath that can act as a closure¶
A KeyPath<Root, Value> is a total typed read: every Root has exactly one Value. It can be read, passed to a generic function, composed with another KeyPath, and compared with another KeyPath. It is more descriptive than passing an anonymous (Root) -> Value getter around.
data class Address(var city: String)
data class Person(val name: String, var address: Address)
val name: KeyPath<Person, String> = keyPath(Person::name)
val person = Person("Blob", Address("Paris"))
person[name] // "Blob"
person.get(keyPath = name) // "Blob"
The square-bracket spelling is Kotlin operator syntax. get(keyPath = …) is the same operation with an explicit label, which is often clearer in an API that accepts several inputs.
KPaths also makes a KeyPath directly implement Kotlin’s function type (Root) -> Value. That
means it works anywhere Kotlin expects a read closure, without writing { person -> name[person] }
or Person::name again:
val people = listOf(
Person("Blob", Address("Paris")),
Person("Jr.", Address("Toronto")),
)
people.map(name) // ["Blob", "Jr."]
people.sortedBy(name) // sorted by name
people.groupBy(name) // Map<String, List<Person>>
The KeyPath does not become “just a closure” when passed this way. It retains its PathId, TypeId,
equality, and composition behavior, so the same name value can also be stored or used with
person[name].
This is why reusable APIs should accept KeyPath<Root, Value> when they need to keep track of a
field, rather than immediately erasing it to (Root) -> Value. A KeyPath-aware API can compare
selected fields, compose an additional KeyPath, and use the KeyPath’s identity in a registry or cache.
See KeyPath and CaseKeyPath API design for complete API designs and the boundary between a
KeyPath and an ordinary closure.
Reading and writing¶
Swift has a hierarchy of KeyPath, WritableKeyPath, and ReferenceWritableKeyPath. KPaths uses the same capability distinction, translated to Kotlin’s update model:
| Type | Read | Write result | Mutation |
|---|---|---|---|
KeyPath<Root, Value> |
get(root) |
none | none |
WritableKeyPath<Root, Value> |
get(root) |
returns a Root |
value-style replacement |
ReferenceWritableKeyPath<Root, Value> |
get(root) |
returns the same Root |
mutates that instance |
keyPath(Person::address) is deliberately read-only even though address is declared var. Kotlin cannot know whether a caller means to reconstruct a value or mutate an existing reference, so choosing either write capability is explicit.
Value-style replacement¶
Use writableKeyPath when writing should produce a replacement root. The get property reference supplies the read operation; set supplies the reconstruction that Kotlin cannot synthesize through a shared data-class interface.
val address = writableKeyPath(
get = Person::address,
set = { person, value -> person.copy(address = value) },
)
val revised = person.setting(address, Address("Toronto"))
person // unchanged
set(keyPath = …, value = …), setting(…), and modifying(…) all return the resulting root. Assign that result when working with value-style state:
val revised = person.modifying(address) { current ->
current.copy(city = current.city.uppercase())
}
For a mutable computed property, KPaths can copy first and then invoke the ordinary Kotlin setter on the copy:
data class User(var rawName: String) {
var displayName: String
get() = rawName.trim()
set(value) { rawName = value }
}
val displayName = writableKeyPath(
property = User::displayName,
copy = { user -> user.copy() },
)
The copy lambda is required because Kotlin synthesizes copy() per data class rather than through a common protocol that a generic path factory can call.
When neither a KProperty1 nor a KMutableProperty1 describes the value, use the named
writableKeyPath overload and provide both directions:
val normalizedName: WritableKeyPath<User, String> = writableKeyPath(
name = "normalizedName",
get = { user -> user.displayName.lowercase() },
set = { user, value -> user.copy(rawName = value.trim()) },
)
Use the PathId overload only for the same narrow library-author case as the read-only KeyPath
factory: custom structural identity or an explicit TypeId.
Reference mutation¶
Use referenceWritableKeyPath when a mutable class is intentionally shared and its existing instance should change:
class Session(var token: String)
val token = referenceWritableKeyPath(Session::token)
val session = Session("old")
session[token] = "new"
check(session.token == "new")
This is the Kotlin counterpart to Swift’s ReferenceWritableKeyPath. A data class is still a reference object in Kotlin, but KPaths treats generated data-class KeyPaths as value-style. On the JVM, a manual ReferenceWritableKeyPath with a data-class root is allowed and emits a runtime warning by default, because it often signals an accidental break from value semantics. Kotlin/Native cannot inspect the data modifier at runtime, so it safely omits that diagnostic; generated data-class paths remain copy-based on every platform.
For a derived in-place value without a mutable property reference, use the named factory and make the mutation explicit:
class Progress(var completed: Int, var total: Int)
val fraction: ReferenceWritableKeyPath<Progress, Double> = referenceWritableKeyPath(
name = "fraction",
get = { progress -> progress.completed.toDouble() / progress.total },
set = { progress, value -> progress.completed = (progress.total * value).toInt() },
)
This form is only for reference semantics. A value-style model should use writableKeyPath(get, set) instead.
Composing KeyPaths¶
Like Swift KeyPaths, KPaths KeyPaths compose. then is the Kotlin-friendly spelling; appending is available when the longer name reads better.
val address = writableKeyPath(
get = Person::address,
set = { person, value -> person.copy(address = value) },
)
val city = writableKeyPath(
get = Address::city,
set = { address, value -> address.copy(city = value) },
)
val personCity = address.then(city)
val revised = person.setting(personCity, "Toronto")
Two writable KeyPaths compose to a WritableKeyPath. A reference-writable outer KeyPath composed with a writable inner KeyPath remains reference-writable. Any composition containing a read-only KeyPath is read-only: KPaths will never invent a reconstruction function just to make a composed KeyPath writable. The API reference documents the complete then overload set.
This capability is useful in generic update APIs. A function accepting
WritableKeyPath<Root, Value> can update a shallow or deeply nested field with the same
implementation, while a KeyPath parameter correctly refuses an operation that needs write-back.
Optional KeyPaths¶
A nullable focus is still a normal, total KeyPath: every root has the property, but its value may
be absent. Its nullability is retained in the focused TypeId:
data class Address(val city: String)
data class Person(val address: Address?)
val address = keyPath(Person::address)
// KeyPath<Person, Address?>
Use thenOptional to read through a nullable focus. It is the Kotlin equivalent of a read-only
Swift optional-chaining key path:
val city = address.thenOptional(keyPath(Address::city))
// KeyPath<Person, String?>
city(Person(Address("Paris"))) // "Paris"
city(Person(null)) // null
val presentCities = people.mapNotNull(city)
thenOptional is deliberately read-only, even if both component KeyPaths are writable. A write
through a missing address has no universal meaning, and assigning null to the final focus
could mean either “clear address” or “leave it alone.” Model that policy explicitly with a
custom writableKeyPath instead.
Force-unwrapping an optional KeyPath¶
When absence is a programming error, use thenForceUnwrapped. It is the explicit, dangerous
counterpart to Swift’s ! key-path segment: it has a non-null focus and remains writable when
both components are writable, but it throws NullPointerException if the intermediate optional
is absent.
val address = writableKeyPath(
get = Person::address,
set = { person, value -> person.copy(address = value) },
)
val city = writableKeyPath(
get = Address::city,
set = { address, value -> address.copy(city = value) },
)
val requiredCity = address.thenForceUnwrapped(city)
// WritableKeyPath<Person, String>
requiredCity.set(Person(Address("Paris")), "Toronto")
requiredCity.get(Person(null)) // throws NullPointerException
Prefer thenOptional unless your domain guarantees presence. The force-unwrapped KeyPath exists
for invariants and migration boundaries, not as a replacement for modeling optional state.
Whole values, collections, and indexes¶
identityKeyPath<Root>() focuses a whole root, analogous to Swift’s \Type.self. Replacing its focus is simply replacing the root value.
val wholePerson = identityKeyPath<Person>()
wholePerson.get(person) // person
wholePerson.set(person, revised) // revised
KPaths provides canonical KeyPaths for common Kotlin standard-library operations:
StringPaths.at(1).get("Blob")
val second = ListPaths<String>().at(1)
second.get(listOf("Blob", "Jr."))
val score = MapPaths<String, Int>().at("blob")
score.set(mapOf("blob" to 1), null) // removes "blob"
ListPaths is read-only. ArrayPaths, MutableListPaths, primitive-array KeyPaths, and MutableMapPaths are reference-writable because their Kotlin APIs mutate an existing collection. An assigned map value of null always removes the key, including for Map<Key, Value?>; KPaths does not introduce a second representation for “stored null” versus “missing key.”
When an API exposes indexed get and set callables, the factories can make the corresponding KeyPath without an intermediate closure:
val second = keyPath(get = List<String>::get, at = 1)
val editableSecond = referenceWritableKeyPath(
get = MutableList<String>::get,
set = MutableList<String>::set,
at = 1,
)
Where to go next¶
This guide owns the ordinary property-reference and writable-path story. For named derived,
indexed, keyed, and whole-value paths, continue to Advanced KeyPaths. For the
generated-catalog naming, diagnostics, and sealed-case surface of @Pathable, continue to
Generated catalogs. For why PathId and TypeId make these values comparable,
read Identity and type metadata; the API-design guide shows
how to retain that information in your own APIs.