steady_state 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b6ac44424729680f31b79e25aa8b110323aee6ec97824f19ac03f54921bc2213
+  data.tar.gz: 77f39b19b580b0930864cf8a867a9e41ae4fc4900356a65123e83359729110f6
+SHA512:
+  metadata.gz: 35ac9ceff1d5997e97b3a40840629b5665d26175e491e8ae28df4dd3fa99a64b4aa419122e60a3fc8372e9a6ccc0afa8c07136ea067eca9662d47d65f4099a58
+  data.tar.gz: e5394a77afb844a74d72f020f22fb343ec1d2d3bea2cdc98a1a0d2db2c6e3a28d0b85cd930b47a4221946830d40f0c52acc9f217d9262337f7c3b4f692678fc0

data/README.md

@@ -0,0 +1,259 @@
+# SteadyState
+
+> A minimalist approach to managing object state, perhaps best described as an "enum with guard rails." Designed to work with `ActiveRecord` and `ActiveModel` classes, or anywhere where Rails validations are used.
+
+## Overview
+
+SteadyState takes idea of a [Finite State Machine](https://en.wikipedia.org/wiki/Finite-state_machine) and cuts out everything but the most basic declaration of states and transitions (i.e. a directed graph). It then uses ActiveModel validations to enforce these transition rules, and plays nicely with other `validates`/`validate` declarations on your model.
+
+All of the features one might expect of a Finite State Machine—take, for example, named events, conditional rules, transition hooks, and event callbacks—can then be implemented using existing methods like `valid?`, `errors`, `after_save`, and so on. This approach is effective in contexts that already rely on these methods for control flow (e.g. a Rails controller).
+
+Both `ActiveRecord` and `ActiveModel` classes are supported, as well as any class adhering to the `ActiveModel::Validations` APIs.
+
+## Installation
+
+Add this to your Gemfile:
+
+```
+gem 'steady_state'
+```
+
+## Getting Started
+
+To enable stateful behavior on an attribute or column, call `steady_state` with the name of the attribute, and define the states as strings, like so:
+
+```ruby
+class Material
+  include ActiveModel::Model
+  include SteadyState
+
+  attr_accessor :state
+
+  steady_state :state do
+    state 'solid', default: true
+    state 'liquid', from: 'solid'
+    state 'gas', from: 'liquid'
+    state 'plasma', from: 'gas'
+  end
+end
+```
+
+The `:from` option specifies the state transition rules, i.e. which state(s) a given state is allowed to transition from. It may accept either a single state, or a list of states:
+
+```ruby
+state 'cancelled', from: %w(step-1 step-2)
+```
+
+The `:default` option defines the state that your object will start in if no other state is provided:
+
+```ruby
+material = Material.new
+material.state # => 'solid'
+```
+
+You may always instantiate a new object in any state, regardless of the default:
+
+```ruby
+material = Material.new(state: 'liquid')
+material.state # => 'liquid'
+```
+
+A class may have any number of these `steady_state` declarations, one per stateful attribute.
+
+### Moving Between States
+
+After your object has been instantiated (or loaded from a database via your ORM), the transitional validations and rules begin to take effect. To change the state, simply use the attribute's setter (e.g. `state=`), and then call `valid?` to see if the change will be accepted:
+
+```ruby
+material.state.solid? # => true
+material.state = 'liquid'
+material.state # => 'liquid'
+material.valid? # => true
+```
+
+If the change is not valid, a validation error will be added to the object:
+
+```ruby
+material.state.liquid? # => true
+material.state = 'solid'
+material.state # => 'solid'
+material.valid? # => false
+material.errors[:state] # => ['is invalid']
+```
+
+#### A Deliberate Design Choice
+
+Notice that even when the rules are violated, the state attribute does not revert to the previous state, nor is an exception raised inside of the setter. This is a deliberate design decision.
+
+Compare this behavior to, say, a numericality validation:
+
+```ruby
+validates :amount, numericality: { greater_than: 0 }
+
+model = MyModel.new(amount: -100)
+model.amount # => -100
+model.valid? # false
+model.errors[:amount] # => ['must be greater than 0']
+```
+
+In keeping with the general pattern of `ActiveModel::Validations`, we rely on an object's _current state in memory_ to determine whether or not it is valid. For both the `state` and `amount` fields, the attribute is allowed to hold an invalid value, resulting in a validation error on the object.
+
+#### Custom Validations
+
+In addition to the built-in transitional validations, you can define your own validations that take effect only when the object enters a specific state:
+
+```ruby
+validates :container, absence: true, if: :solid?
+validates :container, presence: true, if: :liquid?
+```
+
+With such a validation in place, a state change will not be valid unless the related validation rules are resolved at the same time:
+
+```ruby
+object.update!(state: 'liquid') # !! ActiveRecord::RecordInvalid
+object.update!(state: 'liquid', container: Cup.new) # 🎉
+```
+
+With these tools, you can define rich sets of state-aware rules about your object, and then rely simply on built-in methods like `valid?` and `errors` to determine if an operation violates these rules.
+
+### Bringing it All Together
+
+Commonly, state transition events are expected to have names, like "melt" and "evaporate," and other such _action verbs_. SteadyState has no such expectation, and will not define any named events for you.
+
+If you need them, we encourage you to define these transitions using plain ol' Ruby methods, like so:
+
+```ruby
+def melt
+  self.state = 'liquid'
+  valid? # will return `false` if state transition is invalid
+end
+
+def melt!
+  self.state = 'liquid'
+  validate! # will raise an exception if state transition is invalid
+end
+```
+
+If you are using ActiveRecord, you can rely on built-in persistence methods to construct your state transition operations:
+
+```ruby
+def melt
+  update(state: 'liquid')
+end
+
+def melt!
+  update!(state: 'liquid')
+end
+```
+
+For complex persistence operations, we encourage the use of existing persistence helpers like `transaction` and `with_lock`, to provide atomicity and avoid race conditions:
+
+```ruby
+def melt
+  with_lock do
+    if update(state: 'liquid', melted_at: Time.zone.now)
+      owner.update!(melt_count: owner.lock!.melt_count + 1)
+      Delayed::Job.enqueue MeltNotificationJob.new(self)
+      true
+    else
+      false
+    end
+  end
+end
+```
+
+Here is an example Rails controller making use of this new `melt` method:
+
+
+```ruby
+class MaterialsController < ApplicationController
+  def melt
+    @material = Material.find(params[:id])
+    if @material.melt
+      redirect_to material_path(@material)
+    else
+      render :edit
+    end
+  end
+end
+```
+
+With the ability to define your states, apply transitional validations, and persist state changes, you should have everything you need to start using SteadyState inside of your application.
+
+## Addional Features & Configuration
+
+### Predicates
+
+Predicate methods (or "Huh methods") are automatically defined for each state:
+
+```ruby
+material = Material.new
+material.solid? # => true
+material.liquid? # => false
+```
+
+You can disable these if, for instance, they conflict with other methods:
+
+```ruby
+steady_state :status, predicates: false do
+  # ...
+end
+```
+
+Either way, predicate methods are always available on the value itself:
+
+```ruby
+material.status.solid? # => true
+material.status.liquid? # => false
+```
+
+### Scopes
+
+On ActiveRecord objects, scopes are automatically defined for each state:
+
+```ruby
+Material.solid # => query for 'solid' records
+Material.liquid # => query for 'liquid' records
+```
+
+These can be disabled as well:
+
+```ruby
+steady_state :step, scopes: false do
+  # ...
+end
+```
+
+### Next and Previous States
+
+The `may_become?` method can be used to see if setting the state to a particular value would be allowed (ignoring all other validations):
+
+```ruby
+material.state.may_become?('gas') #=> true
+material.state.may_become?('solid') #=> false
+```
+
+To get a list of all of the valid state transitions, use the `next_values` method:
+
+```ruby
+material.state.next_values # => ['gas']
+```
+
+As it stands, state history is not preserved, but it is still possible to get a list of all possible previous states using the `previous_values` method:
+
+```ruby
+material.state.previous_values # => ['solid']
+```
+
+## How to Contribute
+
+We would love for you to contribute! Anything that benefits the majority of `steady_state` users—from a documentation fix to an entirely new feature—is encouraged.
+
+Before diving in, check our issue tracker and consider creating a new issue to get early feedback on your proposed change.
+
+#### Suggested Workflow
+
+* Fork the project and create a new branch for your contribution.
+* Write your contribution (and any applicable test coverage).
+* Make sure all tests pass (bundle exec rake).
+* Submit a pull request.

data/Rakefile

@@ -0,0 +1,16 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+Bundler::GemHelper.install_tasks
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i(rubocop spec)

data/lib/steady_state.rb

@@ -0,0 +1,16 @@
+require 'active_support'
+require 'active_support/core_ext'
+require 'active_model'
+require 'steady_state/attribute'
+
+module SteadyState
+  extend ActiveSupport::Concern
+
+  def self.active_record?(klass)
+    defined?(ActiveRecord::Base) && klass < ActiveRecord::Base
+  end
+
+  included do
+    include Attribute
+  end
+end

data/lib/steady_state/attribute.rb

@@ -0,0 +1,58 @@
+require 'steady_state/attribute/state'
+require 'steady_state/attribute/state_machine'
+require 'steady_state/attribute/transition_validator'
+
+module SteadyState
+  module Attribute
+    extend ActiveSupport::Concern
+
+    included do
+      cattr_reader :state_machines do
+        Hash.new { |h, k| h[k] = StateMachine.new }
+      end
+    end
+
+    class_methods do
+      def steady_state(attr_name, predicates: true, scopes: SteadyState.active_record?(self), &block) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/LineLength
+        overrides = Module.new do
+          define_method :"validate_#{attr_name}_transition_to" do |next_value|
+            if public_send(attr_name).may_become?(next_value)
+              remove_instance_variable("@last_valid_#{attr_name}") if instance_variable_defined?("@last_valid_#{attr_name}")
+            elsif !instance_variable_defined?("@last_valid_#{attr_name}")
+              instance_variable_set("@last_valid_#{attr_name}", public_send(attr_name))
+            end
+          end
+
+          define_method :"#{attr_name}=" do |value|
+            unless instance_variable_defined?("@#{attr_name}_state_initialized")
+              instance_variable_set("@#{attr_name}_state_initialized", true)
+            end
+            public_send(:"validate_#{attr_name}_transition_to", value) if public_send(attr_name).present?
+            super(value)
+          end
+
+          define_method :"#{attr_name}" do |*args, &blk|
+            unless instance_variable_defined?("@#{attr_name}_state_initialized")
+              public_send(:"#{attr_name}=", state_machines[attr_name].start) if super(*args, &blk).blank?
+              instance_variable_set("@#{attr_name}_state_initialized", true)
+            end
+            last_valid_value = instance_variable_get("@last_valid_#{attr_name}") if instance_variable_defined?("@last_valid_#{attr_name}")
+            state_machines[attr_name].new_state super(*args, &blk), last_valid_value
+          end
+        end
+        prepend overrides
+
+        state_machines[attr_name].instance_eval(&block)
+        delegate(*state_machines[attr_name].predicates, to: attr_name, allow_nil: true) if predicates
+        if scopes
+          state_machines[attr_name].states.each do |state|
+            scope state.to_sym, -> { where(attr_name.to_sym => state) }
+          end
+        end
+
+        validates :"#{attr_name}", 'steady_state/attribute/transition' => true,
+                                   inclusion: { in: state_machines[attr_name].states }
+      end
+    end
+  end
+end

data/lib/steady_state/attribute/state.rb

@@ -0,0 +1,25 @@
+module SteadyState
+  module Attribute
+    class State < SimpleDelegator
+      attr_accessor :state_machine, :last_valid_value
+
+      def initialize(state_machine, current_value, last_valid_value)
+        self.state_machine = state_machine
+        self.last_valid_value = last_valid_value
+        super(current_value&.inquiry)
+      end
+
+      def may_become?(new_value)
+        next_values.include?(new_value)
+      end
+
+      def next_values
+        @next_values ||= state_machine.transitions[last_valid_value || self]
+      end
+
+      def previous_values
+        @previous_values ||= state_machine.transitions.select { |_, v| v.include?(last_valid_value || self) }.keys
+      end
+    end
+  end
+end

data/lib/steady_state/attribute/state_machine.rb

@@ -0,0 +1,31 @@
+module SteadyState
+  module Attribute
+    class StateMachine
+      attr_accessor :start
+
+      def state(state, default: false, from: [])
+        states << state
+        self.start = state if default
+        [from].flatten(1).each do |from_state|
+          transitions[from_state] << state
+        end
+      end
+
+      def new_state(value, last_valid_value)
+        State.new(self, value, last_valid_value) unless value.nil?
+      end
+
+      def states
+        @states ||= []
+      end
+
+      def predicates
+        states.map { |state| :"#{state.parameterize.underscore}?" }
+      end
+
+      def transitions
+        @transitions ||= Hash.new { |h, k| h[k] = [] }.with_indifferent_access
+      end
+    end
+  end
+end

data/lib/steady_state/attribute/transition_validator.rb

@@ -0,0 +1,9 @@
+module SteadyState
+  module Attribute
+    class TransitionValidator < ActiveModel::EachValidator
+      def validate_each(obj, attr_name, _value)
+        obj.errors.add(attr_name, :invalid) if obj.instance_variable_defined?("@last_valid_#{attr_name}")
+      end
+    end
+  end
+end

data/lib/steady_state/version.rb

@@ -0,0 +1,3 @@
+module SteadyState
+  VERSION = '0.0.1'.freeze
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require 'steady_state'

data/spec/steady_state/attribute_spec.rb

@@ -0,0 +1,370 @@
+require 'spec_helper'
+
+RSpec.describe SteadyState::Attribute do
+  let(:steady_state_class) do
+    Class.new do
+      include ActiveModel::Model
+      include SteadyState
+
+      def self.model_name
+        ActiveModel::Name.new(self, nil, 'steady_state_class')
+      end
+    end
+  end
+  subject { steady_state_class.new }
+
+  shared_examples 'a basic state machine' do
+    it 'starts on initial state' do
+      expect(subject.state).to eq 'solid'
+    end
+
+    it 'allows initialization to the initial state' do
+      expect(steady_state_class.new(state: 'solid')).to be_valid
+    end
+
+    it 'allows initialization to other states' do
+      expect(steady_state_class.new(state: 'plasma')).to be_valid
+    end
+
+    it 'adds validation errors when initializing to an invalid state' do
+      object = steady_state_class.new(state: 'banana')
+      expect(object).not_to be_valid
+      expect(object.errors[:state]).to match_array(['is not included in the list'])
+    end
+
+    it 'allows valid transitions' do
+      expect(subject.state.may_become?('liquid')).to eq true
+      expect(subject.state.next_values).to match_array(['liquid'])
+      expect(subject.state.previous_values).to match_array([])
+      expect { subject.state = 'liquid' }.to change { subject.state }.from('solid').to('liquid')
+      expect(subject).to be_valid
+
+      expect(subject.state.may_become?('gas')).to eq true
+      expect(subject.state.next_values).to match_array(['gas'])
+      expect(subject.state.previous_values).to match_array(['solid'])
+      expect { subject.state = 'gas' }.to change { subject.state }.from('liquid').to('gas')
+      expect(subject).to be_valid
+
+      expect(subject.state.may_become?('plasma')).to eq true
+      expect(subject.state.next_values).to match_array(['plasma'])
+      expect(subject.state.previous_values).to match_array(['liquid'])
+      expect { subject.state = 'plasma' }.to change { subject.state }.from('gas').to('plasma')
+      expect(subject).to be_valid
+      expect(subject.state.next_values).to be_empty
+      expect(subject.state.previous_values).to match_array(['gas'])
+    end
+
+    it 'adds validation errors for invalid transitions' do
+      expect(subject.state.may_become?('gas')).to eq false
+      expect { subject.state = 'gas' }.to change { subject.state }.from('solid').to('gas')
+      expect(subject).not_to be_valid
+      expect(subject.errors[:state]).to match_array(['is invalid'])
+      expect(subject.state.next_values).to match_array(['liquid'])
+      expect(subject.state.previous_values).to match_array([])
+
+      expect(subject.state.may_become?('plasma')).to eq false
+      expect { subject.state = 'plasma' }.to change { subject.state }.from('gas').to('plasma')
+      expect(subject).not_to be_valid
+      expect(subject.errors[:state]).to match_array(['is invalid'])
+      expect(subject.state.next_values).to match_array(['liquid'])
+      expect(subject.state.previous_values).to match_array([])
+
+      expect(subject.state.may_become?('solid')).to eq false
+      expect { subject.state = 'solid' }.to change { subject.state }.from('plasma').to('solid')
+      expect(subject).not_to be_valid
+      expect(subject.errors[:state]).to match_array(['is invalid'])
+      expect(subject.state.next_values).to match_array(['liquid'])
+      expect(subject.state.previous_values).to match_array([])
+    end
+  end
+
+  context 'with a single field and nothing fancy' do
+    before do
+      steady_state_class.module_eval do
+        attr_accessor :state
+
+        steady_state :state do
+          state 'solid', default: true
+          state 'liquid', from: 'solid'
+          state 'gas', from: 'liquid'
+          state 'plasma', from: 'gas'
+        end
+      end
+    end
+
+    it_behaves_like 'a basic state machine'
+
+    context 'with inheritance' do
+      let(:subclass) do
+        Class.new(steady_state_class) do
+          def initialize
+            # I do my own thing.
+          end
+        end
+      end
+      subject { subclass.new }
+
+      it_behaves_like 'a basic state machine'
+    end
+
+    context 'with an existing state value' do
+      before do
+        steady_state_class.module_eval do
+          def state
+            @state ||= 'liquid'
+          end
+        end
+      end
+
+      it 'starts on existing state' do
+        expect(subject.state).to eq 'liquid'
+      end
+
+      it 'does not allow initialization to an invalid next state' do
+        object = steady_state_class.new(state: 'solid')
+        expect(object).not_to be_valid
+        expect(object.errors[:state]).to match_array(['is invalid'])
+      end
+
+      it 'allows initialization to a valid next state' do
+        expect(steady_state_class.new(state: 'gas')).to be_valid
+      end
+
+      it 'adds validation errors when initializing to an invalid state' do
+        object = steady_state_class.new(state: 'banana')
+        expect(object).not_to be_valid
+        expect(object.errors[:state]).to match_array(['is invalid', 'is not included in the list'])
+      end
+
+      it 'allows valid transitions' do
+        expect(subject).to be_valid
+        expect(subject.state.may_become?('gas')).to eq true
+        expect(subject.state.next_values).to match_array(['gas'])
+        expect(subject.state.previous_values).to match_array(['solid'])
+        expect { subject.state = 'gas' }.to change { subject.state }.from('liquid').to('gas')
+        expect(subject).to be_valid
+
+        expect(subject.state.may_become?('plasma')).to eq true
+        expect(subject.state.next_values).to match_array(['plasma'])
+        expect(subject.state.previous_values).to match_array(['liquid'])
+        expect { subject.state = 'plasma' }.to change { subject.state }.from('gas').to('plasma')
+        expect(subject).to be_valid
+        expect(subject.state.next_values).to be_empty
+        expect(subject.state.previous_values).to match_array(['gas'])
+      end
+
+      it 'adds validation errors for invalid transitions' do
+        expect(subject.state.may_become?('plasma')).to eq false
+        expect { subject.state = 'plasma' }.to change { subject.state }.from('liquid').to('plasma')
+        expect(subject).not_to be_valid
+        expect(subject.errors[:state]).to match_array(['is invalid'])
+        expect(subject.state.next_values).to match_array(['gas'])
+        expect(subject.state.previous_values).to match_array(['solid'])
+
+        expect(subject.state.may_become?('solid')).to eq false
+        expect { subject.state = 'solid' }.to change { subject.state }.from('plasma').to('solid')
+        expect(subject).not_to be_valid
+        expect(subject.errors[:state]).to match_array(['is invalid'])
+        expect(subject.state.next_values).to match_array(['gas'])
+        expect(subject.state.previous_values).to match_array(['solid'])
+      end
+    end
+  end
+
+  context 'with a field reachable by multiple states' do
+    before do
+      steady_state_class.module_eval do
+        attr_accessor :step
+
+        steady_state :step do
+          state 'step-1', default: true
+          state 'step-2', from: 'step-1'
+          state 'cancelled', from: %w(step-1 step-2)
+        end
+      end
+    end
+
+    it 'allows transition from first state' do
+      expect(subject.step.may_become?('step-1')).to eq false
+      expect(subject.step.may_become?('step-2')).to eq true
+      expect(subject.step.may_become?('cancelled')).to eq true
+      expect(subject.step.next_values).to match_array(['cancelled', 'step-2'])
+      expect(subject.step.previous_values).to match_array([])
+      expect { subject.step = 'cancelled' }.to change { subject.step }.from('step-1').to('cancelled')
+      expect(subject.step.next_values).to match_array([])
+      expect(subject.step.previous_values).to match_array(['step-1', 'step-2'])
+      expect(subject).to be_valid
+    end
+
+    it 'allows transition from second state' do
+      expect(subject.step.may_become?('step-1')).to eq false
+      expect(subject.step.may_become?('step-2')).to eq true
+      expect(subject.step.may_become?('cancelled')).to eq true
+      expect(subject.step.next_values).to match_array(['cancelled', 'step-2'])
+      expect(subject.step.previous_values).to match_array([])
+      expect { subject.step = 'step-2' }.to change { subject.step }.from('step-1').to('step-2')
+      expect(subject).to be_valid
+
+      expect(subject.step.may_become?('step-1')).to eq false
+      expect(subject.step.may_become?('step-2')).to eq false
+      expect(subject.step.may_become?('cancelled')).to eq true
+      expect(subject.step.next_values).to match_array(['cancelled'])
+      expect(subject.step.previous_values).to match_array(['step-1'])
+      expect { subject.step = 'cancelled' }.to change { subject.step }.from('step-2').to('cancelled')
+      expect(subject.step.next_values).to match_array([])
+      expect(subject.step.previous_values).to match_array(['step-1', 'step-2'])
+      expect(subject).to be_valid
+    end
+  end
+
+  context 'with the predicates option' do
+    before do
+      options = opts
+      steady_state_class.module_eval do
+        attr_accessor :door
+
+        steady_state :door, options do
+          state 'open', default: true
+          state 'closed', from: 'open'
+          state 'locked', from: 'closed'
+        end
+      end
+    end
+
+    context 'default' do
+      let(:opts) { {} }
+
+      it 'defines a predicate method for each state' do
+        expect(subject).to respond_to(:open?)
+        expect(subject).to respond_to(:closed?)
+        expect(subject).to respond_to(:locked?)
+
+        expect(subject.open?).to eq true
+        expect(subject.closed?).to eq false
+        expect(subject.locked?).to eq false
+
+        subject.door = 'closed'
+        expect(subject.open?).to eq false
+        expect(subject.closed?).to eq true
+        expect(subject.locked?).to eq false
+
+        subject.door = 'locked'
+        expect(subject.open?).to eq false
+        expect(subject.closed?).to eq false
+        expect(subject.locked?).to eq true
+      end
+    end
+
+    context 'enabled' do
+      let(:opts) { { predicates: true } }
+
+      it 'defines a predicate method for each state' do
+        expect(subject).to respond_to(:open?)
+        expect(subject).to respond_to(:closed?)
+        expect(subject).to respond_to(:locked?)
+
+        expect(subject.open?).to eq true
+        expect(subject.closed?).to eq false
+        expect(subject.locked?).to eq false
+
+        subject.door = 'closed'
+        expect(subject.open?).to eq false
+        expect(subject.closed?).to eq true
+        expect(subject.locked?).to eq false
+
+        subject.door = 'locked'
+        expect(subject.open?).to eq false
+        expect(subject.closed?).to eq false
+        expect(subject.locked?).to eq true
+      end
+    end
+
+    context 'disabled' do
+      let(:opts) { { predicates: false } }
+
+      it 'does not define predicate methods' do
+        expect(subject).not_to respond_to(:open?)
+        expect(subject).not_to respond_to(:closed?)
+        expect(subject).not_to respond_to(:locked?)
+      end
+    end
+  end
+
+  context 'with the scopes option' do
+    let(:query_object) { double(where: []) } # rubocop:disable RSpec/VerifiedDoubles
+
+    before do
+      options = opts
+      steady_state_class.module_eval do
+        attr_accessor :car
+
+        def self.defined_scopes
+          @defined_scopes ||= {}
+        end
+
+        def self.scope(name, callable)
+          defined_scopes[name] ||= callable
+        end
+
+        steady_state :car, options do
+          state 'driving', default: true
+          state 'stopped', from: 'driving'
+          state 'parked', from: 'stopped'
+        end
+      end
+    end
+
+    context 'default' do
+      let(:opts) { {} }
+
+      it 'does not define scope methods' do
+        expect(steady_state_class.defined_scopes.keys).to eq []
+      end
+
+      context 'on an ActiveRecord' do
+        let(:steady_state_class) do
+          stub_const('ActiveRecord::Base', Class.new)
+
+          Class.new(ActiveRecord::Base) do
+            include ActiveModel::Model
+            include SteadyState
+          end
+        end
+
+        it 'defines a scope for each state' do
+          expect(steady_state_class.defined_scopes.keys).to eq %i(driving stopped parked)
+
+          expect(query_object).to receive(:where).with(car: 'driving')
+          query_object.instance_exec(&steady_state_class.defined_scopes[:driving])
+          expect(query_object).to receive(:where).with(car: 'stopped')
+          query_object.instance_exec(&steady_state_class.defined_scopes[:stopped])
+          expect(query_object).to receive(:where).with(car: 'parked')
+          query_object.instance_exec(&steady_state_class.defined_scopes[:parked])
+        end
+      end
+    end
+
+    context 'enabled' do
+      let(:opts) { { scopes: true } }
+
+      it 'defines a scope for each state' do
+        expect(steady_state_class.defined_scopes.keys).to eq %i(driving stopped parked)
+
+        expect(query_object).to receive(:where).with(car: 'driving')
+        query_object.instance_exec(&steady_state_class.defined_scopes[:driving])
+        expect(query_object).to receive(:where).with(car: 'stopped')
+        query_object.instance_exec(&steady_state_class.defined_scopes[:stopped])
+        expect(query_object).to receive(:where).with(car: 'parked')
+        query_object.instance_exec(&steady_state_class.defined_scopes[:parked])
+      end
+    end
+
+    context 'disabled' do
+      let(:opts) { { scopes: false } }
+
+      it 'does not define scope methods' do
+        expect(steady_state_class.defined_scopes.keys).to eq []
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: steady_state
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Nathan Griffith
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-10-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-betterment
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  A minimalist approach to managing object state,
+  perhaps best described as "an enum with guard rails."
+  Designed to work with `ActiveRecord` and `ActiveModel` classes,
+  or anywhere where Rails validations are used.
+email:
+- nathan@betterment.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/steady_state.rb
+- lib/steady_state/attribute.rb
+- lib/steady_state/attribute/state.rb
+- lib/steady_state/attribute/state_machine.rb
+- lib/steady_state/attribute/transition_validator.rb
+- lib/steady_state/version.rb
+- spec/spec_helper.rb
+- spec/steady_state/attribute_spec.rb
+homepage: 
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.7
+signing_key: 
+specification_version: 4
+summary: Minimalist state management via "an enum with guard rails"
+test_files:
+- spec/spec_helper.rb
+- spec/steady_state/attribute_spec.rb