Identity and type metadata¶
KeyPaths and CaseKeyPaths are values. Two independently-created values that describe the same KeyPath or CaseKeyPath should compare equal and have the same hash code; equality must not depend on which closure instance happens to implement a getter.
Every KeyPath and CaseKeyPath therefore carries two public, read-only pieces of metadata:
PathIdidentifies the root type and ordered KeyPath or CaseKeyPath segments.TypeIdidentifies the focused type, retaining generic arguments, variance, and nullability.
The library-reserved metadata properties are named __kpaths_id and __kpaths_valueType. They
are intentionally unusual names so ordinary model properties such as id and valueType can be
generated without a collision.
Prefer declaration-derived identity¶
The usual construction forms derive identity from checked Kotlin declarations:
val title = keyPath(Book::title)
val finished = caseKeyPath<DownloadEvent, DownloadEvent.Finished>()
Generated catalogs do the same for source-owned models. You do not need to maintain a separate
string such as "Book.title" or "DownloadEvent.Finished": rename the property or case as part of
normal Kotlin refactoring, and KSP regenerates the matching catalog.
Named custom factories are the intentional exception. Their name is semantic, so choose a stable, root-local identifier and avoid reusing it for unrelated derived computations:
val first = keyPath<Person, String>("normalizedName") { it.name.trim().lowercase() }
val second = keyPath<Person, String>("normalizedName") { it.name.trim().lowercase() }
check(first == second)
check(first.hashCode() == second.hashCode())
The name in a manual named factory is therefore semantic, not a display label. Choose a stable, root-local name. If two distinct KeyPaths share a name and root type, they claim the same identity; if the same conceptual KeyPath gets different names, it will not compare equal.
Why TypeId is richer than KClass¶
String::class identifies the classifier String, but cannot distinguish List<String> from
List<Int> or String from String?. TypeId.of<T>() uses Kotlin's reified type information to
preserve those distinctions:
The TypeId.from(SomeType::class) form is available when only a non-generic class token exists.
For a generic algorithm that is not inline/reified, accept an explicit TypeId from its caller
and use the low-level factory overloads. This is the Kotlin equivalent of explicitly carrying the
type metadata that Swift can often recover from its runtime generic metadata.
Structural segments¶
PathId has property, case, index, key, and custom segments. Composition appends segments while
retaining the original root type. This is why a composed KeyPath or CaseKeyPath has one stable identity rather than
a nested chain of object identities.
Most code never constructs a PathId directly. Use generated catalogs, property references, or
named manual factories. The low-level PathId APIs exist for library authors defining a custom
KeyPath or CaseKeyPath whose identity must remain stable across modules or call sites. Factory
selection belongs in the KeyPaths and
CaseKeyPaths guides; the API reference
documents the low-level constructors.
Why identity changes API design¶
A closure can perform a read, but Kotlin offers no meaningful structural equality or hash for two
closures. An API that accepts (Root) -> Value therefore cannot know whether two callers selected
the same field. It cannot safely deduplicate registrations, reuse a prepared KeyPath, or construct
a stable identifier from that selection.
KeyPaths and CaseKeyPaths solve that narrow problem without making arbitrary closures pretend to be comparable:
data class Book(val title: String)
val visibleColumns = linkedSetOf<AnyKeyPath>()
visibleColumns += keyPath(Book::title)
visibleColumns += keyPath(Book::title)
check(visibleColumns.size == 1)
This makes a KeyPath or CaseKeyPath a good component of a subscription, prepared-query, or configuration key. When caching a computed value, include the input identity or version too; a KeyPath identifies the field being read, not one particular root value. See KeyPath and CaseKeyPath API design for the broader design patterns and recipes for concrete collection uses.