class

Sepia::EventLogger

Main event logger that manages event logging operations.

This class provides the main interface for event logging in Sepia. It manages the active backend and provides convenience methods for common operations.

Class methods

append_event(object : Serializable | Container, event_type : LogEventType, generation : Int32, metadata)

Append an event to the log using the current backend.

This is the main entry point for event logging. It delegates to the configured backend after checking if logging is enabled.

Parameters

object : The Sepia object the event relates to
event_type : Type of event (Created, Updated, Deleted)
generation : Object generation number
metadata : Optional metadata for the event

Example

Sepia::EventLogger.append_event(document, LogEventType::Updated, 2, {"user" => "alice"})

Source

backend

The current event logging backend.

Defaults to PerFileEventLogger, but can be changed to support different storage strategies.

Source

backend=(backend : EventLoggerBackend)

The current event logging backend.

Defaults to PerFileEventLogger, but can be changed to support different storage strategies.

Source

configure(backend : EventLoggerBackend)

Configure the event logging backend.

Parameters

backend : The backend instance to use for event logging

Example

# Use per-file logging (default)
Sepia::EventLogger.configure(PerFileEventLogger.new("./data"))

# Use global logging (future feature)
Sepia::EventLogger.configure(GlobalEventLogger.new("./data/events.jsonl"))

Source

current_generation(object_class : Class, id : String) : Int32

Get the current generation for an object.

This determines what generation number should be used for activity events. It looks at the most recent save event (Created or Updated) to determine the current generation of the object.

Parameters

object_class : The class of the object
id : The object's unique identifier

Returns

The current generation number for the object, or 0 if no save events exist

Example

current_gen = Sepia::EventLogger.current_generation(MyDocument, "doc-123")

Source

last_event(object_class : Class, id : String) : LogEvent | Nil

Get the last event for a specific object.

Convenience method that returns only the most recent event.

Parameters

object_class : The class of the object
id : The object's unique identifier

Returns

The last event for the object, or nil if no events exist

Example

last_event = Sepia::EventLogger.last_event(MyDocument, "doc-123")
if last_event
  puts "Last modified: #{last_event.timestamp}"
end

Source

next_generation(object_class : Class, id : String) : Int32

Get the next generation number for an object.

This method reads the existing events for an object and determines what the next generation number should be based on the last event.

Parameters

object_class : The class of the object
id : The object's unique identifier

Returns

The next generation number (1 for new objects, existing+1 for updates)

Example

next_gen = Sepia::EventLogger.next_generation(MyDocument, "doc-123")
puts "Next generation: #{next_gen}"

Source

read_events(object_class : Class, id : String) : Array(LogEvent)

Read all events for a specific object using the current backend.

Parameters

object_class : The class of the object
id : The object's unique identifier

Returns

Array of events for the specified object, ordered by timestamp

Example

events = Sepia::EventLogger.read_events(MyDocument, "doc-123")
events.each { |event| puts "#{event.timestamp}: #{event.event_type}" }

Source

reset_backend

Reset the event logging backend to a fresh instance.

This is useful in tests when you want to ensure a clean backend that points to the current storage backend.

Source

should_log?(klass : Class) : Bool

Check if event logging is enabled for a class.

Delegates to the current backend's should_log? method.

Parameters

klass : The class to check

Returns

True if events should be logged for this class

Source