Entity Model

Your data classes stay clean. Database metadata lives in wrappers.

Monko uses the same entity model as Karango — the Storable<T> hierarchy from the shared Vault module. This means you can switch between MongoDB and ArangoDB without changing your domain classes.

For the complete Storable reference — including New<T>, Stored<T>, Ref<T>, type conversions, identity comparisons, and type-safe casting — see the Vault: Storable Hierarchy page.

Defining entities

Annotate with @Vault. Your data class contains only domain fields. The wrapper adds _id, _key, and _rev.

@Vault
data class Person(
    val name: String,
    val age: Int,
    val email: String,
    val address: Address = Address(),
)

@Vault
data class Address(
    val city: String = "",
    val zip: String = "",
    val country: String = "",
)

Working with Stored

val stored: Stored<Person> = repo.insert("key-1", Person("Alice", 30, "alice@example.com"))

// Access metadata
stored._id      // "persons/key-1"
stored._key     // "key-1"
stored()        // Person(name="Alice", age=30, ...)

// Modify (creates new Stored with same metadata)
val updated = stored.modify { copy(age = 31) }
repo.save(updated)

// Transform to a different type
val nameOnly = stored.transform { it.name }  // Stored<String>

// Identity checks
stored.hasSameIdAs(other)
stored.hasIdIn(listOf(other1, other2))

MongoDB document IDs

Monko generates MongoDB document IDs as follows:

• If you provide a key via insert(key, value), the document gets _id = "collection/key"
• If no key is provided, Monko generates an ObjectId and converts it to a hex string
• The _key is always the portion after the slash in _id