nxt_state_machine 0.1.0

data/lib/nxt_state_machine/errors/state_already_registered.rb

@@ -0,0 +1,5 @@
+module NxtStateMachine
+  module Errors
+    StateAlreadyRegistered = Class.new(Error)
+  end
+end

data/lib/nxt_state_machine/errors/transition_already_registered.rb

@@ -0,0 +1,5 @@
+module NxtStateMachine
+  module Errors
+    TransitionAlreadyRegistered = Class.new(Error)
+  end
+end

data/lib/nxt_state_machine/errors/transition_halted.rb

@@ -0,0 +1,12 @@
+module NxtStateMachine
+  module Errors
+    class TransitionHalted < Error
+      def initialize(*args, **opts)
+        super(*args)
+        @options = opts
+      end
+
+      attr_reader :options
+    end
+  end
+end

data/lib/nxt_state_machine/errors/transition_not_defined.rb

@@ -0,0 +1,5 @@
+module NxtStateMachine
+  module Errors
+    TransitionNotDefined = Class.new(Error)
+  end
+end

data/lib/nxt_state_machine/errors/unknown_state_error.rb

@@ -0,0 +1,5 @@
+module NxtStateMachine
+  module Errors
+    UnknownStateError = Class.new(Error)
+  end
+end

data/lib/nxt_state_machine/event.rb

@@ -0,0 +1,49 @@
+module NxtStateMachine
+  class Event
+    include NxtRegistry
+
+    def initialize(name, state_machine:, &block)
+      @state_machine = state_machine
+      @name = name
+      @event_transitions = registry("#{name} event transitions")
+
+      configure(&block)
+
+      ensure_event_has_transitions
+    end
+
+    attr_reader :name, :state_machine, :event_transitions
+
+    delegate :before_transition,
+             :after_transition,
+             :around_transition,
+             :on_error,
+             :on_error!,
+             :any_state,
+             :all_states,
+             :all_states_except,
+             to: :state_machine
+
+    def transitions(from:, to:, &block)
+      Array(from).each do |from_state|
+        transition = Transition.new(name, from: from_state, to: to, state_machine: state_machine, &block)
+        state_machine.transitions << transition
+        event_transitions.register(from_state, transition)
+      end
+    end
+
+    alias_method :transition, :transitions
+
+    private
+
+    def configure(&block)
+      instance_exec(&block)
+    end
+
+    def ensure_event_has_transitions
+      return if event_transitions.size > 0
+
+      raise NxtStateMachine::Errors::EventWithoutTransitions, "No transitions for event :#{name} defined"
+    end
+  end
+end

data/lib/nxt_state_machine/event_registry.rb

@@ -0,0 +1,11 @@
+module NxtStateMachine
+  class EventRegistry < NxtRegistry::Registry
+    def initialize
+      super :events do
+        on_key_already_registered do |key|
+          raise NxtStateMachine::Errors::EventAlreadyRegistered, "An event with the name '#{key}' was already registered!"
+        end
+      end
+    end
+  end
+end

data/lib/nxt_state_machine/integrations/active_record.rb

@@ -0,0 +1,77 @@
+module NxtStateMachine
+  module ActiveRecord
+    module ClassMethods
+      def state_machine(name = :default, state_attr: :state, target: nil, &config)
+        machine = super(
+          name,
+          state_attr: state_attr,
+          target: target,
+          &config
+        )
+
+        machine.get_state_with do |target|
+          if target
+            if target.send(state_attr).nil? && target.new_record?
+              target.assign_attributes(state_attr => machine.initial_state.to_s)
+            end
+
+            current_state = target.send(state_attr)
+            current_state&.to_sym
+          end
+        end
+
+        machine.set_state_with do |target, transition|
+          target.transaction do
+            transition.run_before_callbacks
+            result = set_state(target, transition, state_attr, :save)
+            transition.run_after_callbacks
+
+            result
+          end
+        rescue StandardError => error
+          target.assign_attributes(state_attr => transition.from.to_s)
+
+          if error.is_a?(NxtStateMachine::Errors::TransitionHalted)
+            false
+          else
+            raise
+          end
+        end
+
+        machine.set_state_with! do |target, transition|
+          target.transaction do
+            transition.run_before_callbacks
+            result = set_state(target, transition, state_attr, :save!)
+            transition.run_after_callbacks
+
+            result
+          end
+        rescue StandardError
+          target.assign_attributes(state_attr => transition.from.to_s)
+          raise
+        end
+
+        machine
+      end
+    end
+
+    module InstanceMethods
+      private
+
+      def set_state(target, transition, state_attr, method)
+        transition.execute do |block|
+          result = block ? block.call : nil
+          target.assign_attributes(state_attr => transition.to.to_s)
+          set_state_result = target.send(method) || halt_transition
+          block ? result : set_state_result
+        end
+      end
+    end
+
+    def self.included(base)
+      base.include(NxtStateMachine)
+      base.include(InstanceMethods)
+      base.extend(ClassMethods)
+    end
+  end
+end

data/lib/nxt_state_machine/integrations/attr_accessor.rb

@@ -0,0 +1,69 @@
+module NxtStateMachine
+  module AttrAccessor
+    module ClassMethods
+      def state_machine(name = :default, state_attr: :state, target: nil, &config)
+        machine = super(
+          name,
+          state_attr: state_attr,
+          target: target,
+          &config
+        )
+
+        machine.get_state_with do |target|
+          if target.send(state_attr).nil?
+            target.send("#{state_attr}=", initial_state.enum)
+          end
+
+          target.send(state_attr)
+        end
+
+        machine.set_state_with do |target, transition|
+          transition.run_before_callbacks
+          result = set_state(target, transition, state_attr)
+          transition.run_after_callbacks
+
+          result
+        rescue StandardError => error
+          target.send("#{state_attr}=", transition.from.enum)
+
+          if error.is_a?(NxtStateMachine::Errors::TransitionHalted)
+            false
+          else
+            raise
+          end
+        end
+
+        machine.set_state_with! do |target, transition|
+          transition.run_before_callbacks
+          result = set_state(target, transition, state_attr)
+          transition.run_after_callbacks
+
+          result
+        rescue StandardError
+          target.send("#{state_attr}=", transition.from.enum)
+          raise
+        end
+
+        machine
+      end
+    end
+
+    module InstanceMethods
+      private
+
+      def set_state(target, transition, state_attr)
+        transition.execute do |block|
+          result = block ? block.call : nil
+          set_state_result = target.send("#{state_attr}=", transition.to.enum)
+          block ? result : set_state_result
+        end
+      end
+    end
+
+    def self.included(base)
+      base.include(NxtStateMachine)
+      base.include(InstanceMethods)
+      base.extend(ClassMethods)
+    end
+  end
+end

data/lib/nxt_state_machine/integrations/hash.rb

@@ -0,0 +1,67 @@
+module NxtStateMachine
+  module Hash
+    module ClassMethods
+      def state_machine(name = :default, state_attr: :state, target: nil, &config)
+        machine = super(
+          name,
+          state_attr: state_attr,
+          target: target,
+          &config
+        )
+
+        machine.get_state_with do |target|
+          if target[state_attr].nil?
+            target[state_attr] = initial_state.enum
+          end
+
+          target[state_attr]
+        end
+
+        machine.set_state_with do |target, transition|
+          transition.run_before_callbacks
+          result = set_state(target, transition, state_attr)
+          transition.run_after_callbacks
+          result
+        rescue StandardError => error
+          target[state_attr] = transition.from.enum
+
+          if error.is_a?(NxtStateMachine::Errors::TransitionHalted)
+            false
+          else
+            raise
+          end
+        end
+
+        machine.set_state_with! do |target, transition|
+          transition.run_before_callbacks
+          result = set_state(target, transition, state_attr)
+          transition.run_after_callbacks
+
+          result
+        rescue StandardError
+          target[state_attr] = transition.from.enum
+          raise
+        end
+
+        machine
+      end
+    end
+
+    module InstanceMethods
+      private
+
+      def set_state(target, transition, state_attr)
+        transition.execute do |block|
+          result = block ? block.call : nil
+          set_state_result = target[state_attr] = transition.to.enum || halt_transition
+          block ? result : set_state_result
+        end
+      end
+    end
+
+    def self.included(base)
+      base.include(NxtStateMachine)
+      base.extend(ClassMethods)
+    end
+  end
+end

data/lib/nxt_state_machine/state.rb

@@ -0,0 +1,17 @@
+module NxtStateMachine
+  class State
+    def initialize(enum, machine, **opts)
+      @enum = enum
+      @machine = machine
+      @initial = opts.delete(:initial)
+      @transitions = []
+      @options = opts.with_indifferent_access
+    end
+
+    attr_accessor :enum, :initial, :transitions, :machine, :options
+
+    def to_s
+      enum.to_s
+    end
+  end
+end

data/lib/nxt_state_machine/state_machine.rb

@@ -0,0 +1,179 @@
+module NxtStateMachine
+  class StateMachine
+    def initialize(name, class_context, event_registry, **opts)
+      @name = name
+      @class_context = class_context
+      @options = opts
+
+      @states = NxtStateMachine::StateRegistry.new
+      @transitions = Transition::Store.new
+      @events = event_registry
+      @callbacks = CallbackRegistry.new
+      @error_callback_registry = ErrorCallbackRegistry.new
+
+      @initial_state = nil
+    end
+
+    attr_reader :class_context, :states, :transitions, :events, :options, :callbacks, :name, :error_callback_registry
+    attr_accessor :initial_state
+
+    def get_state_with(method = nil, &block)
+      method_or_block = (method || block)
+      @get_state_with ||= method_or_block && Callable.new(method_or_block) ||
+        raise_missing_configuration_error(:get_state_with)
+    end
+
+    def set_state_with(method = nil, &block)
+      method_or_block = (method || block)
+      @set_state_with ||= method_or_block && Callable.new(method_or_block) ||
+        raise_missing_configuration_error(:set_state_with)
+    end
+
+    def set_state_with!(method = nil, &block)
+      method_or_block = (method || block)
+      @set_state_with_bang ||= method_or_block && Callable.new(method_or_block) ||
+        raise_missing_configuration_error(:set_state_with!)
+    end
+
+    def state(*names, **opts, &block)
+      defaults = { initial: false }
+      opts.reverse_merge!(defaults)
+      machine = self
+
+      Array(names).map do |name|
+        if opts.fetch(:initial) && initial_state.present?
+          raise NxtStateMachine::Errors::InitialStateAlreadyDefined, ":#{initial_state.enum} was already defined as the initial state"
+        else
+          state = new_state_class(&block).new(name, self, opts)
+          states.register(name, state)
+          self.initial_state = state if opts.fetch(:initial)
+
+          class_context.define_method "#{name}?" do
+            # States internally are always strings
+            machine.current_state_name(self) == name
+          end
+
+          state
+        end
+      end
+    end
+
+    def transitions
+      @transitions ||= events.values.flat_map(&:event_transitions)
+    end
+
+    def all_transitions_from_to(from: all_states, to: all_states)
+      transitions.select { |transition| transition.transitions_from_to?(from, to) }
+    end
+
+    def any_state
+      states.values.map(&:enum)
+    end
+
+    alias_method :all_states, :any_state
+
+    def all_states_except(*excluded)
+      all_states - excluded
+    end
+
+    def event(name, &block)
+      event = Event.new(name, state_machine: self, &block)
+      events.register(name, event)
+
+      class_context.define_method name do |*args, **opts|
+        event.state_machine.can_transition!(name, event.state_machine.current_state_name(self))
+        transition = event.event_transitions.resolve(event.state_machine.current_state_name(self))
+        transition.prepare(name, self, :set_state_with, *args, **opts)
+      end
+
+      class_context.define_method "#{name}!" do |*args, **opts|
+        event.state_machine.can_transition!(name, event.state_machine.current_state_name(self))
+        transition = event.event_transitions.resolve(event.state_machine.current_state_name(self))
+        transition.prepare("#{name}!", self, :set_state_with!, *args, **opts)
+      end
+
+      class_context.define_method "can_#{name}?" do
+        event.state_machine.can_transition?(name, event.state_machine.current_state_name(self))
+      end
+    end
+
+    def can_transition?(event_name, from)
+      normalized_event_name = event_name
+      event = events.resolve(normalized_event_name)
+      event && event.event_transitions.key?(from)
+    end
+
+    def can_transition!(event, from)
+      return true if can_transition?(event, from)
+      raise NxtStateMachine::Errors::TransitionNotDefined, "No transition :#{event} for state :#{from} defined"
+    end
+
+    def before_transition(from:, to:, run: nil, &block)
+      callbacks.register(from, to, :before, run, block)
+    end
+
+    def after_transition(from:, to:, run: nil, &block)
+      callbacks.register(from, to, :after, run, block)
+    end
+
+    def on_error(error = StandardError, from:, to:, run: nil, &block)
+      error_callback_registry.register(from, to, error, run, block)
+    end
+
+    def on_error!(error = StandardError, from:, to:, run: nil, &block)
+      error_callback_registry.register!(from, to, error, run, block)
+    end
+
+    def around_transition(from:, to:, run: nil, &block)
+      callbacks.register(from, to, :around, run, block)
+    end
+
+    def configure(&block)
+      instance_exec(&block)
+      self
+    end
+
+    def run_before_callbacks(transition, context)
+      run_callbacks(transition, :before, context)
+    end
+
+    def run_after_callbacks(transition, context)
+      run_callbacks(transition, :after, context)
+    end
+
+    def find_error_callback(error, transition)
+      error_callback_registry.resolve(error, transition)
+    end
+
+    def run_callbacks(transition, kind, context)
+      current_callbacks = callbacks.resolve(transition, kind)
+
+      current_callbacks.each do |callback|
+        Callable.new(callback).with_context(context).call(transition)
+      end
+    end
+
+    def current_state_name(context)
+      get_state_with.with_context(context).call(target(context))
+    end
+
+    def target(context)
+      @target_method ||= options[:target] || :itself
+      context.send(@target_method)
+    end
+
+    private
+
+    def raise_missing_configuration_error(method)
+      raise NxtStateMachine::Errors::MissingConfiguration, "Configuration method :#{method} was not defined"
+    end
+
+    def new_state_class(&block)
+      if block
+        Class.new(NxtStateMachine::State, &block)
+      else
+        NxtStateMachine::State
+      end
+    end
+  end
+end

data/lib/nxt_state_machine/state_registry.rb

@@ -0,0 +1,12 @@
+module NxtStateMachine
+  class StateRegistry < NxtRegistry::Registry
+    def initialize
+      super :states do
+        on_key_already_registered do |key|
+          raise NxtStateMachine::Errors::StateAlreadyRegistered,
+                "A state with the name '#{key}' was already registered!"
+        end
+      end
+    end
+  end
+end

data/lib/nxt_state_machine/transition/around_callback_chain.rb

@@ -0,0 +1,26 @@
+module NxtStateMachine
+  class Transition::AroundCallbackChain
+
+    def initialize(transition, context, state_machine)
+      @transition = transition
+      @context = context
+      @state_machine = state_machine
+    end
+
+    def build(proxy)
+      return proxy unless callbacks.any?
+
+      callbacks.map { |c| Callable.new(c).with_context(context) }.reverse.inject(proxy) do |previous, callback|
+        -> { callback.call(previous, transition) }
+      end
+    end
+
+    private
+
+    def callbacks
+      @callbacks ||= state_machine.callbacks.resolve(transition).kind(:around)
+    end
+
+    attr_reader :transition, :context, :state_machine
+  end
+end

data/lib/nxt_state_machine/transition/proxy.rb

@@ -0,0 +1,31 @@
+module NxtStateMachine
+  class Transition::Proxy
+    def initialize(event, state_machine, transition, context)
+      @event = event
+      @transition = transition
+      @state_machine = state_machine
+      @context = context
+    end
+
+    def call(&block)
+      proxy = if block.arity == 1
+        Proc.new do
+          block.call(transition.block_proxy)
+        end
+      else
+        block
+      end
+
+      around_callback_chain(proxy).call
+    end
+
+    private
+
+    def around_callback_chain(proxy)
+      @around_callback_chain ||= Transition::AroundCallbackChain.new(transition, context, state_machine).build(proxy)
+    end
+
+    attr_reader :proxy, :transition, :state_machine, :context, :event
+  end
+end
+

data/lib/nxt_state_machine/transition/store.rb

@@ -0,0 +1,19 @@
+module NxtStateMachine
+  class Transition::Store < Array
+    def <<(transition)
+      ensure_transition_unique(transition)
+      super
+    end
+
+    alias_method :add, :<<
+
+    private
+
+    def ensure_transition_unique(transition)
+      return unless find { |other| other.from.enum == transition.from.enum && other.to.enum == transition.to.enum }
+
+      raise NxtStateMachine::Errors::TransitionAlreadyRegistered,
+            "A transition from :#{transition.from.enum} to :#{transition.to.enum} was already registered"
+    end
+  end
+end

data/lib/nxt_state_machine/transition.rb

@@ -0,0 +1,87 @@
+module NxtStateMachine
+  class Transition
+    def initialize(name, from:, to:, state_machine:, &block)
+      @name = name
+      @from = state_machine.states.resolve(from)
+      @to = state_machine.states.resolve(to)
+      @state_machine = state_machine
+      @block = block
+
+      # TODO: Write a spec that verifies that transitions are unique
+      ensure_states_exist
+    end
+
+    attr_reader :name, :from, :to
+
+    # TODO: Probably would make sense if we could also define the event name to be passed in
+    # => This way we could differentiate what event triggered the callback!!!
+
+    def prepare(event, context, set_state_with_method, *args, **opts)
+      # This exposes the transition block on the transition_to_execute so it can be executed later in :set_state_with
+      current_transition = clone
+      current_transition.send(:context=, context)
+      current_transition.send(:event=, event)
+      current_transition.send(:block_proxy=, nil)
+
+      # block_proxy only is set when the transition accepts a block!
+      if block
+        proxy = Proc.new do
+          # if the block takes arguments we always pass the transition as the first one
+          args.prepend(current_transition) if block.arity > 0
+          context.instance_exec(*args, **opts, &block)
+        end
+
+        current_transition.send(:block_proxy=, proxy)
+      end
+
+      state_machine.send(
+        set_state_with_method
+      ).with_context(
+        context
+      ).call(state_machine.target(context), current_transition)
+    end
+
+    def execute(&block)
+      # This is called on the cloned transition from above!
+      Transition::Proxy.new(event, state_machine,self, context).call(&block)
+    rescue StandardError => error
+      callback = state_machine.find_error_callback(error, self)
+      raise unless callback
+
+      Callable.new(callback).with_context(context).call(error, self)
+    end
+
+    alias_method :with_around_callbacks, :execute
+
+    def run_before_callbacks
+      state_machine.run_before_callbacks(self, context)
+    end
+
+    def run_after_callbacks
+      state_machine.run_after_callbacks(self, context)
+    end
+
+    def transitions_from_to?(from_state, to_state)
+      from.enum.in?(Array(from_state)) && to.enum.in?(Array(to_state))
+    end
+
+    def id
+      @id ||= "#{from.to_s}_#{to.to_s}"
+    end
+
+    attr_reader :block_proxy, :event
+
+    private
+
+    delegate :all_states, to: :state_machine
+
+    attr_reader :block, :state_machine
+    attr_accessor :context
+    attr_writer :block_proxy, :event
+
+    def ensure_states_exist
+      raise NxtStateMachine::Errors::UnknownStateError, "No state with :#{from} registered" unless state_machine.states.key?(from.enum)
+      raise NxtStateMachine::Errors::UnknownStateError, "No state with :#{to} registered" unless state_machine.states.key?(to.enum)
+    end
+  end
+end