Skip to content

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:

// Swift: \Person.name
val name = keyPath(Person::name)
// KeyPath<Person, String>

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:

val name: KeyPath<Person, String> = keyPath(Person::name)

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.