rails_simple_event_sourcing 1.0.3 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be05ef0dea303db4860a86e10e0ed0d62b5e03de00e07ee80ad374f95e20cc1e
-  data.tar.gz: 3eaaf851f72b6a84358e7908a55c2ddc437217467786fac57d658edcc4c70b30
+  metadata.gz: 8bae2bfe7377ee1c5b4db35484463b437c75c8c9822791aef21867d749abd3fc
+  data.tar.gz: b025d6954826b5a1583d0531da3e816386e407c0b26803e903b1c700ecaab2a1
 SHA512:
-  metadata.gz: e19d692f980963be17d5adb2a55678a57be33fb65b04046215d44a1bd48181abfebcc2f3ea8d8cfaf4946570bcf8fb25b0abbc48e28fe7b6a85d253f4b51ca71
-  data.tar.gz: 65ad82bb88d8feae84ea47514debdd95532144830e07d65b36c4482f07ad095de5d374e2e6fb77dcace25984a885b8cc63b79fc729a3854f041b95129e4b923b
+  metadata.gz: d3f40d21d78f8d5a978086439521814a9f3903eda901669b88cafc070ab8c01fd7664cb9e5cfefa35c401384c780bc867137e9486e3d3ee37d58ae4ffa3938f6
+  data.tar.gz: 3aa5edd3c94f4fe350c5409371430e7e242bdfef76e472bd9f394d011b69b97b295438c3161f2d70c38e7cdb1ca42b4d1f59b335994f175cdbd76f86ebd8b0e1

data/README.md

@@ -10,11 +10,13 @@ If you need a more comprehensive solution, check out:
 - [Features](#features)
 - [Requirements](#requirements)
 - [Installation](#installation)
+- [Configuration](#configuration)
 - [Usage](#usage)
   - [Directory Structure](#directory-structure)
   - [Commands](#commands)
   - [Command Handlers](#command-handlers)
   - [Events](#events)
+  - [Registering Command Handlers](#registering-command-handlers)
   - [Controller Integration](#controller-integration)
   - [Update and Delete Operations](#update-and-delete-operations)
   - [Metadata Tracking](#metadata-tracking)
@@ -22,6 +24,8 @@ If you need a more comprehensive solution, check out:
 - [Testing](#testing)
 - [Limitations](#limitations)
 - [Troubleshooting](#troubleshooting)
+  - [Command Handler Registry](#command-handler-registry)
+  - [CommandHandlerNotFoundError](#commandhandlernotfounderror)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -31,6 +35,7 @@ If you need a more comprehensive solution, check out:
 - **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
+- **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
 - **Minimal Configuration** - Convention over configuration approach
@@ -71,6 +76,19 @@ rake db:migrate
 
 This creates the `rails_simple_event_sourcing_events` table that stores your event log.
 
+## Configuration
+
+You can configure the behavior of the gem using the configuration block:
+
+```ruby
+# config/initializers/rails_simple_event_sourcing.rb
+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
+end
+```
+
 ## Usage
 
 ### Architecture Overview
@@ -144,6 +162,11 @@ Command handlers contain the **business logic** for executing commands. They:
 - Handle errors gracefully
 - Return a `RailsSimpleEventSourcing::Result` object
 
+**Handler Discovery:**
+Handlers can be discovered in two ways:
+1. **Explicit Registration** (recommended) - Using the `CommandHandlerRegistry` to register handlers
+2. **Convention-based** - Using naming convention mapping (can be disabled via configuration)
+
 **Result Object:**
 The `Result` struct has three fields:
 - `success?` - Boolean indicating if the operation succeeded
@@ -286,6 +309,38 @@ 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
 
+### 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.
+
+```ruby
+# config/initializers/rails_simple_event_sourcing.rb
+
+RailsSimpleEventSourcing.configure do |config|
+  config.use_naming_convention_fallback = false
+end
+
+Rails.application.config.after_initialize do
+  # Register all command handlers
+  RailsSimpleEventSourcing::CommandHandlerRegistry.register(
+    Customer::Commands::Create,
+    Customer::CommandHandlers::Create
+  )
+
+  RailsSimpleEventSourcing::CommandHandlerRegistry.register(
+    Customer::Commands::Update,
+    Customer::CommandHandlers::Update
+  )
+
+  RailsSimpleEventSourcing::CommandHandlerRegistry.register(
+    Customer::Commands::Delete,
+    Customer::CommandHandlers::Delete
+  )
+end
+```
+
+If you prefer the convention-based approach, you don't need to take any action, as the use_naming_convention_fallback is set to true by default.
+
 ### Controller Integration
 
 Here's how to wire everything together in a controller:
@@ -525,6 +580,35 @@ end
 
 ## Testing
 
+### Setting Up Tests with Command Handler Registry
+
+If you're using the command handler registry with `use_naming_convention_fallback = false`, you'll need to register your command handlers in your tests. There are a few approaches to handling this:
+
+1. **Create an initializer in the test app:**
+
+```ruby
+# test/dummy/config/initializers/rails_simple_event_sourcing.rb
+Rails.application.config.after_initialize do
+  RailsSimpleEventSourcing::CommandHandlerRegistry.register(
+    Customer::Commands::Create,
+    Customer::CommandHandlers::Create
+  )
+  # Register other handlers...
+end
+```
+
+2. **Register in test_helper.rb:**
+
+```ruby
+# test/test_helper.rb
+# After requiring the environment
+RailsSimpleEventSourcing::CommandHandlerRegistry.register(
+  Customer::Commands::Create,
+  Customer::CommandHandlers::Create
+)
+# Register other handlers...
+```
+
 ### Testing Commands
 
 ```ruby
@@ -630,15 +714,51 @@ Be aware of these limitations when using this gem:
 
 ## Troubleshooting
 
+### Command Handler Registry
+
+The gem provides a registry pattern for explicitly mapping commands to their handlers. This is a more robust alternative to the convention-based mapping.
+
+**Configuration:**
+
+```ruby
+# config/initializers/rails_simple_event_sourcing.rb
+RailsSimpleEventSourcing.configure do |config|
+  # Set to false to disable convention-based mapping
+  config.use_naming_convention_fallback = false
+end
+
+# Register command handlers
+Rails.application.config.after_initialize do
+  RailsSimpleEventSourcing::CommandHandlerRegistry.register(
+    Customer::Commands::Create,
+    Customer::CommandHandlers::Create
+  )
+
+  RailsSimpleEventSourcing::CommandHandlerRegistry.register(
+    Customer::Commands::Update,
+    Customer::CommandHandlers::Update
+  )
+
+  RailsSimpleEventSourcing::CommandHandlerRegistry.register(
+    Customer::Commands::Delete,
+    Customer::CommandHandlers::Delete
+  )
+end
+```
+
 ### CommandHandlerNotFoundError
 
-**Error:** `RailsSimpleEventSourcing::CommandHandler::CommandHandlerNotFoundError: Handler Customer::CommandHandlers::Create not found`
+**Error:** `RailsSimpleEventSourcing::CommandHandler::CommandHandlerNotFoundError: Handler Customer::CommandHandlers::Create not found` or `No handler registered for Customer::Commands::Create`
 
-**Cause:** The command handler class doesn't follow the naming convention.
+**Causes:**
+1. The command handler class doesn't follow the naming convention (when using convention-based mapping)
+2. The command handler hasn't been registered with the registry (when using explicit registration)
 
-**Solution:** Ensure your handler namespace matches your command namespace:
-- Command: `Customer::Commands::Create`
-- Handler: `Customer::CommandHandlers::Create` (not `CustomerCommandHandlers::Create`)
+**Solutions:**
+1. Ensure your handler namespace matches your command namespace:
+   - Command: `Customer::Commands::Create`
+   - Handler: `Customer::CommandHandlers::Create` (not `CustomerCommandHandlers::Create`)
+2. Register your command handlers using the registry pattern shown above
 
 ### undefined method 'events' for Customer
 

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

@@ -5,12 +5,14 @@ module RailsSimpleEventSourcing
     extend ActiveSupport::Concern
 
     included do
+      attribute :write_access_enabled, :boolean, default: false
+
       def readonly?
-        super || !@write_access_enabled
+        super || !write_access_enabled
       end
 
       def enable_write_access!
-        @write_access_enabled = true
+        self.write_access_enabled = true
       end
     end
   end

data/lib/rails_simple_event_sourcing/command_handler.rb

@@ -17,11 +17,26 @@ module RailsSimpleEventSourcing
     private
 
     def initialize_command_handler
-      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 = find_handler_class
+      raise CommandHandlerNotFoundError, handler_not_found_message unless handler_class
 
       handler_class.new(command: @command)
     end
+
+    def find_handler_class
+      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
+      end
+
+      handler_class
+    end
+
+    def handler_not_found_message
+      "No handler registered for #{@command.class}. " \
+        "Register one with CommandHandlerRegistry.register(#{@command.class}, YourHandlerClass)"
+    end
   end
 end

data/lib/rails_simple_event_sourcing/command_handler_registry.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  class CommandHandlerRegistry
+    def self.register(command_class, handler_class)
+      registry[command_class] = handler_class
+    end
+
+    def self.handler_for(command_class)
+      registry[command_class]
+    end
+
+    def self.registry
+      @registry ||= {}
+    end
+
+    def self.clear
+      @registry = {}
+    end
+  end
+end

data/lib/rails_simple_event_sourcing/configuration.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  class Configuration
+    attr_accessor :use_naming_convention_fallback
+
+    def initialize
+      @use_naming_convention_fallback = true
+    end
+  end
+end

data/lib/rails_simple_event_sourcing/engine.rb

@@ -8,6 +8,7 @@ require_relative 'commands/base'
 require_relative 'event_applicator'
 require_relative 'event_player'
 require_relative 'result'
+require_relative 'command_handler_registry'
 
 module RailsSimpleEventSourcing
   class Engine < ::Rails::Engine

data/lib/rails_simple_event_sourcing/version.rb

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

data/lib/rails_simple_event_sourcing.rb

@@ -2,7 +2,16 @@
 
 require 'rails_simple_event_sourcing/version'
 require 'rails_simple_event_sourcing/engine'
+require 'rails_simple_event_sourcing/configuration'
+require 'rails_simple_event_sourcing/command_handler_registry'
 
 module RailsSimpleEventSourcing
-  # Your code goes here...
+  def self.configure
+    yield(config) if block_given?
+    config
+  end
+
+  def self.config
+    @config ||= Configuration.new
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_simple_event_sourcing
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.4
 platform: ruby
 authors:
 - Damian Baćkowski
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-13 00:00:00.000000000 Z
+date: 2026-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg
@@ -91,8 +91,10 @@ files:
 - 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_handler_registry.rb
 - lib/rails_simple_event_sourcing/command_handlers/base.rb
 - 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