circulator 2.1.10 → 2.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c4d63bee9efd4c305309b4e77b502e378ad2a8ec7f550b85a25d9f9b1963f9f
-  data.tar.gz: 281ebeb9de99be8dac7b6925ae7d3d51727c54916bca3f9df7c86b6aa5014966
+  metadata.gz: 9232620710fbfe075e26c0ae3bcf1dea0794cdca188b0a9a0ff8529362573ede
+  data.tar.gz: c45d7ac1bdf89fe21107905811d36d0ef4dca37370ea89686d5433cef1aeaaf5
 SHA512:
-  metadata.gz: b9d5d21fb96c45580fd3051b084403aba315d058eee4edb56dfdb4c7b10cc49105b277e60d96c895d4ae0014e0a0298ff79878f4f3a1b61f35b8c480543f491a
-  data.tar.gz: fd20a62b795f3817877c48b8ca810dde022615df11cd100506265436958e4e7326791d8a2dda6b13f898327e5c295f076800d541bc900986524b000ebdc812d9
+  metadata.gz: bfbc391566c29b7dd18005c56c37c21c9d976eeebc2705f92ea726074b93807daf47528f34e07bb449be3a38bca797067742abc64e1d862162cc18924049b47d
+  data.tar.gz: 9edd59a4985b266ad4c590d3e4d05bbe41f381e85a149b84de08adeabf9e1ff141d0a2b5d5dee759e1e1ba8d4dd740c8e33036331694614951994fddab6d4448

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.11] - 2026-02-09
 
 ### Added
 
-- `around` block in flow DSL to wrap transition logic (state read, guards, state change, callbacks) (184527b)
+- action_missing alias for no_action to clarify intent (c576a7c)
+
+### Changed
+
+- 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

@@ -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.11"
 end

metadata

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