rails_simple_event_sourcing 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9789524ed9ede4a4a16561d587fbfc729fe825d0e4196390b6bd39d4196ed56d
-  data.tar.gz: 5bbc7f33e45dd59ce805b06cea72a84a4a8f63c852fc859270eef9f2b8d11cb7
+  metadata.gz: baad400eca4ab6e7629c1bc7a9d30f66841d2da8ee1d3ab1dd3225333bf9ea10
+  data.tar.gz: dd2e881c3f8693aadae17ed44343acbb2633465eaf36d010934173793b91daf3
 SHA512:
-  metadata.gz: 4112017f8f52f621b401dc463be3673f635176bfcee2732a7a0502757d4472a2897328169a68ddea60e4e8ec9726068d45daa8f1f4d70e6b471d42efffbd0da7
-  data.tar.gz: cbe47f8933ff692665a019fce022e1f52bdc849067fb7ae10bbebef02a9fb3c5eb6222d28d3ce5205249e37466a6733544de7dbd388f4aae43fc4a1219cb96c2
+  metadata.gz: c1ed4111dd95c2e6f0bba524606749e98d22c78d7803ea0b1dc2f0f03a27ef39e070d868d25b5ac2491389db08c154221432c2374d647d343299cd2469eb0656
+  data.tar.gz: 44764791b5a57ad810562f1dbf32f5b17f59ee19c047092c19751db5470498cb56797e6c82aece230ddae68ac820dd6505a5ab8e86433d582bb002fef984c7a4

data/README.md

@@ -1,20 +1,100 @@
 # RailsSimpleEventSourcing ![tests](https://github.com/dbackowski/rails_simple_event_sourcing/actions/workflows/minitest.yml/badge.svg) ![codecheck](https://github.com/dbackowski/rails_simple_event_sourcing/actions/workflows/codecheck.yml/badge.svg)
 
-This is a very minimalist implementation of an event sourcing pattern, if you want a full-featured framework in ruby you can check out one of these:
+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.
+
+If you need a more comprehensive solution, check out:
 - https://www.sequent.io
 - https://railseventstore.org
 
-I wanted to learn how to build this from scratch and also wanted to build something that would be very easy to use since most of the fully featured frameworks like the two above require a lot of configuration and learning.
+## Table of Contents
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Directory Structure](#directory-structure)
+  - [Commands](#commands)
+  - [Command Handlers](#command-handlers)
+  - [Events](#events)
+  - [Controller Integration](#controller-integration)
+  - [Update and Delete Operations](#update-and-delete-operations)
+  - [Metadata Tracking](#metadata-tracking)
+  - [Event Querying](#event-querying)
+- [Testing](#testing)
+- [Limitations](#limitations)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- **Immutable Event Log** - All changes stored as immutable events with full audit trail
+- **Automatic Aggregate Reconstruction** - Rebuild model state by replaying events
+- **Built-in Metadata Tracking** - Captures request context (IP, user agent, params, etc.)
+- **Read-only Model Protection** - Prevents accidental direct model modifications
+- **Simple Command Pattern** - Clear command → handler → event flow
+- **PostgreSQL JSONB Storage** - Efficient JSON storage for event payloads and metadata
+- **Minimal Configuration** - Convention over configuration approach
+
+## Requirements
+
+- **Ruby**: 2.7 or higher
+- **Rails**: 6.0 or higher
+- **Database**: PostgreSQL 9.4+ (requires JSONB support)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "rails_simple_event_sourcing"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install rails_simple_event_sourcing
+```
+
+Copy migration to your app:
+```bash
+rails rails_simple_event_sourcing:install:migrations
+```
 
-### Important notice
+Run the migration to create the events table:
+```bash
+rake db:migrate
+```
 
-This plugin will only work with Postgres database because it uses JSONB data type which is only supported by this database.
+This creates the `rails_simple_event_sourcing_events` table that stores your event log.
 
 ## Usage
 
-So how does it all work?
+### Architecture Overview
+
+The event sourcing flow follows this pattern:
 
-Let's start with the directory structure:
+```
+HTTP Request → Controller → Command → CommandHandler → Event → Aggregate (Model)
+                   ↓           ↓            ↓             ↓          ↓
+              Pass data   Parameters    Validation +   Immutable   Database
+                          + Validation   Business      Storage
+                            Rules        Logic
+```
+
+**Flow breakdown:**
+1. **Controller** - Receives request, creates command with params
+2. **Command** - Defines parameters and validation rules (ActiveModel)
+3. **CommandHandler** - Validates command, executes business logic, creates event
+4. **Event** - Immutable record of what happened
+5. **Aggregate** - Model updated via event
+
+### Directory Structure
+
+Let's start with the recommended directory structure:
 
 ```
 app/
@@ -28,17 +108,18 @@ app/
 │  │  │  ├─ create.rb
 ```
 
-The name of the top directory can be different because Rails does not namespace it.
-
-Based on the example above, the usage looks like this
+**Note:** The top directory name (`domain/`) can be different - Rails doesn't enforce this namespace.
 
-Command -> Command Handler -> Create Event (which under the hood writes changes to the appropriate model)
+### Commands
 
-Explanation of each of these blocks above:
+Commands represent **intentions** to perform actions in your system. They are responsible for:
+- Encapsulating action parameters
+- Validating input data (using ActiveModel validations)
+- Being immutable value objects
 
-- `Command` - is responsible for any action you want to take in your system, it is also responsible for validating the input parameters it takes (you can use the same validations you would normally use in models).
+Think of commands as "requests to do something" - they describe what you want to happen, not how it happens.
 
-Example:
+**Example - Create Command:**
 
 ```ruby
 class Customer
@@ -54,14 +135,53 @@ class Customer
 end
 ```
 
-- `CommandHandler` - is responsible for handling the passed command (it automatically checks if a command is valid), making additional API calls, doing additional business logic, and finally creating a proper event. This should always return the `RailsSimpleEventSourcing::Result` struct.
+### Command Handlers
+
+Command handlers contain the **business logic** for executing commands. They:
+- Automatically validate the command before execution
+- Perform business logic and API calls
+- Create events when successful
+- Handle errors gracefully
+- Return a `RailsSimpleEventSourcing::Result` object
+
+**Result Object:**
+The `Result` struct has three fields:
+- `success?` - Boolean indicating if the operation succeeded
+- `data` - Data to return (usually the aggregate/model instance)
+- `errors` - Array or hash of error messages when `success?` is false
+
+**Helper Methods:**
+The base class provides convenience methods:
+- `success_result(data:)` - Creates a successful result
+- `failure_result(errors:)` - Creates a failed result
+
+**Example - Basic Handler:**
+
+```ruby
+class Customer
+  module CommandHandlers
+    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,
+          created_at: Time.zone.now,
+          updated_at: Time.zone.now
+        )
+
+        # Using helper method (recommended)
+        success_result(data: event.aggregate)
 
-This struct has 3 keywords:
-- `success?:` true/false (if everything went well, commands are automatically validated, but there might still be an API call here, etc., so you can return false if something went wrong)
-- `data:` data that you want to return, eg. to the controller (in the example above the `event.aggregate` will return a proper instance of the Customer model)
-- `errors:` in a scenario where you set `success?:false`, you can also return some related errors here (see: test/dummy/app/domain/customer/command_handlers/create.rb for an example)
+        # Or create Result directly
+        # RailsSimpleEventSourcing::Result.new(success?: true, data: event.aggregate)
+      end
+    end
+  end
+end
+```
 
-Example:
+**Example - Handler with Error Handling:**
 
 ```ruby
 class Customer
@@ -76,42 +196,99 @@ class Customer
           updated_at: Time.zone.now
         )
 
-        RailsSimpleEventSourcing::Result.new(success?: true, data: event.aggregate)
+        success_result(data: event.aggregate)
+      rescue ActiveRecord::RecordNotUnique
+        failure_result(errors: ["Email has already been taken"])
+      rescue StandardError => e
+        failure_result(errors: ["An error occurred: #{e.message}"])
       end
     end
   end
 end
 ```
 
-- `Event` - is responsible for storing immutable data of your actions, you should use past tense for naming events since an event is something that has already happened (e.g. customer was created)
+### Events
+
+Events represent **facts** - things that have already happened in your system. They:
+- Store immutable data about state changes
+- Use past tense naming (e.g., `CustomerCreated`, not `CreateCustomer`)
+- Define which aggregate (model) they apply to
+- Are stored permanently in the event log
+
+**Key Concepts:**
+- `aggregate_class` - The model this event applies to (optional - some events may not modify models)
+- `event_attributes` - Fields stored in the event payload
+- `apply(aggregate)` - **Optional** method that applies the event to an aggregate instance
+- `aggregate_id` - Links the event to a specific aggregate instance
+
+**Example - Basic Event (Automatic Application):**
+
+```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
+```
+
+**Automatic Attribute Application:**
 
-Example:
+By default, all attributes declared in `event_attributes` will be **automatically applied** to the aggregate. You don't need to implement the `apply` method unless you have custom logic requirements.
+
+The default implementation sets each event attribute on the aggregate:
+```ruby
+# This happens automatically
+aggregate.first_name = first_name
+aggregate.last_name = last_name
+aggregate.email = email
+# ... and so on for all event_attributes
+```
+
+**Example - Custom Apply Method (When Needed):**
+
+You may still need to implement a custom `apply` method in certain cases:
+- Setting computed or derived values
+- Complex business logic during application
+- Handling nested objects or special data transformations
+- Setting the aggregate ID explicitly (though this is usually handled automatically)
 
 ```ruby
 class Customer
   module Events
     class CustomerCreated < RailsSimpleEventSourcing::Event
-      aggregate_model_name Customer
+      aggregate_class Customer
       event_attributes :first_name, :last_name, :email, :created_at, :updated_at
 
       def apply(aggregate)
+        # Custom logic example
         aggregate.id = aggregate_id
-        aggregate.first_name = first_name
-        aggregate.last_name = last_name
-        aggregate.email = email
-        aggregate.created_at = created_at
-        aggregate.updated_at = updated_at
+        aggregate.full_name = "#{first_name} #{last_name}"  # Computed value
+        aggregate.email_normalized = email.downcase.strip   # Transformation
+
+        # You can still call super to apply remaining attributes automatically
+        super
       end
     end
   end
 end
 ```
 
-In the example above:
-- `aggregate_model_name` is used for the corresponding model (each model is normally set to read-only mode since the only way to modify it should be via events), this param is optional since you can have an event that is not applied to the model, e.g. UserLoginAlreadyTaken
-- `event_attributes` - defines params that will be stored in the event and these params will be available to apply to the model via the `apply(aggregate)` method (where aggregate is an instance of your model passed in aggregate_model_name).
+**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
+- `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
 
-Here is an example of a custom controller that uses all the blocks described above:
+**Note on aggregate_class:**
+- 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
+
+### Controller Integration
+
+Here's how to wire everything together in a controller:
 
 ```ruby
 class CustomersController < ApplicationController
@@ -132,15 +309,60 @@ class CustomersController < ApplicationController
 end
 ```
 
-Now, if you make an API call using curl:
+### Update and Delete Operations
+
+**Update Example:**
+
+```ruby
+class CustomersController < ApplicationController
+  def update
+    cmd = Customer::Commands::Update.new(
+      aggregate_id: params[:id],
+      first_name: params[:first_name],
+      last_name: params[:last_name],
+      email: params[:email]
+    )
+    handler = RailsSimpleEventSourcing::CommandHandler.new(cmd).call
+
+    if handler.success?
+      render json: handler.data
+    else
+      render json: { errors: handler.errors }, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+**Delete Example:**
+
+```ruby
+class CustomersController < ApplicationController
+  def destroy
+    cmd = Customer::Commands::Delete.new(aggregate_id: params[:id])
+    handler = RailsSimpleEventSourcing::CommandHandler.new(cmd).call
+
+    if handler.success?
+      head :no_content
+    else
+      render json: { errors: handler.errors }, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+**Important:** For update and delete operations, you must pass `aggregate_id` to identify which record to modify. See the full examples in `test/dummy/app/domain/customer/`.
+
+### Testing the API
+
+Create a customer using curl:
 
 ```sh
 curl -X POST http://localhost:3000/customers \
   -H 'Content-Type: application/json' \
-  -d '{ "first_name": "John", "last_name": "Doe" }' | jq
+  -d '{ "first_name": "John", "last_name": "Doe", "email": "john@example.com" }' | jq
 ```
 
-You will get the response:
+Response:
 
 ```json
 {
@@ -152,117 +374,373 @@ You will get the response:
 }
 ```
 
-Run `rails c` and do the following:
+### Event Querying
+
+Open the Rails console (`rails c`) to explore the event log:
+
+```ruby
+# Get the customer
+customer = Customer.last
+# => #<Customer id: 1, first_name: "John", last_name: "Doe", ...>
+
+# Access all events for this customer
+customer.events
+# => [#<Customer::Events::CustomerCreated...>]
+
+# Get specific event details
+event = customer.events.first
+event.payload
+# => {"first_name"=>"John", "last_name"=>"Doe", "email"=>"john@example.com", ...}
+
+event.metadata
+# => {"request_id"=>"2a40d4f9-509b-4b49-a39f-d978679fa5ef",
+#     "request_ip"=>"::1",
+#     "request_user_agent"=>"curl/8.6.0", ...}
+
+# Query events by type
+RailsSimpleEventSourcing::Event.where(event_type: "Customer::Events::CustomerCreated")
+
+# Get events in a date range
+customer.events.where(created_at: 1.week.ago..Time.now)
+
+# Get all events for a specific aggregate
+RailsSimpleEventSourcing::Event.where(eventable_type: "Customer", eventable_id: 1)
+```
+
+**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
+- `aggregate_id` - Links to the aggregate instance
+- `eventable` - Polymorphic relation to the aggregate
+
+### Metadata Tracking
+
+To automatically capture request metadata (IP address, user agent, request ID, etc.), include the concern in your ApplicationController:
+
+**Setup:**
 
 ```ruby
-Customer.last
-=>
-#<Customer:0x0000000107e20998
- id: 1,
- first_name: "John",
- last_name: "Doe",
- created_at: Sat, 03 Aug 2024 16:52:30.829043000 UTC +00:00,
- updated_at: Sat, 03 Aug 2024 16:52:30.848243000 UTC +00:00>
-Customer.last.events
-[#<Customer::Events::CustomerCreated:0x0000000108dbcac8
-  id: 1,
-  type: "Customer::Events::CustomerCreated",
-  event_type: "Customer::Events::CustomerCreated",
-  aggregate_id: "1",
-  eventable_type: "Customer",
-  eventable_id: 1,
-  payload: {"last_name"=>"Doe", "created_at"=>"2024-08-03T16:58:59.952Z", "first_name"=>"John", "updated_at"=>"2024-08-03T16:58:59.952Z"},
-  metadata:
-   {"request_id"=>"2a40d4f9-509b-4b49-a39f-d978679fa5ef",
-    "request_ip"=>"::1",
-    "request_params"=>{"action"=>"create", "customer"=>{"last_name"=>"Doe", "first_name"=>"John"}, "last_name"=>"Doe", "controller"=>"customers", "first_name"=>"John"},
-    "request_user_agent"=>"curl/8.6.0"},
-  created_at: Sat, 03 Aug 2024 16:58:59.973815000 UTC +00:00,
-  updated_at: Sat, 03 Aug 2024 16:58:59.973815000 UTC +00:00>]
-```
-
-As you can see, customer has been created and if you check its `.events` relationship, you should see an event that created it.
-This event has the same attributes in the payload as you set using the `event_attributes` method of the `Customer::Events::CustomerCreated` class.
-There is also a metadata field, which is also defined as JSON, and you can store additional things in this field (this is just for information).
-
-To have these metadata fields populated automatically, you need to include `RailsSimpleEventSourcing::SetCurrentRequestDetails` in your ApplicationController.
-
-Example:
+class ApplicationController < ActionController::Base
+  include RailsSimpleEventSourcing::SetCurrentRequestDetails
+end
+```
+
+**Default Metadata:**
+By default, the following is captured:
+- `request_id` - Unique request identifier
+- `request_user_agent` - Client user agent
+- `request_referer` - HTTP referer
+- `request_ip` - Client IP address
+- `request_params` - Request parameters (filtered using Rails parameter filter)
 
+**Customizing Metadata:**
+Override the `event_metadata` method in your controller:
 
 ```ruby
 class ApplicationController < ActionController::Base
   include RailsSimpleEventSourcing::SetCurrentRequestDetails
+
+  def event_metadata
+    parameter_filter = ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters)
+
+    {
+      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
+    }
+  end
 end
 ```
 
-You can override metadata fields by defining the `event_metadata` method in the controller, this method should return a Hash which will be stored in the metadata field of the event.
+**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 = {...}`.
+
+### Model Configuration
 
-By default, this method looks like this:
+Models that use event sourcing should include the `RailsSimpleEventSourcing::Events` module:
 
 ```ruby
-def event_metadata
-  parameter_filter = ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters)
-
-  {
-    request_id: request.uuid,
-    request_user_agent: request.user_agent,
-    request_referer: request.referer,
-    request_ip: request.ip,
-    request_params: parameter_filter.filter(request.params)
-  }
+class Customer < ApplicationRecord
+  include RailsSimpleEventSourcing::Events
 end
 ```
 
-#### Important notice
+**This provides:**
+- `.events` association - Access all events for this aggregate
+- Read-only protection - Prevents accidental direct modifications
+- Event replay capability - Reconstruct state from events
+
+### Immutability and Read-Only Protection
+
+**Important Principles:**
+- **Events are immutable** - Once created, events should never be modified
+- **Models are read-only** - Aggregates should only be modified through events
+- Both have built-in protection against accidental changes
+
+### Soft Deletes
 
-The data stored in the events should be immutable (i.e., you shouldn't change it after it's created), so they have simple protection against accidental modification, which means that the model is marked as read-only.
+**Recommendation:** Use soft deletes instead of hard deletes to preserve event history.
 
-The same goes for models, any model that should be updated by events should include `include RailsSimpleEventSourcing::Events`, this will give you access to the `.events` relation and you will have read-only protection as well (model should only be updated by creating an event).
+**Why?**
+- Events are linked to aggregates via foreign keys
+- Hard deleting a record can orphan its events
+- Event log becomes incomplete
+- Cannot reconstruct historical state
 
-Example:
+**How to implement:**
 
 ```ruby
+# Migration
+class AddDeletedAtToCustomers < ActiveRecord::Migration[7.0]
+  def change
+    add_column :customers, :deleted_at, :datetime
+    add_index :customers, :deleted_at
+  end
+end
+
+# Model
 class Customer < ApplicationRecord
   include RailsSimpleEventSourcing::Events
+
+  scope :active, -> { where(deleted_at: nil) }
+  scope :deleted, -> { where.not(deleted_at: nil) }
+
+  def soft_delete
+    update(deleted_at: Time.current)
+  end
+end
+
+# Event
+class Customer::Events::CustomerDeleted < RailsSimpleEventSourcing::Event
+  aggregate_class Customer
+  event_attributes :deleted_at
+
+  # No need to implement apply - deleted_at will be automatically set on the aggregate
 end
 ```
 
-One thing to note here is that it would be better to do soft-deletes (mark record as deleted) instead of deleting records from the DB, since every record has relations called `events` when you have all the events that were applied to it.
+## Testing
 
-#### More examples
+### Testing Commands
 
-There is a sample application in the `test/dummy/app` directory so you can see how updates and deletes are handled.
+```ruby
+require "test_helper"
 
-## Installation
-Add this line to your application's Gemfile:
+class Customer::Commands::CreateTest < ActiveSupport::TestCase
+  test "valid command" do
+    cmd = Customer::Commands::Create.new(
+      first_name: "John",
+      last_name: "Doe",
+      email: "john@example.com"
+    )
+
+    assert cmd.valid?
+  end
+
+  test "invalid without email" do
+    cmd = Customer::Commands::Create.new(
+      first_name: "John",
+      last_name: "Doe"
+    )
+
+    assert_not cmd.valid?
+    assert_includes cmd.errors[:email], "can't be blank"
+  end
+end
+```
+
+### Testing Command Handlers
 
 ```ruby
-gem "rails_simple_event_sourcing"
+require "test_helper"
+
+class Customer::CommandHandlers::CreateTest < ActiveSupport::TestCase
+  test "creates customer and event" do
+    cmd = Customer::Commands::Create.new(
+      first_name: "John",
+      last_name: "Doe",
+      email: "john@example.com"
+    )
+
+    result = RailsSimpleEventSourcing::CommandHandler.new(cmd).call
+
+    assert result.success?
+    assert_instance_of Customer, result.data
+    assert_equal "John", result.data.first_name
+    assert_equal 1, result.data.events.count
+  end
+
+  test "handles duplicate email" do
+    # Create first customer
+    Customer::Events::CustomerCreated.create(
+      first_name: "Jane",
+      last_name: "Doe",
+      email: "john@example.com"
+    )
+
+    # Try to create duplicate
+    cmd = Customer::Commands::Create.new(
+      first_name: "John",
+      last_name: "Doe",
+      email: "john@example.com"
+    )
+
+    result = RailsSimpleEventSourcing::CommandHandler.new(cmd).call
+
+    assert_not result.success?
+    assert_includes result.errors, "Email has already been taken"
+  end
+end
 ```
 
-And then execute:
-```bash
-$ bundle
+### Testing in Controllers
+
+```ruby
+require "test_helper"
+
+class CustomersControllerTest < ActionDispatch::IntegrationTest
+  test "creates customer" do
+    post customers_url, params: {
+      first_name: "John",
+      last_name: "Doe",
+      email: "john@example.com"
+    }, as: :json
+
+    assert_response :success
+    assert_equal "John", JSON.parse(response.body)["first_name"]
+  end
+end
 ```
 
-Or install it yourself as:
-```bash
-$ gem install rails_simple_event_sourcing
+## Limitations
+
+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
+- **No Saga Support** - No built-in support for long-running processes or sagas
+- **Single Database** - Events and aggregates must be in the same database
+
+## Troubleshooting
+
+### CommandHandlerNotFoundError
+
+**Error:** `RailsSimpleEventSourcing::CommandHandler::CommandHandlerNotFoundError: Handler Customer::CommandHandlers::Create not found`
+
+**Cause:** The command handler class doesn't follow the naming convention.
+
+**Solution:** Ensure your handler namespace matches your command namespace:
+- Command: `Customer::Commands::Create`
+- Handler: `Customer::CommandHandlers::Create` (not `CustomerCommandHandlers::Create`)
+
+### undefined method 'events' for Customer
+
+**Error:** `undefined method 'events' for #<Customer>`
+
+**Cause:** The model doesn't include the `RailsSimpleEventSourcing::Events` module.
+
+**Solution:**
+```ruby
+class Customer < ApplicationRecord
+  include RailsSimpleEventSourcing::Events
+end
 ```
 
-Copy migration to your app:
+### ActiveRecord::ReadOnlyRecord when updating model
+
+**Error:** `ActiveRecord::ReadOnlyRecord: Customer is marked as readonly`
+
+**Cause:** Trying to directly modify a model that uses event sourcing.
+
+**Solution:** Create an event instead:
 ```ruby
-rails rails_simple_event_sourcing:install:migrations
+# Don't do this:
+customer.update(first_name: "Jane")
+
+# Do this:
+cmd = Customer::Commands::Update.new(aggregate_id: customer.id, first_name: "Jane", ...)
+RailsSimpleEventSourcing::CommandHandler.new(cmd).call
 ```
 
-And then run the migration in order to create the rails_simple_event_sourcing_events table (the table that will store the event log):
+### Missing aggregate_id for updates
+
+**Error:** `undefined method 'id' for nil:NilClass`
+
+**Cause:** Forgot to pass `aggregate_id` to update/delete commands.
+
+**Solution:**
 ```ruby
-rake db:migrate
+# Include aggregate_id in the command
+cmd = Customer::Commands::Update.new(
+  aggregate_id: params[:id],  # This is required
+  first_name: params[:first_name],
+  # ...
+)
+```
+
+### Metadata is empty in tests
+
+**Issue:** Event metadata is empty when creating events in tests.
+
+**Cause:** Events created outside HTTP requests don't have automatic metadata.
+
+**Solution:**
+```ruby
+# Manually set metadata in tests
+RailsSimpleEventSourcing::CurrentRequest.metadata = {
+  request_id: "test-123",
+  test_mode: true
+}
 ```
 
 ## Contributing
-Contribution directions go here.
+
+Contributions are welcome! Here's how you can help:
+
+1. **Report Bugs**: Open an issue on GitHub with:
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Ruby/Rails/PostgreSQL versions
+
+2. **Submit Pull Requests**:
+   - Fork the repository
+   - Create a feature branch (`git checkout -b feature/my-feature`)
+   - Write tests for your changes
+   - Ensure all tests pass (`rake test`)
+   - Follow existing code style
+   - Commit with clear messages
+   - Push and open a PR
+
+3. **Running Tests**:
+   ```bash
+   bundle install
+   cd test/dummy
+   rails db:create db:migrate RAILS_ENV=test
+   cd ../..
+   rake test
+   ```
+
+4. **Code Style**:
+   - Follow Ruby style guide
+   - Use RuboCop for linting
+   - Write clear, descriptive variable/method names
+   - Add comments for complex logic
+
+### More Examples
+
+See the `test/dummy/app/domain/customer/` directory for complete examples of:
+- Commands (create, update, delete)
+- Command handlers with error handling
+- Events (created, updated, deleted)
+- Controller integration
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  module AggregateConfiguration
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def aggregate_class(name = nil)
+        return @aggregate_class if name.nil?
+
+        @aggregate_class = name
+      end
+    end
+
+    def aggregate_class
+      self.class.aggregate_class
+    end
+
+    def aggregate_defined?
+      aggregate_class.present?
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  module EventAttributes
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def event_attributes(*attributes)
+        attributes.each do |attribute|
+          define_payload_accessor(attribute)
+        end
+      end
+
+      private
+
+      def define_payload_accessor(attribute)
+        define_method(attribute) do
+          self.payload ||= {}
+          self.payload[attribute.to_s]
+        end
+
+        define_method("#{attribute}=") do |value|
+          self.payload ||= {}
+          self.payload[attribute.to_s] = value
+        end
+      end
+    end
+  end
+end

data/app/models/rails_simple_event_sourcing/event.rb

@@ -2,85 +2,51 @@
 
 module RailsSimpleEventSourcing
   class Event < ApplicationRecord
+    prepend ApplyWithReturningAggregate
     include ReadOnly
+    include EventAttributes
+    include AggregateConfiguration
 
     belongs_to :eventable, polymorphic: true, optional: true
-
     alias aggregate eventable
 
-    after_initialize :initialize_event
-    before_validation :enable_write_access_on_self, if: :new_record?
-    before_validation :apply_on_aggregate, if: :aggregate_defined?
-    before_save :add_metadata
-    before_save :assing_aggregate_id_and_persist_aggregate, if: :aggregate_defined?
-
-    def self.aggregate_model_name(name)
-      singleton_class.instance_variable_set(:@aggregate_model_name, name)
-    end
-
-    def aggregate_model_name
-      self.class.singleton_class.instance_variable_get(:@aggregate_model_name)
-    end
+    # Callbacks for automatic aggregate lifecycle
+    before_validation :setup_event_fields, on: :create
+    before_validation :apply_event_to_aggregate, on: :create, if: :aggregate_defined?
+    before_save :persist_aggregate, if: :aggregate_defined?
 
-    def self.event_attributes(*attributes)
-      @event_attributes ||= []
-
-      attributes.map(&:to_s).each do |attribute|
-        define_method attribute do
-          self.payload ||= {}
-          self.payload[attribute]
-        end
-
-        define_method "#{attribute}=" do |argument|
-          self.payload ||= {}
-          self.payload[attribute] = argument
-        end
+    def apply(aggregate)
+      payload.each do |key, value|
+        aggregate.send("#{key}=", value) if aggregate.respond_to?("#{key}=") && value.present?
       end
-
-      @event_attributes
-    end
-
-    def apply(_aggregate)
-      raise NoMethodError, "You must implement #{self.class}#apply"
+      aggregate
     end
 
     private
 
-    def aggregate_defined?
-      aggregate_model_name.present?
-    end
-
-    def initialize_event
-      self.class.prepend RailsSimpleEventSourcing::ApplyWithReturningAggregate
-      @aggregate = find_or_build_aggregate if aggregate_defined?
-      self.event_type = self.class
-      self.eventable = @aggregate
-    end
-
-    def enable_write_access_on_self
+    def setup_event_fields
       enable_write_access!
+      self.event_type = self.class
+      self.metadata = CurrentRequest.metadata&.compact&.presence
     end
 
-    def apply_on_aggregate
-      @aggregate.enable_write_access!
-      apply(@aggregate)
-    end
+    def apply_event_to_aggregate
+      @aggregate_for_persistence = aggregate_repository.find_or_build(aggregate_id)
+      self.eventable = @aggregate_for_persistence
 
-    def assing_aggregate_id_and_persist_aggregate
-      @aggregate.save! if aggregate_id.present?
-      self.aggregate_id = @aggregate.id
+      applicator = EventApplicator.new(self)
+      applicator.apply_to_aggregate(@aggregate_for_persistence)
     end
 
-    def add_metadata
-      return if CurrentRequest.metadata.blank?
+    def persist_aggregate
+      return unless @aggregate_for_persistence
 
-      self.metadata = CurrentRequest.metadata.compact.presence
+      aggregate_repository.save!(@aggregate_for_persistence) if aggregate_id.present?
+      self.aggregate_id = @aggregate_for_persistence.id
     end
 
-    def find_or_build_aggregate
-      return aggregate_model_name.find(aggregate_id).lock! if aggregate_id.present?
-
-      aggregate_model_name.new
+    def aggregate_repository
+      @aggregate_repository ||= AggregateRepository.new(aggregate_class)
     end
   end
 end

data/lib/rails_simple_event_sourcing/aggregate_repository.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  class AggregateRepository
+    def initialize(aggregate_class)
+      @aggregate_class = aggregate_class
+    end
+
+    def find_or_build(aggregate_id)
+      if aggregate_id.present?
+        find_with_lock(aggregate_id)
+      else
+        build_new
+      end
+    end
+
+    def save!(aggregate)
+      aggregate.enable_write_access!
+      aggregate.save!
+    end
+
+    private
+
+    def find_with_lock(aggregate_id)
+      @aggregate_class.find(aggregate_id).lock!
+    end
+
+    def build_new
+      @aggregate_class.new
+    end
+  end
+end

data/lib/rails_simple_event_sourcing/command_handler.rb

@@ -2,6 +2,8 @@
 
 module RailsSimpleEventSourcing
   class CommandHandler
+    class CommandHandlerNotFoundError < StandardError; end
+
     def initialize(command)
       @command = command
     end
@@ -15,7 +17,11 @@ module RailsSimpleEventSourcing
     private
 
     def initialize_command_handler
-      @command.class.to_s.gsub('::Commands::', '::CommandHandlers::').constantize.new(command: @command)
+      handler_class_name = @command.class.to_s.gsub('::Commands::', '::CommandHandlers::')
+      handler_class = handler_class_name.safe_constantize
+      raise CommandHandlerNotFoundError, "Handler #{handler_class_name} not found" unless handler_class
+
+      handler_class.new(command: @command)
     end
   end
 end

data/lib/rails_simple_event_sourcing/command_handlers/base.rb

@@ -10,6 +10,14 @@ module RailsSimpleEventSourcing
       def call
         raise NoMethodError, "You must implement #{self.class}#call"
       end
+
+      def success_result(data: nil)
+        RailsSimpleEventSourcing::Result.new(success?: true, data:)
+      end
+
+      def failure_result(errors:)
+        RailsSimpleEventSourcing::Result.new(success?: false, errors:)
+      end
     end
   end
 end

data/lib/rails_simple_event_sourcing/engine.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
+require_relative 'aggregate_repository'
+require_relative 'apply_with_returning_aggregate'
+require_relative 'command_handler'
 require_relative 'command_handlers/base'
 require_relative 'commands/base'
-require_relative 'command_handler'
-require_relative 'apply_with_returning_aggregate'
+require_relative 'event_applicator'
+require_relative 'event_player'
 require_relative 'result'
 
 module RailsSimpleEventSourcing

data/lib/rails_simple_event_sourcing/event_applicator.rb

@@ -0,0 +1,32 @@
+# 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

data/lib/rails_simple_event_sourcing/event_player.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  class EventPlayer
+    def initialize(aggregate)
+      @aggregate = aggregate
+    end
+
+    def replay_stream
+      events = load_event_stream
+      apply_events(events)
+    end
+
+    private
+
+    def load_event_stream
+      @aggregate.events.order(created_at: :asc)
+    end
+
+    def apply_events(events)
+      events.each do |event|
+        event.apply(@aggregate)
+      end
+    end
+  end
+end

data/lib/rails_simple_event_sourcing/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_simple_event_sourcing
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Damian Baćkowski
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-08 00:00:00.000000000 Z
+date: 2026-01-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg
@@ -78,6 +78,8 @@ files:
 - Rakefile
 - app/assets/config/rails_simple_event_sourcing_manifest.js
 - app/controllers/concerns/rails_simple_event_sourcing/set_current_request_details.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
 - app/models/concerns/rails_simple_event_sourcing/read_only.rb
 - app/models/rails_simple_event_sourcing.rb
@@ -86,11 +88,14 @@ 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_repository.rb
 - lib/rails_simple_event_sourcing/apply_with_returning_aggregate.rb
 - lib/rails_simple_event_sourcing/command_handler.rb
 - lib/rails_simple_event_sourcing/command_handlers/base.rb
 - lib/rails_simple_event_sourcing/commands/base.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/result.rb
 - lib/rails_simple_event_sourcing/version.rb
 - lib/tasks/rails_simple_event_sourcing_tasks.rake
@@ -114,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.4.21
 signing_key:
 specification_version: 4
 summary: Rails engine for simple event sourcing.