Compile-time object mapping for Kotlin Multiplatform — annotate your wire models, get type-safe mappers generated by KSP. No reflection, no runtime registry, no boilerplate.

data class User(val id: Long, val joined: LocalDate)

@MapTo(User::class)
data class UserResponse(val id: Long, val joined: String)

// generated at compile time:
val user: User = UserResponse(7, "2026-06-12").toUser()

What makes that different from every mapper you've hand-written:

• Failures are typed, not silent. toX() throws a typed MappingException on a hard failure — never a surprise crash from an unrelated bug. The fallback ladder (value > constructor default > null > error) keeps one bad field from destroying a payload, every absorbed error is reported to an observability sink, and if you'd rather have failures as values, opt in per-mapping or module-wide with a return wrapper (toXResult(): Result<X>, toXFlow(): Flow<X>, or your own).
• Errors carry a path. Cannot convert customer.address.zipCode: … — R8-safe, three objects deep.
• Lossy conversions don't compile. Long → Int fails the build with a guiding message instead of silently truncating in production.
• User–author parity. Your converters, validators, and collection wrappers run on exactly the same rails as the 35 built-ins — no privileged internals.

Full guide on GitBook: https://kmapper.gitbook.io/docs

Source Markdown in the repo: English · Türkçe — installation, the mental model, field mapping, null-safety, converters, validation, collections, enums, return wrappers, error handling, observability, multi-module setup, full annotation reference.

Prefer reading code? The sample gallery has 26 runnable examples covering every feature, ordered basic → advanced (./gradlew sample:runSample).

Working on a project that uses KMapper? Start here:

• llms.txt — curated index of the docs (llmstxt.org format); llms-full.txt — the entire guide as one file for context ingestion. (The GitBook site serves its own at kmapper.gitbook.io/docs/llms.txt.)
• docs/AGENTS.md — consumer cheat sheet: the 3-rule mental model, annotation table, sharp edges, and compile-error → fix mappings.
• Writing 1.x-era API (@Ignore, @UseMapTypeConverter, @ValidateFrom/To, @MapDefaultValue)? Those names still resolve but fail compilation with guided ERROR-level deprecations naming the 2.0 replacement — follow the message or the migration guide.

plugins {
    id("com.google.devtools.ksp") version "2.3.10-2.0.5"
}

dependencies {
    implementation("io.github.sahsenvar:kmapper-core:3.0.0")
    implementation("io.github.sahsenvar:kmapper-annotations:3.0.0")
    ksp("io.github.sahsenvar:kmapper-compiler:3.0.0")
}

Want a module-wide return wrapper (e.g. every mapping also gets toXResult()) without repeating wrapper = … on each @MapTo? Add the optional Gradle plugin:

plugins {
    id("io.github.sahsenvar.kmapper") version "3.0.0"
}

import com.sahsenvar.kmapper.gradle.KMapperWrapper

KMapper { wrapper = KMapperWrapper.KtResult }

KMP setup and add-ons: installation guide.

Group io.github.sahsenvar:

kotlinx-datetime (LocalDate, Instant, …) and kotlin.time.Duration converters are core built-ins — no add-on needed.

Latest release: 3.0.0 (12 artifacts) — on Maven Central. 3.0.0 is a breaking change: generated mappers now return the plain toX() by default (it throws on a hard failure) instead of toXResult(): Result<X> — see return wrappers to opt back into Result, Flow, or your own wrapper. Upgrading from 2.x, see the Migrating from 2.x section of that same page; upgrading from 1.x? Migration guide · CHANGELOG.

Design ledger & implementation plans live in docs/superpowers/ and docs/converter-redesign.md.