GhostSerialization
1.2.3indexedHigh-performance, zero-reflection JSON serializer generating optimized zero-copy byte serializers via compile-time code generation; thread-safe registry, null-safety and memory/DoS safeguards, prewarm.
High-performance, zero-reflection JSON serializer generating optimized zero-copy byte serializers via compile-time code generation; thread-safe registry, null-safety and memory/DoS safeguards, prewarm.
JSON at the speed of bits — Byte-first serialization for Kotlin Multiplatform.
⚡ Bitwise O(1) field matching · Native reader per input format · Up to 6–32× less heap · Zero reflection · 825/825 tests passed
👉 Try the Interactive Demo →
|
📦 Maven Central → · 1.2.4
Ghost generates all serialization code at compile time via KSP — and then goes several steps further:
Result on a real Twitter-like payload vs KotlinX Serialization:
▶️ Watch the Demo Video (docs/ghost.mp4) →
Real benchmark on Android vs KotlinX Serialization — running in the
ghost-sampleCompose Multiplatform app.
ktor-ghost achieving +66% throughput and 50% RAM reduction vs standard Ktor.# gradle/libs.versions.toml
[versions]
ghost = "1.2.4"
ksp = "2.1.10-1.0.31"
[libraries]
ghost-api = { module = "com.ghostserializer:ghost-api", version.ref = "ghost" }
ghost-serialization = { module = "com.ghostserializer:ghost-serialization", version.ref = "ghost" }
ghost-compiler = { module = "com.ghostserializer:ghost-compiler", version.ref = }
// build.gradle.kts
plugins {
id("com.google.devtools.ksp") version "2.1.10-1.0.31"
id("com.ghostserializer.ghost") version "1.2.4"
}
@GhostSerialization
data class User(val id: Long, val name: String, val email: String)
val user: User = Ghost.deserialize(responseBytes) // ByteArray — fastest path
val json: String = Ghost.encodeToString(user)
Ghost uses three reader types and two writer types, all generated by KSP:
Ghost.deserialize<User>(bytes: ByteArray)
└─ GhostJsonFlatReader ← zero alloc, bitwise trie field match
Ghost.deserialize<User>(json: String)
└─ GhostJsonStringReader ← native char[] scan, no encodeToByteArray
Ghost.deserializeStreaming<User>(source: BufferedSource)
└─ GhostJsonReader ← O(1) memory regardless of payload size
Ghost.encodeToBytes(user) → GhostJsonFlatWriter (pre-encoded headers, thread-local pool)
Ghost.encodeToString(user) → FlatCharArrayWriter (pooled, platform-tuned warm capacity)
All paths are fully monomorphic — the JIT compiles them to near-native throughput after warmup.
For a deep dive into the compiler plugin, thread-local buffer pool mechanics, and fast parsing architecture, see the Architecture Guide →.
git clone https://github.com/juanchurtado1991/GhostSerialization.git
./gradlew ciTestJvm # JVM modules (Linux / macOS / Windows)
./gradlew ciTest # + Android unit tests; + iOS on macOS
| Requirement | Version |
|---|---|
| JDK | 17 |
| Kotlin / KSP |
→ Full contributing guide → — dev environment, adding test modules, benchmarks, PR checklist.
See CHANGELOG.md for version history.
Developed with ❤️ by the Ghost Serializer team. 👻
| Technique | What it means |
|---|
| Bitwise O(1) trie field matching | No string comparison, no heap allocation per field |
Long bitmask for required fields | Checking all required fields = one CPU instruction |
| Dedicated reader per input format | ByteArray, Okio stream, String — no cross-format conversion |
| Thread-local reader/writer pools | Zero GC pressure in steady state |
| KSP2 + Kotlin 2.1.10 | Fastest incremental builds, strict compile-time safety |
| Throughput | Memory |
|---|
| Decode (String) | +26.7% faster | −69.6% heap |
| Decode (Bytes) | +71.9% faster | −84.4% heap |
| Decode (Streaming) | +78.8% faster | −30.7% heap |
| Encode (String) | +39.5% faster | +10.5% heap |
| Encode (Bytes) | +80.5% faster | −81.0% heap |
| Encode (Streaming) | +49.0% faster | −6.2% heap |
| Guide | Platform / Category | Description |
|---|
| Installation | ![]() | Version catalog, repositories, KSP setup, ghost.textChannel opt-in |
| Usage — Android | ![]() | Gradle plugin, Retrofit, Resilience, Custom Decoders |
| Usage — KMP | ![]() | Shared module, Ktor, Sealed classes, Structural Transformations |
| Usage — iOS / Swift | ![]() | XCFramework export, Bridge setup, Alamofire integration |
| Usage — Spring Boot | ![]() | Auto-config, MVC + WebFlux, @GhostStrict, @GhostCoerce |
| Advanced Features | ![]() | Byte-first, @GhostFlatten, @GhostWrap, Contextual Serializers, Platform limits |
| Architecture | ![]() | Compiler pipeline, buffer pool mechanics, O(1) bitwise field matching |
| Benchmarks | ![]() | Full results, run instructions, JIT log analysis |
| Contributing | ![]() | Dev environment, test modules, PR checklist, supported platforms |
| Project | Description |
|---|
| ghost-sample (this repo) | KMP Compose benchmark app — Android, Desktop JVM, iOS |
| ghost-android-test-app | Standalone Android app — on-device benchmark |
| ghost-ios-test-app | Standalone iOS app — Xcode + XCFramework |
| ghost-spring-boot-test-app | Spring Boot WebFlux dashboard + benchmark.py |
| 2.1.10 / 2.1.10-1.0.31 |
| Android SDK | API 36 (for unit tests) |
Surfaced from shared tags and platforms — no rankings paid for.