steady_state 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6ac44424729680f31b79e25aa8b110323aee6ec97824f19ac03f54921bc2213
-  data.tar.gz: 77f39b19b580b0930864cf8a867a9e41ae4fc4900356a65123e83359729110f6
+  metadata.gz: c80b6cce9dbf7702cdf8fd0d97c21794bcbc6a67c2ea688fcf5b150ee217df5a
+  data.tar.gz: 67bc8bc9e117e55ac21b4dcba713dbf97627354c1997e906fbb317ef06b42ac6
 SHA512:
-  metadata.gz: 35ac9ceff1d5997e97b3a40840629b5665d26175e491e8ae28df4dd3fa99a64b4aa419122e60a3fc8372e9a6ccc0afa8c07136ea067eca9662d47d65f4099a58
-  data.tar.gz: e5394a77afb844a74d72f020f22fb343ec1d2d3bea2cdc98a1a0d2db2c6e3a28d0b85cd930b47a4221946830d40f0c52acc9f217d9262337f7c3b4f692678fc0
+  metadata.gz: 374352c07075b3ccb50c1c018e6b8e654ebcc84675d44e4024406dde923ba28699f58daf7b67f8161cff8ee41d9e4f75c77f59680f165b62e527787b7dd00e65
+  data.tar.gz: 6d493623807a7332a1e3b96a9849d46b6a33d59e8405dbb935ef66de4d9b054b2c471ca8421feb7f75810a2aa6694b0173a64be694a69a31a6210de2232018b0

data/README.md

@@ -23,12 +23,9 @@ gem 'steady_state'
 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
+class Material < ApplicationRecord
   include SteadyState
 
-  attr_accessor :state
-
   steady_state :state do
     state 'solid', default: true
     state 'liquid', from: 'solid'
@@ -65,20 +62,19 @@ A class may have any number of these `steady_state` declarations, one per statef
 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']
+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
@@ -98,55 +94,27 @@ 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:
+### Saving Changes to 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.
+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
+  with_lock { update(state: 'liquid') }
 end
 
 def melt!
-  self.state = 'liquid'
-  validate! # will raise an exception if state transition is invalid
+  with_lock { update!(state: 'liquid') }
 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
-```
+The use of `with_lock` is *strongly encouraged* in order to prevent race conditions that might result in invalid state transitions.
 
-For complex persistence operations, we encourage the use of existing persistence helpers like `transaction` and `with_lock`, to provide atomicity and avoid race conditions:
+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
@@ -178,7 +146,7 @@ class MaterialsController < ApplicationController
 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.
+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
 
@@ -207,6 +175,24 @@ 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:
@@ -245,6 +231,33 @@ As it stands, state history is not preserved, but it is still possible to get a
 material.state.previous_values # => ['solid']
 ```
 
+### 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.

data/lib/steady_state/attribute.rb

@@ -13,7 +13,7 @@ module SteadyState
     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
+      def steady_state(attr_name, predicates: true, states_getter: true, scopes: SteadyState.active_record?(self), &block) # rubocop:disable 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)
@@ -43,6 +43,15 @@ module SteadyState
         prepend overrides
 
         state_machines[attr_name].instance_eval(&block)
+
+        if states_getter
+          cattr_reader(:"#{attr_name.to_s.pluralize}") do
+            state_machines[attr_name].states.map do |state|
+              State.new(state_machines[attr_name], state, nil)
+            end
+          end
+        end
+
         delegate(*state_machines[attr_name].predicates, to: attr_name, allow_nil: true) if predicates
         if scopes
           state_machines[attr_name].states.each do |state|

data/lib/steady_state/version.rb

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

data/spec/steady_state/attribute_spec.rb

@@ -290,6 +290,39 @@ RSpec.describe SteadyState::Attribute do
     end
   end
 
+  context 'with the states_getter option' do
+    let(:query_object) { double(where: []) } # rubocop:disable RSpec/VerifiedDoubles
+
+    before do
+      options = opts
+      steady_state_class.module_eval do
+        attr_accessor :car
+
+        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 'defines states getter method' do
+        expect(steady_state_class.cars).to eq %w(driving stopped parked)
+      end
+    end
+
+    context 'disabled' do
+      let(:opts) { { states_getter: false } }
+
+      it 'does not define states getter method' do
+        expect { steady_state_class.cars }.to raise_error(NoMethodError, /undefined method `cars'/)
+      end
+    end
+  end
+
   context 'with the scopes option' do
     let(:query_object) { double(where: []) } # rubocop:disable RSpec/VerifiedDoubles
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: steady_state
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Nathan Griffith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-10-23 00:00:00.000000000 Z
+date: 2022-02-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -119,8 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.7
+rubygems_version: 3.3.7
 signing_key: 
 specification_version: 4
 summary: Minimalist state management via "an enum with guard rails"