aasm 5.1.1 → 5.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2f4099a66f8d753c2bd7c06b3c378dcd37b47acf9b2f7487784e7762742c1c4
-  data.tar.gz: 8971b36f1b066c08d3a4d278a99d7c1e5386be72182da62b51a82db1e60e9e9f
+  metadata.gz: a088e1285940890f3c1a87b6cf0534e80702a96d2fb6eb42b43ff0cf50e6c57d
+  data.tar.gz: b96c64d2458639d217540b8787b1f718d80cd8e64b2661825435a795d5796a93
 SHA512:
-  metadata.gz: c24e544b82cfc4616f3e3ff033b7a5ab68bff7bd834b115797e9127ca361effe241ffb1adaedcdb595711a6757f2e0a8e0a8d606a9bc812c28707a1ee845ef40
-  data.tar.gz: 421636d1e59e52b8d6b4ddff7dd373fecd9a19ef67b90935e856b1ee980bae9a5a4a8526e62238de9ecc84a7783362e8d5b2005c53b9c7754368be79724c6255
+  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.
 
@@ -307,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
@@ -350,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
 ```
 
@@ -386,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
@@ -434,6 +448,14 @@ 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
@@ -495,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
 
 ```
@@ -698,7 +720,7 @@ end
 AASM comes with support for ActiveRecord and allows automatic persisting of the object's
 state in the database.
 
-Add `gem 'after_commit_everywhere', '~> 0.1', '>= 0.1.5'` to your Gemfile 
+Add `gem 'after_commit_everywhere', '~> 1.0'` to your Gemfile.
 
 ```ruby
 class Job < ActiveRecord::Base
@@ -736,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
@@ -764,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.
 
@@ -800,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
@@ -1007,7 +1060,7 @@ 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', '~> 0.1', '>= 0.1.5'`
+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
@@ -1031,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
@@ -1051,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 |
 | ------ | ------- |
@@ -1107,7 +1160,7 @@ end
 Whatever column name is used, make sure to add a migration to provide this column
 (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 
+value in database then AASM callbacks on the initial state will not be fired upon
 instantiation of the model.
 
 ```ruby
@@ -1408,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
 
@@ -1438,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
@@ -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

@@ -73,7 +73,7 @@ module AASM
           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', '~> 0.1', '>= 0.1.5'` to your Gemfile in order to fix that.
+                Please add `gem 'after_commit_everywhere', '~> 1.0'` to your Gemfile in order to fix that.
             MSG
             yield
           end

data/lib/aasm/persistence/base.rb

@@ -59,7 +59,9 @@ module AASM
     # make sure to create a (named) scope for each state
     def state_with_scope(*args)
       names = state_without_scope(*args)
-      names.each { |name| create_scope(name) if create_scope?(name) }
+      names.each do |name|
+        create_scopes(name)
+      end
     end
     alias_method :state_without_scope, :state
     alias_method :state, :state_with_scope
@@ -71,7 +73,16 @@ module AASM
     end
 
     def create_scope(name)
-      @klass.aasm_create_scope(@name, name)
+      @klass.aasm_create_scope(@name, name) if create_scope?(name)
+    end
+
+    def create_scopes(name)
+      if namespace?
+        # Create default scopes even when namespace? for backward compatibility
+        namepaced_name = "#{namespace}_#{name}"
+        create_scope(namepaced_name)
+      end
+      create_scope(name)
     end
   end # Base
 

data/lib/aasm/version.rb

@@ -1,3 +1,3 @@
 module AASM
-  VERSION = "5.1.1"
+  VERSION = "5.5.0"
 end

data/lib/generators/aasm/orm_helpers.rb

@@ -29,7 +29,7 @@ RUBY
       end
 
       def model_exists?
-        File.exists?(File.join(destination_root, model_path))
+        File.exist?(File.join(destination_root, model_path))
       end
 
       def model_path

data/lib/generators/active_record/templates/migration.rb

@@ -1,4 +1,4 @@
-class AASMCreate<%= table_name.camelize %> < ActiveRecord::Migration[<%=  ActiveRecord::VERSION::STRING.to_f %>]
+class AasmCreate<%= table_name.camelize %> < ActiveRecord::Migration[<%=  ActiveRecord::VERSION::STRING.to_f %>]
   def change
     create_table(:<%= table_name %>) do |t|
       t.string :<%= column_name %>