Chronicle.Captures (cratis_chronicle v3.16.1)

Idiomatic API for working with Chronicle captures.

Captures turn data that arrives from outside the event log into events appended to this event store. Declare one with use Chronicle.Captures.Capture (see its moduledoc for the DSL) and either register it with Chronicle.Client's captures: option (or otp_app: auto-discovery), or call the functions here directly.

Usage

{:ok, _} = Chronicle.Captures.register(MyApp.Captures.InvoiceCapture)
{:ok, _} = Chronicle.Captures.start(MyApp.Captures.InvoiceCapture)
{:ok, captures} = Chronicle.Captures.list()

Options

Every function accepts:

:client — the client name (default: Chronicle.Client)

Summary

Functions

captured_events(capture_name, opts \\ [])

Reads the private events a capture has appended, most recent first.

delete(capture, opts \\ [])

Deletes a capture, identified by its module or its capture id.

list(opts \\ [])

Lists every capture registered for the current event store.

register(capture, opts \\ [])

Registers (saves) a capture.

register_discovered(opts \\ [])

Registers every discoverable capture.

start(capture, opts \\ [])

Starts a capture, identified by its module or its capture id.

stop(capture, opts \\ [])

Stops a capture, identified by its module or its capture id.

validate(capture, opts \\ [])

Validates a capture declaration against the kernel's CDL compiler, without saving it.

Functions

captured_events(capture_name, opts \\ [])

@spec captured_events(String.t(), keyword()) :: {:ok, [map()]} | {:error, term()}

Reads the private events a capture has appended, most recent first.

delete(capture, opts \\ [])

@spec delete(module() | String.t(), keyword()) :: :ok | {:error, term()}

Deletes a capture, identified by its module or its capture id.

list(opts \\ [])

@spec list(keyword()) ::
  {:ok, [Chronicle.Captures.CaptureDetails.t()]} | {:error, term()}

Lists every capture registered for the current event store.

register(capture, opts \\ [])

@spec register(module(), keyword()) ::
  {:ok, Chronicle.Captures.CaptureDetails.t()} | {:error, term()}

Registers (saves) a capture.

capture is a module using Chronicle.Captures.Capture. Saving an already-started capture fails on the kernel; stop it first.

register_discovered(opts \\ [])

@spec register_discovered(keyword()) :: :ok | {:error, term()}

Registers every discoverable capture.

Idempotent: skips a capture whose declaration already matches the kernel's. Warns (rather than failing) before saving over a started capture whose declaration changed — saving a started capture stops it, so it comes back stopped. Starts a capture only when it declares start: true.

start(capture, opts \\ [])

@spec start(module() | String.t(), keyword()) :: :ok | {:error, term()}

Starts a capture, identified by its module or its capture id.

stop(capture, opts \\ [])

@spec stop(module() | String.t(), keyword()) :: :ok | {:error, term()}

Stops a capture, identified by its module or its capture id.

validate(capture, opts \\ [])

@spec validate(module() | String.t(), keyword()) ::
  {:ok, [String.t()]} | {:error, term()}

Validates a capture declaration against the kernel's CDL compiler, without saving it.

capture is either a module using Chronicle.Captures.Capture or raw CDL text.