statesman 0.0.1

data/lib/statesman/adapters/memory.rb

@@ -0,0 +1,39 @@
+require "json"
+
+module Statesman
+  module Adapters
+    class Memory
+      attr_reader :transition_class
+      attr_reader :history
+      attr_reader :parent_model
+
+      # We only accept mode as a parameter to maintain a consistent interface
+      # with other adapters which require it.
+      def initialize(transition_class, parent_model)
+        @history = []
+        @transition_class = transition_class
+        @parent_model = parent_model
+      end
+
+      def create(to, before_cbs, after_cbs, metadata = {})
+        transition = transition_class.new(to, next_sort_key, metadata)
+
+        before_cbs.each { |cb| cb.call(@parent_model, transition) }
+        @history << transition
+        after_cbs.each { |cb| cb.call(@parent_model, transition) }
+
+        transition
+      end
+
+      def last
+        @history.sort_by(&:sort_key).last
+      end
+
+      private
+
+      def next_sort_key
+        (last && last.sort_key + 10) || 0
+      end
+    end
+  end
+end

data/lib/statesman/callback.rb

@@ -0,0 +1,34 @@
+require "statesman/exceptions"
+
+module Statesman
+  class Callback
+    attr_reader :from
+    attr_reader :to
+    attr_reader :callback
+
+    def initialize(from: nil, to: nil, callback: nil)
+      unless callback.respond_to?(:call)
+        raise InvalidCallbackError, "No callback passed"
+      end
+
+      @from = from
+      @to = to
+      @callback = callback
+    end
+
+    def call(*args)
+      callback.call(*args)
+    end
+
+    def applies_to?(from: nil, to: nil)
+      # rubocop:disable RedundantSelf
+      (self.from.nil? && self.to.nil?) ||
+      (from.nil? && to == self.to) ||
+      (self.from.nil? && to == self.to) ||
+      (from == self.from && to.nil?) ||
+      (from == self.from && self.to.nil?) ||
+      (from == self.from && to == self.to)
+      # rubocop:enable RedundantSelf
+    end
+  end
+end

data/lib/statesman/config.rb

@@ -0,0 +1,23 @@
+require "json"
+require "statesman/exceptions"
+
+module Statesman
+  class Config
+    attr_reader :adapter_class
+
+    def initialize(block = nil)
+      instance_eval(&block) unless block.nil?
+    end
+
+    # rubocop:disable TrivialAccessors
+    def storage_adapter(adapter_class)
+      @adapter_class = adapter_class
+    end
+    # rubocop:enable TrivialAccessors
+
+    def transition_class(*args)
+      args.each { |klass| klass.serialize(:metadata, JSON) }
+    end
+
+  end
+end

data/lib/statesman/exceptions.rb

@@ -0,0 +1,8 @@
+module Statesman
+  class InvalidStateError < StandardError; end
+  class InvalidTransitionError < StandardError; end
+  class InvalidCallbackError < StandardError; end
+  class GuardFailedError < StandardError; end
+  class TransitionFailedError < StandardError; end
+  class UnserializedMetadataError < StandardError; end
+end

data/lib/statesman/guard.rb

@@ -0,0 +1,15 @@
+require "statesman/callback"
+require "statesman/exceptions"
+
+module Statesman
+  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/statesman/machine.rb

@@ -0,0 +1,231 @@
+require "statesman/version"
+require "statesman/exceptions"
+require "statesman/guard"
+require "statesman/callback"
+require "statesman/transition"
+
+module Statesman
+  # 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
+
+    module ClassMethods
+      attr_reader :initial_state
+
+      def states
+        @states ||= []
+      end
+
+      def state(name, initial: false)
+        name = name.to_s
+        if initial
+          validate_initial_state(name)
+          @initial_state = name
+        end
+        states << name
+      end
+
+      def successors
+        @successors ||= {}
+      end
+
+      def before_callbacks
+        @before_callbacks ||= []
+      end
+
+      def after_callbacks
+        @after_callbacks ||= []
+      end
+
+      def guards
+        @guards ||= []
+      end
+
+      def transition(from: nil, to: nil)
+        from = to_s_or_nil(from)
+        to = Array(to).map { |item| to_s_or_nil(item) }
+
+        successors[from] ||= []
+
+        ([from] + to).each { |state| validate_state(state) }
+
+        successors[from] += to
+      end
+
+      def before_transition(from: nil, to: nil, &block)
+        from = to_s_or_nil(from)
+        to   = to_s_or_nil(to)
+
+        validate_callback_condition(from: from, to: to)
+        before_callbacks << Callback.new(from: from, to: to, callback: block)
+      end
+
+      def after_transition(from: nil, to: nil, &block)
+        from = to_s_or_nil(from)
+        to   = to_s_or_nil(to)
+
+        validate_callback_condition(from: from, to: to)
+        after_callbacks << Callback.new(from: from, to: to, callback: block)
+      end
+
+      def guard_transition(from: nil, to: nil, &block)
+        from = to_s_or_nil(from)
+        to   = to_s_or_nil(to)
+
+        validate_callback_condition(from: from, to: to)
+        guards << Guard.new(from: from, to: to, callback: block)
+      end
+
+      def validate_callback_condition(from: nil, to: nil)
+        from = to_s_or_nil(from)
+        to   = to_s_or_nil(to)
+
+        [from, to].compact.each { |state| validate_state(state) }
+        return if from.nil? && to.nil?
+
+        validate_not_from_terminal_state(from)
+        validate_not_to_initial_state(to)
+
+        return if from.nil? || to.nil?
+
+        validate_from_and_to_state(from, to)
+      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,
+                "Cannont 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,
+                "Cannont 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
+
+      private
+
+      def validate_state(state)
+        unless states.include?(state.to_s)
+          raise InvalidStateError, "Invalid state '#{state}'"
+        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
+    end
+
+    def initialize(object, transition_class: Statesman::Transition)
+      @object = object
+      @storage_adapter = Statesman.storage_adapter.new(transition_class,
+                                                       object)
+    end
+
+    def current_state
+      last_action = last_transition
+      last_action ? last_action.to_state : self.class.initial_state
+    end
+
+    def last_transition
+      @storage_adapter.last
+    end
+
+    def can_transition_to?(new_state, metadata = nil)
+      validate_transition(from: current_state,
+                          to: new_state,
+                          metadata: metadata)
+      true
+    rescue TransitionFailedError, GuardFailedError
+      false
+    end
+
+    def history
+      @storage_adapter.history
+    end
+
+    def transition_to!(new_state, metadata = nil)
+      initial_state = current_state
+      new_state = new_state.to_s
+
+      validate_transition(from: initial_state,
+                          to: new_state,
+                          metadata: metadata)
+
+      before_cbs = before_callbacks_for(from: initial_state, to: new_state)
+      after_cbs = after_callbacks_for(from: initial_state, to: new_state)
+
+      @storage_adapter.create(new_state, before_cbs, after_cbs, metadata)
+
+      true
+    end
+
+    def transition_to(new_state, metadata = nil)
+      self.transition_to!(new_state, metadata)
+    rescue
+      false
+    end
+
+    private
+
+    def guards_for(from: nil, to: nil)
+      select_callbacks_for(self.class.guards, from: from, to: to)
+    end
+
+    def before_callbacks_for(from: nil, to: nil)
+      select_callbacks_for(self.class.before_callbacks, from: from, to: to)
+    end
+
+    def after_callbacks_for(from: nil, to: nil)
+      select_callbacks_for(self.class.after_callbacks, from: from, to: to)
+    end
+
+    def select_callbacks_for(callbacks, from: nil, to: nil)
+      from = to_s_or_nil(from)
+      to   = to_s_or_nil(to)
+      callbacks.select { |callback| callback.applies_to?(from: from, to: to) }
+    end
+
+    def validate_transition(from: nil, to: nil, metadata: nil)
+      from = to_s_or_nil(from)
+      to   = to_s_or_nil(to)
+
+      # Call all guards, they raise exceptions if they fail
+      guards_for(from: from, to: to).each do |guard|
+        guard.call(@object, last_transition, metadata)
+      end
+
+      successors = self.class.successors[from] || []
+      unless successors.include?(to)
+        raise TransitionFailedError,
+              "Cannot transition from '#{from}' to '#{to}'"
+      end
+    end
+
+    def to_s_or_nil(input)
+      input.nil? ? input : input.to_s
+    end
+  end
+end

data/lib/statesman/transition.rb

@@ -0,0 +1,15 @@
+module Statesman
+  class Transition
+    attr_accessor :created_at
+    attr_accessor :to_state
+    attr_accessor :sort_key
+    attr_accessor :metadata
+
+    def initialize(to, sort_key, metadata = nil)
+      @created_at = Time.now
+      @to_state = to
+      @sort_key = sort_key
+      @metadata = metadata
+    end
+  end
+end

data/lib/statesman/version.rb

@@ -0,0 +1,3 @@
+module Statesman
+  VERSION = "0.0.1"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,33 @@
+require "statesman"
+require "sqlite3"
+require "active_record"
+require "support/active_record"
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+
+  config.order = 'random'
+
+  config.before(:each) do
+    # Connect to & cleanup test database
+    ActiveRecord::Base.establish_connection(adapter: "sqlite3",
+                                            database: DB.to_s)
+
+    %w(my_models my_model_transitions).each do |table_name|
+      sql = "DROP TABLE IF EXISTS #{table_name};"
+      ActiveRecord::Base.connection.execute(sql)
+    end
+
+    def prepare_model_table
+      silence_stream(STDOUT) { CreateMyModelMigration.migrate(:up) }
+    end
+
+    def prepare_transitions_table
+      silence_stream(STDOUT) { CreateMyModelTransitionMigration.migrate(:up) }
+    end
+  end
+
+  config.after(:each) { DB.delete if DB.exist? }
+end

data/spec/statesman/adapters/active_record_spec.rb

@@ -0,0 +1,50 @@
+require "spec_helper"
+require "statesman/adapters/shared_examples"
+require "statesman/exceptions"
+
+describe Statesman::Adapters::ActiveRecord do
+  before do
+    prepare_model_table
+    prepare_transitions_table
+  end
+
+  before { MyModelTransition.serialize(:metadata, JSON) }
+
+  let(:model) { MyModel.create(current_state: :pending) }
+  it_behaves_like "an adapter", described_class, MyModelTransition
+
+  describe "#initialize" do
+    context "with unserialized metadata" do
+      before { MyModelTransition.stub(serialized_attributes: {}) }
+
+      it "raises an exception if metadata is not serialized" do
+        expect do
+          described_class.new(MyModelTransition, MyModel)
+        end.to raise_exception(Statesman::UnserializedMetadataError)
+      end
+    end
+  end
+
+  describe "#last" do
+    let(:adapter) { described_class.new(MyModelTransition, model) }
+
+    context "with a previously looked up transition" do
+      before do
+        adapter.create(:y, [], [])
+        adapter.last
+      end
+
+      it "caches the transition" do
+        MyModel.any_instance.should_receive(:my_model_transitions).never
+        adapter.last
+      end
+
+      context "and a new transition" do
+        before { adapter.create(:z, [], []) }
+        it "retrieves the new transition from the database" do
+          expect(adapter.last.to_state).to eq("z")
+        end
+      end
+    end
+  end
+end