rails_simple_event_sourcing 1.0.5 → 1.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d30476e9eae518afc83f79c53c821eed02ca3029de688ec4431fa12b0b1838ac
-  data.tar.gz: 6ae993b5cc5ec4288909560b2983b24e7786fd237249bd1737e56b64b56c1323
+  metadata.gz: 9415504de52817629c90a90ad0fff708ad8f829c768ed88485b8eae53f241c18
+  data.tar.gz: 2344f7a06e5c3b9dca5d0b6c98b1526ad73088c59cde9a0c64f2b5cb6a227ec6
 SHA512:
-  metadata.gz: 1d00b4ec0df1f3a08f089e2ed307fc638cfbe92f7c7a5f6c54b48c3a02ed065e00aa8e0ceb421302ed2daaad6883281c6606caa7a45b88683cb9f9ce57fbf8c2
-  data.tar.gz: fa7af20a15464beaf0cc0722cf342fc8ca96b84c9fde7c581ef8b53a0eb7ce360bc5b857be870b4cc45001595743310870803f28d526ca127159be1ec86c2e2d
+  metadata.gz: 3f2ec958c3dab2f9b398ed1bd0bfddec38fb13c720762ab57cc45c59091d9116f07af133601a19dae083ba5c40b32177cbfaa4809cb6af1a37cf569ed941693d
+  data.tar.gz: 32b8d673ca804d1ef03e5e55a561011fd052d70789afc078b9f8c7becff373d310bb2d24da411e6fc8a2fa869720a3aad487fbc4a93c5290cc2ce9a4f4d81c4d

data/README.md

@@ -21,6 +21,7 @@ If you need a more comprehensive solution, check out:
   - [Update and Delete Operations](#update-and-delete-operations)
   - [Metadata Tracking](#metadata-tracking)
   - [Event Querying](#event-querying)
+  - [Events Viewer](#events-viewer)
 - [Testing](#testing)
 - [Limitations](#limitations)
 - [Troubleshooting](#troubleshooting)
@@ -38,6 +39,7 @@ If you need a more comprehensive solution, check out:
 - **Command Handler Registry** - Explicit command-to-handler mapping with fallback to convention
 - **Simple Command Pattern** - Clear command → handler → event flow
 - **PostgreSQL JSONB Storage** - Efficient JSON storage for event payloads and metadata
+- **Built-in Events Viewer** - Web UI for browsing, searching, and inspecting events
 - **Minimal Configuration** - Convention over configuration approach
 
 ## Requirements
@@ -86,6 +88,9 @@ RailsSimpleEventSourcing.configure do |config|
   # When true, falls back to convention-based handler resolution
   # When false, requires explicit registration of all handlers
   config.use_naming_convention_fallback = true
+
+  # Number of events displayed per page in the Events Viewer (defaults to 25)
+  config.events_per_page = 50
 end
 ```
 
@@ -462,6 +467,25 @@ customer.events.where(created_at: 1.week.ago..Time.now)
 RailsSimpleEventSourcing::Event.where(eventable_type: "Customer", eventable_id: 1)
 ```
 
+**Reconstructing Aggregate State:**
+
+You can reconstruct the aggregate state as it was at any point in time by calling `aggregate_state` on an event. This replays all events for that aggregate up to and including the given event's version, returning the resulting attributes. This is useful for debugging, auditing, or understanding how an aggregate evolved over time.
+
+```ruby
+event = customer.events.last
+event.aggregate_state
+# => {"id"=>1, "first_name"=>"John", "last_name"=>"Doe", "email"=>"john@example.com", ...}
+
+# Compare state at different points in time
+first_event = customer.events.first
+first_event.aggregate_state
+# => {"id"=>1, "first_name"=>"John", "last_name"=>"Doe", ...}
+
+latest_event = customer.events.last
+latest_event.aggregate_state
+# => {"id"=>1, "first_name"=>"Jane", "last_name"=>"Smith", ...}
+```
+
 **Event Structure:**
 - `payload` - Contains the event attributes you defined (as JSON)
 - `metadata` - Contains request context (request ID, IP, user agent, params)
@@ -514,6 +538,58 @@ end
 **Metadata Outside HTTP Requests:**
 When events are created outside HTTP requests (background jobs, console, tests), metadata will be empty unless you manually set it using `CurrentRequest.metadata = {...}`.
 
+### Events Viewer
+
+The gem ships with a built-in web UI for browsing and inspecting your event log. It is mounted as a Rails engine.
+
+**Setup:**
+
+Mount the engine in your `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount RailsSimpleEventSourcing::Engine, at: "/event-store"
+end
+```
+
+Then navigate to `/event-store` in your browser to access the viewer.
+
+**Password Protection:**
+
+In production you will likely want to restrict access to the events viewer.
+
+*Using Rack::Auth::Basic middleware:*
+
+```ruby
+Rails.application.routes.draw do
+  mount Rack::Auth::Basic.new(
+    RailsSimpleEventSourcing::Engine,
+    "Event Store"
+  ) { |username, password|
+    ActiveSupport::SecurityUtils.secure_compare(username, "admin") &
+    ActiveSupport::SecurityUtils.secure_compare(password, Rails.application.credentials.event_sourcing_password || "secret")
+  }, at: "/event-store"
+end
+```
+
+*Using Devise authentication:*
+
+```ruby
+Rails.application.routes.draw do
+  authenticate :user, ->(user) { user.admin? } do
+    mount RailsSimpleEventSourcing::Engine, at: "/event-store"
+  end
+end
+```
+
+**Features:**
+
+- **Event list** - Paginated table of all events sorted by newest first, showing event type, aggregate, aggregate ID, version, and timestamp
+- **Event detail** - Click any event to view its full payload, metadata, and the reconstructed aggregate state at that version
+- **Version navigation** - Navigate between previous/next versions of the same aggregate from the detail page
+- **Filtering** - Filter events by event type or aggregate type using dropdown selectors
+- **Search** - Search by aggregate ID, or use `key:value` syntax to search within payload and metadata (e.g., `email:john@example.com`)
+
 ### Model Configuration
 
 Models that use event sourcing should include the `RailsSimpleEventSourcing::Events` module:

data/app/controllers/rails_simple_event_sourcing/application_controller.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/rails_simple_event_sourcing/events_controller.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  class EventsController < ApplicationController
+    def index
+      @event_types = event_types
+      @aggregates = aggregates
+      paginate(search_events)
+    end
+
+    def show
+      @event = Event.find(params[:id])
+      @aggregate_state = @event.aggregate_state
+      find_adjacent_versions
+    end
+
+    private
+
+    def event_types
+      return Event.descendants.map(&:name).sort if Rails.env.production?
+
+      Event.distinct.pluck(:event_type).sort
+    end
+
+    def aggregates
+      return Event.descendants.filter_map(&:aggregate_class).map(&:name).uniq.sort if Rails.env.production?
+
+      Event.where.not(eventable_type: nil).distinct.pluck(:eventable_type).sort
+    end
+
+    def search_events
+      EventSearch.new(
+        scope: Event.all,
+        event_type: params[:event_type],
+        aggregate: params[:aggregate],
+        query: params[:q]
+      ).call
+    end
+
+    def paginate(scope)
+      @paginator = Paginator.new(
+        scope:,
+        per_page: RailsSimpleEventSourcing.config.events_per_page,
+        cursor: params[:after] || params[:before],
+        direction: params[:before].present? ? :prev : :next
+      )
+    end
+
+    def find_adjacent_versions
+      return if @event.aggregate_id.blank?
+
+      scope = Event.where(aggregate_id: @event.aggregate_id)
+      @previous_version = scope.where(version: ...@event.version).order(version: :desc).first
+      @next_version = scope.where('version > ?', @event.version).order(version: :asc).first
+    end
+  end
+end

data/app/helpers/rails_simple_event_sourcing/events_helper.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  module EventsHelper
+  end
+end

data/app/models/rails_simple_event_sourcing/event.rb

@@ -9,14 +9,10 @@ module RailsSimpleEventSourcing
     belongs_to :eventable, polymorphic: true, optional: true
     alias aggregate eventable
 
-    # Validations
     validates :version, presence: true, numericality: { only_integer: true, greater_than: 0 }
     validates :version, uniqueness: { scope: :aggregate_id }, if: -> { aggregate_id.present? }
 
-    # Callbacks for automatic aggregate lifecycle
-    before_validation :setup_event_fields, on: :create
-    before_validation :apply_event_to_aggregate, on: :create, if: :aggregate_defined?
-    before_validation :set_version
+    before_validation :setup_for_create, on: :create
     before_save :persist_aggregate, if: :aggregate_defined?
 
     def apply(aggregate)
@@ -25,14 +21,36 @@ module RailsSimpleEventSourcing
       end
     end
 
+    def aggregate_state
+      return unless aggregate_defined? && aggregate_id.present?
+
+      aggregate = aggregate_class.new
+      aggregate.id = aggregate_id
+      EventPlayer.new(aggregate).replay_stream(up_to_version: version)
+      aggregate.attributes
+    end
+
     private
 
+    def setup_for_create
+      setup_event_fields
+      setup_aggregate if aggregate_defined?
+      set_version
+    end
+
     def setup_event_fields
       enable_write_access!
       self.event_type = self.class
       self.metadata = CurrentRequest.metadata&.compact&.presence
     end
 
+    def setup_aggregate
+      @aggregate = aggregate_repository.find_or_build(aggregate_id)
+      @aggregate.enable_write_access!
+      self.eventable = @aggregate
+      EventPlayer.new(@aggregate).replay_and_apply(self)
+    end
+
     def set_version
       self.version ||= calculate_next_version
     end
@@ -44,19 +62,11 @@ module RailsSimpleEventSourcing
       max_version + 1
     end
 
-    def apply_event_to_aggregate
-      @aggregate_for_persistence = aggregate_repository.find_or_build(aggregate_id)
-      self.eventable = @aggregate_for_persistence
-
-      applicator = EventApplicator.new(self)
-      applicator.apply_to_aggregate(@aggregate_for_persistence)
-    end
-
     def persist_aggregate
-      return unless @aggregate_for_persistence
+      return unless @aggregate
 
-      aggregate_repository.save!(@aggregate_for_persistence) if aggregate_id.present?
-      self.aggregate_id = @aggregate_for_persistence.id
+      aggregate_repository.save!(@aggregate)
+      self.aggregate_id = @aggregate.id
     end
 
     def aggregate_repository

data/app/views/layouts/rails_simple_event_sourcing/application.html.erb

@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Event Sourcing - Events</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <%= csrf_meta_tags %>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; background: #f5f7fa; color: #333; line-height: 1.6; }
+    .container { max-width: 1200px; margin: 0 auto; padding: 20px; }
+    h1 { font-size: 1.5rem; margin-bottom: 20px; color: #1a1a2e; }
+    h2 { font-size: 1.25rem; margin-bottom: 16px; color: #1a1a2e; }
+    a { color: #4361ee; text-decoration: none; }
+    a:hover { text-decoration: underline; }
+
+    .header { background: #1a1a2e; color: #fff; padding: 16px 0; margin-bottom: 24px; }
+    .header .container { display: flex; align-items: center; justify-content: space-between; }
+    .header h1 { color: #fff; margin: 0; font-size: 1.2rem; }
+    .header a { color: #a8b2d1; }
+    .header a:hover { color: #fff; }
+
+    .search-form { margin-bottom: 20px; display: flex; gap: 8px; align-items: center; flex-wrap: wrap; }
+    .search-form select { padding: 8px 12px; border: 1px solid #ddd; border-radius: 6px; font-size: 0.95rem; background: #fff; }
+    .search-form select:focus { outline: none; border-color: #4361ee; box-shadow: 0 0 0 2px rgba(67,97,238,0.15); }
+    .search-form input[type="text"] { flex: 1; padding: 8px 12px; border: 1px solid #ddd; border-radius: 6px; font-size: 0.95rem; min-width: 200px; }
+    .search-form input[type="text"]:focus { outline: none; border-color: #4361ee; box-shadow: 0 0 0 2px rgba(67,97,238,0.15); }
+    .search-form button { padding: 8px 20px; background: #4361ee; color: #fff; border: none; border-radius: 6px; cursor: pointer; font-size: 0.95rem; }
+    .search-form button:hover { background: #3a56d4; }
+    .clear-link { padding: 8px 16px; background: #eee; border-radius: 6px; color: #333 !important; display: flex; align-items: center; }
+
+    .card { background: #fff; border-radius: 8px; box-shadow: 0 1px 3px rgba(0,0,0,0.08); padding: 20px; margin-bottom: 20px; }
+
+    table { width: 100%; border-collapse: collapse; }
+    th, td { padding: 10px 12px; text-align: left; border-bottom: 1px solid #eee; font-size: 0.9rem; }
+    th { background: #f8f9fa; font-weight: 600; color: #555; text-transform: uppercase; font-size: 0.75rem; letter-spacing: 0.5px; }
+    tr:hover { background: #f8f9fb; }
+
+    .badge { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 0.8rem; font-weight: 500; background: #e8eaf6; color: #3949ab; }
+    .text-muted { color: #888; font-size: 0.85rem; }
+    .text-mono { font-family: "SF Mono", Monaco, "Cascadia Code", monospace; font-size: 0.85rem; }
+
+    .pagination { display: flex; align-items: center; justify-content: center; gap: 4px; margin-top: 20px; flex-wrap: wrap; }
+    .pagination a, .pagination span { display: inline-block; padding: 6px 12px; border-radius: 4px; font-size: 0.9rem; }
+    .pagination a { background: #fff; border: 1px solid #ddd; color: #333; }
+    .pagination a:hover { background: #f0f0f0; text-decoration: none; }
+    .pagination .current { background: #4361ee; color: #fff; border: 1px solid #4361ee; font-weight: 600; }
+    .pagination .gap { border: none; color: #888; }
+    .pagination .disabled { color: #ccc; border-color: #eee; pointer-events: none; }
+
+    .detail-grid { display: grid; grid-template-columns: 140px 1fr; gap: 8px 16px; }
+    .detail-grid dt { font-weight: 600; color: #555; font-size: 0.85rem; }
+    .detail-grid dd { font-size: 0.9rem; }
+    pre.json { background: #f5f7fa; border: 1px solid #e2e6ea; border-radius: 6px; padding: 12px; overflow-x: auto; font-size: 0.85rem; line-height: 1.5; }
+
+    .info-bar { display: flex; justify-content: space-between; align-items: center; margin-bottom: 12px; color: #666; font-size: 0.85rem; }
+    .back-link { margin-bottom: 16px; display: inline-block; font-size: 0.9rem; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <%= yield %>
+  </div>
+</body>
+</html>

data/app/views/rails_simple_event_sourcing/events/_pagination.html.erb

@@ -0,0 +1,15 @@
+<% if @paginator.prev? || @paginator.next? %>
+  <nav class="pagination">
+    <% if @paginator.prev? %>
+      <%= link_to "Prev", events_path(before: @paginator.prev_cursor, q: params[:q], event_type: params[:event_type], aggregate: params[:aggregate]) %>
+    <% else %>
+      <span class="disabled">Prev</span>
+    <% end %>
+
+    <% if @paginator.next? %>
+      <%= link_to "Next", events_path(after: @paginator.next_cursor, q: params[:q], event_type: params[:event_type], aggregate: params[:aggregate]) %>
+    <% else %>
+      <span class="disabled">Next</span>
+    <% end %>
+  </nav>
+<% end %>

data/app/views/rails_simple_event_sourcing/events/index.html.erb

@@ -0,0 +1,47 @@
+<%= form_with url: events_path, method: :get, local: true, class: "search-form" do %>
+  <%= select_tag :event_type, options_for_select([["All event types", ""]] + @event_types.map { |t| [t, t] }, params[:event_type]) %>
+  <%= select_tag :aggregate, options_for_select([["All aggregates", ""]] + @aggregates.map { |a| [a, a] }, params[:aggregate]) %>
+  <%= text_field_tag :q, params[:q], placeholder: "Aggregate ID or key:value from payload or metadata" %>
+  <button type="submit">Search</button>
+  <% if params[:q].present? || params[:event_type].present? || params[:aggregate].present? %>
+    <%= link_to "Clear", events_path, class: "clear-link" %>
+  <% end %>
+<% end %>
+
+<div class="card">
+  <div class="info-bar">
+    <span>Events</span>
+  </div>
+
+  <table>
+    <thead>
+      <tr>
+        <th>ID</th>
+        <th>Event Type</th>
+        <th>Aggregate</th>
+        <th>Aggregate ID</th>
+        <th>Version</th>
+        <th>Created At</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% @paginator.records.each do |event| %>
+        <tr>
+          <td class="text-mono"><%= link_to event.id, event_path(event) %></td>
+          <td><span class="badge"><%= event.event_type %></span></td>
+          <td><%= event.aggregate_class&.name || "-" %></td>
+          <td class="text-mono"><%= event.aggregate_id || "-" %></td>
+          <td><%= event.version %></td>
+          <td class="text-muted"><%= event.read_attribute(:created_at)&.strftime("%Y-%m-%d %H:%M:%S") %></td>
+        </tr>
+      <% end %>
+      <% if @paginator.records.empty? %>
+        <tr>
+          <td colspan="6" style="text-align: center; color: #888; padding: 32px;">No events found.</td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+
+  <%= render "pagination" %>
+</div>

data/app/views/rails_simple_event_sourcing/events/show.html.erb

@@ -0,0 +1,55 @@
+<%= link_to "&larr; Back to events".html_safe, events_path(q: params[:q]), class: "back-link" %>
+
+<div class="card">
+  <dl class="detail-grid">
+    <dt>Event Type</dt>
+    <dd><span class="badge"><%= @event.event_type %></span></dd>
+
+    <dt>Aggregate</dt>
+    <dd><%= @event.aggregate_class&.name || "-" %></dd>
+
+    <dt>Aggregate ID</dt>
+    <dd class="text-mono"><%= @event.aggregate_id || "-" %></dd>
+
+    <dt>Version</dt>
+    <dd>
+      <% if @previous_version %>
+        <%= link_to "&larr; Previous".html_safe, event_path(@previous_version) %>
+      <% end %>
+      <%= @event.version %>
+      <% if @next_version %>
+        <%= link_to "Next &rarr;".html_safe, event_path(@next_version) %>
+      <% end %>
+    </dd>
+
+    <dt>Created At</dt>
+    <dd><%= @event.read_attribute(:created_at)&.strftime("%Y-%m-%d %H:%M:%S %Z") %></dd>
+  </dl>
+</div>
+
+<h2>Payload</h2>
+<div class="card">
+  <% if @event.payload.present? %>
+    <pre class="json"><%= JSON.pretty_generate(@event.payload) %></pre>
+  <% else %>
+    <p class="text-muted">No payload</p>
+  <% end %>
+</div>
+
+<h2>Metadata</h2>
+<div class="card">
+  <% if @event.metadata.present? %>
+    <pre class="json"><%= JSON.pretty_generate(@event.metadata) %></pre>
+  <% else %>
+    <p class="text-muted">No metadata</p>
+  <% end %>
+</div>
+
+<h2>Aggregate State (at version <%= @event.version %>)</h2>
+<div class="card">
+  <% if @aggregate_state.present? %>
+    <pre class="json"><%= JSON.pretty_generate(@aggregate_state) %></pre>
+  <% else %>
+    <p class="text-muted">No aggregate</p>
+  <% end %>
+</div>

data/config/routes.rb

@@ -1,2 +1,6 @@
-Rails.application.routes.draw do
+# frozen_string_literal: true
+
+RailsSimpleEventSourcing::Engine.routes.draw do
+  resources :events, only: [:index, :show]
+  root to: "events#index"
 end

data/db/migrate/20231231133250_create_rails_simple_event_sourcing_events.rb

@@ -15,7 +15,6 @@ class CreateRailsSimpleEventSourcingEvents < ActiveRecord::Migration[7.1]
 
       t.index :type
       t.index :event_type
-      t.index :aggregate_id
       t.index %i[aggregate_id version], unique: true, name: 'index_events_on_aggregate_id_and_version'
       t.index :payload, using: :gin
       t.index :metadata, using: :gin

data/lib/rails_simple_event_sourcing/aggregate_repository.rb

@@ -15,7 +15,6 @@ module RailsSimpleEventSourcing
     end
 
     def save!(aggregate)
-      aggregate.enable_write_access!
       aggregate.save!
     end
 

data/lib/rails_simple_event_sourcing/command_handler.rb

@@ -27,16 +27,18 @@ module RailsSimpleEventSourcing
       handler_class = CommandHandlerRegistry.handler_for(@command.class)
 
       if handler_class.nil? && RailsSimpleEventSourcing.config.use_naming_convention_fallback
-        handler_class_name = @command.class.to_s.gsub('::Commands::', '::CommandHandlers::')
-        handler_class = handler_class_name.safe_constantize
+        @convention_handler_name = @command.class.to_s.sub('::Commands::', '::CommandHandlers::')
+        handler_class = @convention_handler_name.safe_constantize
       end
 
       handler_class
     end
 
     def handler_not_found_message
-      "No handler registered for #{@command.class}. " \
-        "Register one with CommandHandlerRegistry.register(#{@command.class}, YourHandlerClass)"
+      message = "No handler found for #{@command.class}."
+      message += " Tried convention-based lookup: #{@convention_handler_name} (not found)." if @convention_handler_name
+      message += " Register one with CommandHandlerRegistry.register(#{@command.class}, YourHandlerClass)"
+      message
     end
   end
 end

data/lib/rails_simple_event_sourcing/command_handler_registry.rb

@@ -2,12 +2,23 @@
 
 module RailsSimpleEventSourcing
   class CommandHandlerRegistry
+    class CommandAlreadyRegisteredError < StandardError
+    end
+
     @registry = Concurrent::Map.new
 
     def self.register(command_class, handler_class)
+      if @registry.key?(command_class)
+        raise CommandAlreadyRegisteredError, "Command handler already registered for #{command_class}"
+      end
+
       @registry[command_class] = handler_class
     end
 
+    def self.deregister(command_class)
+      @registry.delete(command_class)
+    end
+
     def self.handler_for(command_class)
       @registry[command_class]
     end

data/lib/rails_simple_event_sourcing/configuration.rb

@@ -2,10 +2,11 @@
 
 module RailsSimpleEventSourcing
   class Configuration
-    attr_accessor :use_naming_convention_fallback
+    attr_accessor :use_naming_convention_fallback, :events_per_page
 
     def initialize
       @use_naming_convention_fallback = true
+      @events_per_page = 25
     end
   end
 end

data/lib/rails_simple_event_sourcing/engine.rb

@@ -4,8 +4,9 @@ require_relative 'aggregate_repository'
 require_relative 'command_handler'
 require_relative 'command_handlers/base'
 require_relative 'commands/base'
-require_relative 'event_applicator'
 require_relative 'event_player'
+require_relative 'event_search'
+require_relative 'paginator'
 require_relative 'result'
 require_relative 'command_handler_registry'
 

data/lib/rails_simple_event_sourcing/event_player.rb

@@ -6,15 +6,22 @@ module RailsSimpleEventSourcing
       @aggregate = aggregate
     end
 
-    def replay_stream
-      events = load_event_stream
+    def replay_and_apply(new_event)
+      replay_stream unless @aggregate.new_record?
+      new_event.apply(@aggregate)
+    end
+
+    def replay_stream(up_to_version: nil)
+      events = load_event_stream(up_to_version:)
       apply_events(events)
     end
 
     private
 
-    def load_event_stream
-      @aggregate.events.order(version: :asc)
+    def load_event_stream(up_to_version:)
+      scope = @aggregate.events.order(version: :asc)
+      scope = scope.where(version: ..up_to_version) if up_to_version
+      scope
     end
 
     def apply_events(events)

data/lib/rails_simple_event_sourcing/event_search.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  class EventSearch
+    KEY_VALUE_PATTERN = /\A([^:]+):(.+)\z/
+
+    def initialize(scope:, event_type: nil, aggregate: nil, query: nil)
+      @scope = scope
+      @event_type = event_type
+      @aggregate = aggregate
+      @query = query&.strip
+    end
+
+    def call
+      filter_by_event_type
+      filter_by_aggregate
+      filter_by_query
+      @scope
+    end
+
+    private
+
+    def filter_by_event_type
+      return if @event_type.blank?
+
+      @scope = @scope.where(event_type: @event_type)
+    end
+
+    def filter_by_aggregate
+      return if @aggregate.blank?
+
+      @scope = @scope.where(eventable_type: @aggregate)
+    end
+
+    def filter_by_query
+      return if @query.blank?
+
+      if (match = @query.match(KEY_VALUE_PATTERN))
+        filter_by_key_value(match[1], match[2])
+      else
+        filter_by_aggregate_id(@query)
+      end
+    end
+
+    def filter_by_key_value(key, value)
+      json_fragment = { key => value }.to_json
+      @scope = @scope.where(
+        'payload @> :json::jsonb OR metadata @> :json::jsonb',
+        json: json_fragment
+      )
+    end
+
+    def filter_by_aggregate_id(value)
+      @scope = @scope.where(aggregate_id: value)
+    end
+  end
+end

data/lib/rails_simple_event_sourcing/paginator.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  class Paginator
+    attr_reader :per_page
+
+    def initialize(scope:, per_page:, cursor: nil, direction: :next)
+      @scope = scope
+      @per_page = per_page
+      @cursor = cursor&.to_i
+      @direction = direction
+    end
+
+    def records
+      @records ||= fetch_records
+    end
+
+    def next_cursor
+      records.last&.id
+    end
+
+    def prev_cursor
+      records.first&.id
+    end
+
+    def next?
+      records
+      @has_next
+    end
+
+    def prev?
+      records
+      @has_prev
+    end
+
+    private
+
+    def fetch_records
+      if @cursor.nil?
+        fetch_first_page
+      elsif @direction == :prev
+        fetch_prev_page
+      else
+        fetch_next_page
+      end
+    end
+
+    def fetch_first_page
+      rows = @scope.order(id: :desc).limit(@per_page + 1).to_a
+      @has_prev = false
+      @has_next = rows.size > @per_page
+      rows.first(@per_page)
+    end
+
+    def fetch_next_page
+      rows = @scope.where(id: ...@cursor).order(id: :desc).limit(@per_page + 1).to_a
+      @has_prev = true
+      @has_next = rows.size > @per_page
+      rows.first(@per_page)
+    end
+
+    def fetch_prev_page
+      rows = @scope.where('id > ?', @cursor).order(id: :asc).limit(@per_page + 1).to_a
+      @has_next = true
+      @has_prev = rows.size > @per_page
+      rows.first(@per_page).reverse
+    end
+  end
+end

data/lib/rails_simple_event_sourcing/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsSimpleEventSourcing
-  VERSION = '1.0.5'
+  VERSION = '1.0.7'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_simple_event_sourcing
 version: !ruby/object:Gem::Version
-  version: 1.0.5
+  version: 1.0.7
 platform: ruby
 authors:
 - Damian Baćkowski
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-25 00:00:00.000000000 Z
+date: 2026-02-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg
@@ -78,6 +78,9 @@ files:
 - Rakefile
 - app/assets/config/rails_simple_event_sourcing_manifest.js
 - app/controllers/concerns/rails_simple_event_sourcing/set_current_request_details.rb
+- app/controllers/rails_simple_event_sourcing/application_controller.rb
+- app/controllers/rails_simple_event_sourcing/events_controller.rb
+- app/helpers/rails_simple_event_sourcing/events_helper.rb
 - app/models/concerns/rails_simple_event_sourcing/aggregate_configuration.rb
 - app/models/concerns/rails_simple_event_sourcing/event_attributes.rb
 - app/models/concerns/rails_simple_event_sourcing/events.rb
@@ -85,6 +88,10 @@ files:
 - app/models/rails_simple_event_sourcing.rb
 - app/models/rails_simple_event_sourcing/current_request.rb
 - app/models/rails_simple_event_sourcing/event.rb
+- app/views/layouts/rails_simple_event_sourcing/application.html.erb
+- app/views/rails_simple_event_sourcing/events/_pagination.html.erb
+- app/views/rails_simple_event_sourcing/events/index.html.erb
+- app/views/rails_simple_event_sourcing/events/show.html.erb
 - config/routes.rb
 - db/migrate/20231231133250_create_rails_simple_event_sourcing_events.rb
 - lib/rails_simple_event_sourcing.rb
@@ -95,8 +102,9 @@ files:
 - lib/rails_simple_event_sourcing/commands/base.rb
 - lib/rails_simple_event_sourcing/configuration.rb
 - lib/rails_simple_event_sourcing/engine.rb
-- lib/rails_simple_event_sourcing/event_applicator.rb
 - lib/rails_simple_event_sourcing/event_player.rb
+- lib/rails_simple_event_sourcing/event_search.rb
+- lib/rails_simple_event_sourcing/paginator.rb
 - lib/rails_simple_event_sourcing/result.rb
 - lib/rails_simple_event_sourcing/version.rb
 - lib/tasks/rails_simple_event_sourcing_tasks.rake

data/lib/rails_simple_event_sourcing/event_applicator.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module RailsSimpleEventSourcing
-  class EventApplicator
-    def initialize(event)
-      @event = event
-    end
-
-    def apply_to_aggregate(aggregate)
-      enable_aggregate_writes(aggregate)
-      replay_history_if_needed(aggregate)
-      apply_current_event(aggregate)
-    end
-
-    private
-
-    def enable_aggregate_writes(aggregate)
-      aggregate.enable_write_access!
-    end
-
-    def replay_history_if_needed(aggregate)
-      return if aggregate.new_record?
-
-      player = EventPlayer.new(aggregate)
-      player.replay_stream
-    end
-
-    def apply_current_event(aggregate)
-      @event.apply(aggregate)
-    end
-  end
-end