@spec all_events(evented_schema(), Ecto.UUID.t()) :: [struct()]

Returns all events for a record from the beginning.

Events are returned in insertion order.

Example

events = Spector.all_events(MyApp.User, user_id)

@spec bringup(evented_schema(), bringup_opts()) :: {:ok, [evented_struct()]}

Import existing database records into the event log.

Reads all rows from the schema's table and migrates each to Spector management: deletes the original record and creates a new one with a UUIDv7 ID and corresponding event. The entire operation runs in a single transaction.

Records that are already tracked by Spector (have existing events) are skipped.

Options

• :action - The action to use for the event (default: :insert). Use a custom action like :import to trigger different changeset behavior during migration.

• :attr_fn - A function that takes a record and returns the attributes map to insert (default: extracts all schema fields except the primary key). Use this to transform or augment data during migration.

• :transfer - A function that receives the old record and the new record before the old record is deleted. Use this to update associations or perform other transfer operations (default: no-op).

Returns {:ok, [struct]} on success or {:error, reason} on failure.

Timestamps

By default, bringup creates new records, so inserted_at and updated_at timestamps will be set to the current time. To preserve original timestamps from the source records, include them in the attr_fn and ensure your changeset accepts them.

If you don't want your regular changeset to accept timestamp fields, use a custom action like :import to handle them separately:

# Register :import as a custom action
use Spector.Evented, events: MyApp.Events, actions: [:import]

# Handle :import with timestamp support
def changeset(changeset, attrs) when changeset.action == :import do
  changeset
  |> cast(attrs, [:name, :inserted_at, :updated_at])
  |> validate_required([:name])
end

# Regular changeset doesn't accept timestamps
def changeset(changeset, attrs) do
  changeset
  |> cast(attrs, [:name])
  |> validate_required([:name])
end

# Pass timestamps in attr_fn
attr_fn = fn record ->
  %{name: record.name, inserted_at: record.inserted_at, updated_at: record.updated_at}
end

{:ok, users} = Spector.bringup(MyApp.User, action: :import, attr_fn: attr_fn)

Examples

Basic usage migrates all untracked records (timestamps reset to now):

{:ok, users} = Spector.bringup(MyApp.User)

Use a custom attr_fn to transform data during migration:

{:ok, users} = Spector.bringup(MyApp.User, attr_fn: fn record ->
  %{
    name: String.upcase(record.name),
    value: record.value || 0  # provide defaults for nil values
  }
end)

Use a transfer function to update associations before the old record is deleted:

{:ok, users} = Spector.bringup(MyApp.User, transfer: fn old, new ->
  Repo.update_all(
    from(p in Post, where: p.user_id == ^old.id),
    set: [user_id: new.id]
  )
end)

@spec changeset_put_event_id(Ecto.Changeset.t(), attrs(), atom()) ::
  Ecto.Changeset.t()

Assigns the current event ID to a changeset field.

When Spector calls your changeset/2 function, it includes an :__event_id__ key in the attrs map. This function extracts that ID and assigns it to the specified field in your changeset.

This is useful for embedded schemas and {:array, :map} rollup records where you want each record to have a unique ID that matches its creation event.

Parameters

• changeset - The changeset to modify
• attrs - The attrs map passed to changeset/2 (contains :__event_id__)
• field - The field to assign the event ID to (default: :id)

Example

def changeset(message, attrs) do
  message
  |> Ecto.Changeset.cast(attrs, [:content, :role])
  |> Spector.changeset_put_event_id(attrs)
  |> Ecto.Changeset.validate_required([:id, :content, :role])
end

@spec delete(evented_struct()) ::
  {:ok, evented_struct()} | {:error, Ecto.Changeset.t()}

Delete a record, creating a delete event in the event log.

Returns {:ok, struct} on success or {:error, changeset} on failure.

The delete event is recorded in the event log before the record is removed from the database, providing a complete audit trail.

Example

{:ok, user} = Spector.delete(user)

@spec execute(evented_struct(), action(), attrs()) ::
  {:ok, evented_struct()} | {:error, Ecto.Changeset.t()}

Execute an action on a record, creating an event in the event log.

This is the general-purpose function for applying any action to a record, including custom actions defined in the schema's :actions option.

Returns {:ok, struct} on success or {:error, changeset} on failure.

The function rolls forward from the event log to reconstruct current state, applies the action through the schema's changeset/2 function, and records the new event.

Example

# Using a custom :archive action
{:ok, item} = Spector.execute(item, :archive, %{archived_at: DateTime.utc_now()})

# The :update action (same as Spector.update/2)
{:ok, user} = Spector.execute(user, :update, %{name: "New Name"})

@spec fetch_attr(attrs(), atom()) :: {:ok, any()} | :error

Fetches a field from attrs, checking both atom and string keys.

Returns {:ok, value} if the key exists, or :error if not found.

This is useful in changesets where attrs may come with string keys (from JSON) or atom keys (from internal calls).

Example

def changeset(record, attrs) do
  case Spector.fetch_attr(attrs, :parent_id) do
    {:ok, parent_id} -> # handle parent_id
    :error -> # no parent_id provided
  end
end

@spec fetch_attr!(attrs(), atom()) :: any()

Fetches a field from attrs, checking both atom and string keys.

Returns the value if the key exists, or raises KeyError if not found.

Example

def changeset(record, attrs) do
  parent_id = Spector.fetch_attr!(attrs, :parent_id)
  # use parent_id
end

@spec get(evented_schema(), String.t()) :: evented_struct() | nil

Retrieve the current state of a record by replaying its events.

Returns the struct if found, or nil if no events exist for the given ID.

This is useful for embedded schemas (without database tables) or when you want to reconstruct state purely from the event log.

Example

user = Spector.get(MyApp.User, "019ac640-dfc0-7407-8238-39a9c45e8813")

@spec get_attr(attrs(), atom(), any()) :: any()

Gets a field from attrs, checking both atom and string keys.

Returns the value if the key exists, or default if not found.

Example

def changeset(record, attrs) do
  parent_id = Spector.get_attr(attrs, :parent_id, nil)
  # use parent_id, which may be nil
end

@spec insert(evented_schema(), attrs(), action()) ::
  {:ok, evented_struct()} | {:error, Ecto.Changeset.t()}

Insert a new record, creating an event in the event log.

Returns {:ok, struct} on success or {:error, changeset} on failure.

Example

{:ok, user} = Spector.insert(MyApp.User, %{name: "Alice", email: "alice@example.com"})

The inserted struct will have a new UUIDv7 id assigned.

Returns all events up to and including the given event.

Events are returned in insertion order. The specified event is included as the last element in the result.

Example

events = Spector.previous_events(event)

@spec recent_events(evented_schema(), Ecto.UUID.t()) :: [struct()]

Returns events starting from the most recent savepoint.

If no savepoint exists, returns all events from the beginning. The savepoint event itself is included as the first element.

Events are returned in insertion order.

Use of this function over all_events/2 is preferable; if the schema does not support savepoints, the two functions behave identically.

Example

events = Spector.recent_events(MyApp.User, user_id)

Create a savepoint event capturing the current state of a record.

Returns {:ok, struct} on success or raises on failure.

Savepoints store the complete state of a record at a point in time, allowing event replay to start from the savepoint instead of replaying all events from the beginning. This is useful for records with long event histories.

The schema must implement the savepoint/2 callback to define how the current state is converted to an attrs map:

@behaviour Spector.Evented

@impl true
def savepoint(record, _version) do
  %{name: record.name, email: record.email}
end

Forms

There are two ways to create a savepoint:

From a record (savepoint/1)

Pass the record directly. This verifies that the record matches the current state in the event log (replayed events must produce the same field values). This guards against creating savepoints from stale records:

{:ok, user} = Spector.savepoint(user)

If the record is stale (e.g., another process updated it), this raises an error.

From schema and ID (savepoint/2)

Pass the schema module and record ID. This replays events to determine current state without verification:

{:ok, user} = Spector.savepoint(MyApp.User, user_id)

Use this form when you don't have the record in memory or don't need stale record detection.

@spec update(evented_struct(), attrs()) ::
  {:ok, evented_struct()} | {:error, Ecto.Changeset.t()}

Update an existing record, creating an event in the event log.

This is a convenience function that calls execute(record, :update, attrs).

Returns {:ok, struct} on success or {:error, changeset} on failure.

Example

{:ok, user} = Spector.update(user, %{name: "Alice Smith"})