capri: Type-safe, atomic Gleam bindings for Khepri, the modern distributed database for the BEAM

Capri introduces type-safe, atomic Gleam bindings for Khepri, a modern distributed database designed for the BEAM. The README focuses on the core concepts and safety model of these bindings. To use Capri, one must first initialize Khepri and create a StoreHandle via capri.init/2. This handle is employed for accessing and manipulating the Khepri store or cluster.

Repositories within this module represent the persistence layer for terms, as outlined in Domain-Driven Design. However, unlike traditional Active Record patterns, Gleam does not support "active" Records, thus repositories are used instead.

To define a repository, capri.repository/3 can be utilized, and to open or create it for a specific store, capri.bind/3 is employed. The binding process involves validating the repository identity and version against the stored metadata at the prefix. The resultant typed prefix and child paths utilize the repository capability for decoding and validating records.

Migrations are an integral part of this system, being both atomic, versioned, and reversible transformations of data and schema. Each migration includes a decoder for its target version, ensuring that schema changes occur in synchronization. It is essential that every migration increments the repository version by exactly one. Although unsafe migrations (irreversible changes) can be created, it is strongly recommended to avoid them.

Projections within Capri are typed views of the data, maintained in local ETS tables by Khepri. They serve as ephemeral caches rather than authoritative repository state. The default projection type allows fetching a sole value from a set projection via projection.get/2 and creating a bag projection with projection.many/1, which enables multiple records to share a key. To query for values, one can use projection.all/2.

To join a cluster, capri.reset_and_join_cluster/2 or capri.reset_local_member/1 can be used. These functions erase local data, allowing the system to connect to other Khepri instances. The name Capri has a phonetic similarity to Capri, a type of pants, and the pun plays a role in naming the bindings for Khepri. Capri is licensed under the GNU Affero General Public License, version 3, or any later version, ensuring that the software is free for redistribution and modification, although without any warranty.