Maryk: Kotlin Multiplatform Data Modeling and Storage

Maryk lets you define a strongly typed data model once, then use that same model for validation, serialization, querying, storage, tooling, and sync across Kotlin Multiplatform targets.

Use Maryk when you want:

• One schema shared by clients, servers, tools, and tests.
• Stable binary-compatible property indexes instead of reflection-heavy runtime mapping.
• Version-aware storage: historic reads, change queries, update streams, and efficient sync.
• Typed queries and mutations, atomic change sets, and serializable transaction scopes over the same models.
• One request API across in-memory, browser IndexedDB, embedded RocksDB, distributed FoundationDB, and remote stores.
• Portable JSON, YAML, and ProtoBuf serialization built from the same model definitions.

Maryk is a good fit for local-first apps, cross-platform products, Kotlin-heavy backends, tools that need typed data files, and systems where schema evolution and incremental sync matter.

Start with the website for the best reading path. Source docs live in this repository and the website is maintained in website/.

Use the typed request API as your main API for application reads, writes, history, and sync. SQL is an optional layer for reporting, ad hoc queries, and tabular integrations; it is not required to use Maryk stores.

Getting Started

These docs describe the current source branch. When using a published artifact, read the matching release tag and use the same version for every Maryk module.

Add the core dependency:

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.maryk:maryk-core:<maryk-version>")
}

Define a model:

import maryk.core.models.RootDataModel
import maryk.core.properties.definitions.date
import maryk.core.properties.definitions.string
import kotlinx.datetime.LocalDate

object Person : RootDataModel<Person>() {
    val firstName by string(index = 1u)
    val lastName by string(index = 2u)
    val dateOfBirth by date(index = 3u)
}

val johnSmith = Person.create {
    firstName with "John"
    lastName with "Smith"
    dateOfBirth with LocalDate(2017, 12, 5)
}

Person.validate(johnSmith)

val json = Person.Serializer.writeJson(johnSmith, pretty = true)
val fromJson = Person.Serializer.readJson(json)

For a complete model → store → query flow, read Getting Started or First Store Tutorial.

Storage Engines

• Memory: in-memory, non-persistent, best for tests and fast local feedback.
• IndexedDB: persistent browser storage for JS and WasmJS apps.
• RocksDB: embedded persistent storage for desktop, mobile, and single-node server use.
• FoundationDB: distributed transactional storage on supported platforms with libfdb_c.
• Remote Store: expose a local Maryk store over HTTP and optionally SSH-tunnel it.

See store/README.md for the decision guide.

Platform Support

Maryk is Kotlin Multiplatform. Platform support depends on the module:

• Core modeling, validation, querying, SQL, JSON/YAML serialization, generator support, Memory Store, shared store logic, test models, and test helpers target JVM, Android, JS, WasmJS, Linux x64 and ARM64, Windows, iOS, macOS, watchOS, tvOS, and Android Native.
• IndexedDB Store targets JS browser and WasmJS browser for persistent browser storage.
• File IO targets JVM, Linux x64 and ARM64, Windows, iOS, macOS, watchOS, tvOS, and Android Native.
• RocksDB Store targets JVM, Android, Linux x64 and ARM64, Windows, iOS, macOS, watchOS, tvOS, and Android Native through the rocksdb-multiplatform bindings.
• FoundationDB Store targets JVM, Linux x64 and ARM64, and macOS where the FoundationDB client library (libfdb_c) is available.
• Remote Store targets JVM, Linux x64 and ARM64, and macOS.
• CLI native binaries target Linux x64 and macOS, with JVM execution also available.
• The desktop App runs on the JVM.

Documentation Map

• Core – Data models, property types, keys, queries, versioning, serialization.
• Library – Shared utilities for things like Strings and ByteArrays.
• File – Minimal cross-platform file IO layer used by tooling and stores.
• SQL (optional) – Bounded SQL queries and mutations for reporting, ad hoc queries, and tabular integrations.
• JSON & YAML – Streaming parsers and writers.
• Generator – Code generation from YAML and JSON models.
• Test Library – Testing utilities and helpers.
• CLI – Interactive terminal client for browsing and editing stores.
• App – Desktop UI for browsing and editing stores.
• Stores:
  • Shared – Shared logic for building stores.
  • Memory – In-memory store (non-persistent).
  • IndexedDB – Persistent browser store for JS and WasmJS.
  • RocksDB – Persistent, high-performance store.
  • FoundationDB – Persistent, scalable transactional store (multiplatform where libfdb_c is available).
  • Remote – HTTP/SSH gateway and client for remote access.
  • Tests – Common tests to ensure store reliability.

Repository Development

Requires JDK 21. Confirm with java -version before running Gradle.

Useful commands:

./gradlew jvmTest
./gradlew :store:memory:jvmTest
./gradlew :cli:jvmTest
cd website && yarn build

When editing website pages generated from repository docs, update the source file listed in website/README.md.

Contributing

Issues, discussions, docs fixes, examples, store improvements, and PRs are welcome. Good first contributions usually live in docs, examples, tests, CLI/App workflows, or store-specific edge cases.