circulator 2.1.9 → 2.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d069df555d7f1ac9aa1865cacef2c3bda5373a287c899f23068abe56cf3c379
-  data.tar.gz: c79dbba353dbe721587f3361599385a280a93f9c9655b4fcae01de5359ec8f1e
+  metadata.gz: 8c4d63bee9efd4c305309b4e77b502e378ad2a8ec7f550b85a25d9f9b1963f9f
+  data.tar.gz: 281ebeb9de99be8dac7b6925ae7d3d51727c54916bca3f9df7c86b6aa5014966
 SHA512:
-  metadata.gz: ca22e7ae65647826445f17464a74427524bda9fa4d3fa8cb34a1ff47bc8f6c036c5f35a624de6c6853334677add37decd5f27fcbe19bfcb5e4c9edd54606d8f9
-  data.tar.gz: d7c0c520cda68eee6e470a66fa8be95c3f332a3b36bb1314964a2c55f51a763667a2de745c0ea65a319e83eaf5b475cf1303a5961e67877fdbadb4154596ed37
+  metadata.gz: b9d5d21fb96c45580fd3051b084403aba315d058eee4edb56dfdb4c7b10cc49105b277e60d96c895d4ae0014e0a0298ff79878f4f3a1b61f35b8c480543f491a
+  data.tar.gz: fd20a62b795f3817877c48b8ca810dde022615df11cd100506265436958e4e7326791d8a2dda6b13f898327e5c295f076800d541bc900986524b000ebdc812d9

data/CHANGELOG.md

@@ -5,12 +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.9] - 2026-01-08
+## [2.1.10] - 2026-02-06
 
 ### Added
 
-- Flow#merge to merge existing flows with extensions (d1eb47d)
-
-### Changed
-
-- Circulator.extension applies immediately to existing flows (d1eb47d)
+- `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.
@@ -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,14 @@ 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

data/lib/circulator/version.rb

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

data/lib/circulator.rb

@@ -116,14 +116,14 @@ module Circulator
           flow_module.remove_method(method_name)
         end
 
-        klass.send(:define_flow_method, attribute_name: attribute_name, action: action, transitions: transitions, object: object, owner: flow_module)
+        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: attribute_name, state: state, object: object, owner: flow_module)
+        klass.send(:define_state_method, attribute_name:, state:, object:, owner: flow_module)
       end
     end
   end
@@ -253,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)
@@ -311,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
 
@@ -499,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.9
+  version: 2.1.10
 platform: ruby
 authors:
 - Jim Gay