rails_simple_event_sourcing 1.0.11 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e55cdcaaea329dd389ea7bd44f539e6b676c45d5f0f400cf3cbdd0a67f61021
-  data.tar.gz: ca8f42fb05104799d8ab73eb14290cc5941b0e05b4b504d8c3f8ba3dde26c971
+  metadata.gz: 1a12c3adaddba63ac71f028aa700a4c14826999551657b1cafe758d9d7c1a66f
+  data.tar.gz: 480fcef167c89edb26e9ebe04596f3a90fe9cc04e58064bcb46309abba5926f6
 SHA512:
-  metadata.gz: 41c3718c3caadc0d5cbe82f87158b540c9e78831c4342bc37f582fc28b38cd1ec77f58ec02c8083cd9dde321c6cbe8aa29aded5a96456c6eac7a2e25ead78fc6
-  data.tar.gz: a53c32406b3a37e448af71401524e85d4f03afdf9dc59d68e4c286ad32030686f1cf4ab961f63b86fb1f4037cb7d996c5128541b474f1db2a817a0b258c9abfa
+  metadata.gz: 47f6eddbbd5b4ad08e586caad344024432b716ac354b01bdd17494cff94b3b4419735a203a1425d7b3798a401685f8a8c1f28bacc50ceac3afe748fdb22c80b0
+  data.tar.gz: 4800824fd957523c51466fafe888b80541fcf1a52abab599435e32dd3a18871e4e5ea6b18acba24579c45762558952a03118157aeed4f2bb7c2a29ce49589132

data/README.md

@@ -2,6 +2,8 @@
 
 A minimalist implementation of the event sourcing pattern for Rails applications. This gem provides a simple, opinionated approach to event sourcing without the complexity of full-featured frameworks.
 
+You don't have to go all-in. The gem can be applied to a single model or a specific part of your domain while the rest of your application continues using standard ActiveRecord. This makes it easy to adopt incrementally — start with a new feature or migrate an existing model to event sourcing when it makes sense, without rewriting your entire system.
+
 If you need a more comprehensive solution, check out:
 - https://www.sequent.io
 - https://railseventstore.org
@@ -22,7 +24,9 @@ If you need a more comprehensive solution, check out:
   - [Metadata Tracking](#metadata-tracking)
   - [Event Querying](#event-querying)
   - [Events Viewer](#events-viewer)
+  - [Adding Event Sourcing to an Existing Model](#adding-event-sourcing-to-an-existing-model)
   - [Event Subscriptions](#event-subscriptions)
+  - [Event Schema Versioning](#event-schema-versioning)
 - [Testing](#testing)
 - [Limitations](#limitations)
 - [Troubleshooting](#troubleshooting)
@@ -42,6 +46,7 @@ If you need a more comprehensive solution, check out:
 - **PostgreSQL JSONB Storage** - Efficient JSON storage for event payloads and metadata
 - **Built-in Events Viewer** - Web UI for browsing, searching, and inspecting events
 - **Event Subscriptions** - React to events after they are committed (send emails, send webhooks, etc.)
+- **Event Schema Versioning** - Built-in upcasting to evolve event schemas without modifying stored data
 - **Minimal Configuration** - Convention over configuration approach
 
 ## Requirements
@@ -102,12 +107,16 @@ end
 
 The event sourcing flow follows this pattern:
 
-```
-HTTP Request → Controller → Command → CommandHandler → Event → Aggregate (Model)
-                   ↓           ↓            ↓             ↓          ↓
-              Pass data   Parameters    Validation +   Immutable   Database
-                          + Validation   Business      Storage
-                            Rules        Logic
+```mermaid
+flowchart TD
+    A[HTTP Request] --> B[Controller]
+    B -->|Pass data| C[Command]
+    C -->|Parameters\n+ Validation Rules| D[CommandHandler]
+    D -->|Validation +\nBusiness Logic| E[Event]
+    E -->|Immutable\nStorage| F[Aggregate\nModel]
+    F --> G[(Database)]
+    E --> H[EventBus]
+    H -->|after commit| I[Subscribers\nActiveJob]
 ```
 
 **Flow breakdown:**
@@ -116,6 +125,8 @@ HTTP Request → Controller → Command → CommandHandler → Event → Aggrega
 3. **CommandHandler** - Validates command, executes business logic, creates event
 4. **Event** - Immutable record of what happened
 5. **Aggregate** - Model updated via event
+6. **EventBus** - After the transaction commits, enqueues subscriber jobs
+7. **Subscribers** - ActiveJob classes that react to events asynchronously (send emails, sync external systems, etc.)
 
 ### Directory Structure
 
@@ -127,13 +138,15 @@ app/
 │  ├─ customer/
 │  │  ├─ command_handlers/
 │  │  │  ├─ create.rb
-│  │  ├─ events/
-│  │  │  ├─ customer_created.rb
 │  │  ├─ commands/
 │  │  │  ├─ create.rb
+│  │  ├─ events/
+│  │  │  ├─ customer_created.rb
+│  │  ├─ subscribers/
+│  │  │  ├─ send_welcome_email.rb
 ```
 
-**Note:** The top directory name (`domain/`) can be different - Rails doesn't enforce this namespace.
+**Note:** The top directory name (`domain/`) can be different - Rails doesn't enforce this namespace. Subscribers are ActiveJob classes (see [Event Subscriptions](#event-subscriptions)), so you can also place them in `app/jobs/` or any other autoloaded directory if that better fits your project structure.
 
 ### Commands
 
@@ -177,6 +190,7 @@ Handlers can be discovered in two ways:
 **Result Object:**
 The `Result` class has three fields:
 - `success?` - Boolean indicating if the operation succeeded
+- `failure?` - Boolean indicating if the operation failed (inverse of `success?`)
 - `data` - Data to return (usually the aggregate/model instance)
 - `errors` - Array or hash of error messages when `success?` is false
 
@@ -194,7 +208,7 @@ It supports a chainable API for use in controllers:
 - `on_success { |data| }` - Executes the block (yielding `data`) if the result is successful
 - `on_failure { |errors| }` - Executes the block (yielding `errors`) if the result failed
 
-Both methods return `self`, so they can be chained. The predicate `success?` remains available for use in conditionals and tests.
+Both methods return `self`, so they can be chained. The predicates `success?` and `failure?` remain available for use in conditionals and tests.
 
 ```ruby
 result = RailsSimpleEventSourcing::Result.success(data: customer)
@@ -205,9 +219,10 @@ result
   .on_failure { |errors| render json: { errors: }, status: :unprocessable_entity }
 
 # Predicate (preferred in tests)
-result.success? # => true
-result.data     # => #<Customer ...>
-result.errors   # => nil
+result.success?  # => true
+result.failure?  # => false
+result.data      # => #<Customer ...>
+result.errors    # => nil
 ```
 
 **Helper Methods in Handlers:**
@@ -223,9 +238,9 @@ class Customer
     class Create < RailsSimpleEventSourcing::CommandHandlers::Base
       def call
         event = Customer::Events::CustomerCreated.create(
-          first_name: @command.first_name,
-          last_name: @command.last_name,
-          email: @command.email,
+          first_name: command.first_name,
+          last_name: command.last_name,
+          email: command.email,
           created_at: Time.zone.now,
           updated_at: Time.zone.now
         )
@@ -245,9 +260,9 @@ class Customer
     class Create < RailsSimpleEventSourcing::CommandHandlers::Base
       def call
         event = Customer::Events::CustomerCreated.create(
-          first_name: @command.first_name,
-          last_name: @command.last_name,
-          email: @command.email,
+          first_name: command.first_name,
+          last_name: command.last_name,
+          email: command.email,
           created_at: Time.zone.now,
           updated_at: Time.zone.now
         )
@@ -335,6 +350,7 @@ end
 **Understanding the Event Structure:**
 - `aggregate_class Customer` - Specifies which model this event modifies
 - `event_attributes` - Defines what data gets stored in the event's JSON payload and what will be automatically applied
+- `current_version` - Optional; declares the current schema version for this event (defaults to 1). See [Event Schema Versioning](#event-schema-versioning)
 - `apply(aggregate)` - Optional method; only implement if you need custom logic beyond automatic attribute assignment
 - `aggregate_id` - Auto-generated for creates, must be provided for updates/deletes
 
@@ -342,6 +358,55 @@ end
 - Optional - you can have events without an aggregate (e.g., `UserLoginFailed` for logging only)
 - The corresponding model should include `RailsSimpleEventSourcing::Events` for read-only protection
 
+**Example - Event without an aggregate:**
+
+When you want to record something that happened without modifying any model (audit logs, failed attempts, notifications, etc.), simply omit `aggregate_class`:
+
+```ruby
+class Customer
+  module Events
+    class CustomerEmailTaken < RailsSimpleEventSourcing::Event
+      event_attributes :first_name, :last_name, :email
+    end
+  end
+end
+```
+
+These events are stored in the event log like any other event, but they don't create or update an aggregate. You can create them directly:
+
+```ruby
+Customer::Events::CustomerEmailTaken.create!(
+  first_name: 'John',
+  last_name: 'Doe',
+  email: 'john@example.com'
+)
+```
+
+Or from within a command handler as part of your business logic:
+
+```ruby
+class Customer
+  module CommandHandlers
+    class Create < RailsSimpleEventSourcing::CommandHandlers::Base
+      def call
+        if Customer.exists?(email: command.email)
+          Customer::Events::CustomerEmailTaken.create!(
+            first_name: command.first_name,
+            last_name: command.last_name,
+            email: command.email
+          )
+          return failure(errors: { email: ['already taken'] })
+        end
+
+        # ... create the customer event
+      end
+    end
+  end
+end
+```
+
+This is useful for recording domain-significant occurrences that don't map to a state change on a model.
+
 ### Registering Command Handlers
 
 The recommended approach is to register command handlers explicitly using the registry. This makes the command-to-handler mapping explicit and avoids relying on naming conventions.
@@ -387,7 +452,7 @@ class CustomersController < ApplicationController
       email: params[:email]
     )
 
-    RailsSimpleEventSourcing::CommandHandler.new(cmd).call
+    RailsSimpleEventSourcing.dispatch(cmd)
       .on_success { |data| render json: data }
       .on_failure { |errors| render json: { errors: }, status: :unprocessable_entity }
   end
@@ -408,7 +473,7 @@ class CustomersController < ApplicationController
       email: params[:email]
     )
 
-    RailsSimpleEventSourcing::CommandHandler.new(cmd).call
+    RailsSimpleEventSourcing.dispatch(cmd)
       .on_success { |data| render json: data }
       .on_failure { |errors| render json: { errors: }, status: :unprocessable_entity }
   end
@@ -422,7 +487,7 @@ class CustomersController < ApplicationController
   def destroy
     cmd = Customer::Commands::Delete.new(aggregate_id: params[:id])
 
-    RailsSimpleEventSourcing::CommandHandler.new(cmd).call
+    RailsSimpleEventSourcing.dispatch(cmd)
       .on_success { head :no_content }
       .on_failure { |errors| render json: { errors: }, status: :unprocessable_entity }
   end
@@ -477,7 +542,7 @@ event.metadata
 #     "request_user_agent"=>"curl/8.6.0", ...}
 
 # Query events by type
-RailsSimpleEventSourcing::Event.where(event_type: "Customer::Events::CustomerCreated")
+RailsSimpleEventSourcing::Event.where(type: "Customer::Events::CustomerCreated")
 
 # Get events in a date range
 customer.events.where(created_at: 1.week.ago..Time.now)
@@ -508,7 +573,7 @@ latest_event.aggregate_state
 **Event Structure:**
 - `payload` - Contains the event attributes you defined (as JSON)
 - `metadata` - Contains request context (request ID, IP, user agent, params)
-- `event_type` - The event class name
+- `type` - The event class name (Rails STI column)
 - `aggregate_id` - Links to the aggregate instance
 - `eventable` - Polymorphic relation to the aggregate
 
@@ -532,23 +597,36 @@ By default, the following is captured:
 - `request_ip` - Client IP address
 - `request_params` - Request parameters (filtered using Rails parameter filter)
 
-**Customizing Metadata:**
-Override the `event_metadata` method in your controller:
+**Adding Custom Metadata:**
+Override `custom_event_metadata` to add your own fields — they are merged into the defaults:
 
 ```ruby
 class ApplicationController < ActionController::Base
   include RailsSimpleEventSourcing::SetCurrentRequestDetails
 
-  def event_metadata
-    parameter_filter = ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters)
+  def custom_event_metadata
+    {
+      current_user_id: current_user&.id,
+      tenant_id: current_tenant&.id
+    }
+  end
+end
+```
+
+The method must return a hash. Any keys it returns are merged on top of the default metadata (custom keys take precedence on collision).
+
+**Overriding Default Metadata Entirely:**
+If you need full control over what is captured, override `default_event_metadata` instead:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include RailsSimpleEventSourcing::SetCurrentRequestDetails
 
+  def default_event_metadata
     {
       request_id: request.uuid,
-      request_user_agent: request.user_agent,
-      request_ip: request.ip,
-      request_params: parameter_filter.filter(request.params),
-      current_user_id: current_user&.id,  # Add custom fields
-      tenant_id: current_tenant&.id
+      request_ip: request.ip
+      # only keep what you need
     }
   end
 end
@@ -669,9 +747,64 @@ class Customer::Events::CustomerDeleted < RailsSimpleEventSourcing::Event
 end
 ```
 
+### Adding Event Sourcing to an Existing Model
+
+You can introduce event sourcing to a model that already has data. The key step is importing existing records as initial events so that every aggregate has a complete event history going forward.
+
+**Step 1 — Set up the event and command classes as usual:**
+
+```ruby
+class Customer
+  module Events
+    class CustomerCreated < RailsSimpleEventSourcing::Event
+      aggregate_class Customer
+      event_attributes :first_name, :last_name, :email, :created_at, :updated_at
+    end
+  end
+end
+```
+
+**Step 2 — Include the module in your model:**
+
+```ruby
+class Customer < ApplicationRecord
+  include RailsSimpleEventSourcing::Events
+end
+```
+
+**Step 3 — Create a migration task to import existing records as events:**
+
+```ruby
+# lib/tasks/import_customer_events.rake
+namespace :events do
+  desc "Import existing customers as CustomerCreated events"
+  task import_customers: :environment do
+    Customer.find_each do |customer|
+      next if customer.events.exists?
+
+      Customer::Events::CustomerCreated.create!(
+        aggregate_id: customer.id,
+        first_name: customer.first_name,
+        last_name: customer.last_name,
+        email: customer.email,
+        created_at: customer.created_at,
+        updated_at: customer.updated_at
+      )
+    end
+  end
+end
+```
+
+Run with:
+```bash
+rake events:import_customers
+```
+
+After the import, every existing record has a `CustomerCreated` event as its baseline. From that point on, all changes go through the command/event flow while the rest of your application remains unchanged.
+
 ### Event Subscriptions
 
-The `EventBus` lets you react to events after they are persisted and committed to the database. Subscribers run **after the transaction commits**, so they never execute against data that could later be rolled back.
+The `EventBus` lets you react to events after they are persisted and committed to the database. Subscribers are **ActiveJob classes** that are enqueued **after the transaction commits**, so they never execute against data that could later be rolled back and they don't block the HTTP response.
 
 **Registering subscribers:**
 
@@ -680,35 +813,45 @@ The `EventBus` lets you react to events after they are persisted and committed t
 Rails.application.config.after_initialize do
   RailsSimpleEventSourcing::EventBus.subscribe(
     Customer::Events::CustomerCreated,
-    Subscribers::SendWelcomeEmail
+    Customer::Subscribers::SendWelcomeEmail
   )
 
   RailsSimpleEventSourcing::EventBus.subscribe(
     Customer::Events::CustomerCreated,
-    Subscribers::CreateStripeCustomer
+    Customer::Subscribers::CreateStripeCustomer
   )
 
   RailsSimpleEventSourcing::EventBus.subscribe(
     Customer::Events::CustomerDeleted,
-    Subscribers::CancelStripeSubscription
+    Customer::Subscribers::CancelStripeSubscription
   )
 end
 ```
 
 **Writing a subscriber:**
 
-Any object that responds to `call(event)` works — a class with `.call`, a lambda, or a proc:
+Subscribers must be ActiveJob classes. Each subscriber is enqueued as its own job, giving you per-subscriber retry logic, queue configuration, and error isolation out of the box.
 
 ```ruby
-module Subscribers
-  class SendWelcomeEmail
-    def self.call(event)
-      WelcomeMailer.with(email: event.email).deliver_later
+class Customer
+  module Subscribers
+    class SendWelcomeEmail < ApplicationJob
+      queue_as :default
+
+      def perform(event)
+        WelcomeMailer.with(email: event.email).deliver_later
+      end
     end
   end
 end
 ```
 
+Since each subscriber is a standalone job, you get native ActiveJob benefits:
+- **Per-subscriber queues** — route critical subscribers to high-priority queues
+- **Per-subscriber retries** — configure `retry_on` per subscriber
+- **Error isolation** — a failing subscriber doesn't affect others
+- **Visibility** — each subscriber appears as its own job in your queue dashboard
+
 **Subscribing to all events:**
 
 Subscribe to `RailsSimpleEventSourcing::Event` to receive every event regardless of type — useful for audit loggers or metrics:
@@ -716,39 +859,112 @@ Subscribe to `RailsSimpleEventSourcing::Event` to receive every event regardless
 ```ruby
 RailsSimpleEventSourcing::EventBus.subscribe(
   RailsSimpleEventSourcing::Event,
-  Subscribers::AuditLogger
+  Customer::Subscribers::AuditLogger
 )
 ```
 
-If you subscribe the same callable to both a specific event class and `RailsSimpleEventSourcing::Event`, it will be called twice — once for each subscription. This is intentional and consistent with standard pub/sub behaviour.
+If you subscribe the same job to both a specific event class and `RailsSimpleEventSourcing::Event`, it will be enqueued twice — once for each subscription. This is intentional and consistent with standard pub/sub behaviour.
 
 **Testing with EventBus:**
 
-Call `RailsSimpleEventSourcing::EventBus.reset!` in your test `setup` to clear all subscriptions between tests:
+Use `ActiveJob::TestHelper` to assert that subscriber jobs are enqueued. Call `RailsSimpleEventSourcing::EventBus.reset!` in your test `setup` to clear all subscriptions between tests:
 
 ```ruby
 class MyTest < ActiveSupport::TestCase
+  include ActiveJob::TestHelper
+
   setup do
     RailsSimpleEventSourcing::EventBus.reset!
   end
 
-  test "sends welcome email on customer created" do
-    emails = []
+  test "enqueues welcome email job on customer created" do
     RailsSimpleEventSourcing::EventBus.subscribe(
       Customer::Events::CustomerCreated,
-      ->(event) { emails << event.email }
+      Customer::Subscribers::SendWelcomeEmail
     )
 
-    Customer::Events::CustomerCreated.create!(
-      first_name: "John", last_name: "Doe", email: "john@example.com",
-      created_at: Time.zone.now, updated_at: Time.zone.now
-    )
+    assert_enqueued_jobs 1 do
+      Customer::Events::CustomerCreated.create!(
+        first_name: "John", last_name: "Doe", email: "john@example.com",
+        created_at: Time.zone.now, updated_at: Time.zone.now
+      )
+    end
+  end
+end
+```
+
+### Event Schema Versioning
 
-    assert_includes emails, "john@example.com"
+Over time, event schemas may need to change — fields get renamed, split, or added. Since events are immutable and stored forever, the gem provides built-in **upcasting** support to transparently transform old event payloads to the current schema when read.
+
+**How it works:**
+
+Each event class can declare a `current_version` and register `upcaster` blocks that transform payloads from one version to the next. When an event is loaded from the database, the `payload` method automatically runs the necessary upcasters to bring old data up to the current schema. The stored data is never modified — upcasting happens on read.
+
+**Example — splitting a `name` field into `first_name` and `last_name`:**
+
+```ruby
+class Customer
+  module Events
+    class CustomerCreated < RailsSimpleEventSourcing::Event
+      aggregate_class Customer
+      current_version 2
+      event_attributes :first_name, :last_name, :email, :created_at, :updated_at
+
+      # v1 had a single "name" field, v2 splits it into first_name and last_name
+      upcaster(1) do |payload|
+        if payload.key?('name')
+          parts = payload.delete('name').to_s.split(' ', 2)
+          payload['first_name'] = parts[0]
+          payload['last_name'] = parts[1]
+        end
+        payload
+      end
+    end
+  end
+end
+```
+
+**Chaining multiple upcasters:**
+
+Upcasters are applied sequentially. A v1 event will run through `upcaster(1)`, then `upcaster(2)`, and so on until it reaches the `current_version`:
+
+```ruby
+class Customer
+  module Events
+    class CustomerCreated < RailsSimpleEventSourcing::Event
+      aggregate_class Customer
+      current_version 3
+      event_attributes :first_name, :last_name, :email, :phone, :created_at, :updated_at
+
+      # v1 -> v2: split "name" into first_name/last_name
+      upcaster(1) do |payload|
+        if payload.key?('name')
+          parts = payload.delete('name').to_s.split(' ', 2)
+          payload['first_name'] = parts[0]
+          payload['last_name'] = parts[1]
+        end
+        payload
+      end
+
+      # v2 -> v3: add phone with default
+      upcaster(2) do |payload|
+        payload['phone'] ||= 'unknown'
+        payload
+      end
+    end
   end
 end
 ```
 
+**Key points:**
+
+- `current_version` is optional — if not called, the schema version defaults to 1
+- New events are stored with the current version, so they skip upcasting entirely
+- If an upcaster is missing for a version in the chain, a `RuntimeError` is raised
+- Upcasting is transparent to `apply` — custom or default `apply` methods receive the already-upcasted payload
+- Events without `aggregate_class` do not use schema versioning (the `schema_version` column is left `nil`)
+
 ## Testing
 
 ### Setting Up Tests with Command Handler Registry
@@ -821,7 +1037,7 @@ class Customer::CommandHandlers::CreateTest < ActiveSupport::TestCase
       email: "john@example.com"
     )
 
-    result = RailsSimpleEventSourcing::CommandHandler.new(cmd).call
+    result = RailsSimpleEventSourcing.dispatch(cmd)
 
     assert result.success?
     assert_instance_of Customer, result.data
@@ -844,7 +1060,7 @@ class Customer::CommandHandlers::CreateTest < ActiveSupport::TestCase
       email: "john@example.com"
     )
 
-    result = RailsSimpleEventSourcing::CommandHandler.new(cmd).call
+    result = RailsSimpleEventSourcing.dispatch(cmd)
 
     assert_not result.success?
     assert_includes result.errors, "Email has already been taken"
@@ -876,7 +1092,6 @@ end
 Be aware of these limitations when using this gem:
 
 - **PostgreSQL Only** - Requires PostgreSQL 9.4+ for JSONB support
-- **No Event Versioning** - No built-in support for evolving event schemas over time
 - **No Snapshots** - All aggregate reconstruction done by replaying all events (can be slow for aggregates with many events)
 - **No Projections** - No built-in read model or projection support
 - **Manual aggregate_id** - Must manually track and pass `aggregate_id` for updates/deletes
@@ -957,7 +1172,7 @@ customer.update(first_name: "Jane")
 
 # Do this:
 cmd = Customer::Commands::Update.new(aggregate_id: customer.id, first_name: "Jane", ...)
-RailsSimpleEventSourcing::CommandHandler.new(cmd).call
+RailsSimpleEventSourcing.dispatch(cmd)
 ```
 
 ### Missing aggregate_id for updates

data/app/controllers/concerns/rails_simple_event_sourcing/set_current_request_details.rb

@@ -10,10 +10,14 @@ module RailsSimpleEventSourcing
       private
 
       def set_event_metadata
-        CurrentRequest.metadata = event_metadata
+        CurrentRequest.metadata = default_event_metadata.merge(custom_event_metadata)
       end
 
-      def event_metadata
+      def custom_event_metadata
+        {}
+      end
+
+      def default_event_metadata
         parameter_filter = ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters)
 
         {

data/app/controllers/rails_simple_event_sourcing/events_controller.rb

@@ -11,6 +11,8 @@ module RailsSimpleEventSourcing
     def show
       @event = Event.find(params[:id])
       @aggregate_state = @event.aggregate_state
+      @payload_links         = AggregateLinksBuilder.new(@event.payload).call
+      @aggregate_state_links = AggregateLinksBuilder.new(@aggregate_state).call
       find_adjacent_versions
     end
 
@@ -19,7 +21,7 @@ module RailsSimpleEventSourcing
     def event_types
       return Event.descendants.map(&:name).sort if Rails.env.production?
 
-      Event.distinct.pluck(:event_type).sort
+      Event.distinct.pluck(:type).sort
     end
 
     def aggregates
@@ -31,7 +33,7 @@ module RailsSimpleEventSourcing
     def search_events
       EventSearch.new(
         scope: Event.all,
-        event_type: params[:event_type],
+        type: params[:event_type],
         aggregate: params[:aggregate],
         query: params[:q]
       ).call

data/app/models/concerns/rails_simple_event_sourcing/schema_versioning.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  module SchemaVersioning
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def current_version(version)
+        @current_schema_version = version
+      end
+
+      def schema_version_number
+        @current_schema_version || 1
+      end
+
+      def upcaster(from_version, &block)
+        upcasters[from_version] = block
+      end
+
+      def upcasters
+        @upcasters ||= {}
+      end
+    end
+
+    included do
+      before_validation :set_schema_version, on: :create
+    end
+
+    def payload
+      data = super
+      return data if new_record?
+
+      upcast(data)
+    end
+
+    private
+
+    def upcast(data)
+      return data if data.nil? || schema_version.nil?
+
+      current = schema_version
+      target = self.class.schema_version_number
+
+      while current < target
+        upcaster = self.class.upcasters[current]
+        raise "Missing upcaster from version #{current} to #{current + 1} for #{self.class}" unless upcaster
+
+        data = upcaster.call(data)
+        current += 1
+      end
+
+      data
+    end
+
+    def set_schema_version
+      return unless aggregate_defined?
+
+      self.schema_version = self.class.schema_version_number
+    end
+  end
+end

data/app/models/rails_simple_event_sourcing/event.rb

@@ -5,6 +5,7 @@ module RailsSimpleEventSourcing
     include ReadOnly
     include EventAttributes
     include AggregateConfiguration
+    include SchemaVersioning
 
     belongs_to :eventable, polymorphic: true, optional: true
     alias aggregate eventable
@@ -24,7 +25,7 @@ module RailsSimpleEventSourcing
 
     def apply(aggregate)
       payload.each do |key, value|
-        raise "Unknown attribute '#{key}' on #{aggregate.class}" unless aggregate.respond_to?("#{key}=")
+        raise ArgumentError, "Unknown attribute '#{key}' on #{aggregate.class}" unless aggregate.respond_to?("#{key}=")
 
         aggregate.send("#{key}=", value)
       end
@@ -49,7 +50,6 @@ module RailsSimpleEventSourcing
 
     def setup_event_fields
       enable_write_access!
-      self.event_type = self.class
       self.metadata = CurrentRequest.metadata&.compact&.presence
     end
 

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

@@ -47,7 +47,7 @@
     .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 { display: grid; grid-template-columns: max-content 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; }

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

@@ -28,7 +28,7 @@
       <% @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><span class="badge"><%= event.type %></span></td>
           <td><%= event.aggregate_class&.name || "-" %></td>
           <td class="text-mono"><%= event.aggregate_id || "-" %></td>
           <td><%= event.version %></td>

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

@@ -3,7 +3,7 @@
 <div class="card">
   <dl class="detail-grid">
     <dt>Event Type</dt>
-    <dd><span class="badge"><%= @event.event_type %></span></dd>
+    <dd><span class="badge"><%= @event.type %></span></dd>
 
     <dt>Aggregate</dt>
     <dd><%= @event.aggregate_class&.name || "-" %></dd>
@@ -27,10 +27,32 @@
   </dl>
 </div>
 
-<h2>Payload</h2>
+<% links_on     = params[:links] == "1" %>
+<% toggle_label = links_on ? "Hide links" : "Show links" %>
+<% toggle_url   = links_on ? event_path(@event) : event_path(@event, links: "1") %>
+
+<div style="display:flex; align-items:baseline; justify-content:space-between; margin-bottom:16px;">
+  <h2 style="margin-bottom:0">Payload</h2>
+  <%= link_to toggle_label, toggle_url, class: "badge" %>
+</div>
 <div class="card">
   <% if @event.payload.present? %>
-    <pre class="json"><%= JSON.pretty_generate(@event.payload) %></pre>
+    <% if links_on %>
+      <dl class="detail-grid">
+        <% @event.payload.each do |key, value| %>
+          <dt class="text-mono"><%= key %></dt>
+          <dd>
+            <% if (rel = @payload_links[key.to_s]) %>
+              <%= link_to value, event_path(rel[:event_id]), title: rel[:aggregate_type] %>
+            <% else %>
+              <span class="text-mono"><%= value.inspect %></span>
+            <% end %>
+          </dd>
+        <% end %>
+      </dl>
+    <% else %>
+      <pre class="json"><%= JSON.pretty_generate(@event.payload) %></pre>
+    <% end %>
   <% else %>
     <p class="text-muted">No payload</p>
   <% end %>
@@ -45,10 +67,28 @@
   <% end %>
 </div>
 
-<h2>Aggregate State (at version <%= @event.version %>)</h2>
+<div style="display:flex; align-items:baseline; justify-content:space-between; margin-bottom:16px;">
+  <h2 style="margin-bottom:0">Aggregate State (at version <%= @event.version %>)</h2>
+  <%= link_to toggle_label, toggle_url, class: "badge" %>
+</div>
 <div class="card">
   <% if @aggregate_state.present? %>
-    <pre class="json"><%= JSON.pretty_generate(@aggregate_state) %></pre>
+    <% if links_on %>
+      <dl class="detail-grid">
+        <% @aggregate_state.each do |key, value| %>
+          <dt class="text-mono"><%= key %></dt>
+          <dd>
+            <% if (rel = @aggregate_state_links[key.to_s]) %>
+              <%= link_to value, event_path(rel[:event_id]), title: rel[:aggregate_type] %>
+            <% else %>
+              <span class="text-mono"><%= value.inspect %></span>
+            <% end %>
+          </dd>
+        <% end %>
+      </dl>
+    <% else %>
+      <pre class="json"><%= JSON.pretty_generate(@aggregate_state) %></pre>
+    <% end %>
   <% else %>
     <p class="text-muted">No aggregate</p>
   <% end %>

data/db/migrate/20231231133250_create_rails_simple_event_sourcing_events.rb

@@ -5,16 +5,15 @@ class CreateRailsSimpleEventSourcingEvents < ActiveRecord::Migration[7.1]
     create_table :rails_simple_event_sourcing_events do |t|
       t.references :eventable, polymorphic: true
       t.string :type, null: false
-      t.string :event_type, null: false
       t.string :aggregate_id
       t.bigint :version
       t.jsonb :payload
       t.jsonb :metadata
+      t.integer :schema_version
 
       t.timestamps
 
       t.index :type
-      t.index :event_type
       t.index %i[eventable_type aggregate_id version],
               unique: true,
               name: 'index_events_on_eventable_type_and_aggregate_id_and_version'

data/lib/rails_simple_event_sourcing/aggregate_links_builder.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  class AggregateLinksBuilder
+    def initialize(data)
+      @data = data
+    end
+
+    def call
+      return {} if @data.blank?
+
+      @data.filter_map { |key, value| entry_for(key.to_s, value) }.to_h
+    end
+
+    private
+
+    def entry_for(key, value)
+      return unless key.end_with?('_id') && value.present?
+
+      klass = resolve_klass(key)
+      return unless klass
+
+      latest_event = Event.where(eventable_type: klass.name, aggregate_id: value.to_s).order(version: :desc).first
+      return unless latest_event
+
+      [key, { aggregate_type: klass.name, aggregate_id: value, event_id: latest_event.id }]
+    end
+
+    def resolve_klass(key)
+      klass = key.delete_suffix('_id').camelize.safe_constantize
+      return klass if event_sourced?(klass)
+
+      event_sourced_classes.each do |source|
+        assoc = source.reflect_on_all_associations(:belongs_to).find { |r| r.foreign_key.to_s == key }
+        next unless assoc
+
+        target = assoc.class_name.safe_constantize
+        return target if event_sourced?(target)
+      end
+
+      nil
+    end
+
+    def event_sourced?(klass)
+      klass&.ancestors&.include?(RailsSimpleEventSourcing::Events)
+    end
+
+    def event_sourced_classes
+      @event_sourced_classes ||=
+        Event.where.not(eventable_type: nil)
+             .distinct.pluck(:eventable_type)
+             .filter_map(&:safe_constantize)
+             .select { |k| event_sourced?(k) }
+    end
+  end
+end

data/lib/rails_simple_event_sourcing/command_handler.rb

@@ -11,12 +11,12 @@ module RailsSimpleEventSourcing
     def call
       return Result.failure(errors: @command.errors) unless @command.valid?
 
-      initialize_command_handler.call
+      build_handler.call
     end
 
     private
 
-    def initialize_command_handler
+    def build_handler
       handler_class = find_handler_class
       raise CommandHandlerNotFoundError, handler_not_found_message unless handler_class
 
@@ -24,21 +24,25 @@ module RailsSimpleEventSourcing
     end
 
     def find_handler_class
-      handler_class = CommandHandlerRegistry.handler_for(@command.class)
+      CommandHandlerRegistry.handler_for(@command.class) || convention_handler_class
+    end
 
-      if handler_class.nil? && RailsSimpleEventSourcing.config.use_naming_convention_fallback
-        @convention_handler_name = @command.class.to_s.sub('::Commands::', '::CommandHandlers::')
-        handler_class = @convention_handler_name.safe_constantize
-      end
+    def convention_handler_class
+      return unless RailsSimpleEventSourcing.config.use_naming_convention_fallback
 
-      handler_class
+      convention_handler_name.safe_constantize
+    end
+
+    def convention_handler_name
+      @convention_handler_name ||= @command.class.to_s.sub('::Commands::', '::CommandHandlers::')
     end
 
     def handler_not_found_message
-      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
+      msg = "No handler found for #{@command.class}."
+      if RailsSimpleEventSourcing.config.use_naming_convention_fallback
+        msg += " Tried convention-based lookup: #{convention_handler_name} (not found)."
+      end
+      msg + " Register one with CommandHandlerRegistry.register(#{@command.class}, YourHandlerClass)"
     end
   end
 end

data/lib/rails_simple_event_sourcing/command_handlers/base.rb

@@ -3,8 +3,6 @@
 module RailsSimpleEventSourcing
   module CommandHandlers
     class Base
-      delegate :success, :failure, to: 'RailsSimpleEventSourcing::Result'
-
       def initialize(command:)
         @command = command
       end
@@ -12,6 +10,18 @@ module RailsSimpleEventSourcing
       def call
         raise NotImplementedError, "You must implement #{self.class}#call"
       end
+
+      private
+
+      attr_reader :command
+
+      def success(data: nil)
+        Result.success(data:)
+      end
+
+      def failure(errors:)
+        Result.failure(errors:)
+      end
     end
   end
 end

data/lib/rails_simple_event_sourcing/engine.rb

@@ -6,6 +6,7 @@ require_relative 'command_handler'
 require_relative 'command_handlers/base'
 require_relative 'commands/base'
 require_relative 'event_player'
+require_relative 'aggregate_links_builder'
 require_relative 'event_search'
 require_relative 'paginator'
 require_relative 'result'

data/lib/rails_simple_event_sourcing/event_bus.rb

@@ -6,12 +6,16 @@ module RailsSimpleEventSourcing
 
     class << self
       def subscribe(event_class, subscriber)
+        unless subscriber.is_a?(Class) && subscriber < ActiveJob::Base
+          raise ArgumentError, "Subscriber must be an ActiveJob class, got #{subscriber}"
+        end
+
         @subscriptions[event_class.to_s] << subscriber
       end
 
       def dispatch(event)
-        ancestors_with_subscriptions(event).each do |subscriber|
-          subscriber.call(event)
+        subscribers_for(event).each do |subscriber|
+          subscriber.perform_later(event)
         end
       end
 
@@ -21,7 +25,7 @@ module RailsSimpleEventSourcing
 
       private
 
-      def ancestors_with_subscriptions(event)
+      def subscribers_for(event)
         event.class.ancestors
              .select { |ancestor| @subscriptions.key?(ancestor.to_s) }
              .flat_map { |ancestor| @subscriptions[ancestor.to_s] }

data/lib/rails_simple_event_sourcing/event_search.rb

@@ -4,15 +4,15 @@ module RailsSimpleEventSourcing
   class EventSearch
     KEY_VALUE_PATTERN = /\A([^:]+):(.+)\z/
 
-    def initialize(scope:, event_type: nil, aggregate: nil, query: nil)
+    def initialize(scope:, type: nil, aggregate: nil, query: nil)
       @scope = scope
-      @event_type = event_type
+      @type = type
       @aggregate = aggregate
       @query = query&.strip
     end
 
     def call
-      filter_by_event_type
+      filter_by_type
       filter_by_aggregate
       filter_by_query
       @scope
@@ -20,10 +20,10 @@ module RailsSimpleEventSourcing
 
     private
 
-    def filter_by_event_type
-      return if @event_type.blank?
+    def filter_by_type
+      return if @type.blank?
 
-      @scope = @scope.where(event_type: @event_type)
+      @scope = @scope.where(type: @type)
     end
 
     def filter_by_aggregate

data/lib/rails_simple_event_sourcing/result.rb

@@ -25,17 +25,21 @@ module RailsSimpleEventSourcing
       @success
     end
 
-    def on_success(&block)
-      raise ArgumentError, 'Block required' unless block
+    def failure?
+      !@success
+    end
+
+    def on_success
+      raise ArgumentError, 'Block required' unless block_given?
 
-      block.call(data) if success?
+      yield data if success?
       self
     end
 
-    def on_failure(&block)
-      raise ArgumentError, 'Block required' unless block
+    def on_failure
+      raise ArgumentError, 'Block required' unless block_given?
 
-      block.call(errors) unless success?
+      yield errors unless success?
       self
     end
   end

data/lib/rails_simple_event_sourcing/version.rb

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

data/lib/rails_simple_event_sourcing.rb

@@ -14,4 +14,8 @@ module RailsSimpleEventSourcing
   def self.config
     @config ||= Configuration.new
   end
+
+  def self.dispatch(command)
+    CommandHandler.new(command).call
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_simple_event_sourcing
 version: !ruby/object:Gem::Version
-  version: 1.0.11
+  version: 1.1.0
 platform: ruby
 authors:
 - Damian Baćkowski
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-12 00:00:00.000000000 Z
+date: 2026-03-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg
@@ -98,6 +98,7 @@ files:
 - app/models/concerns/rails_simple_event_sourcing/event_attributes.rb
 - app/models/concerns/rails_simple_event_sourcing/events.rb
 - app/models/concerns/rails_simple_event_sourcing/read_only.rb
+- app/models/concerns/rails_simple_event_sourcing/schema_versioning.rb
 - app/models/rails_simple_event_sourcing.rb
 - app/models/rails_simple_event_sourcing/current_request.rb
 - app/models/rails_simple_event_sourcing/event.rb
@@ -108,6 +109,7 @@ files:
 - config/routes.rb
 - db/migrate/20231231133250_create_rails_simple_event_sourcing_events.rb
 - lib/rails_simple_event_sourcing.rb
+- lib/rails_simple_event_sourcing/aggregate_links_builder.rb
 - lib/rails_simple_event_sourcing/aggregate_repository.rb
 - lib/rails_simple_event_sourcing/command_handler.rb
 - lib/rails_simple_event_sourcing/command_handler_registry.rb