circulator 2.1.10 → 2.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c4d63bee9efd4c305309b4e77b502e378ad2a8ec7f550b85a25d9f9b1963f9f
-  data.tar.gz: 281ebeb9de99be8dac7b6925ae7d3d51727c54916bca3f9df7c86b6aa5014966
+  metadata.gz: d7dbf52b54ebf9536c2d5cac336376e6fa1fadbdd614794bd7322349c714bbc0
+  data.tar.gz: c81382ec182f2d2b2b4f13d73c8228675efed7f5f5ee80886a58d8b77820db76
 SHA512:
-  metadata.gz: b9d5d21fb96c45580fd3051b084403aba315d058eee4edb56dfdb4c7b10cc49105b277e60d96c895d4ae0014e0a0298ff79878f4f3a1b61f35b8c480543f491a
-  data.tar.gz: fd20a62b795f3817877c48b8ca810dde022615df11cd100506265436958e4e7326791d8a2dda6b13f898327e5c295f076800d541bc900986524b000ebdc812d9
+  metadata.gz: c996bdd7a378930fbf14cdfabad9b83b099db386932ea6fab946c38bcd5d649dce25bbc2730b87747b5f46937b55727a06964e8930154b4da23745cf27cdb757
+  data.tar.gz: 24cd2abfe4e710269d4a3a39ed9606bb158b395fa66fa83c5892e9cc060850131c9d9704693a214762eed2efe97ec39a64e4b97378f2e6bda98a1f52ef5adcdf

data/CHANGELOG.md

@@ -5,8 +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.10] - 2026-02-06
+## [2.1.12] - 2026-02-17
 
 ### Added
 
-- `around` block in flow DSL to wrap transition logic (state read, guards, state change, callbacks) (184527b)
+- Named test sampler classes for reuse across test files (b6bcb4e)
+- bang method variants for flow actions (673d8a0)
+- Circulator::InvalidTransition exception class (673d8a0)
+- host-namespaced InvalidTransition subclass per class with flows (673d8a0)
+- flow! instance method and variant: keyword on flow (673d8a0)
+- FLOW_VARIANTS registry that drives method definition (673d8a0)
+
+### Changed
+
+- Flow attribute writers are private after flow definition Version: minor (35ea18f)

data/README.md

@@ -294,6 +294,39 @@ 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:

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,14 +136,53 @@ 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?
-        @no_action = block
+        @action_missing = block
       else
-        @no_action
+        @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?
         @around = block

data/lib/circulator/version.rb

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

data/lib/circulator.rb

@@ -2,6 +2,8 @@ require "circulator/version"
 require "circulator/flow"
 
 module Circulator
+  class InvalidTransition < StandardError; end
+
   # Global registry for extensions
   @extensions = Hash.new { |h, k| h[k] = [] }
 
@@ -109,14 +111,17 @@ module Circulator
 
       # 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("_")
+        base_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)
+        # Remove existing methods so they can be redefined with updated transitions
+        FLOW_VARIANTS.each_value do |suffix|
+          full_name = "#{base_name}#{suffix}"
+          flow_module.remove_method(full_name) if flow_module.method_defined?(full_name)
         end
 
-        klass.send(:define_flow_method, attribute_name:, action:, transitions:, object:, owner: flow_module)
+        FLOW_VARIANTS.each_key do |variant|
+          klass.send(["define", variant, "flow_method"].compact.join("_"), attribute_name:, action:, transitions:, object:, owner: flow_module)
+        end
       end
 
       # Define predicate methods for any new states
@@ -129,6 +134,7 @@ module Circulator
   end
 
   FLOW_MODULE_NAME = "FlowMethods"
+  FLOW_VARIANTS = {:bang => "!", nil => ""}.freeze
 
   # Declare a flow for an attribute.
   #
@@ -275,6 +281,11 @@ module Circulator
     # Pass the flows_proc to Flow so it can create transition_maps of the same type
     @flows[model_key][attribute_name] = Flow.new(self, attribute_name, flows_proc:, &block)
 
+    # Define InvalidTransition exception on the host class if not already defined
+    unless const_defined?(:InvalidTransition, false)
+      const_set(:InvalidTransition, Class.new(Circulator::InvalidTransition))
+    end
+
     flow_module = ancestors.find { |ancestor|
       ancestor.name.to_s =~ /#{FLOW_MODULE_NAME}/o
     } || Module.new.tap do |mod|
@@ -298,7 +309,9 @@ module Circulator
           states.add(transition_data[:to])
         end
       end
-      define_flow_method(attribute_name:, action:, transitions:, object:, owner: flow_module)
+      FLOW_VARIANTS.each_key do |variant|
+        send(["define", variant, "flow_method"].compact.join("_"), attribute_name:, action:, transitions:, object:, owner: flow_module)
+      end
     end
 
     # Define predicate methods for each state (skip nil)
@@ -306,6 +319,15 @@ module Circulator
       next if state.nil?
       define_state_method(attribute_name:, state:, object:, owner: flow_module)
     end
+
+    # Make the attribute writer private so that state changes must go through
+    # the generated flow methods. This prevents bypassing guards and transition
+    # logic by directly assigning the attribute. The writer is only made private
+    # for self-managed flows (not model-based flows where the attribute belongs
+    # to a different class).
+    if object.nil? && method_defined?("#{attribute_name}=")
+      private "#{attribute_name}="
+    end
   end
   alias_method :circulator, :flow
 
@@ -363,6 +385,30 @@ module Circulator
     end
   end
 
+  def define_bang_flow_method(attribute_name:, action:, transitions:, object:, owner:)
+    bang_method = [object, attribute_name, action].compact.join("_") << "!"
+    return if owner.method_defined?(bang_method)
+
+    non_bang_method = [object, attribute_name, action].compact.join("_")
+    owner.define_method(bang_method) do |*args, flow_target: self, **kwargs, &block|
+      current_value = flow_target.send(attribute_name)
+      current_state = current_value.respond_to?(:to_sym) ? current_value.to_sym : current_value
+
+      transition = transitions[current_state]
+      unless transition
+        raise self.class.const_get(:InvalidTransition),
+          "No transition #{action} on #{attribute_name} from #{current_state.inspect}"
+      end
+
+      if transition[:allow_if] && !Circulator.evaluate_guard(flow_target, transition[:allow_if], *args, **kwargs)
+        raise self.class.const_get(:InvalidTransition),
+          "Guard prevented #{action} on #{attribute_name} from #{current_state.inspect}"
+      end
+
+      send(non_bang_method, *args, flow_target:, **kwargs, &block)
+    end
+  end
+
   module_function def evaluate_guard(target, allow_if, *args, **kwargs)
     case allow_if
     when Array
@@ -409,16 +455,21 @@ module Circulator
   module InstanceMethods
     # Use this method to call an action on the attribute.
     #
+    # Accepts an optional +variant:+ keyword to select a method variant.
+    # See +FLOW_VARIANTS+ for the available variants and their suffixes.
+    #
     # Example:
     #
     #   test_object.flow(:approve, :status)
     #   test_object.flow(:approve, :status, "arg1", "arg2", key: "value")
-    def flow(action, attribute, *args, flow_target: self, **kwargs, &block)
+    #   test_object.flow(:approve, :status, variant: :bang)
+    def flow(action, attribute, *args, flow_target: self, variant: nil, **kwargs, &block)
       target_name = if flow_target != self
         Circulator.methodize_name(Circulator.model_key(flow_target))
       end
       external_attribute_name = [target_name, attribute].compact.join("_")
-      method_name = "#{external_attribute_name}_#{action}"
+      suffix = Circulator::FLOW_VARIANTS.fetch(variant)
+      method_name = "#{external_attribute_name}_#{action}#{suffix}"
       if respond_to?(method_name)
         send(method_name, *args, flow_target:, **kwargs, &block)
       elsif flow_target.respond_to?(method_name)
@@ -426,6 +477,17 @@ module Circulator
       else
         raise "Invalid action for the current state of #{attribute} (#{flow_target.send(attribute).inspect}): #{action}"
       end
+    rescue KeyError
+      raise ArgumentError, "Invalid variant: #{variant.inspect}"
+    end
+
+    # Bang variant of flow that raises InvalidTransition on failure.
+    #
+    # Example:
+    #
+    #   test_object.flow!(:approve, :status)
+    def flow!(action, attribute, *args, **kwargs, &block)
+      flow(action, attribute, *args, variant: :bang, **kwargs, &block)
     end
 
     # Get available actions for an attribute based on current state

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: circulator
 version: !ruby/object:Gem::Version
-  version: 2.1.10
+  version: 2.1.12
 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: []