circulator 2.1.8 → 2.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad89c887b2b9cb0b3fc2a12bb0a8da92480828f4d8bb594700233f4b1c0ee9fd
-  data.tar.gz: 4400d66545332b1bd4bc09028611efe7ce04a06076520e1f8a860f3089bb8d49
+  metadata.gz: 8c4d63bee9efd4c305309b4e77b502e378ad2a8ec7f550b85a25d9f9b1963f9f
+  data.tar.gz: 281ebeb9de99be8dac7b6925ae7d3d51727c54916bca3f9df7c86b6aa5014966
 SHA512:
-  metadata.gz: 31d7f74c6167dd0c0e51180d8cb585a5da27a9cab543bc32b0ec2da1c819ccd0cff3920446b94496baa36cf2b4005610f535054ce863a08f2ac691ca6ee70ff2
-  data.tar.gz: 4fcf8a370b45aa9d883c5ce4b10f4b714b66c5d5f4f5cdf638281ee01f5636687505c1be94297e5abb072f1de5db8b082edd500cd0b9ccaa769a08a280de743e
+  metadata.gz: b9d5d21fb96c45580fd3051b084403aba315d058eee4edb56dfdb4c7b10cc49105b277e60d96c895d4ae0014e0a0298ff79878f4f3a1b61f35b8c480543f491a
+  data.tar.gz: fd20a62b795f3817877c48b8ca810dde022615df11cd100506265436958e4e7326791d8a2dda6b13f898327e5c295f076800d541bc900986524b000ebdc812d9

data/CHANGELOG.md

@@ -5,8 +5,8 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [2.1.8] - 2026-01-07
+## [2.1.10] - 2026-02-06
 
 ### Added
 
-- Detailed conditional information display in DOT and PlantUML diagrams (dce5b69)
+- `around` block in flow DSL to wrap transition logic (state read, guards, state change, callbacks) (184527b)

data/README.md

@@ -10,6 +10,7 @@ A lightweight and flexible state machine implementation for Ruby that allows you
 - **Conditional Transitions**: Support for guards and conditional logic
 - **Nested State Dependencies**: State machines can depend on the state of other attributes
 - **Transition Callbacks**: Execute code before, during, or after transitions
+- **Around Wrapping**: Wrap all transitions in a flow with shared logic (e.g., `with_lock`)
 - **Multiple State Machines**: Define multiple independent state machines per class
 - **Framework Agnostic**: Works with plain Ruby objects, no Rails or ActiveRecord required
 - **100% Test Coverage**: Thoroughly tested with comprehensive test suite
@@ -293,6 +294,68 @@ class Payment
 end
 ```
 
+#### Wrapping Transitions with `around`
+
+Use the `around` block to wrap all transitions in a flow with shared logic. The block receives a `transition` proc that you must call for the transition to execute:
+
+```ruby
+class Order
+  extend Circulator
+
+  attr_accessor :status
+
+  flow :status do
+    around do |transition|
+      puts "before transition"
+      transition.call
+      puts "after transition"
+    end
+
+    state :pending do
+      action :approve, to: :approved
+    end
+  end
+end
+```
+
+The `around` block is `instance_exec`'d on the instance (consistent with transition blocks and `allow_if` procs), so `self` is the object being transitioned.
+
+**Transactional safety with ActiveRecord:**
+
+This is particularly useful for wrapping transitions in a database lock to prevent race conditions:
+
+```ruby
+class Order < ApplicationRecord
+  extend Circulator
+
+  flow :status do
+    around do |transition|
+      with_lock { transition.call }
+    end
+
+    state :pending do
+      action :approve, to: :approved do
+        self.approved_at = Time.current
+      end
+    end
+
+    state :approved do
+      action :ship, to: :shipped
+    end
+  end
+end
+
+# The guard check, transition block, state change, and caller block
+# all execute inside the lock — no wrapper methods needed
+order.status_approve
+```
+
+**Key behaviors:**
+
+- The state read, guard checks (`allow_if`), and state change all run **inside** the wrapper, so the entire check-then-act sequence is atomic
+- If `transition.call` is never called, the transition does not execute
+- Each flow can have its own `around` block (or none) — flows without one behave exactly as before
+
 #### Extending Flows
 
 You can extend existing flows using `Circulator.extension`. This is useful for plugins, multi-tenant applications, or conditional feature enhancement. Extensions are registered globally and automatically applied when a class defines its flow.
@@ -338,7 +401,7 @@ doc.status_revise  # => :draft (from extension)
 
 **How Extensions Work:**
 
-Extensions are registered globally using `Circulator.extension(class_name, attribute)` and are automatically applied when the class defines its flow. Multiple extensions can be registered for the same class/attribute and are applied in registration order. Extensions must be registered before the class definition (typically in initializers).
+Extensions are registered globally using `Circulator.extension(class_name, attribute)` and are automatically applied when the class defines its flow. Multiple extensions can be registered for the same class/attribute and are applied in registration order. Extensions can be registered before or after the class definition—if registered after, they are applied immediately to the existing flow.
 
 By default, when an extension defines the same action from the same state as the base flow, the extension completely replaces the base definition (last-defined wins). To implement intelligent composition where extensions add their conditions/blocks additively, your application can configure a custom `flows_proc` that uses a Hash-like object with merge logic. Circulator remains dependency-free and supports any compatible Hash implementation.
 
@@ -497,12 +560,7 @@ To install this gem onto your local machine, run bundle exec rake install.
 
 This project is managed with [Reissue](https://github.com/SOFware/reissue).
 
-To release a new version, make your changes and be sure to update the CHANGELOG.md.
-
-To release a new version:
-
-    bundle exec rake build:checksum
-    bundle exec rake release
+Releases are automated via the [shared release workflow](https://github.com/SOFware/reissue/blob/main/.github/workflows/SHARED_WORKFLOW_README.md). Trigger a release by running the "Release gem to RubyGems.org" workflow from the Actions tab.
 
 ## Contributing
 

data/Rakefile

@@ -22,4 +22,5 @@ Reissue::Task.create :reissue do |task|
   task.changelog_file = "CHANGELOG.md"
   task.version_limit = 1
   task.fragment = :git
+  task.push_finalize = :branch
 end

data/lib/circulator/flow.rb

@@ -88,6 +88,42 @@ module Circulator
       end
     end
 
+    def around(&block)
+      if block_given?
+        @around = block
+      else
+        @around
+      end
+    end
+
+    # Merge an extension block into this flow
+    #
+    # Creates an extension flow from the block and merges its transitions
+    # and states into this flow. Returns self for convenience.
+    #
+    # Example:
+    #
+    #   existing_flow.merge do
+    #     state :pending do
+    #       action :send_to_legal, to: :legal_review
+    #     end
+    #   end
+    #
+    def merge(&block)
+      extension_flow = Flow.new(@klass, @attribute_name, @states, extension: true, flows_proc: @flows_proc, &block)
+
+      # Merge transition map
+      extension_flow.transition_map.each do |action, transitions|
+        @transition_map[action] = if @transition_map[action]
+          @transition_map[action].merge(transitions)
+        else
+          transitions
+        end
+      end
+
+      self
+    end
+
     private
 
     def validate_allow_if(allow_if)
@@ -172,21 +208,9 @@ module Circulator
       key = "#{class_name}:#{@attribute_name}"
       extensions = Circulator.extensions[key]
 
-      # Apply each extension by creating a new Flow and merging its transition_map
+      # Apply each extension using merge
       extensions.each do |extension_block|
-        extension_flow = Flow.new(@klass, @attribute_name, @states, extension: true, flows_proc: @flows_proc, &extension_block)
-        extension_flow.transition_map.each do |action, transitions|
-          @transition_map[action] = if @transition_map[action]
-            @transition_map[action].merge(transitions)
-          else
-            transitions
-          end
-        end
-
-        # Merge states from extension
-        extension_flow.instance_variable_get(:@states).each do |state|
-          @states.add(state)
-        end
+        merge(&extension_block)
       end
     end
   end

data/lib/circulator/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Circulator
-  VERSION = "2.1.8"
+  VERSION = "2.1.10"
 end

data/lib/circulator.rb

@@ -70,8 +70,66 @@ module Circulator
 
       key = "#{class_name}:#{attribute_name}"
       @extensions[key] << block
+
+      # If the class already exists and has flows defined, apply the extension immediately
+      apply_extension_to_existing_flow(class_name, attribute_name, block)
+    end
+
+    private
+
+    def apply_extension_to_existing_flow(class_name, attribute_name, block)
+      # Try to get the class constant
+      klass = begin
+        Object.const_get(class_name.to_s)
+      rescue NameError
+        return # Class doesn't exist yet, extension will be applied when flow is defined
+      end
+
+      # Check if the class has flows and the specific attribute flow
+      return unless klass.respond_to?(:flows) && klass.flows
+
+      model_key = Circulator.model_key(klass.to_s)
+      existing_flow = klass.flows.dig(model_key, attribute_name.to_sym)
+      return unless existing_flow
+
+      # Merge the extension into the existing flow
+      existing_flow.merge(&block)
+
+      # Re-define flow methods for any new actions/states
+      redefine_flow_methods(klass, attribute_name, existing_flow)
+    end
+
+    def redefine_flow_methods(klass, attribute_name, flow)
+      flow_module = klass.ancestors.find { |ancestor|
+        ancestor.name.to_s =~ /#{FLOW_MODULE_NAME}/o
+      }
+      return unless flow_module
+
+      object = nil # Extensions only work on the same class model
+
+      # Define or redefine methods for actions (need to redefine if transitions changed)
+      flow.transition_map.each do |action, transitions|
+        method_name = [object, attribute_name, action].compact.join("_")
+
+        # Remove existing method so it can be redefined with updated transitions
+        if flow_module.method_defined?(method_name)
+          flow_module.remove_method(method_name)
+        end
+
+        klass.send(:define_flow_method, attribute_name:, action:, transitions:, object:, owner: flow_module)
+      end
+
+      # Define predicate methods for any new states
+      states = flow.instance_variable_get(:@states)
+      states.each do |state|
+        next if state.nil?
+        klass.send(:define_state_method, attribute_name:, state:, object:, owner: flow_module)
+      end
     end
   end
+
+  FLOW_MODULE_NAME = "FlowMethods"
+
   # Declare a flow for an attribute.
   #
   # Specify the attribute to be used for states and actions.
@@ -195,6 +253,21 @@ module Circulator
   #  test_object.flow(:unknown, :status, "signal")
   #  # Will raise an UnhandledSignalError
   #
+  # You can also provide an around block to wrap the flow logic.
+  #
+  # Example:
+  #
+  #  flow(:status) do
+  #    around do |flow_logic|
+  #      with_logging do
+  #        flow_logic.call
+  #      end
+  #    end
+  #  end
+  #
+  #  test_object.status_approve
+  #  # Will log the flow logic according to the with_logging block behavior
+  #
   def flow(attribute_name, model: to_s, flows_proc: Circulator.default_flow_proc, &block)
     @flows ||= flows_proc.call
     model_key = Circulator.model_key(model)
@@ -203,11 +276,11 @@ module Circulator
     @flows[model_key][attribute_name] = Flow.new(self, attribute_name, flows_proc:, &block)
 
     flow_module = ancestors.find { |ancestor|
-      ancestor.name.to_s =~ /FlowMethods/
+      ancestor.name.to_s =~ /#{FLOW_MODULE_NAME}/o
     } || Module.new.tap do |mod|
       include mod
 
-      const_set(:FlowMethods, mod)
+      const_set(FLOW_MODULE_NAME.to_sym, mod)
     end
 
     object = if model == to_s
@@ -253,65 +326,62 @@ module Circulator
     raise ArgumentError, "Method already defined: #{object_attribute_method}" if owner.method_defined?(object_attribute_method)
 
     owner.define_method(object_attribute_method) do |*args, flow_target: self, **kwargs, &block|
-      current_value = flow_target.send(attribute_name)
+      flow_logic = -> {
+        current_value = flow_target.send(attribute_name)
 
-      transition = if current_value.respond_to?(:to_sym)
-        transitions[current_value.to_sym]
-      else
-        transitions[current_value]
-      end
+        transition = if current_value.respond_to?(:to_sym)
+          transitions[current_value.to_sym]
+        else
+          transitions[current_value]
+        end
 
-      unless transition
-        flow_target.instance_exec(attribute_name, action, &flows.dig(Circulator.model_key(flow_target), attribute_name).no_action)
-        return
-      end
+        unless transition
+          flow_target.instance_exec(attribute_name, action, &flows.dig(Circulator.model_key(flow_target), attribute_name).no_action)
+          return
+        end
+
+        return if transition[:allow_if] && !Circulator.evaluate_guard(flow_target, transition[:allow_if], *args, **kwargs)
+
+        flow_target.instance_exec(*args, **kwargs, &transition[:block]) if transition[:block]
 
-      if transition[:allow_if]
-        # Handle array-based allow_if (array of symbols and/or procs)
-        if transition[:allow_if].is_a?(Array)
-          return unless transition[:allow_if].all? do |guard|
-            case guard
-            when Symbol
-              flow_target.send(guard, *args, **kwargs)
-            when Proc
-              flow_target.instance_exec(*args, **kwargs, &guard)
-            end
-          end
-        # Handle hash-based allow_if (checking other attribute states)
-        elsif transition[:allow_if].is_a?(Hash)
-          attribute_name_to_check, valid_states = transition[:allow_if].first
-          current_state = flow_target.send(attribute_name_to_check)
-
-          # Convert current state to symbol if possible
-          current_state = current_state.to_sym if current_state.respond_to?(:to_sym)
-
-          # Convert valid_states to array of symbols
-          valid_states_array = Array(valid_states).map { |s| s.respond_to?(:to_sym) ? s.to_sym : s }
-
-          # Return early if current state is not in the valid states
-          return unless valid_states_array.include?(current_state)
-        elsif transition[:allow_if].is_a?(Symbol)
-          # Handle symbol-based allow_if (method name)
-          return unless flow_target.send(transition[:allow_if])
+        if transition[:to].respond_to?(:call)
+          flow_target.send("#{attribute_name}=", flow_target.instance_exec(*args, **kwargs, &transition[:to]))
         else
-          # Handle proc-based allow_if (original behavior)
-          return unless flow_target.instance_exec(*args, **kwargs, &transition[:allow_if])
+          flow_target.send("#{attribute_name}=", transition[:to])
+        end.tap do
+          flow_target.instance_exec(*args, **kwargs, &block) if block
         end
-      end
+      }
 
-      if transition[:block]
-        flow_target.instance_exec(*args, **kwargs, &transition[:block])
-      end
+      around_block = flows.dig(Circulator.model_key(flow_target), attribute_name)&.around
 
-      if transition[:to].respond_to?(:call)
-        flow_target.send("#{attribute_name}=", flow_target.instance_exec(*args, **kwargs, &transition[:to]))
+      if around_block
+        flow_target.instance_exec(flow_logic, &around_block)
       else
-        flow_target.send("#{attribute_name}=", transition[:to])
-      end.tap do
-        if block
-          flow_target.instance_exec(*args, **kwargs, &block)
+        flow_logic.call
+      end
+    end
+  end
+
+  module_function def evaluate_guard(target, allow_if, *args, **kwargs)
+    case allow_if
+    when Array
+      allow_if.all? do |guard|
+        case guard
+        when Symbol then target.send(guard, *args, **kwargs)
+        when Proc then target.instance_exec(*args, **kwargs, &guard)
         end
       end
+    when Hash
+      attribute_name, valid_states = allow_if.first
+      current_state = target.send(attribute_name)
+      current_state = current_state.to_sym if current_state.respond_to?(:to_sym)
+      valid_states_array = Array(valid_states).map { |s| s.respond_to?(:to_sym) ? s.to_sym : s }
+      valid_states_array.include?(current_state)
+    when Symbol
+      target.send(allow_if, *args, **kwargs)
+    else
+      target.instance_exec(*args, **kwargs, &allow_if)
     end
   end
 
@@ -441,28 +511,7 @@ module Circulator
     end
 
     def check_allow_if(allow_if, *args, **kwargs)
-      case allow_if
-      when Array
-        # All guards in array must be true (AND logic)
-        allow_if.all? do |guard|
-          case guard
-          when Symbol
-            send(guard, *args, **kwargs)
-          when Proc
-            instance_exec(*args, **kwargs, &guard)
-          end
-        end
-      when Hash
-        attribute_name, valid_states = allow_if.first
-        current_state = send(attribute_name)
-        current_state = current_state.to_sym if current_state.respond_to?(:to_sym)
-        valid_states_array = Array(valid_states).map { |s| s.respond_to?(:to_sym) ? s.to_sym : s }
-        valid_states_array.include?(current_state)
-      when Symbol
-        send(allow_if, *args, **kwargs)
-      else # Proc
-        instance_exec(*args, **kwargs, &allow_if)
-      end
+      Circulator.evaluate_guard(self, allow_if, *args, **kwargs)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: circulator
 version: !ruby/object:Gem::Version
-  version: 2.1.8
+  version: 2.1.10
 platform: ruby
 authors:
 - Jim Gay