Macro for defining Chronicle declarative projections.

A declarative projection is a standalone module that defines how events map onto a read model. Unlike model-bound projections — where from declarations live directly inside the read model module — a declarative projection keeps the read model as a pure data structure while the projection logic lives in a separate module.

Quick Example

defmodule MyApp.Projections.AccountSummaryProjection do
  use Chronicle.Projections.Projection, model: MyApp.ReadModels.AccountSummary

  from MyApp.Events.AccountOpened,
    set: [
      account_id: :event_source_id,
      owner_name: :owner_name,
      balance: :initial_balance
    ]

  from MyApp.Events.FundsDeposited,
    add: [balance: :amount]

  from MyApp.Events.FundsWithdrawn,
    subtract: [balance: :amount]
end

The read model (AccountSummary) is a plain struct using use Chronicle.ReadModels.ReadModel with no from declarations — it is a pure data shape, not a projection definition.

Options

• :model — (required) the read model module this projection writes into.
• :id — identifier string for this projection. Defaults to the last segment of the module name (e.g. "AccountSummaryProjection"). A defaulted id (pin it explicitly to silence this) emits a one-time warning when discovered — see Chronicle.Discovery.DefaultedIdWarning.
• :passive — when true, the projection does not actively observe events and never writes to a materialized sink; its read model is resolved on demand via immediate projection when looked up by id. Defaults to false.

Projection Macros

The following macros are available and carry the same options as their counterparts in Chronicle.ReadModels.ReadModel:

• from/1, from/2 — maps properties from an event onto the read model.
• join/2 — joins a secondary event onto the model by a matching field.
• removed_with/1, removed_with/2 — removes the model instance when the given event occurs.
• removed_with_join/1, removed_with_join/2 — removes the model instance when a secondary event matches it by a property instead of by its own key.
• clear_with/2, clear_with/3 — sets a field back to no value; sugar for from event, clear: [...].
• from_every/1 — applies property mappings on every event, regardless of type.
• variant_of/2 — declares this projection to be one of several mutually exclusive representations of the same logical entity. See Chronicle.ReadModels.ReadModel.
• enters_on/1, enters_on/2 — names the event(s) that may create or resurrect this variant.

Registering with Chronicle.Client

{Chronicle.Client,
  ...
  projections: [MyApp.Projections.AccountSummaryProjection]}

Or use otp_app: auto-discovery — modules that export __chronicle_projection__/1 are discovered automatically.

Introspection

MyApp.Projections.AccountSummaryProjection.__chronicle_projection__(:id)
MyApp.Projections.AccountSummaryProjection.__chronicle_projection__(:id_source)
MyApp.Projections.AccountSummaryProjection.__chronicle_projection__(:model)
MyApp.Projections.AccountSummaryProjection.__chronicle_projection__(:from)
MyApp.Projections.AccountSummaryProjection.__chronicle_projection__(:join)
MyApp.Projections.AccountSummaryProjection.__chronicle_projection__(:removed_with)
MyApp.Projections.AccountSummaryProjection.__chronicle_projection__(:from_every)