aasm 5.0.8 → 5.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c02be243049ac08482ee6dd9de9b388d7f965019012f680507b75aee43e1819c
-  data.tar.gz: e41809b4fd44cd1d5358e4da499c6b2691caf6a2b6f0b1cf24816458af711522
+  metadata.gz: a088e1285940890f3c1a87b6cf0534e80702a96d2fb6eb42b43ff0cf50e6c57d
+  data.tar.gz: b96c64d2458639d217540b8787b1f718d80cd8e64b2661825435a795d5796a93
 SHA512:
-  metadata.gz: c5e49eeff60a68201dccfd988525030946a5f4e2ff080a8818ec729f7bb88291b6f333ccf8666a241dfb72b38a2f30333afbc4d284c3c6103eaab49446630b8e
-  data.tar.gz: d2d16d9368d1c8dfd8f50baaea1f07b525798a017fc612c27705161606ae27e1cdd1ea15b979d6d916cfd8abaa81479ff20c72577f8dbbd140dcb78572683845
+  metadata.gz: 85a0532a6257477070680b2864c27191f618a61091fe9ba0c2c0672e99aa53c4b61968e4987607c4e5747bb42686cff6667966c90cf4592e87ad0324175e711c
+  data.tar.gz: 1abfc89101b1cdf7440a82446b6c600d65fe6f2bfc83575a85dc2ef0edb04968cc509c9ff88ec2ce68f4aa8b72283f75301a0fcfefffa16fc0347cb31f11c492

data/README.md

@@ -20,6 +20,7 @@
   - [Extending AASM](#extending-aasm)
   - [ActiveRecord](#activerecord)
   - [Bang events](#bang-events)
+  - [Timestamps](#timestamps)
   - [ActiveRecord enums](#activerecord-enums)
   - [Sequel](#sequel)
   - [Dynamoid](#dynamoid)
@@ -212,15 +213,28 @@ class LogRunTime
 end
 ```
 
-Also, you can pass parameters to events:
+#### Parameters
+You can pass parameters to events:
 
 ```ruby
   job = Job.new
   job.run(:defragmentation)
 ```
 
-In this case the `set_process` would be called with `:defragmentation` argument.
+All guards and after callbacks will receive these parameters. In this case `set_process` would be called with
+`:defragmentation` argument.
 
+If the first argument to the event is a state (e.g. `:running` or `:finished`), the first argument is consumed and
+the state machine will attempt to transition to that state. Add comma separated parameter for guards and callbacks
+
+```ruby
+  job = Job.new
+  job.run(:running, :defragmentation)
+```
+In this case `set_process` won't be called, job will transition to running state and callback will receive
+`:defragmentation` as parameter
+
+#### Error Handling
 In case of an error during the event processing the error is rescued and passed to `:error`
 callback, which can handle it or re-raise it for further propagation.
 
@@ -260,8 +274,8 @@ begin
   new_state       enter
   ...update state...
   event           before_success      # if persist successful
-  transition      success             # if persist successful
-  event           success             # if persist successful
+  transition      success             # if persist successful, database update not guaranteed
+  event           success             # if persist successful, database update not guaranteed
   old_state       after_exit
   new_state       after_enter
   event           after
@@ -275,6 +289,8 @@ ensure
 end
 ```
 
+Use event's `after_commit` callback if it should be fired after database update.
+
 #### The current event triggered
 
 While running the callbacks you can easily retrieve the name of the event triggered
@@ -305,7 +321,7 @@ and then
 Let's assume you want to allow particular transitions only if a defined condition is
 given. For this you can set up a guard per transition, which will run before actually
 running the transition. If the guard returns `false` the transition will be
-denied (raising `AASM::InvalidTransition` or returning `false` itself):
+denied (raising `AASM::InvalidTransition`):
 
 ```ruby
 class Cleaner
@@ -348,7 +364,7 @@ job.clean                 # => raises AASM::InvalidTransition
 job.may_clean_if_needed?  # => true
 job.clean_if_needed!      # idle
 
-job.clean_if_dirty(:clean) # => false
+job.clean_if_dirty(:clean) # => raises AASM::InvalidTransition
 job.clean_if_dirty(:dirty) # => true
 ```
 
@@ -384,7 +400,7 @@ If you prefer a more Ruby-like guard syntax, you can use `if` and `unless` as we
   end
 ```
 
-You can invoke a Class instead a method since this Class responds to `call`
+You can invoke a Class instead of a method if the Class responds to `call`
 
 ```ruby
     event :sleep do
@@ -432,11 +448,38 @@ job.stage1_completed
 job.aasm.current_state # stage3
 ```
 
+You can define transition from any defined state by omitting `from`:
+
+```ruby
+event :abort do
+  transitions to: :aborted
+end
+```
+
+### Display name for state
+
+You can define display name for state using :display option
+
+```ruby
+class Job
+  include AASM
+
+  aasm do
+    state :stage1, initial: true, display: 'First Stage'
+    state :stage2
+    state :stage3
+  end
+end
+
+job = Job.new
+job.aasm.human_state
+
+```
 
 ### Multiple state machines per class
 
 Multiple state machines per class are supported. Be aware though that _AASM_ has been
-built with one state machine per class in mind. Nonetheless, here's how to do it (see below). Please note that you will need to specify database columns for where your pertinent states will be stored - we have specified two columns `move_state` and `work_state` in the example below. See the [Column name & migration](https://github.com/aasm/aasm#column-name--migration) section for further info. 
+built with one state machine per class in mind. Nonetheless, here's how to do it (see below). Please note that you will need to specify database columns for where your pertinent states will be stored - we have specified two columns `move_state` and `work_state` in the example below. See the [Column name & migration](https://github.com/aasm/aasm#column-name--migration) section for further info.
 
 ```ruby
 class SimpleMultipleExample
@@ -474,13 +517,13 @@ simple = SimpleMultipleExample.new
 
 simple.aasm(:move).current_state
 # => :standing
-simple.aasm(:work).current
+simple.aasm(:work).current_state
 # => :sleeping
 
 simple.start
 simple.aasm(:move).current_state
 # => :standing
-simple.aasm(:work).current
+simple.aasm(:work).current_state
 # => :processing
 
 ```
@@ -677,6 +720,8 @@ end
 AASM comes with support for ActiveRecord and allows automatic persisting of the object's
 state in the database.
 
+Add `gem 'after_commit_everywhere', '~> 1.0'` to your Gemfile.
+
 ```ruby
 class Job < ActiveRecord::Base
   include AASM
@@ -713,7 +758,7 @@ job.aasm.fire!(:run) # saved
 
 Saving includes running all validations on the `Job` class. If
 `whiny_persistence` flag is set to `true`, exception is raised in case of
-failure. If `whiny_persistence` flag is set to false, methods with a bang return
+failure. If `whiny_persistence` flag is set to `false`, methods with a bang return
 `true` if the state transition is successful or `false` if an error occurs.
 
 If you want make sure the state gets saved without running validations (and
@@ -741,7 +786,7 @@ class Job < ActiveRecord::Base
 end
 ```
 
-Also You can skip the validation at instance level with `some_event_name_without_validation!` method.
+Also, you can skip the validation at instance level with `some_event_name_without_validation!` method.
 With this you have the flexibility of having validation for all your transitions by default and then skip it wherever required.
 Please note that only state column will be updated as mentioned in the above example.
 
@@ -777,6 +822,37 @@ job.aasm_state = :running # => raises AASM::NoDirectAssignmentError
 job.aasm_state # => 'sleeping'
 ```
 
+### Timestamps
+
+You can tell _AASM_ to try to write a timestamp whenever a new state is entered.
+If `timestamps: true` is set, _AASM_ will look for a field named like the new state plus `_at` and try to fill it:
+
+```ruby
+class Job < ActiveRecord::Base
+  include AASM
+
+  aasm timestamps: true do
+    state :sleeping, initial: true
+    state :running
+
+    event :run do
+      transitions from: :sleeping, to: :running
+    end
+  end
+end
+```
+
+resulting in this:
+
+```ruby
+job = Job.create
+job.running_at # => nil
+job.run!
+job.running_at # => 2020-02-20 20:00:00
+```
+
+Missing timestamp fields are silently ignored, so it is not necessary to have setters (such as ActiveRecord columns) for *all* states when using this option.
+
 #### ActiveRecord enums
 
 You can use
@@ -981,6 +1057,12 @@ job.run
 job.save! #notify_about_running_job is not run
 ```
 
+Please note that `:after_commit` AASM callbacks behaves around custom implementation
+of transaction pattern rather than a real-life DB transaction. This fact still causes
+the race conditions and redundant callback calls within nested transaction. In order
+to fix that it's highly recommended to add `gem 'after_commit_everywhere', '~> 1.0'`
+to your `Gemfile`.
+
 If you want to encapsulate state changes within an own transaction, the behavior
 of this nested transaction might be confusing. Take a look at
 [ActiveRecord Nested Transactions](http://api.rubyonrails.org/classes/ActiveRecord/Transactions/ClassMethods.html)
@@ -1002,7 +1084,7 @@ end
 
 which then leads to `transaction(requires_new: false)`, the Rails default.
 
-Additionally, if you do not want any of your active record actions to be
+Additionally, if you do not want any of your ActiveRecord actions to be
 wrapped in a transaction, you can specify the `use_transactions` flag. This can
 be useful if you want want to persist things to the database that happen as a
 result of a transaction or callback, even when some error occurs. The
@@ -1022,7 +1104,7 @@ end
 
 ### Pessimistic Locking
 
-AASM supports [Active Record pessimistic locking via `with_lock`](http://api.rubyonrails.org/classes/ActiveRecord/Locking/Pessimistic.html#method-i-with_lock) for database persistence layers.
+AASM supports [ActiveRecord pessimistic locking via `with_lock`](http://api.rubyonrails.org/classes/ActiveRecord/Locking/Pessimistic.html#method-i-with_lock) for database persistence layers.
 
 | Option | Purpose |
 | ------ | ------- |
@@ -1076,7 +1158,10 @@ end
 ```
 
 Whatever column name is used, make sure to add a migration to provide this column
-(of type `string`):
+(of type `string`).
+Do not add default value for column at the database level. If you add default
+value in database then AASM callbacks on the initial state will not be fired upon
+instantiation of the model.
 
 ```ruby
 class AddJobState < ActiveRecord::Migration
@@ -1092,7 +1177,7 @@ end
 
 ### Log State Changes
 
-Logging state change can be done using [paper_trail](https://github.com/paper-trail-gem/paper_trail) gem 
+Logging state change can be done using [paper_trail](https://github.com/paper-trail-gem/paper_trail) gem
 
 Example of implementation can be found here [https://github.com/nitsujri/aasm-papertrail-example](https://github.com/nitsujri/aasm-papertrail-example)
 
@@ -1376,7 +1461,7 @@ After installing AASM you can run generator:
 ```
 Replace NAME with the Model name, COLUMN_NAME is optional(default is 'aasm_state').
 This will create a model (if one does not exist) and configure it with aasm block.
-For Active record orm a migration file is added to add aasm state column to table.
+For ActiveRecord orm a migration file is added to add aasm state column to table.
 
 ### Docker
 
@@ -1406,6 +1491,12 @@ Feel free to
 * [Anil Maurya](http://github.com/anilmaurya) (since 2016)
 
 
+
+## Stargazers over time
+
+[![Stargazers over time](https://starchart.cc/aasm/aasm.svg)](https://starchart.cc/aasm/aasm)
+
+
 ## [Contributing](CONTRIBUTING.md)
 
 ## Warranty ##

data/lib/aasm/base.rb

@@ -37,6 +37,9 @@ module AASM
       # string for a specific lock type i.e. FOR UPDATE NOWAIT
       configure :requires_lock, false
 
+      # automatically set `"#{state_name}_at" = ::Time.now` on state changes
+      configure :timestamps, false
+
       # set to true to forbid direct assignment of aasm_state column (in ActiveRecord)
       configure :no_direct_assignment, false
 
@@ -51,19 +54,12 @@ module AASM
       # Configure a logger, with default being a Logger to STDERR
       configure :logger, Logger.new(STDERR)
 
+      # setup timestamp-setting callback if enabled
+      setup_timestamps(@name)
+
       # make sure to raise an error if no_direct_assignment is enabled
       # and attribute is directly assigned though
-      aasm_name = @name
-
-      if @state_machine.config.no_direct_assignment
-        @klass.send(:define_method, "#{@state_machine.config.column}=") do |state_name|
-          if self.class.aasm(:"#{aasm_name}").state_machine.config.no_direct_assignment
-            raise AASM::NoDirectAssignmentError.new('direct assignment of AASM column has been disabled (see AASM configuration for this class)')
-          else
-            super(state_name)
-          end
-        end
-      end
+      setup_no_direct_assignment(@name)
     end
 
     # This method is both a getter and a setter
@@ -227,7 +223,20 @@ module AASM
         end
       end
 
-      klass.send(:define_method, method_name, method_definition)
+      klass.send(:define_method, method_name, method_definition).tap do |sym|
+        apply_ruby2_keyword(klass, sym)
+      end
+    end
+
+    def apply_ruby2_keyword(klass, sym)
+      if RUBY_VERSION >= '2.7.1'
+        if klass.instance_method(sym).parameters.find { |type, _| type.to_s.start_with?('rest') }
+          # If there is a place where you are receiving in *args, do ruby2_keywords.
+          klass.module_eval do
+            ruby2_keywords sym
+          end
+        end
+      end
     end
 
     def namespace?
@@ -267,5 +276,28 @@ module AASM
       end
     end
 
+    def setup_timestamps(aasm_name)
+      return unless @state_machine.config.timestamps
+
+      after_all_transitions do
+        if self.class.aasm(:"#{aasm_name}").state_machine.config.timestamps
+          ts_setter = "#{aasm(aasm_name).to_state}_at="
+          respond_to?(ts_setter) && send(ts_setter, ::Time.now)
+        end
+      end
+    end
+
+    def setup_no_direct_assignment(aasm_name)
+      return unless @state_machine.config.no_direct_assignment
+
+      @klass.send(:define_method, "#{@state_machine.config.column}=") do |state_name|
+        if self.class.aasm(:"#{aasm_name}").state_machine.config.no_direct_assignment
+          raise AASM::NoDirectAssignmentError.new('direct assignment of AASM column has been disabled (see AASM configuration for this class)')
+        else
+          super(state_name)
+        end
+      end
+    end
+
   end
 end

data/lib/aasm/configuration.rb

@@ -24,6 +24,9 @@ module AASM
     # for ActiveRecord: use pessimistic locking
     attr_accessor :requires_lock
 
+    # automatically set `"#{state_name}_at" = ::Time.now` on state changes
+    attr_accessor :timestamps
+
     # forbid direct assignment in aasm_state column (in ActiveRecord)
     attr_accessor :no_direct_assignment
 

data/lib/aasm/core/event.rb

@@ -2,17 +2,18 @@
 
 module AASM::Core
   class Event
-    include DslHelper
+    include AASM::DslHelper
 
-    attr_reader :name, :state_machine, :options
+    attr_reader :name, :state_machine, :options, :default_display_name
 
     def initialize(name, state_machine, options = {}, &block)
       @name = name
       @state_machine = state_machine
       @transitions = []
-      @valid_transitions = {}
+      @valid_transitions = Hash.new { |h, k| h[k] = {} }
       @guards = Array(options[:guard] || options[:guards] || options[:if])
       @unless = Array(options[:unless]) #TODO: This could use a better name
+      @default_display_name = name.to_s.gsub(/_/, ' ').capitalize
 
       # from aasm4
       @options = options # QUESTION: .dup ?
@@ -78,8 +79,9 @@ module AASM::Core
 
     def fire_transition_callbacks(obj, *args)
       from_state = obj.aasm(state_machine.name).current_state
-      transition = @valid_transitions[from_state]
-      @valid_transitions[from_state].invoke_success_callbacks(obj, *args) if transition
+      transition = @valid_transitions[obj.object_id][from_state]
+      transition.invoke_success_callbacks(obj, *args) if transition
+      @valid_transitions.delete(obj.object_id)
     end
 
     def ==(event)
@@ -109,6 +111,10 @@ module AASM::Core
       transitions.flat_map(&:failures)
     end
 
+    def to_s
+      name.to_s
+    end
+
   private
 
     def attach_event_guards(definitions)
@@ -148,7 +154,7 @@ module AASM::Core
             result = transition
           else
             result = to_state || Array(transition.to).first
-            Array(transition.to).each {|to| @valid_transitions[to] = transition }
+            Array(transition.to).each {|to| @valid_transitions[obj.object_id][to] = transition }
             transition.execute(obj, *args)
           end
 

data/lib/aasm/core/invokers/class_invoker.rb

@@ -17,7 +17,7 @@ module AASM
         end
 
         def invoke_subject
-          @result = retrieve_instance.call
+          @result = instance.call
         end
 
         private

data/lib/aasm/core/invokers/literal_invoker.rb

@@ -30,7 +30,9 @@ module AASM
           raise(*record_error) unless record.respond_to?(subject, true)
           return record.__send__(subject) if subject_arity.zero?
           return record.__send__(subject, *args) if subject_arity < 0
-          record.__send__(subject, *args[0..(subject_arity - 1)])
+          req_args = args[0..(subject_arity - 1)]
+          return record.__send__(subject, **req_args[0]) if req_args[0].is_a?(Hash)
+          record.__send__(subject, *req_args)
         end
         # rubocop:enable Metrics/AbcSize
 

data/lib/aasm/core/state.rb

@@ -2,12 +2,13 @@
 
 module AASM::Core
   class State
-    attr_reader :name, :state_machine, :options
+    attr_reader :name, :state_machine, :options, :default_display_name
 
     def initialize(name, klass, state_machine, options={})
       @name = name
       @klass = klass
       @state_machine = state_machine
+      @default_display_name = name.to_s.gsub(/_/, ' ').capitalize
       update(options)
     end
 
@@ -54,11 +55,11 @@ module AASM::Core
     end
 
     def display_name
-      @display_name ||= begin
+      @display_name = begin
         if Module.const_defined?(:I18n)
           localized_name
         else
-          name.to_s.gsub(/_/, ' ').capitalize
+          @default_display_name
         end
       end
     end
@@ -75,8 +76,8 @@ module AASM::Core
   private
 
     def update(options = {})
-      if options.key?(:display) then
-        @display_name = options.delete(:display)
+      if options.key?(:display)
+        @default_display_name = options.delete(:display)
       end
       @options = options
       self

data/lib/aasm/core/transition.rb

@@ -2,7 +2,7 @@
 
 module AASM::Core
   class Transition
-    include DslHelper
+    include AASM::DslHelper
 
     attr_reader :from, :to, :event, :opts, :failures
     alias_method :options, :opts

data/lib/aasm/dsl_helper.rb

@@ -1,30 +1,32 @@
-module DslHelper
+module AASM
+  module DslHelper
 
-  class Proxy
-    attr_accessor :options
+    class Proxy
+      attr_accessor :options
 
-    def initialize(options, valid_keys, source)
-      @valid_keys = valid_keys
-      @source = source
+      def initialize(options, valid_keys, source)
+        @valid_keys = valid_keys
+        @source = source
 
-      @options = options
-    end
+        @options = options
+      end
 
-    def method_missing(name, *args, &block)
-      if @valid_keys.include?(name)
-        options[name] = Array(options[name])
-        options[name] << block if block
-        options[name] += Array(args)
-      else
-        @source.send name, *args, &block
+      def method_missing(name, *args, &block)
+        if @valid_keys.include?(name)
+          options[name] = Array(options[name])
+          options[name] << block if block
+          options[name] += Array(args)
+        else
+          @source.send name, *args, &block
+        end
       end
     end
-  end
 
-  def add_options_from_dsl(options, valid_keys, &block)
-    proxy = Proxy.new(options, valid_keys, self)
-    proxy.instance_eval(&block)
-    proxy.options
-  end
+    def add_options_from_dsl(options, valid_keys, &block)
+      proxy = Proxy.new(options, valid_keys, self)
+      proxy.instance_eval(&block)
+      proxy.options
+    end
 
-end
+  end
+end

data/lib/aasm/errors.rb

@@ -17,5 +17,6 @@ module AASM
   end
 
   class UndefinedState < RuntimeError; end
+  class UndefinedEvent < UndefinedState; end
   class NoDirectAssignmentError < RuntimeError; end
 end

data/lib/aasm/instance_base.rb

@@ -1,6 +1,5 @@
 module AASM
   class InstanceBase
-
     attr_accessor :from_state, :to_state, :current_event
 
     def initialize(instance, name=:default) # instance of the class including AASM, name of the state machine
@@ -28,7 +27,7 @@ module AASM
     end
 
     def human_state
-      AASM::Localizer.new.human_state_name(@instance.class, state_object_for_name(current_state))
+      state_object_for_name(current_state).display_name
     end
 
     def states(options={}, *args)
@@ -115,12 +114,15 @@ module AASM
     end
 
     def fire(event_name, *args, &block)
+      event_exists?(event_name)
+
       @instance.send(event_name, *args, &block)
     end
 
     def fire!(event_name, *args, &block)
-      event_name = event_name.to_s.+("!").to_sym
-      @instance.send(event_name, *args, &block)
+      event_exists?(event_name, true)
+      bang_event_name = "#{event_name}!".to_sym
+      @instance.send(bang_event_name, *args, &block)
     end
 
     def set_current_state_with_persistence(state)
@@ -129,5 +131,14 @@ module AASM
       save_success
     end
 
+    private
+
+    def event_exists?(event_name, bang = false)
+      event = @instance.class.aasm(@name).state_machine.events[event_name.to_sym]
+      return true if event
+
+      event_error = bang ? "#{event_name}!" : event_name
+      raise AASM::UndefinedEvent, "Event :#{event_error} doesn't exist" if event.nil?
+    end
   end
 end

data/lib/aasm/localizer.rb

@@ -5,7 +5,7 @@ module AASM
         list << :"#{i18n_scope(klass)}.events.#{i18n_klass(ancestor)}.#{event}"
         list
       end
-      translate_queue(checklist) || I18n.translate(checklist.shift, :default => event.to_s.humanize)
+      translate_queue(checklist) || I18n.translate(checklist.shift, :default => default_display_name(event))
     end
 
     def human_state_name(klass, state)
@@ -14,7 +14,7 @@ module AASM
         list << item_for(klass, state, ancestor, :old_style => true)
         list
       end
-      translate_queue(checklist) || I18n.translate(checklist.shift, :default => state.to_s.humanize)
+      translate_queue(checklist) || I18n.translate(checklist.shift, :default => default_display_name(state))
     end
 
   private
@@ -46,8 +46,18 @@ module AASM
     end
 
     def ancestors_list(klass)
+      has_active_record_base = defined?(::ActiveRecord::Base)
       klass.ancestors.select do |ancestor|
-        ancestor.respond_to?(:model_name) unless ancestor.name == 'ActiveRecord::Base'
+        not_active_record_base = has_active_record_base ? (ancestor != ::ActiveRecord::Base) : true
+        ancestor.respond_to?(:model_name) && not_active_record_base
+      end
+    end
+
+    def default_display_name(object) # Can use better arguement name
+      if object.respond_to?(:default_display_name)
+        object.default_display_name
+      else
+        object.to_s.gsub(/_/, ' ').capitalize
       end
     end
   end

data/lib/aasm/persistence/active_record_persistence.rb

@@ -61,6 +61,24 @@ module AASM
 
         private
 
+        def aasm_execute_after_commit
+          begin
+            require 'after_commit_everywhere'
+            raise LoadError unless Gem::Version.new(::AfterCommitEverywhere::VERSION) >= Gem::Version.new('0.1.5')
+
+            self.extend ::AfterCommitEverywhere
+            after_commit do
+              yield
+            end
+          rescue LoadError
+            warn <<-MSG
+  [DEPRECATION] :after_commit AASM callback is not safe in terms of race conditions and redundant calls.
+                Please add `gem 'after_commit_everywhere', '~> 1.0'` to your Gemfile in order to fix that.
+            MSG
+            yield
+          end
+        end
+
         def aasm_raise_invalid_record
           raise ActiveRecord::RecordInvalid.new(self)
         end