# 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 < ApplicationRecord include SteadyState 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.with_lock do # if this is an ActiveRecord, a lock is necessary to avoid race conditions 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: material.state.liquid? # => true material.state = 'solid' material.state # => 'solid' material.valid? # => false material.errors[:state] # => ['is invalid'] end ``` #### 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. ### Saving Changes to State 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 with_lock { update(state: 'liquid') } end def melt! with_lock { update!(state: 'liquid') } end ``` The use of `with_lock` is *strongly encouraged* in order to prevent race conditions that might result in invalid state transitions. This is especially important for operations with side-effects, as a transactional lock will both prevent race conditions and guarantee an atomic rollback if anything raises an exception: ```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 ``` ### Custom Validations Using the supplied predicate methods, 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. ### 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'] ``` ### The "States Getter" A pluralized, class-level helper method can be used to access all possible state values: ```ruby Material.states # => ['solid', 'liquid', 'gas'] ``` These values respond to reflection methods like `may_become?`, `next_values`, and `previous_values`. ``` Material.states.first.solid? # => true Material.states[1].may_become?('solid') # => false Material.states[1].next_values # => ['gas'] ``` The automatic definition of this class method can be disabled by passing `states_getter: false`: ```ruby steady_state :step, states_getter: false do # ... end MyClass.steps # => NoMethodError ``` ### ActiveModel Support SteadyState is also available to classes that are not database-backed, as long as they include the `ActiveModel::Model` mixin: ```ruby class Material include ActiveModel::Model attr_accessor :state steady_state :state do state 'solid', default: true state 'liquid', from: 'solid' end 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 end ``` ## 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.