rails_machine 0.0.6 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 4af0035757028b9a274654be5553733c35b3b86c
-  data.tar.gz: 902c57516ac9603ead3293150fe5bdbf6439b3a6
+SHA256:
+  metadata.gz: d7039049332c0e432df8f5b0607349b0bdc798201fb87c97dfa2c5e2bf95e0c0
+  data.tar.gz: c76c94732fc8d6ebdbe440a9cfd683d2da66fef62a096f94c3c58947d9628fd5
 SHA512:
-  metadata.gz: 15e6ab9e4f8f566e3f22a6f0ca6dc408084a6d2853446d59a5bdc7f9290569c04fba8e8e328690a5eca22c67de107a0a6600295ae417807c5531930684933f67
-  data.tar.gz: 689a28349e74c30d1d4130e100a7e8485eee6c8f3af8558d8adf14b67910e79fab3698b3cf692ad9fbf768a51b35615662c28ed2b8e3c2477333fa9bc1937689
+  metadata.gz: 52e2406afb168f5d94a5814958a6ca16923986143319e313c7424f7d1126aa791662faf409e612f0be2a3184f7c2f65201e2a5913af97ea832c5086ff744e7c5
+  data.tar.gz: a6566d45aee104ec86c0d57390e6b4d6918884647cf2c26685e7845225bb1654d84acf62219c664cc306a4709dd2b2c5b0af874d0d936096c31ee1dd3571c0e7

data/README.rdoc

@@ -1,3 +1,113 @@
 = RailsMachine
 
-This project rocks and uses MIT-LICENSE.
+A small state machine for ActiveRecord models, built on top of Rails enums.
+
+== Installation
+
+Add to your Gemfile:
+
+  gem 'rails_machine'
+
+Requires Ruby >= 3.0 and ActiveRecord >= 7.0.
+
+== Usage
+
+Add an integer column to your model to hold the state:
+
+  class AddStateToVehicles < ActiveRecord::Migration[7.0]
+    def change
+      add_column :vehicles, :state, :integer, default: 0, null: false
+    end
+  end
+
+Include +RailsMachine+ and declare the machine:
+
+  class Vehicle < ActiveRecord::Base
+    include RailsMachine
+
+    rails_machine do
+      state :stopped
+      state :idling
+      state :driving
+      state :broken
+
+      init_state :stopped
+
+      transition from: :stopped, to: :idling
+      transition from: :idling,  to: :stopped
+      transition from: :idling,  to: :driving
+      transition from: :driving, to: :idling
+
+      transition from: :any,    to: :broken
+      transition from: :broken, to: :stopped, guards: [->(v) { v.inspected? }]
+    end
+  end
+
+== States
+
+States are stored as Rails enums. IDs start at 0 and increment by 1, or you can set them explicitly:
+
+  state :stopped           # id 0
+  state :idling            # id 1
+  state :archived, id: 99  # id 99
+  state :legacy            # id 100
+
+You get all the usual enum helpers for free:
+
+  vehicle.stopped?      # => true
+  vehicle.idling!       # persists the transition
+  Vehicle.stopped       # scope
+  Vehicle.states        # { "stopped" => 0, "idling" => 1, ... }
+
+Defining the same state name twice raises +ArgumentError+.
+
+== Init states
+
++init_state+ declares which states a record is allowed to start in. Records saved with any other initial value fail validation.
+
+  init_state :stopped
+  init_state :broken   # multiple allowed
+
+If no +init_state+ is declared, any state is accepted on creation.
+
+== Transitions
+
+Each +transition+ defines a legal +from+ → +to+ pair. Attempting an undeclared transition raises +ActiveRecord::RecordInvalid+ on save (or returns +false+ from +valid?+).
+
++:any+ is a wildcard:
+
+  transition from: :any, to: :broken      # any state can become :broken
+  transition from: :broken, to: :any      # :broken can become anything
+  transition from: :any, to: :any         # no restrictions
+
+== Guards
+
+Guards are callables that receive the record and must return truthy for the transition to pass:
+
+  transition from: :broken, to: :stopped, guards: [->(v) { v.inspected? }]
+
+If every guard on every matching transition returns falsy, validation adds a +:guard_failed+ error.
+
+== Custom column
+
+Pass +column:+ to use something other than +:state+:
+
+  rails_machine column: :status do
+    state :draft
+    state :published
+    transition from: :draft, to: :published
+  end
+
+== Error messages
+
+Validation failures add errors on the state column with these keys:
+
+* +:invalid_init_state+ — record was created in a state not listed in +init_state+
+* +:transition_not_found+ — no transition defined for the attempted state change
+* +:guard_failed+ — a matching transition exists but its guard(s) returned falsy
+
+Default English messages ship with the gem. Override them under +en.errors.messages+ in your own locale files.
+
+== License
+
+MIT.

data/config/locales/rails_machine.en.yml

@@ -0,0 +1,6 @@
+en:
+  errors:
+    messages:
+      invalid_init_state: "is not a valid initial state"
+      transition_not_found: "transition is not allowed"
+      guard_failed: "transition was blocked by a guard"

data/lib/rails_machine/configuration.rb

@@ -4,7 +4,7 @@ module RailsMachine
     attr_reader :states, :transitions, :init_states
 
     def initialize
-      @states = []
+      @states = {}
       @init_states = []
       @transitions = Hash.new{|hash,key| hash[key] = [] }
     end
@@ -19,7 +19,8 @@ module RailsMachine
     end
 
     def state(name, id: next_id)
-      @states << [name, id]
+      raise ArgumentError, "State :#{name} is already defined" if @states.key?(name)
+      @states[name] = id
     end
 
     def transition(from: :any, to: :any, guards: [])
@@ -30,7 +31,7 @@ module RailsMachine
       if @states.empty?
         0
       else
-        @states.map(&:second).max.next
+        @states.values.max.next
       end
     end
   end

data/lib/rails_machine/version.rb

@@ -1,3 +1,3 @@
 module RailsMachine
-  VERSION = "0.0.6"
+  VERSION = "1.0.0"
 end

data/lib/rails_machine.rb

@@ -1,22 +1,16 @@
 require 'rails_machine/configuration'
 
+I18n.load_path << File.expand_path('../config/locales/rails_machine.en.yml', __dir__)
+
 module RailsMachine
   extend ActiveSupport::Concern
 
   included do
-    cattr_accessor :transitions
-
-    validate :allowed_state, if: :state_changed?
-    private
-    cattr_accessor :init_states
-  end
+    cattr_accessor :transitions, instance_writer: false
+    cattr_accessor :init_states, instance_writer: false
 
-  def allowed_state
-    if self.new_record?
-      validate_init_state
-    else
-      validate_transition
-    end
+    validate :validate_init_state, on: :create
+    validate :validate_transition, on: :update, if: :state_changed?
   end
 
   def validate_init_state
@@ -26,6 +20,7 @@ module RailsMachine
   end
 
   def valid_init_state
+    return true if self.state.nil?
     init_states.empty? || init_states.include?(self.state.to_sym)
   end
 
@@ -41,14 +36,14 @@ module RailsMachine
 
   module ClassMethods
     def rails_machine(column: :state, &blk)
-      raise ArgumentError unless block_given?
+      raise ArgumentError, "rails_machine requires a configuration block" unless block_given?
 
       configuration = Configuration.new
       configuration.run(&blk)
 
-      self.transitions = configuration.transitions
-      self.init_states = configuration.init_states
-      enum column => Hash[configuration.states]
+      self.transitions = configuration.transitions.transform_values(&:freeze).freeze
+      self.init_states = configuration.init_states.freeze
+      enum column, configuration.states
 
       validates_presence_of column
     end

metadata

@@ -1,56 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: rails_machine
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 1.0.0
 platform: ruby
 authors:
 - Grzegorz Łuszczek
 - Adrian Słapa
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.6'
 - !ruby/object:Gem::Dependency
-  name: rspec-rails
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
 description: Simple implementation of state machine for Rails using enums.
@@ -64,6 +63,7 @@ files:
 - MIT-LICENSE
 - README.rdoc
 - Rakefile
+- config/locales/rails_machine.en.yml
 - lib/rails_machine.rb
 - lib/rails_machine/configuration.rb
 - lib/rails_machine/version.rb
@@ -72,25 +72,21 @@ homepage: https://github.com/grzlus/rails_machine
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '2.1'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.2.2
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: State machine for Rails.
 test_files: []
-has_rdoc: