rails_simple_event_sourcing 1.0.10 → 1.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 363c7b48bf081711402a94d5173386ba8e1ffd509ac33c89ce7bde1a853060c9
-  data.tar.gz: 24d5817b59610902c2aae1a1e7b843163b0a07970c6c26cceab78ba9cb006453
+  metadata.gz: d389be62e627ddf2443c6e7d781d1abbab7aaacf7b908741a753e4dbe370c978
+  data.tar.gz: 4dea2cb2546bd903a566edff8f0fb192be5b02ae1f45f36004cf58ba7d30a64a
 SHA512:
-  metadata.gz: 1e3265492aec66a1a4fc6727e528dcc0116682c292a6cb84b40fe8498ac87c930db16fec5c00dca3294ec840834ff18cd6795baabd6ab59e58bb9e6a54e5401a
-  data.tar.gz: 0d4b556f0c895d4d029aedfb80ba397e78bfcf1abb050c7d10a6b9ddc1177da92658cfa0f7d7ab245583cdfdbd1af9188b61dbe2b37619895df2c11204c12b5a
+  metadata.gz: 2e7671967605ab8714cdb39dec920b7fc1449bf4c4adedd77cf409fa89db7497e2f462c1176decb149d9191b01cdd973e88708de836c8f7f88bef98328246608
+  data.tar.gz: a3543ef2e0dd176bb85099be1b4d65e9cc0f148644eb5011435920325447114218f84fff9fa6a4721d462e35c2d1568f9ba4665648ff27b26fc7d3cdab550526

data/README.md

@@ -22,6 +22,7 @@ If you need a more comprehensive solution, check out:
   - [Metadata Tracking](#metadata-tracking)
   - [Event Querying](#event-querying)
   - [Events Viewer](#events-viewer)
+  - [Event Subscriptions](#event-subscriptions)
 - [Testing](#testing)
 - [Limitations](#limitations)
 - [Troubleshooting](#troubleshooting)
@@ -40,12 +41,13 @@ If you need a more comprehensive solution, check out:
 - **Simple Command Pattern** - Clear command → handler → event flow
 - **PostgreSQL JSONB Storage** - Efficient JSON storage for event payloads and metadata
 - **Built-in Events Viewer** - Web UI for browsing, searching, and inspecting events
+- **Event Subscriptions** - React to events after they are committed (send emails, send webhooks, etc.)
 - **Minimal Configuration** - Convention over configuration approach
 
 ## Requirements
 
-- **Ruby**: 2.7 or higher
-- **Rails**: 6.0 or higher
+- **Ruby**: 3.2 or higher
+- **Rails**: 7.1.2 or higher
 - **Database**: PostgreSQL 9.4+ (requires JSONB support)
 
 ## Installation
@@ -175,6 +177,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
 
@@ -192,7 +195,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)
@@ -203,9 +206,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:**
@@ -221,9 +225,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
         )
@@ -243,9 +247,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
         )
@@ -667,6 +671,86 @@ class Customer::Events::CustomerDeleted < RailsSimpleEventSourcing::Event
 end
 ```
 
+### 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.
+
+**Registering subscribers:**
+
+```ruby
+# config/initializers/rails_simple_event_sourcing.rb
+Rails.application.config.after_initialize do
+  RailsSimpleEventSourcing::EventBus.subscribe(
+    Customer::Events::CustomerCreated,
+    Subscribers::SendWelcomeEmail
+  )
+
+  RailsSimpleEventSourcing::EventBus.subscribe(
+    Customer::Events::CustomerCreated,
+    Subscribers::CreateStripeCustomer
+  )
+
+  RailsSimpleEventSourcing::EventBus.subscribe(
+    Customer::Events::CustomerDeleted,
+    Subscribers::CancelStripeSubscription
+  )
+end
+```
+
+**Writing a subscriber:**
+
+Any object that responds to `call(event)` works — a class with `.call`, a lambda, or a proc:
+
+```ruby
+module Subscribers
+  class SendWelcomeEmail
+    def self.call(event)
+      WelcomeMailer.with(email: event.email).deliver_later
+    end
+  end
+end
+```
+
+**Subscribing to all events:**
+
+Subscribe to `RailsSimpleEventSourcing::Event` to receive every event regardless of type — useful for audit loggers or metrics:
+
+```ruby
+RailsSimpleEventSourcing::EventBus.subscribe(
+  RailsSimpleEventSourcing::Event,
+  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.
+
+**Testing with EventBus:**
+
+Call `RailsSimpleEventSourcing::EventBus.reset!` in your test `setup` to clear all subscriptions between tests:
+
+```ruby
+class MyTest < ActiveSupport::TestCase
+  setup do
+    RailsSimpleEventSourcing::EventBus.reset!
+  end
+
+  test "sends welcome email on customer created" do
+    emails = []
+    RailsSimpleEventSourcing::EventBus.subscribe(
+      Customer::Events::CustomerCreated,
+      ->(event) { emails << event.email }
+    )
+
+    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_includes emails, "john@example.com"
+  end
+end
+```
+
 ## Testing
 
 ### Setting Up Tests with Command Handler Registry

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

@@ -6,7 +6,7 @@ module RailsSimpleEventSourcing
 
     included do
       def readonly?
-        super || !write_access_enabled
+        super || !write_access_enabled?
       end
 
       def enable_write_access!
@@ -19,8 +19,8 @@ module RailsSimpleEventSourcing
 
       private
 
-      def write_access_enabled
-        @write_access_enabled ||= false
+      def write_access_enabled?
+        @write_access_enabled == true
       end
     end
   end

data/app/models/rails_simple_event_sourcing/event.rb

@@ -20,6 +20,7 @@ module RailsSimpleEventSourcing
     before_validation :setup_for_create, on: :create
     before_save :persist_aggregate, if: :aggregate_defined?
     after_create :disable_write_access!
+    after_commit :dispatch_to_event_bus, on: :create
 
     def apply(aggregate)
       payload.each do |key, value|
@@ -81,5 +82,9 @@ module RailsSimpleEventSourcing
     def aggregate_repository
       @aggregate_repository ||= AggregateRepository.new(aggregate_class)
     end
+
+    def dispatch_to_event_bus
+      EventBus.dispatch(self)
+    end
   end
 end

data/db/migrate/20231231133250_create_rails_simple_event_sourcing_events.rb

@@ -7,7 +7,7 @@ class CreateRailsSimpleEventSourcingEvents < ActiveRecord::Migration[7.1]
       t.string :type, null: false
       t.string :event_type, null: false
       t.string :aggregate_id
-      t.integer :version
+      t.bigint :version
       t.jsonb :payload
       t.jsonb :metadata
 
@@ -15,7 +15,9 @@ class CreateRailsSimpleEventSourcingEvents < ActiveRecord::Migration[7.1]
 
       t.index :type
       t.index :event_type
-      t.index %i[aggregate_id version], unique: true, name: 'index_events_on_aggregate_id_and_version'
+      t.index %i[eventable_type aggregate_id version],
+              unique: true,
+              name: 'index_events_on_eventable_type_and_aggregate_id_and_version'
       t.index :payload, using: :gin
       t.index :metadata, using: :gin
     end

data/lib/rails_simple_event_sourcing/aggregate_repository.rb

@@ -21,7 +21,7 @@ module RailsSimpleEventSourcing
     private
 
     def find_with_lock(aggregate_id)
-      @aggregate_class.find(aggregate_id).lock!
+      @aggregate_class.lock.find(aggregate_id)
     end
 
     def build_new

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

@@ -10,6 +10,7 @@ require_relative 'event_search'
 require_relative 'paginator'
 require_relative 'result'
 require_relative 'command_handler_registry'
+require_relative 'event_bus'
 
 module RailsSimpleEventSourcing
   class Engine < ::Rails::Engine

data/lib/rails_simple_event_sourcing/event_bus.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  class EventBus
+    @subscriptions = Concurrent::Map.new { |h, k| h[k] = Concurrent::Array.new }
+
+    class << self
+      def subscribe(event_class, subscriber)
+        @subscriptions[event_class.to_s] << subscriber
+      end
+
+      def dispatch(event)
+        ancestors_with_subscriptions(event).each do |subscriber|
+          subscriber.call(event)
+        end
+      end
+
+      def reset!
+        @subscriptions = Concurrent::Map.new { |h, k| h[k] = Concurrent::Array.new }
+      end
+
+      private
+
+      def ancestors_with_subscriptions(event)
+        event.class.ancestors
+             .select { |ancestor| @subscriptions.key?(ancestor.to_s) }
+             .flat_map { |ancestor| @subscriptions[ancestor.to_s] }
+      end
+    end
+  end
+end

data/lib/rails_simple_event_sourcing/paginator.rb

@@ -37,33 +37,31 @@ module RailsSimpleEventSourcing
 
     def fetch_records
       if @cursor.nil?
-        fetch_first_page
+        fetch_forward(@scope.order(id: :desc), has_prev: false)
       elsif @direction == :prev
-        fetch_prev_page
+        fetch_backward(@scope.where('id > ?', @cursor).order(id: :asc))
       else
-        fetch_next_page
+        fetch_forward(@scope.where(id: ...@cursor).order(id: :desc), has_prev: true)
       end
     end
 
-    def fetch_first_page
-      rows = @scope.order(id: :desc).limit(@per_page + 1).to_a
-      @has_prev = false
-      @has_next = rows.size > @per_page
-      rows.first(@per_page)
+    def fetch_forward(scoped_query, has_prev:)
+      rows, has_more = paginate(scoped_query)
+      @has_prev = has_prev
+      @has_next = has_more
+      rows
     end
 
-    def fetch_next_page
-      rows = @scope.where(id: ...@cursor).order(id: :desc).limit(@per_page + 1).to_a
-      @has_prev = true
-      @has_next = rows.size > @per_page
-      rows.first(@per_page)
+    def fetch_backward(scoped_query)
+      rows, has_more = paginate(scoped_query)
+      @has_next = true
+      @has_prev = has_more
+      rows.reverse
     end
 
-    def fetch_prev_page
-      rows = @scope.where('id > ?', @cursor).order(id: :asc).limit(@per_page + 1).to_a
-      @has_next = true
-      @has_prev = rows.size > @per_page
-      rows.first(@per_page).reverse
+    def paginate(scoped_query)
+      rows = scoped_query.limit(@per_page + 1).to_a
+      [rows.first(@per_page), rows.size > @per_page]
     end
   end
 end

data/lib/rails_simple_event_sourcing/result.rb

@@ -25,6 +25,10 @@ module RailsSimpleEventSourcing
       @success
     end
 
+    def failure?
+      !@success
+    end
+
     def on_success(&block)
       raise ArgumentError, 'Block required' unless block
 

data/lib/rails_simple_event_sourcing/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_simple_event_sourcing
 version: !ruby/object:Gem::Version
-  version: 1.0.10
+  version: 1.0.12
 platform: ruby
 authors:
 - Damian Baćkowski
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-08 00:00:00.000000000 Z
+date: 2026-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg
@@ -94,7 +94,6 @@ files:
 - app/controllers/concerns/rails_simple_event_sourcing/set_current_request_details.rb
 - app/controllers/rails_simple_event_sourcing/application_controller.rb
 - app/controllers/rails_simple_event_sourcing/events_controller.rb
-- app/helpers/rails_simple_event_sourcing/events_helper.rb
 - app/models/concerns/rails_simple_event_sourcing/aggregate_configuration.rb
 - app/models/concerns/rails_simple_event_sourcing/event_attributes.rb
 - app/models/concerns/rails_simple_event_sourcing/events.rb
@@ -116,6 +115,7 @@ files:
 - lib/rails_simple_event_sourcing/commands/base.rb
 - lib/rails_simple_event_sourcing/configuration.rb
 - lib/rails_simple_event_sourcing/engine.rb
+- lib/rails_simple_event_sourcing/event_bus.rb
 - lib/rails_simple_event_sourcing/event_player.rb
 - lib/rails_simple_event_sourcing/event_search.rb
 - lib/rails_simple_event_sourcing/paginator.rb
@@ -135,7 +135,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/app/helpers/rails_simple_event_sourcing/events_helper.rb

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