capri/projection

Types

Builder

opaque </>

A projection definition awaiting its globally unique ETS table name.

pub opaque type Builder(record, key)

Error

</>

Projection construction, lifecycle, and lookup failures.

pub type Error {
  BuildFailed(reason: dynamic.Dynamic)
  StoreError(khepri_error.Error)
  RuntimeError(reason: dynamic.Dynamic)
  RepositoryMismatch(expected: String, actual: String)
  InvalidData(errors: List(decode.DecodeError))
  ProjectionUnavailable
  MultipleValues
  UnexpectedProjectionRows(rows: dynamic.Dynamic)
}

Constructors

```
BuildFailed(reason: dynamic.Dynamic)
```
```
StoreError(khepri_error.Error)
```
```
RuntimeError(reason: dynamic.Dynamic)
```

RepositoryMismatch(expected: String, actual: String)

InvalidData(errors: List(decode.DecodeError))

```
ProjectionUnavailable
```
```
MultipleValues
```

UnexpectedProjectionRows(rows: dynamic.Dynamic)

Projection

opaque </>

A typed, derived ETS view maintained by Khepri.

Projections are ephemeral caches, not authoritative repositories. They are immediately consistent on the writer and leader, and eventually consistent on other followers.

pub opaque type Projection(record, key)

Values

all

</>

pub fn all(
  projection: Projection(record, key),
  key: key,
) -> Result(List(record), Error)

Read and decode all repository records for a projection key.

This works for both set and bag projections. Missing keys return an empty list; an unavailable projection remains an explicit error.

get

</>

pub fn get(
  projection: Projection(record, key),
  key: key,
) -> Result(option.Option(record), Error)

Read exactly one projected repository record from the local ETS table.

Use all for bag projections. None means the key is absent; ProjectionUnavailable means the local table does not currently exist.

many

</>

pub fn many(
  builder: Builder(record, key),
) -> Builder(record, key)

Allow multiple repository records to share one projection key.

Bag projections are appropriate for one-to-many query views. Duplicate encoded records are coalesced according to ETS bag semantics.

named

</>

pub fn named(
  builder: Builder(record, key),
  name: atom.Atom,
) -> Result(Projection(record, key), Error)

Finish a projection definition with a bounded, globally unique atom.

Khepri uses this atom as a node-global named ETS table. Do not create names from unbounded or user-controlled input.

new

</>

pub fn new(
  repository: repository.Repository(record),
  extractor: fn(record) -> key,
) -> Builder(record, key)

Begin building a typed projection derived from a repository.

Khepri evaluates the extractor directly against decoded repository records.

rebuild

</>

pub fn rebuild(
  store: lifecycle.StoreHandle,
  prefix: repository.Prefix(record),
  projection: Projection(record, key),
) -> Result(Nil, Error)

Unregister and synchronously register a projection again.

This is intended for application startup and rebuilds the view from existing repository records. The projection table is briefly unavailable between the two commands.

register

</>

pub fn register(
  store: lifecycle.StoreHandle,
  prefix: repository.Prefix(record),
  projection: Projection(record, key),
) -> Result(Nil, Error)

Register a projection over every direct record beneath a repository prefix. Existing records are projected retroactively.

unregister

</>

pub fn unregister(
  store: lifecycle.StoreHandle,
  projection: Projection(record, key),
) -> Result(Nil, Error)

Idempotently unregister a projection and delete its local ETS table.