state_machine_enum 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4902a42140176efda107ea4e5caef0b4bd3f8e64554b2fde61f3507e51e80d96
-  data.tar.gz: 9f85490534c6667640cd050e13eeaf7ce202bbd5757e7ade6cd4d6cb4c191b90
+  metadata.gz: 255a61ddbdf562c086709c6fbe51e37533ac15bf47bd698d0aae2086e2157569
+  data.tar.gz: 759c5a66316166c230d37576d2a087cb93978620a1984f9d10ece17b9ba2f89e
 SHA512:
-  metadata.gz: 10ae6f605953606f563a80aa15b9cc7a70eedc73593d152aba3d5ab773b0243002dc13b0f66888e83008d6c0a341bee762a5bdbde61712e2310833b1345bc067
-  data.tar.gz: 8b7c7b452a1e0b962b9ef2f643dcdd220597474c87269dc4565bb5a8974af000e78bed0f2c41f8da40adf663a51bcdd21d0a6b7bb9bb3bab0f8a597c36d90032
+  metadata.gz: 8197dc76f3536c972ab610da6259dc4c0d53ebd049addd747965acb925f43be39b4bb78948edf315b3f257ce107f68db3c989a7f7340f8b65931f901a8da505c
+  data.tar.gz: f219d01939f927981cdd45b3c72fe76ab3a19bbd7c56028a5c6e5ebae64a36adfa36c61e1310afd0ae2ab78c3697af00f8ddee44f9afb02ee8ccc73935a13e9d

data/CHANGELOG.md

@@ -3,6 +3,13 @@ All notable changes to this project will be documented in this file.
 
 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).
 
+## 0.1.3
+
+### Changed
+
+- Added more documentation and improvements to the readme
+- Little code styling
+
 ## 0.1.2
 
 ### Added

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,7 +16,7 @@ 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
 
@@ -23,33 +26,117 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## 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|
+  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.
+
+# 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
+```
+
+`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
 ```
 
-And then it will offer bunch of convenient methods and callbacks that ensure proper state transitions.
+## 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
 ```
-user = User.new(state: 'registered')
-user.active?
-user.registered! # throws InvalidState error, because state can not transition to "registered".
+
+## 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.3"
 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,38 +30,42 @@ 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
 
@@ -82,12 +83,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 +100,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)
+          return if collector._may_transition?(val, next_state)
+
+          raise InvalidState, "#{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.3
 platform: ruby
 authors:
 - Julik Tarkhanov
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-18 00:00:00.000000000 Z
+date: 2024-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -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.5.18
 signing_key:
 specification_version: 4
 summary: Define possible state transitions for a field