circulator 2.1.9 → 2.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d069df555d7f1ac9aa1865cacef2c3bda5373a287c899f23068abe56cf3c379
-  data.tar.gz: c79dbba353dbe721587f3361599385a280a93f9c9655b4fcae01de5359ec8f1e
+  metadata.gz: 9232620710fbfe075e26c0ae3bcf1dea0794cdca188b0a9a0ff8529362573ede
+  data.tar.gz: c45d7ac1bdf89fe21107905811d36d0ef4dca37370ea89686d5433cef1aeaaf5
 SHA512:
-  metadata.gz: ca22e7ae65647826445f17464a74427524bda9fa4d3fa8cb34a1ff47bc8f6c036c5f35a624de6c6853334677add37decd5f27fcbe19bfcb5e4c9edd54606d8f9
-  data.tar.gz: d7c0c520cda68eee6e470a66fa8be95c3f332a3b36bb1314964a2c55f51a763667a2de745c0ea65a319e83eaf5b475cf1303a5961e67877fdbadb4154596ed37
+  metadata.gz: bfbc391566c29b7dd18005c56c37c21c9d976eeebc2705f92ea726074b93807daf47528f34e07bb449be3a38bca797067742abc64e1d862162cc18924049b47d
+  data.tar.gz: 9edd59a4985b266ad4c590d3e4d05bbe41f381e85a149b84de08adeabf9e1ff141d0a2b5d5dee759e1e1ba8d4dd740c8e33036331694614951994fddab6d4448

data/CHANGELOG.md

@@ -5,12 +5,17 @@ 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.11] - 2026-02-09
 
 ### Added
 
-- Flow#merge to merge existing flows with extensions (d1eb47d)
+- action_missing alias for no_action to clarify intent (c576a7c)
 
 ### Changed
 
-- Circulator.extension applies immediately to existing flows (d1eb47d)
+- Improved inline documentation for no_action and around methods (c576a7c)
+- Added method documentation for Flow DSL methods (2546989)
+
+### Removed
+
+- @no_action internal instance_variable and switched to @action_missing Version: minor (c576a7c)

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,101 @@ class Payment
 end
 ```
 
+#### Handling Missing Transitions with `action_missing`
+
+By default, if you call an action on an object whose current state doesn't define a transition for that action, Circulator raises an error. Use `action_missing` (aliased as `no_action`) to customize this behavior.
+
+This is triggered when, for example, you call `order.status_ship` but the object is in `:pending` and `:ship` only has a transition defined from `:processing`.
+
+```ruby
+class Order
+  extend Circulator
+
+  attr_accessor :status
+
+  flow :status do
+    action_missing do |attribute_name, action|
+      Rails.logger.warn "No #{action} transition from #{send(attribute_name)} for #{attribute_name}"
+    end
+
+    state :pending do
+      action :process, to: :processing
+    end
+
+    state :processing do
+      action :ship, to: :shipped
+    end
+  end
+end
+
+order = Order.new
+order.status = :pending
+
+order.status_ship  # => logs warning instead of raising
+```
+
+#### 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 +593,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

@@ -6,7 +6,7 @@ module Circulator
       @klass = klass
       @attribute_name = attribute_name
       @states = states
-      @no_action = ->(attribute_name, action) { raise "No action found for the current state of #{attribute_name} (#{send(attribute_name)}): #{action}" }
+      @action_missing = ->(attribute_name, action) { raise "No action found for the current state of #{attribute_name} (#{send(attribute_name)}): #{action}" }
       @flows_proc = flows_proc
       @transition_map = flows_proc.call
 
@@ -18,6 +18,18 @@ module Circulator
     end
     attr_reader :transition_map
 
+    # Declares a state in the flow. The block is evaluated in the context
+    # of the flow, allowing you to define actions that transition from
+    # this state. A state with no block acts as a terminal state.
+    #
+    #   flow(:status) do
+    #     state :pending do
+    #       action :approve, to: :approved
+    #     end
+    #
+    #     state :approved # terminal state
+    #   end
+    #
     def state(name, &block)
       name = name.to_sym if name.respond_to?(:to_sym)
       @states.add(name)
@@ -26,6 +38,34 @@ module Circulator
       remove_instance_variable(:@current_state)
     end
 
+    # Declares a transition from one or more states to a destination state.
+    # Must be called inside a +state+ block, or with an explicit +from:+ option.
+    #
+    # Generates a method named +<attribute>_<action>+ on the class that
+    # performs the transition when called.
+    #
+    # ==== Options
+    #
+    # +to+::       The destination state (Symbol) or a callable that returns
+    #              the destination state at runtime.
+    # +from+::     One or more source states. Defaults to the enclosing
+    #              +state+ block. Pass an Array to define the same action
+    #              from multiple states.
+    # +allow_if+:: A guard condition that must be truthy for the transition
+    #              to proceed. Accepts a Proc, Symbol (method name), Hash
+    #              (checks another flow's state), or Array of those.
+    # +&block+::   A block executed on the instance during the transition,
+    #              before the state is changed.
+    #
+    #   state :pending do
+    #     action :approve, to: :approved, allow_if: :reviewer? do
+    #       self.approved_at = Time.now
+    #     end
+    #   end
+    #
+    #   # Or with an explicit from:
+    #   action :cancel, from: [:pending, :processing], to: :cancelled
+    #
     def action(name, to:, from: :__not_specified__, allow_if: nil, &block)
       raise "You must be in a state block or have a `from` option to declare an action" unless defined?(@current_state) || from != :__not_specified__
 
@@ -61,6 +101,22 @@ module Circulator
       end
     end
 
+    # Attaches an +allow_if+ guard to an existing action after it has been
+    # defined. This is useful when the guard logic needs to be defined
+    # separately from the action itself, such as in an extension.
+    #
+    # Must be called inside a +state+ block, or with an explicit +from:+ option.
+    # The action must already exist in the transition map.
+    #
+    # Example:
+    #
+    #   flow(:status) do
+    #     state :pending do
+    #       action :approve, to: :approved
+    #       action_allowed(:approve) { current_user.admin? }
+    #     end
+    #   end
+    #
     def action_allowed(name, from: :__not_specified__, &block)
       raise "You must be in a state block or have a `from` option to declare an action" unless defined?(@current_state) || from != :__not_specified__
 
@@ -80,11 +136,58 @@ module Circulator
       end
     end
 
-    def no_action(&block)
+    # Called when an action is invoked but no transition is defined for the
+    # current state. For example, if an object is in :approved and you call
+    # an action that only has a transition from :pending, this block runs.
+    #
+    # By default, raises an error. Override to silently ignore, log, or
+    # handle the missing transition however you like.
+    #
+    # The block receives two arguments: the attribute name and the action name.
+    #
+    # Example:
+    #
+    #   flow(:status) do
+    #     action_missing do |attribute_name, action|
+    #       Rails.logger.warn("No transition for #{attribute_name} in #{action}")
+    #     end
+    #   end
+    def action_missing(&block)
+      if block_given?
+        @action_missing = block
+      else
+        @action_missing
+      end
+    end
+    alias_method :no_action, :action_missing
+
+    # Wraps every transition in this flow. The block receives a lambda that
+    # executes the transition logic (guard check, state change, and any
+    # transition block). You must call +transition.call+ for the transition
+    # to actually happen — omitting it prevents the state change entirely.
+    #
+    # Useful for wrapping transitions in database transactions, logging,
+    # instrumentation, or any before/after behavior.
+    #
+    # Example:
+    #
+    #   flow(:status) do
+    #     around do |transition|
+    #       ActiveRecord::Base.transaction do
+    #         transition.call
+    #       end
+    #     end
+    #
+    #     state :pending do
+    #       action :approve, to: :approved
+    #     end
+    #   end
+    #
+    def around(&block)
       if block_given?
-        @no_action = block
+        @around = block
       else
-        @no_action
+        @around
       end
     end
 

data/lib/circulator/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Circulator
-  VERSION = "2.1.9"
+  VERSION = "2.1.11"
 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.11
 platform: ruby
 authors:
 - Jim Gay
@@ -46,7 +46,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Simple state machine
 test_files: []