circulator 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34d38ad852dfc0dea3071103c368fa9d77224c7a390b7fc10c6a39fde2e2b507
-  data.tar.gz: c67068423ece22963cdf64391f0424251a8c23caebf08280a6bb977b1a18bd4b
+  metadata.gz: f0a33536db417f338113b2ef4a5656a38994652f4454f8583ea8e22d626a0e9e
+  data.tar.gz: 394085a68c1a7444192264fa69152be2827663284f4221b844f4fbfcb45cf64b
 SHA512:
-  metadata.gz: dc4264165cdb3fdf72ec246dcabc02c0bacff9d20f24a167984e6521517550cc131fd0711f289892c8263fea6ac6c07dcc1d39c0ed77165dbf74d2a3d044f331
-  data.tar.gz: d85440b2e40cc2aa2ff1f7848f5b4dc63b94c2217ebdd7918488967489badb439edcb1c5f39c0b762634f1739ce38405ad19e841a7f4b84c2bb8671262418ec3
+  metadata.gz: 4489ca3bf464fe0b37ad3b2e41096fcce05a2d5bcc5348d25e7750f278c666fd10c266e397635846b0093d1ace1064da754d50a0d6973b07f2a4086b5983926d
+  data.tar.gz: 4da4067d6b07dccc9207e17c6095b236dab9f9e7c1d6399f5ff0c475b761b84da34490ec5d8d61ab71678e18fd014b327f6f9358b5aa571b8c70e19306698da6

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).
 
-## [1.0.0] - 2025-09-11
+## [2.0.0] - 2025-09-12
 
-### 
+### Removed
 
-- Initial release.
+- The `Circulator::Diverter` module has been and features added to `Circulator` itself.

data/README.md

@@ -39,7 +39,7 @@ gem install circulator
 
 ```ruby
 class Order
-  extend Circulator::Diverter
+  extend Circulator
 
   attr_accessor :status
 
@@ -77,7 +77,7 @@ order.status_deliver  # => :delivered
 
 ```ruby
 class Document
-  extend Circulator::Diverter
+  extend Circulator
 
   attr_accessor :state, :reviewed_by
 
@@ -97,7 +97,7 @@ end
 
 ```ruby
 class Task
-  extend Circulator::Diverter
+  extend Circulator
 
   attr_accessor :priority, :urgency_level
 
@@ -114,7 +114,7 @@ end
 
 ```ruby
 class Server
-  extend Circulator::Diverter
+  extend Circulator
 
   attr_accessor :power_state, :network_state
 
@@ -147,7 +147,7 @@ end
 
 ```ruby
 class Payment
-  extend Circulator::Diverter
+  extend Circulator
 
   attr_accessor :status, :processed_at
 

data/lib/circulator/flow.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "diverter"
-
 module Circulator
   class Flow
     def initialize(klass, attribute_name, states = Set.new, &block)
@@ -70,4 +68,4 @@ module Circulator
       end
     end
   end
-end
+end

data/lib/circulator/version.rb

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

data/lib/circulator.rb

@@ -1,3 +1,241 @@
 require "circulator/version"
-require "circulator/diverter"
 require "circulator/flow"
+
+module Circulator
+  # Declare a flow for an attribute.
+  #
+  # Specify the attribute to be used for states and actions.
+  #
+  # Example:
+  #
+  #   flow(:status) do
+  #     state :pending do
+  #       action :approve, to: :approved
+  #     end
+  #   end
+  #
+  # The above declares a flow for the `status` attribute. When in the `pending`
+  # state, the `approve` action will transition the `status` to `approved`.
+  #
+  # This creates a `status_approve` method which will change the state in memory.
+  #
+  # You will also have a instance method `flow` which will allow you to specify
+  # the action to take on the attribute.
+  #
+  # Example:
+  #
+  #   test_object.status_approve
+  #   # OR
+  #   test_object.flow(:approve, :status)
+  #
+  # You can also provide a block to receive arguments
+  #
+  # Example:
+  #
+  #   flow(:status) do
+  #     state :pending do
+  #       action :approve, to: :approved do |*args, **kwargs|
+  #         @args_received = {args: args, kwargs: kwargs}
+  #       end
+  #       action_allowed(:approve) { true } # Optional. Check some value on self
+  #     end
+  #   end
+  #
+  # The block will be evalutaed on the instance of the class declaring the flow.
+  # So `self` inside that action block will be the instance of the class.
+  #
+  # Example:
+  #
+  #   test_object.status_approve("arg1", "arg2", key: "value")
+  #   # @args_received will be {args: ["arg1", "arg2"], kwargs: {key: "value"}}
+  #
+  # If the action is not allowed, the transition will not be executed.
+  #
+  # Example:
+  #
+  #  flow(:status) do
+  #    state :pending do
+  #      action :approve, to: :approved do
+  #        @args_received = {args: args, kwargs: kwargs}
+  #      end
+  #      action_allowed(:approve) { false }
+  #    end
+  #  end
+  #
+  #  test_object.status_approve
+  #  # Will not transition because the action is not allowed
+  #
+  # You may also specify the `allow_if` option to check a condition before
+  # the action is allowed. The callable will be evaluated on the instance of
+  # the class declaring the flow. So `self` inside that block will be the
+  # instance of the class.
+  #
+  # Example:
+  #
+  #  flow(:status) do
+  #    state :pending do
+  #      action :approve, to: :approved, allow_if: -> { true }
+  #    end
+  #  end
+  #
+  #  test_object.status_approve
+  #  # Will transition to :approved if the condition is true
+  #
+  # If you declare states separately, for example in an enum, you can use the
+  # `action` method to declare the action on the attribute.
+  #
+  # Example:
+  #
+  #  enum :status, {pending: 0, approved: 1, rejected: 2}
+  #  flow(:status) do
+  #    action :approve, to: :approved, from: :pending
+  #    action :reject, to: :rejected, from: :approved do |rejected_at|
+  #      self.rejected_at = rejected_at
+  #    end
+  #  end
+  #
+  #  test_object.status_approve
+  #  # Will transition to :approved
+  #  test_object.status_reject
+  #  # Will transition to :rejected and set the rejected_at attribute
+  #
+  # By default, if there is no transition for the current state, the flow will
+  # raise an error. You can specify a no_action block to handle this case.
+  #
+  # Example:
+  #
+  #  flow(:status) do
+  #    no_action { |attribute_name, action| raise "Nope!" }
+  #  end
+  #
+  #  test_object.status_approve
+  #  # Will raise an error
+  #
+  # You can also provide a custom action for other behavior for a set of states and
+  # use the `to` option as a callable to set the attribute.
+  #
+  # Example:
+  #
+  #  flow(:status) do
+  #    action :unknown, to: -> { status }, from: [:enforcing, :monitoring, :ignoring] do |signal|
+  #      raise UnhandledSignalError, signal
+  #    end
+  #  end
+  #
+  #  test_object.flow(:unknown, :status, "signal")
+  #  # Will raise an UnhandledSignalError
+  #
+  def flow(attribute_name, model: to_s, &block)
+    @flows ||= {}
+    model_key = Circulator.model_key(model)
+    @flows[model_key] ||= {}
+    @flows[model_key][attribute_name] = Flow.new(model, attribute_name, &block)
+
+    flow_module = ancestors.find { |ancestor|
+      ancestor.name.to_s =~ /FlowMethods/
+    } || Module.new.tap do |mod|
+      include mod
+
+      const_set(:FlowMethods, mod)
+    end
+
+    object = if model == to_s
+      nil
+    else
+      Circulator.methodize_name(model)
+    end
+
+    @flows.dig(model_key, attribute_name).transition_map.each do |action, transitions|
+      define_flow_method(attribute_name:, action:, transitions:, object:, owner: flow_module)
+    end
+  end
+  alias_method :circulator, :flow
+
+  def define_flow_method(attribute_name:, action:, transitions:, object:, owner:)
+    object_attribute_method = [object, attribute_name, action].compact.join("_")
+    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)
+
+      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
+
+      if transition[:allow_if]
+        return unless flow_target.instance_exec(*args, **kwargs, &transition[:allow_if])
+      end
+
+      if transition[:block]
+        flow_target.instance_exec(*args, **kwargs, &transition[:block])
+      end
+
+      if transition[:to].respond_to?(:call)
+        flow_target.send("#{attribute_name}=", flow_target.instance_exec(*args, **kwargs, &transition[:to]))
+      else
+        flow_target.send("#{attribute_name}=", transition[:to])
+      end.tap do
+        if block
+          flow_target.instance_exec(*args, **kwargs, &block)
+        end
+      end
+    end
+  end
+
+  module_function def model_key(object)
+    if object.is_a?(String)
+      if object.start_with?("#<Class:")
+        "anonymous_#{object.split("0x")[1]}".sub(">", "")
+      else
+        object
+      end
+    else
+      model_key(object.class.name || object.class.to_s)
+    end
+  end
+
+  module_function def methodize_name(name)
+    name.split("::").map { |part| part.gsub(/([a-z])([A-Z])/, '\1_\2') }.join("_").downcase
+  end
+
+  def self.extended(base)
+    base.include(InstanceMethods)
+    base.singleton_class.attr_reader :flows
+  end
+
+  module InstanceMethods
+    # Use this method to call an action on the attribute.
+    #
+    # 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)
+      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}"
+      if respond_to?(method_name)
+        send(method_name, *args, flow_target:, **kwargs, &block)
+      elsif flow_target.respond_to?(method_name)
+        flow_target.send(method_name, *args, **kwargs, &block)
+      else
+        raise "Invalid action for the current state of #{attribute} (#{flow_target.send(attribute).inspect}): #{action}"
+      end
+    end
+
+    private
+
+    def flows
+      self.class.flows
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: circulator
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Jim Gay
@@ -20,7 +20,6 @@ files:
 - README.md
 - Rakefile
 - lib/circulator.rb
-- lib/circulator/diverter.rb
 - lib/circulator/flow.rb
 - lib/circulator/version.rb
 homepage: https://github.com/SOFware/circulator

data/lib/circulator/diverter.rb

@@ -1,242 +0,0 @@
-# frozen_string_literal: true
-
-module Circulator
-  module Diverter
-    # Declare a flow for an attribute.
-    #
-    # Specify the attribute to be used for states and actions.
-    #
-    # Example:
-    #
-    #   flow(:status) do
-    #     state :pending do
-    #       action :approve, to: :approved
-    #     end
-    #   end
-    #
-    # The above declares a flow for the `status` attribute. When in the `pending`
-    # state, the `approve` action will transition the `status` to `approved`.
-    #
-    # This creates a `status_approve` method which will change the state in memory.
-    #
-    # You will also have a instance method `flow` which will allow you to specify
-    # the action to take on the attribute.
-    #
-    # Example:
-    #
-    #   test_object.status_approve
-    #   # OR
-    #   test_object.flow(:approve, :status)
-    #
-    # You can also provide a block to receive arguments
-    #
-    # Example:
-    #
-    #   flow(:status) do
-    #     state :pending do
-    #       action :approve, to: :approved do |*args, **kwargs|
-    #         @args_received = {args: args, kwargs: kwargs}
-    #       end
-    #       action_allowed(:approve) { true } # Optional. Check some value on self
-    #     end
-    #   end
-    #
-    # The block will be evalutaed on the instance of the class declaring the flow.
-    # So `self` inside that action block will be the instance of the class.
-    #
-    # Example:
-    #
-    #   test_object.status_approve("arg1", "arg2", key: "value")
-    #   # @args_received will be {args: ["arg1", "arg2"], kwargs: {key: "value"}}
-    #
-    # If the action is not allowed, the transition will not be executed.
-    #
-    # Example:
-    #
-    #  flow(:status) do
-    #    state :pending do
-    #      action :approve, to: :approved do
-    #        @args_received = {args: args, kwargs: kwargs}
-    #      end
-    #      action_allowed(:approve) { false }
-    #    end
-    #  end
-    #
-    #  test_object.status_approve
-    #  # Will not transition because the action is not allowed
-    #
-    # You may also specify the `allow_if` option to check a condition before
-    # the action is allowed. The callable will be evaluated on the instance of
-    # the class declaring the flow. So `self` inside that block will be the
-    # instance of the class.
-    #
-    # Example:
-    #
-    #  flow(:status) do
-    #    state :pending do
-    #      action :approve, to: :approved, allow_if: -> { true }
-    #    end
-    #  end
-    #
-    #  test_object.status_approve
-    #  # Will transition to :approved if the condition is true
-    #
-    # If you declare states separately, for example in an enum, you can use the
-    # `action` method to declare the action on the attribute.
-    #
-    # Example:
-    #
-    #  enum :status, {pending: 0, approved: 1, rejected: 2}
-    #  flow(:status) do
-    #    action :approve, to: :approved, from: :pending
-    #    action :reject, to: :rejected, from: :approved do |rejected_at|
-    #      self.rejected_at = rejected_at
-    #    end
-    #  end
-    #
-    #  test_object.status_approve
-    #  # Will transition to :approved
-    #  test_object.status_reject
-    #  # Will transition to :rejected and set the rejected_at attribute
-    #
-    # By default, if there is no transition for the current state, the flow will
-    # raise an error. You can specify a no_action block to handle this case.
-    #
-    # Example:
-    #
-    #  flow(:status) do
-    #    no_action { |attribute_name, action| raise "Nope!" }
-    #  end
-    #
-    #  test_object.status_approve
-    #  # Will raise an error
-    #
-    # You can also provide a custom action for other behavior for a set of states and
-    # use the `to` option as a callable to set the attribute.
-    #
-    # Example:
-    #
-    #  flow(:status) do
-    #    action :unknown, to: -> { status }, from: [:enforcing, :monitoring, :ignoring] do |signal|
-    #      raise UnhandledSignalError, signal
-    #    end
-    #  end
-    #
-    #  test_object.flow(:unknown, :status, "signal")
-    #  # Will raise an UnhandledSignalError
-    #
-    def flow(attribute_name, model: to_s, &block)
-      @flows ||= {}
-      model_key = Circulator::Diverter.model_key(model)
-      @flows[model_key] ||= {}
-      @flows[model_key][attribute_name] = Circulator::Flow.new(model, attribute_name, &block)
-
-      flow_module = ancestors.find { |ancestor|
-        ancestor.name.to_s =~ /FlowMethods/
-      } || Module.new.tap do |mod|
-        include mod
-
-        const_set(:FlowMethods, mod)
-      end
-
-      object = if model == to_s
-        nil
-      else
-        Circulator::Diverter.methodize_name(model)
-      end
-
-      @flows.dig(model_key, attribute_name).transition_map.each do |action, transitions|
-        define_flow_method(attribute_name:, action:, transitions:, object:, owner: flow_module)
-      end
-    end
-    alias_method :circulator, :flow
-
-    def define_flow_method(attribute_name:, action:, transitions:, object:, owner:)
-      object_attribute_method = [object, attribute_name, action].compact.join("_")
-      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)
-
-        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::Diverter.model_key(flow_target), attribute_name).no_action)
-          return
-        end
-
-        if transition[:allow_if]
-          return unless flow_target.instance_exec(*args, **kwargs, &transition[:allow_if])
-        end
-
-        if transition[:block]
-          flow_target.instance_exec(*args, **kwargs, &transition[:block])
-        end
-
-        if transition[:to].respond_to?(:call)
-          flow_target.send("#{attribute_name}=", flow_target.instance_exec(*args, **kwargs, &transition[:to]))
-        else
-          flow_target.send("#{attribute_name}=", transition[:to])
-        end.tap do
-          if block
-            flow_target.instance_exec(*args, **kwargs, &block)
-          end
-        end
-      end
-    end
-
-    module_function def model_key(object)
-      if object.is_a?(String)
-        if object.start_with?("#<Class:")
-          "anonymous_#{object.split("0x")[1]}".sub(">", "")
-        else
-          object
-        end
-      else
-        model_key(object.class.name || object.class.to_s)
-      end
-    end
-
-    module_function def methodize_name(name)
-      name.split("::").map { |part| part.gsub(/([a-z])([A-Z])/, '\1_\2') }.join("_").downcase
-    end
-
-    def self.extended(base)
-      base.include(InstanceMethods)
-      base.singleton_class.attr_reader :flows
-    end
-
-    module InstanceMethods
-      # Use this method to call an action on the attribute.
-      #
-      # 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)
-        target_name = if flow_target != self
-          Circulator::Diverter.methodize_name(Circulator::Diverter.model_key(flow_target))
-        end
-        external_attribute_name = [target_name, attribute].compact.join("_")
-        method_name = "#{external_attribute_name}_#{action}"
-        if respond_to?(method_name)
-          send(method_name, *args, flow_target:, **kwargs, &block)
-        elsif flow_target.respond_to?(method_name)
-          flow_target.send(method_name, *args, **kwargs, &block)
-        else
-          raise "Invalid action for the current state of #{attribute} (#{flow_target.send(attribute).inspect}): #{action}"
-        end
-      end
-
-      private
-
-      def flows
-        self.class.flows
-      end
-    end
-  end
-end