Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/betterment/steady_state

Simple state management via "an enum with guard rails"
https://github.com/betterment/steady_state

aasm rails ruby state-machine

Last synced: 3 months ago
JSON representation

Simple state management via "an enum with guard rails"

Awesome Lists containing this project

README 

        
# 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

```



`steady_state` also follows the same `prefix` api as `delegate` in Rails.  You may optionally define your scopes to be prefixed to the name of the state machine with `prefix: true`, or you may provide a custom prefix with `prefix: :some_custom_name`.  This may be useful when dealing with multiple state machines on one object.



```ruby

steady_state :temperature, scopes: { prefix: true } do

  state 'cold', default: true

end



steady_state :color_temperature, scopes: { prefix: 'color' } do

  state 'cold', default: true

end



Material.solid # => query for 'solid' records

Material.temperature_cold # => query for records with a cold temperature

Material.color_cold # => query for for records with a cold color temperature

```



### 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.