ruby_event_store-process_manager 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 459fcf11b24e60ad73c40d07162b3580da26c0a219330fa07a14a566274f1bb3
+  data.tar.gz: 8d570d1bfa61aa1f6f8d998d1003fcccf2589e46b56f18bc1f956f122915c027
+SHA512:
+  metadata.gz: f3dd0d8b9a41458c621dc6bce7de3f01982a321f07c5979a1246d726e9c18ab34330a203566f85d8635288984fc03fb030153d495d2d0b9d38f69a15cff4f685
+  data.tar.gz: fbe268a31631a812682d10c26370e0a853dc83b148b2b9ca8097c2fc7b33d70cb7051f01c5f935524394b27b4df049d527fed9a981c457eccd87a2ffe49e1be4

data/README.md

@@ -0,0 +1,75 @@
+# ruby_event_store-process_manager
+
+Build stateful process managers on top of [RubyEventStore](https://railseventstore.org). The state is rebuilt from events before each reaction, so a process can coordinate events from multiple parts of an application without a separate state store.
+
+## Installation
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem "ruby_event_store-process_manager"
+```
+
+## Usage
+
+This process releases an authorized payment when its order expires:
+
+```ruby
+class ReleasePaymentOnOrderExpiration
+  include RubyEventStore::ProcessManager.with_state { ProcessState }
+
+  subscribes_to(
+    Payments::PaymentAuthorized,
+    Payments::PaymentReleased,
+    Pricing::OfferExpired
+  )
+
+  private
+
+  def fetch_id(event)
+    event.data.fetch(:order_id)
+  end
+
+  def apply(event)
+    case event
+    when Payments::PaymentAuthorized
+      state.with(payment_authorized: true)
+    when Payments::PaymentReleased
+      state.with(payment_authorized: false)
+    when Pricing::OfferExpired
+      state.with(order_expired: true)
+    else
+      state
+    end
+  end
+
+  def act
+    command_bus.call(Payments::ReleasePayment.new(order_id: id)) if state.release?
+  end
+
+  ProcessState = Data.define(:payment_authorized, :order_expired) do
+    def initialize(payment_authorized: false, order_expired: false) = super
+
+    def release?
+      payment_authorized && order_expired
+    end
+  end
+end
+```
+
+Subscribe it to the event store:
+
+```ruby
+process = ReleasePaymentOnOrderExpiration.new(event_store, command_bus)
+
+event_store.subscribe(
+  process,
+  to: ReleasePaymentOnOrderExpiration.subscribed_events
+)
+```
+
+`fetch_id` identifies the process instance, `apply` evolves its state, and `act` issues commands based on the rebuilt state. The state class must support a no-argument constructor. `apply` must always return the next state, including for events that do not change it.
+
+## License
+
+MIT

data/lib/ruby_event_store/process_manager/retry.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RubyEventStore
+  module ProcessManager
+    module Retry
+      def with_retry
+        yield
+      rescue RubyEventStore::WrongExpectedEventVersion
+        yield
+      end
+    end
+  end
+end

data/lib/ruby_event_store/process_manager/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyEventStore
+  module ProcessManager
+    VERSION = "0.1.0"
+  end
+end

data/lib/ruby_event_store/process_manager.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "process_manager/version"
+require_relative "process_manager/retry"
+
+module RubyEventStore
+  module ProcessManager
+    module ProcessMethods
+      def initialize(event_store, command_bus)
+        @event_store = event_store
+        @command_bus = command_bus
+      end
+
+      def call(event)
+        @state = initial_state
+        @id = fetch_id(event)
+        build_state(event)
+        act
+      end
+
+      private
+
+      attr_reader :event_store, :command_bus, :id
+
+      def build_state(event)
+        with_retry do
+          past_events = event_store.read.stream(stream_name).to_a
+          last_stored = past_events.size - 1
+          event_store.link(event.event_id, stream_name:, expected_version: last_stored)
+          (past_events + [event]).each { |ev| @state = apply(ev) }
+        end
+      end
+
+      def stream_name
+        "#{self.class.name}$#{id}"
+      end
+    end
+
+    module Subscriptions
+      def self.extended(host_class)
+        host_class.instance_variable_set(:@subscribed_events, [])
+      end
+
+      def subscribes_to(*events)
+        @subscribed_events += events
+      end
+
+      attr_reader :subscribed_events
+    end
+
+    def self.with_state(&state_class_block)
+      unless block_given?
+        raise ArgumentError, "A block returning the state class is required."
+      end
+
+      Module.new do
+        @state_definition_block = state_class_block
+
+        define_method(:initial_state) do
+          block = self.class.instance_variable_get(:@state_definition_block)
+          raise "State definition block not found on #{self.class}" unless block
+
+          state_class = block.call
+          raise "State definition block did not return a Class" unless state_class.is_a?(Class)
+
+          state_class.new
+        end
+
+        define_method(:state) do
+          @state
+        end
+
+        def self.included(host_class)
+          host_class.instance_variable_set(:@state_definition_block, @state_definition_block)
+
+          host_class.include(ProcessMethods)
+          host_class.include(Retry)
+          host_class.extend(Subscriptions)
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: ruby_event_store-process_manager
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Arkency
+bindir: bin
+cert_chain: []
+date: 2026-07-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_event_store
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+email: dev@arkency.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/ruby_event_store/process_manager.rb
+- lib/ruby_event_store/process_manager/retry.rb
+- lib/ruby_event_store/process_manager/version.rb
+homepage: https://railseventstore.org
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://railseventstore.org
+  source_code_uri: https://github.com/RailsEventStore/rails_event_store
+  bug_tracker_uri: https://github.com/RailsEventStore/rails_event_store/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Stateful process manager with event-sourced state for RubyEventStore
+test_files: []