Entity Model

Any Kotlin data class can become a database entity. Karango wraps it with metadata (IDs, revisions) using the Storable<T> hierarchy — your data stays clean, the database details live in the wrapper.

Karango uses the Storable<T> hierarchy from the shared Vault module. This page covers the same types with ArangoDB-specific examples.

The core idea

Your data class is just data. ArangoDB metadata (_id, _key, _rev) lives in the wrapper, not in your class:

// Your data — no database concerns
@Vault
data class Person(val name: String, val age: Int)

// After inserting into ArangoDB:
val stored: Stored<Person> = repo.insert(Person("Alice", 30))

stored()      // Person(name="Alice", age=30) — your data
stored._id    // "persons/abc123" — database ID
stored._key   // "abc123" — document key
stored._rev   // "_abc123def" — revision for optimistic locking

The Storable hierarchy

Karango uses the Storable<T> sealed hierarchy from the shared Vault module. Three concrete types — New<T>, Stored<T>, and Ref<T> — represent different entity lifecycle states. Here is a quick example of the most common pattern:

// Load → modify → save
val person: Stored<Person> = repo.findById(id)!!

person().name  // "Alice" — access your data
person._id         // "persons/abc123" — database metadata

val updated = person.modify { it.copy(name = "Alice Smith") }
repo.save(updated)  // updated._id is still "persons/abc123"

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