state_machine_enum 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4902a42140176efda107ea4e5caef0b4bd3f8e64554b2fde61f3507e51e80d96
-  data.tar.gz: 9f85490534c6667640cd050e13eeaf7ce202bbd5757e7ade6cd4d6cb4c191b90
+  metadata.gz: 0a64dc12150ea615573c5fc5ce222e80fa8f2959392c94f3c6a80fae6efa53cd
+  data.tar.gz: 63b7a19ac4794c1b75d5e4d8a6b93964e5b9400d394927458d44893d2c9f4a31
 SHA512:
-  metadata.gz: 10ae6f605953606f563a80aa15b9cc7a70eedc73593d152aba3d5ab773b0243002dc13b0f66888e83008d6c0a341bee762a5bdbde61712e2310833b1345bc067
-  data.tar.gz: 8b7c7b452a1e0b962b9ef2f643dcdd220597474c87269dc4565bb5a8974af000e78bed0f2c41f8da40adf663a51bcdd21d0a6b7bb9bb3bab0f8a597c36d90032
+  metadata.gz: b705009767fb54820386c8748f1747a45d2145dc177355569a794669d1514bac07cb9f5666999950d158ed1b9fba3808eebb8b28f63fdeab3da1818314919598
+  data.tar.gz: 187ee30f697c019617f45b057e709d404a2cd11083e57c0f7387f24272a27a17ce7afce6da31b8dff675914498589b9a13e4a64c1eab0e21fe6101d1aa277b75

data/CHANGELOG.md

@@ -1,24 +1,28 @@
-# Changelog
-All notable changes to this project will be documented in this file.
+## 0.1.4
 
-This format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+* Raise `InvalidTransition` which is a subclass of `InvalidState`. That exception contains the following properties which can be used:
+  * `attribute_name` is the name of the enum attribute
+  * `from_state` is the state the transition was attempted from
+  * `to_state` is the state the transition was going to
+  * `already_in_target_state?` is `true` if a repeated transition was attempted
+* Some more code styling
+* Relax dependencies so that Bundler does not complain on Rails 8.x apps
 
-## 0.1.2
-
-### Added
+## 0.1.3
 
-- basic tests for a library
+* Added more documentation and improvements to the readme
+* Little code styling
 
-### Changed
+## 0.1.2
 
-- #ensure_<attribute>_may_transition_to! method now actually verifies that an attribute can transition to a new state.
+* Add basic tests
+* `#ensure_<attribute>_may_transition_to!` now actually verifies that an attribute can transition to the new state.
 
 ## 0.1.1
 
-### Added
 
-- Provide real authorts of this gem.
+* Provide real authors.
 
 ## 0.1.0
 
-- Initial release
+* Initial release

data/README.md

@@ -1,7 +1,10 @@
 # StateMachineEnum
 
-This concern adds a method called "state_machine_enum" useful for defining an enum using string values along with valid state transitions. Validations will be added for the state transitions and a proper enum is going to be defined. For example:
+This concern adds a method called "state_machine_enum".
+Useful for defining an enum using string values along with valid state transitions.
+Validations will be added for the state transitions and a proper enum is going to be defined.
 
+For example:
 ```ruby
 state_machine_enum :state do |states|
   states.permit_transition(:created, :approved_pending_settlement)
@@ -13,43 +16,127 @@ end
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Install the gem and add it to the application's Gemfile by executing:
 
-    $ bundle add state_machine_enum
+  $ bundle add state_machine_enum
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install state_machine_enum
+  $ gem install state_machine_enum
 
 ## Usage
 
-StateMachineEnum needs to be extended and then it could be used, as example in AR model.
+StateMachineEnum needs to be included and then it could be used, for example, in an ActiveRecord model.
 
-```
+```ruby
 class User < ApplicationRecord
   include StateMachineEnum
 
-  state_machine_enum :state do |s|
-    s.permit_transition(:registered, :active)
-    s.permit_transition(:active, :banned)
-    s.permit_transition(:banned, :active)
-    s.permit_transition(:active, :deleted)
+  state_machine_enum :state, prefix: :state do |s|
+  s.permit_transition(:registered, :active)
+  s.permit_transition(:active, :banned)
+  s.permit_transition(:banned, :active)
+  s.permit_transition(:active, :deleted)
   end
 end
+
+user = User.new(state: 'active')
+# with the prefix: :state
+user.state_active?  # => true
+# or without the prefix: :state
+user.active? # => true
+
+# The transition check happens when updating the state like this
+user.update!(state: :registered)
+# or when using the shortcut (add state_ because we have prefix: :state above)
+user.state_registered!
 ```
+The last command throws an InvalidState error: Invalid transition from active to registered
+This is because the state was not permitted to transition back to "registered" from "active".
+If you do want this, `s.permit_transition(:active, :registered)` should be added.
 
-And then it will offer bunch of convenient methods and callbacks that ensure proper state transitions.
+# API
 
+## state_machine_enum(state, prefix: nil) &block
+Creation method that sets up the state_machine_enum in your ruby object.
+Note the prefix here to prefix the method. This is optional of course.
+This works the same as when you would add `enum :state, {registered: "registered"}` in rails for example, except when using state_machine_enum
+you don't need to add an `enum` as well, we do this for you.
+
+## after_inline_transition_to(to) &block
+Runs the block inside `after_inline_transition_to` as a before_save action.
+For example the state updates to :registered, but before the model is saved
+
+```ruby
+state_machine_enum :state, prefix: "state" do |s|
+  s.permit_transition(:registered, :active)
+  s.after_inline_transition_to(:active) do |model|
+    model.another_attr = Time.now.utc
+  end
+end
 ```
-user = User.new(state: 'registered')
-user.active?
-user.registered! # throws InvalidState error, because state can not transition to "registered".
+
+`another_attr` is automatically set to the current utc time.
+
+## after_committed_transition_to(to) &block
+Runs the block inside `after_committed_transition_to` as an after_commit action.
+For example if you want to do something after it has committed to the database when the state is
+updated to :registered
+
+```ruby
+state_machine_enum :state, prefix: "state" do |s|
+  s.permit_transition(:registered, :active)
+  s.after_committed_transition_to(:active) do |model|
+    model.send_notification!
+  end
+end
 ```
+
+## after_any_committed_transition_to(to) &block
+Runs together with all the `after_committed_transition_to` hooks.
+For example if you want to do something after any state update has commited.
+
+```ruby
+state_machine_enum :state, prefix: "state" do |s|
+  s.permit_transition(:registered, :active)
+  s.permit_transition(:active, :suspended)
+  s.after_any_committed_transition_to do |model|
+    log_changes!
+  end
+end
+```
+
+## Ensure methods
+With a couple of ensure methods we can check beforehand for valid state transitions without actually having to do the state transition.
+This allows you to bail out of calls where the model is not in a desired state or won't be able to perform a transition, by raising an InvalidState exception
+
+## ensure_<attribute>_one_of!(state1, state2, etc)
+E.g. seen from the previous examples, calling `ensure_state_one_of!(:registered, :active, :fake)`
+will raise an InvalidState error because :fake is not present in state enum.
+
+## ensure_<attribute>_may_transition_to!(to)
+Calling `ensure_state_may_transition_to!(:active)` when the state is currently in :suspended
+will raise an InvalidState error because we did not permite the transition from :active to :suspended.
+
+## <attribute>_may_transition_to?(to)
+Predicate to check if a transition is possible with the rules we've set.
+
+```ruby
+state_machine_enum :state, prefix: "state" do |s|
+  s.permit_transition(:registered, :active)
+end
+
+state_may_transition_to?(:active) # => true
+```
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`,
+which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/lib/state_machine_enum/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StateMachineEnum
-  VERSION = "0.1.2"
+  VERSION = "0.1.4"
 end

data/lib/state_machine_enum.rb

@@ -13,16 +13,13 @@ require "active_support/concern"
 #     states.permit_transition(:created, :rejected)
 #     states.permit_transition(:approved_pending_settlement, :settled)
 #   end
-
 module StateMachineEnum
   extend ActiveSupport::Concern
 
+  # This keeps track of the states and rules we allow.
   class StatesCollector
-    attr_reader :states
-    attr_reader :after_commit_hooks
-    attr_reader :common_after_commit_hooks
-    attr_reader :after_attribute_write_hooks
-    attr_reader :common_after_write_hooks
+    attr_reader :states, :after_commit_hooks, :common_after_commit_hooks,
+      :after_attribute_write_hooks, :common_after_write_hooks
 
     def initialize
       @transitions = Set.new
@@ -33,44 +30,63 @@ module StateMachineEnum
       @common_after_write_hooks = []
     end
 
+    # Add a 'rule' that allows a transition in a single direction
     def permit_transition(from, to)
       @states << from.to_s << to.to_s
       @transitions << [from.to_s, to.to_s]
     end
 
-    def may_transition?(from, to)
-      @transitions.include?([from.to_s, to.to_s])
-    end
-
+    # Runs after the attributes have changed, but before the state is saved
     def after_inline_transition_to(target_state, &blk)
       @after_attribute_write_hooks[target_state.to_s] ||= []
       @after_attribute_write_hooks[target_state.to_s] << blk.to_proc
     end
 
+    # Will run after the specified transition has comitted
     def after_committed_transition_to(target_state, &blk)
       @after_commit_hooks[target_state.to_s] ||= []
       @after_commit_hooks[target_state.to_s] << blk.to_proc
     end
 
+    # A generic block that will run together with every committed transition.
     def after_any_committed_transition(&blk)
       @common_after_commit_hooks << blk.to_proc
     end
 
-    def validate(model, attribute_name)
+    def _validate(model, attribute_name)
       return unless model.persisted?
 
       was = model.attribute_was(attribute_name)
       is = model[attribute_name]
 
-      unless was == is || @transitions.include?([was, is])
-        model.errors.add(attribute_name, "Invalid transition from #{was} to #{is}")
-      end
+      return if (was == is) || @transitions.include?([was, is])
+
+      model.errors.add(attribute_name, "Invalid transition from #{was} to #{is}")
+    end
+
+    def _may_transition?(from, to)
+      @transitions.include?([from.to_s, to.to_s])
     end
   end
 
   class InvalidState < StandardError
   end
 
+  class InvalidTransition < InvalidState
+    attr_reader :attribute_name, :from_state, :to_state
+
+    def already_in_target_state?
+      @from_state == @to_state
+    end
+
+    def initialize(attribute_name, attempted_transition_from_state, attempted_transition_to_state, *args_for_super)
+      @attribute_name = attribute_name.to_s
+      @from_state = attempted_transition_from_state.to_s
+      @to_state = attempted_transition_to_state.to_s
+      super(*args_for_super)
+    end
+  end
+
   class_methods do
     def state_machine_enum(attribute_name, **options_for_enum)
       # Collect the states
@@ -82,12 +98,13 @@ module StateMachineEnum
 
         # Define validations for transitions
         validates attribute_name, presence: true
-        validate { |model| collector.validate(model, attribute_name) }
+        validate { |model| collector._validate(model, attribute_name) }
 
-        # Define inline hooks
+        # Define after attribute change (before save) hooks
         before_save do |model|
           _value_was, value_has_become = model.changes[attribute_name]
           next unless value_has_become
+
           hook_procs = collector.after_attribute_write_hooks[value_has_become].to_a + collector.common_after_write_hooks.to_a
           hook_procs.each do |hook_proc|
             hook_proc.call(model)
@@ -98,29 +115,34 @@ module StateMachineEnum
         after_commit do |model|
           _value_was, value_has_become = model.previous_changes[attribute_name]
           next unless value_has_become
+
           hook_procs = collector.after_commit_hooks[value_has_become].to_a + collector.common_after_commit_hooks.to_a
           hook_procs.each do |hook_proc|
             hook_proc.call(model)
           end
         end
 
-        # Define the check methods
+        # Define the ensure methods
         define_method(:"ensure_#{attribute_name}_one_of!") do |*allowed_states|
           val = self[attribute_name]
           return if Set.new(allowed_states.map(&:to_s)).include?(val)
+
           raise InvalidState, "#{attribute_name} must be one of #{allowed_states.inspect} but was #{val.inspect}"
         end
 
         define_method(:"ensure_#{attribute_name}_may_transition_to!") do |next_state|
           val = self[attribute_name]
-          raise InvalidState, "#{attribute_name} already is #{val.inspect}" if next_state.to_s == val
-          raise InvalidState, "#{attribute_name} may not transition from #{val.inspect} to #{next_state.inspect}" unless collector.may_transition?(val, next_state)
+          raise InvalidTransition.new(attribute_name, val, next_state, "#{attribute_name} already is #{val.inspect}") if next_state.to_s == val
+          return if collector._may_transition?(val, next_state)
+
+          raise InvalidTransition.new(attribute_name, val, next_state, "#{attribute_name} may not transition from #{val.inspect} to #{next_state.inspect}")
         end
 
         define_method(:"#{attribute_name}_may_transition_to?") do |next_state|
           val = self[attribute_name]
           return false if val == next_state.to_s
-          collector.may_transition?(val, next_state)
+
+          collector._may_transition?(val, next_state)
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: state_machine_enum
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Julik Tarkhanov
@@ -10,22 +10,22 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-18 00:00:00.000000000 Z
+date: 2025-03-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '7'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '7'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -44,16 +44,16 @@ dependencies:
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '7'
+        version: '7.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '7'
+        version: '7.0'
 description: Concern that makes it easy to define and enforce possibe state transitions
   for a field/object
 email:
@@ -94,7 +94,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Define possible state transitions for a field