statesmin 1.0.0

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/statesmin.rb

@@ -0,0 +1,8 @@
+module Statesmin
+  autoload :Callback,         'statesmin/callback'
+  autoload :Guard,            'statesmin/guard'
+  autoload :Machine,          'statesmin/machine'
+  autoload :TransitionHelper, 'statesmin/transition_helper'
+  autoload :Version,          'statesmin/version'
+  require 'statesmin/railtie' if defined?(::Rails::Railtie)
+end

data/lib/statesmin/callback.rb

@@ -0,0 +1,52 @@
+require_relative "exceptions"
+
+module Statesmin
+  class Callback
+    attr_reader :from
+    attr_reader :to
+    attr_reader :callback
+
+    def initialize(options = { from: nil, to: nil, callback: nil })
+      unless options[:callback].respond_to?(:call)
+        raise InvalidCallbackError, "No callback passed"
+      end
+
+      @from     = options[:from]
+      @to       = Array(options[:to])
+      @callback = options[:callback]
+    end
+
+    def call(*args)
+      callback.call(*args)
+    end
+
+    def applies_to?(options = { from: nil, to: nil })
+      matches(options[:from], options[:to])
+    end
+
+    private
+
+    def matches(from, to)
+      matches_all_transitions ||
+        matches_to_state(from, to) ||
+        matches_from_state(from, to) ||
+        matches_both_states(from, to)
+    end
+
+    def matches_all_transitions
+      from.nil? && to.empty?
+    end
+
+    def matches_from_state(from, to)
+      (from == self.from && (to.nil? || self.to.empty?))
+    end
+
+    def matches_to_state(from, to)
+      ((from.nil? || self.from.nil?) && self.to.include?(to))
+    end
+
+    def matches_both_states(from, to)
+      from == self.from && self.to.include?(to)
+    end
+  end
+end

data/lib/statesmin/exceptions.rb

@@ -0,0 +1,21 @@
+module Statesmin
+  class InvalidStateError < StandardError; end
+  class InvalidTransitionError < StandardError; end
+  class InvalidCallbackError < StandardError; end
+  class GuardFailedError < StandardError; end
+  class TransitionFailedError < StandardError; end
+  class TransitionConflictError < StandardError; end
+
+  class NotImplementedError < StandardError
+    def initialize(method_name, transition_class_name)
+      super(_message(method_name, transition_class_name))
+    end
+
+    private
+
+    def _message(method_name, transition_class_name)
+      "'#{method_name}' method is not defined in '#{transition_class_name}'." \
+      "Either define this method or do not include 'TransitionHelper'."
+    end
+  end
+end

data/lib/statesmin/guard.rb

@@ -0,0 +1,13 @@
+require_relative "callback"
+require_relative "exceptions"
+
+module Statesmin
+  class Guard < Callback
+    def call(*args)
+      unless super(*args)
+        raise GuardFailedError,
+              "Guard on transition from: '#{from}' to '#{to}' returned false"
+      end
+    end
+  end
+end

data/lib/statesmin/machine.rb

@@ -0,0 +1,276 @@
+require_relative "version"
+require_relative "exceptions"
+require_relative "guard"
+require_relative "callback"
+
+module Statesmin
+  # The main module, that should be `extend`ed in to state machine classes.
+  module Machine
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.send(:attr_reader, :object)
+    end
+
+    # Retry any transitions that fail due to a TransitionConflictError
+    def self.retry_conflicts(max_retries = 1)
+      retry_attempt = 0
+
+      begin
+        yield
+      rescue TransitionConflictError
+        retry_attempt += 1
+        retry_attempt <= max_retries ? retry : raise
+      end
+    end
+
+    module ClassMethods
+      attr_reader :initial_state
+
+      def states
+        @states ||= []
+      end
+
+      def state(name, options = { initial: false })
+        name = name.to_s
+        if options[:initial]
+          validate_initial_state(name)
+          @initial_state = name
+        end
+        states << name
+      end
+
+      def successors
+        @successors ||= {}
+      end
+
+      def callbacks
+        @callbacks ||= {
+          before:       [],
+          after:        [],
+          after_commit: [],
+          guards:       []
+        }
+      end
+
+      def transition(from: nil, to: nil)
+        from = to_s_or_nil(from)
+        to = array_to_s_or_nil(to)
+
+        raise InvalidStateError, "No to states provided." if to.empty?
+
+        successors[from] ||= []
+
+        ([from] + to).each { |state| validate_state(state) }
+
+        successors[from] += to
+      end
+
+      def before_transition(options = {}, &block)
+        add_callback(callback_type: :before, callback_class: Callback,
+                     from: options[:from], to: options[:to], &block)
+      end
+
+      def guard_transition(options = {}, &block)
+        add_callback(callback_type: :guards, callback_class: Guard,
+                     from: options[:from], to: options[:to], &block)
+      end
+
+      def after_transition(options = { after_commit: false }, &block)
+        callback_type = options[:after_commit] ? :after_commit : :after
+
+        add_callback(callback_type: callback_type, callback_class: Callback,
+                     from: options[:from], to: options[:to], &block)
+      end
+
+      def validate_callback_condition(options = { from: nil, to: nil })
+        from = to_s_or_nil(options[:from])
+        to   = array_to_s_or_nil(options[:to])
+
+        ([from] + to).compact.each { |state| validate_state(state) }
+        return if from.nil? && to.empty?
+
+        validate_not_from_terminal_state(from)
+        to.each { |state| validate_not_to_initial_state(state) }
+
+        return if from.nil? || to.empty?
+
+        to.each { |state| validate_from_and_to_state(from, state) }
+      end
+
+      # Check that the 'from' state is not terminal
+      def validate_not_from_terminal_state(from)
+        unless from.nil? || successors.keys.include?(from)
+          raise InvalidTransitionError,
+                "Cannot transition away from terminal state '#{from}'"
+        end
+      end
+
+      # Check that the 'to' state is not initial
+      def validate_not_to_initial_state(to)
+        unless to.nil? || successors.values.flatten.include?(to)
+          raise InvalidTransitionError,
+                "Cannot transition to initial state '#{to}'"
+        end
+      end
+
+      # Check that the transition is valid when 'from' and 'to' are given
+      def validate_from_and_to_state(from, to)
+        unless successors.fetch(from, []).include?(to)
+          raise InvalidTransitionError,
+                "Cannot transition from '#{from}' to '#{to}'"
+        end
+      end
+
+      def validate_state(state)
+        unless states.include?(state.to_s)
+          raise InvalidStateError, "Invalid state '#{state}'"
+        end
+      end
+
+      private
+
+      def add_callback(callback_type: nil, callback_class: nil,
+                       from: nil, to: nil, &block)
+        validate_callback_type_and_class(callback_type, callback_class)
+
+        from = to_s_or_nil(from)
+        to   = array_to_s_or_nil(to)
+
+        validate_callback_condition(from: from, to: to)
+
+        callbacks[callback_type] <<
+          callback_class.new(from: from, to: to, callback: block)
+      end
+
+      def validate_callback_type_and_class(callback_type, callback_class)
+        if callback_type.nil?
+          raise ArgumentError.new("missing keyword: callback_type")
+        end
+        if callback_class.nil?
+          raise ArgumentError.new("missing keyword: callback_class")
+        end
+      end
+
+      def validate_initial_state(state)
+        unless initial_state.nil?
+          raise InvalidStateError, "Cannot set initial state to '#{state}', " \
+                                   "already defined as #{initial_state}."
+        end
+      end
+
+      def to_s_or_nil(input)
+        input.nil? ? input : input.to_s
+      end
+
+      def array_to_s_or_nil(input)
+        Array(input).map { |item| to_s_or_nil(item) }
+      end
+    end
+
+    attr_reader :current_state
+
+    def initialize(object, options = {})
+      @object = object
+
+      if (new_state = options[:state] && options[:state].to_s)
+        self.class.validate_state(new_state)
+        @current_state = new_state
+      else
+        @current_state = self.class.initial_state
+      end
+      send(:after_initialize) if respond_to? :after_initialize
+    end
+
+    def in_state?(*states)
+      states.flatten.any? { |state| current_state == state.to_s }
+    end
+
+    def allowed_transitions
+      successors_for(current_state).select do |state|
+        can_transition_to?(state)
+      end
+    end
+
+    def can_transition_to?(new_state, metadata = {})
+      validate_transition(from: current_state,
+                          to: new_state,
+                          metadata: metadata)
+      true
+    rescue TransitionFailedError, GuardFailedError
+      false
+    end
+
+    def transition_to!(new_state, metadata = {}, &block)
+      initial_state = current_state
+      new_state = new_state.to_s
+
+      validate_transition(from: initial_state,
+                          to: new_state,
+                          metadata: metadata)
+
+      block_value = block.call(new_state, metadata) if block_given?
+      @current_state = new_state
+
+      block_value || true
+    end
+
+    def execute(phase, initial_state, new_state, transition)
+      callbacks = callbacks_for(phase, from: initial_state, to: new_state)
+      callbacks.each { |cb| cb.call(@object, transition) }
+    end
+
+    def transition_to(new_state, metadata = {}, &block)
+      self.transition_to!(new_state, metadata, &block)
+    rescue TransitionFailedError, GuardFailedError
+      false
+    end
+
+    private
+
+    def adapter_class(transition_class)
+      if transition_class == Statesmin::Adapters::MemoryTransition
+        Adapters::Memory
+      else
+        Statesmin.storage_adapter
+      end
+    end
+
+    def successors_for(from)
+      self.class.successors[from] || []
+    end
+
+    def guards_for(options = { from: nil, to: nil })
+      select_callbacks_for(self.class.callbacks[:guards], options)
+    end
+
+    def callbacks_for(phase, options = { from: nil, to: nil })
+      select_callbacks_for(self.class.callbacks[phase], options)
+    end
+
+    def select_callbacks_for(callbacks, options = { from: nil, to: nil })
+      from = to_s_or_nil(options[:from])
+      to   = to_s_or_nil(options[:to])
+      callbacks.select { |callback| callback.applies_to?(from: from, to: to) }
+    end
+
+    def validate_transition(options = { from: nil, to: nil, metadata: nil })
+      from = to_s_or_nil(options[:from])
+      to   = to_s_or_nil(options[:to])
+
+      successors = self.class.successors[from] || []
+      unless successors.include?(to)
+        raise TransitionFailedError,
+              "Cannot transition from '#{from}' to '#{to}'"
+      end
+
+      # Call all guards, they raise exceptions if they fail
+      guards_for(from: from, to: to).each do |guard|
+        guard.call(@object, options[:metadata])
+      end
+    end
+
+    def to_s_or_nil(input)
+      input.nil? ? input : input.to_s
+    end
+  end
+end

data/lib/statesmin/railtie.rb

@@ -0,0 +1,5 @@
+module Statesmin
+  class Railtie < ::Rails::Railtie
+    railtie_name :statesmin
+  end
+end

data/lib/statesmin/transition_helper.rb

@@ -0,0 +1,41 @@
+require_relative "exceptions"
+
+module Statesmin
+  module TransitionHelper
+    # Methods to delegate to `state_machine`
+    DELEGATED_METHODS = [:allowed_transitions, :can_transition_to?,
+                         :current_state, :in_state?].freeze
+
+    # Delegate the methods
+    DELEGATED_METHODS.each do |method_name|
+      module_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{method_name}(*args)
+          state_machine.#{method_name}(*args)
+        end
+      RUBY
+    end
+
+    def transition_to!(next_state, data = {})
+      raise_transition_not_defined_error unless respond_to?(:transition)
+      state_machine.transition_to!(next_state, data) do
+        transition(next_state, data)
+      end
+    end
+
+    def transition_to(next_state, data = {})
+      transition_to!(next_state, data)
+    rescue Statesmin::TransitionFailedError, Statesmin::GuardFailedError
+      false
+    end
+
+    private
+
+    def state_machine
+      raise Statesmin::NotImplementedError.new('state_machine', self.class.name)
+    end
+
+    def raise_transition_not_defined_error
+      raise Statesmin::NotImplementedError.new('transition', self.class.name)
+    end
+  end
+end

data/lib/statesmin/version.rb

@@ -0,0 +1,3 @@
+module Statesmin
+  VERSION = "1.0.0"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+require "statesmin"
+require "rspec/its"
+
+RSpec.configure do |config|
+  config.raise_errors_for_deprecations!
+  config.mock_with(:rspec) { |mocks| mocks.verify_partial_doubles = true }
+
+  config.default_formatter = 'doc'
+  config.color = true
+  config.order = "random"
+end