A Kotlin Multiplatform project that deep-clones @Serializable values.
The cloning logic lives in commonMain and works on every Kotlin target. It uses
a tiny custom Kotlin serialization format: a value is encoded into an in-memory
ArrayDeque of its primitive components and decoded straight back into a new
instance.
Instead of @Serializable, you can annotate a class with @Cloneable (a
@MetaSerializable annotation). The serialization plugin then generates a
serializer for it, and Cloner.clone works out of the box.
@Cloneable
data class Holder(val value: Int)- Guard —
Cloner.clonereturnsnullimmediately when the input isnull. - Encode —
ClonerEncoder(anAbstractEncoder) walks the object graph using the compiler-generated serializer. Every primitive value is appended to an in-memoryArrayDeque<Any?>(serializedValues). Nested objects and collections are encoded recursively into the same deque; collections store their size before their elements. Nullable values are marked with aBooleanmarker (truefor a present value,falsefornull), so aStringsuch as"NULL"or"!!"can never be confused with a marker. - Decode —
ClonerDecoder(anAbstractDecoder) reads that deque back. It pops values in the same order, reconstructs nested objects and collections, and returns a brand-new instance.elementsCounttracks how many elements belong to the current structure sodecodeElementIndex()can signalDECODE_DONEat the right point.
Because every primitive, nested object, and collection is recreated during decoding, the result is a true deep copy: the clone shares no mutable state with the original.
Convenience extensions are also available:
val copy = original.clone()
val copy2 = original.clone(serializersModule)The example below uses Person(name, Address(city, zip), tags) and shows how the
internal ArrayDeque is filled during encoding and emptied during decoding.
val original = Person("Ada", Address("Paris", 75000), mutableListOf("dev", "math"))
// ---------- ENCODING (fills the deque) ----------
// ClonerEncoder appends primitive components in traversal order:
// "Ada" -> ["Ada"]
// "Paris" -> ["Ada", "Paris"]
// 75000 -> ["Ada", "Paris", 75000]
// tags size 2 -> ["Ada", "Paris", 75000, 2]
// "dev" -> ["Ada", "Paris", 75000, 2, "dev"]
// "math" -> ["Ada", "Paris", 75000, 2, "dev", "math"]
//
// Final encoded deque:
// ["Ada", "Paris", 75000, 2, "dev", "math"]
val copy = Cloner.clone(original)
// ---------- DECODING (empties the deque) ----------
// ClonerDecoder pops values in the same order:
// pop "Ada" -> deque ["Paris", 75000, 2, "dev", "math"]
// pop "Paris" -> deque [75000, 2, "dev", "math"]
// pop 75000 -> deque [2, "dev", "math"]
// pop 2 -> collection size, deque ["dev", "math"]
// pop "dev" -> deque ["math"]
// pop "math" -> deque []
//
// Result: Person("Ada", Address("Paris", 75000), ["dev", "math"])
println(original === copy) // false
println(original.address === copy.address) // false
println(original.tags === copy.tags) // falseimport io.github.godox.cloner.Cloner
import kotlinx.serialization.Serializable
@Serializable
data class Person(val name: String, val age: Int, val tags: List<String> = emptyList())
fun main() {
val original = Person("Ada", 36, listOf("dev", "math"))
val copy = Cloner.clone(original) // deep copy
}Polymorphic values are supported by passing a SerializersModule:
val clone = Cloner.clone(value, serializersModule)To avoid configuring kotlinx-serialization manually, apply the provided plugin in your module:
plugins {
kotlin("multiplatform") // or kotlin("jvm")
id("io.github.godox.cloner") version "1.0.0"
}The plugin applies kotlin("plugin.serialization") and adds the
kotlinx-serialization-core dependency. You still annotate your classes with
@Serializable (or a @MetaSerializable marker).
The dependency configuration is configurable:
cloner {
dependencyConfiguration = "api" // default: "implementation"
// set to "" to disable adding the dependency automatically
}Measured on the JVM (single thread) by cloning a List<BenchItem> of the given
size 10 times and averaging. BenchItem holds an Int, a String and a
List<String> of 5 elements.
| Instances cloned | Cloner.clone (ms) | Data class copy (ms) |
|---|---|---|
| 10 | 0.2 | 0.0 |
| 100 | 0.8 | 0.1 |
| 1000 | 1.4 | 0.3 |
| 10000 | 6.0 | 3.1 |
The "Data class copy" column measures a hand-written deep copy using
copy() plus toMutableList() on the nested list. The benchmark lives in
commonTest (BenchmarkTest) and can be re-run with
./gradlew jvmTest --tests "io.github.godox.cloner.BenchmarkTest".
All Kotlin Multiplatform targets are enabled in build.gradle.kts:
- JVM
- JS (IR) — browser and Node.js
- Wasm (JS) — browser and Node.js
- Native: Linux (x64/arm64), Windows (mingwX64), macOS (x64/arm64), iOS (x64/arm64/simulator), tvOS, watchOS
Kotlin/Native compilation requires a supported host platform.