README.md

Maryk: Cross-Platform Data Modeling and Storage

Maryk is a Kotlin Multiplatform framework for defining, validating, serializing, and storing data models consistently across multiple platforms, including iOS, macOS, Linux, Windows, Android, JVM, and JavaScript. With a fully version-aware data store and flexible querying, Maryk makes it easy to maintain complex data structures while ensuring backward compatibility and efficient data handling.

The RocksDB persistence layer is available for the JVM, iOS, macOS, Android and Linux.

Key Features

• Unified Data Modeling: Define your data models once and use them everywhere, ensuring a single source of truth across platforms.

• Flexible Property Types and Inheritance: Create models with a variety of property types, and reuse model structures to build complex data hierarchies.

• Built-in Validation: Enforce data quality with validations such as required fields, uniqueness, min/max constraints, and regex checks.

• Cross-Platform Serialization: Seamlessly serialize and deserialize data as JSON, YAML, or Protocol Buffers, facilitating easy communication between clients and services.

• Model Serialization & Compatibility: Serialize your schemas themselves and run compatibility checks across different clients, ensuring smooth upgrades and migrations.

• Version-Aware Storage and Queries: Store data in NoSQL data stores (in-memory/RocksDB/HBase) and leverage versioning to request historical states, compare past values, and minimize bandwidth by fetching only changed fields.

• Data Aggregations & Insights: Perform aggregations (count, sum, average, min/max, grouped by time intervals or enums) for richer analytics and decision-making.

Getting Started

1. Add Maryk Core Dependency:
   In your build.gradle.kts:

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

2. Define Your Data Models:
   Create a Kotlin data model:

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

3. Create and Validate Instances:

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

// Validate the object
Person.validate(johnSmith)

4. Serialize Your Data Objects:

// Serialize to JSON
val json = Person.writeJson(johnSmith)

// Deserialize from JSON
val personFromJson = Person.readJson(json)

5. Choose a Data Store:

• In-memory store (non-persistent, suitable for testing)
• RocksDB-based store (persistent, efficient for local storage)
• HBase-based store (persistent and scalable store)

Documentation

For detailed information, check out:

• Core – Data models, queries, parsers, readers.
• Library – Shared utilities for things like Strings and ByteArrays.
• JSON & YAML – Streaming parsers and writers.
• Generator – Code generation from YAML and JSON models.
• Test Library – Testing utilities and helpers.
• DataFrame Integration – DataFrame helper functions for Maryk objects.
• Stores:
  • Shared – Shared logic for building stores.
  • Memory – In-memory store (non-persistent).
  • RocksDB – Persistent, high-performance store.
  • HBase – Persistent, scalabable high-performance store.
  • Tests – Common tests to ensure store reliability.

Contributing

We welcome contributions through feature requests, issue reports, and pull requests.

Your involvement helps Maryk grow and improve!