state_machines-activerecord 0.302.0 → 0.304.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 56832b6fe9e7b6bdab1c9890fbf6078015b095c85e7b07f38f991012ee471402
4
- data.tar.gz: 26cd99926e156dba1f805a7077934a0ee6af40b3f699c60ff44d2a533cd3500b
3
+ metadata.gz: 0bbcceaec257df5578ab8bf04f47cfd101f78e831d15b7ba4b048b19cca809a9
4
+ data.tar.gz: a232e3e525e159618e8ab68335a1e7f153db451f924397ca8ac3243fac2dbe40
5
5
  SHA512:
6
- metadata.gz: 1af35637c8e020ccdf292d27e9ef1ed40f3dd50d3dc17a027bf35a4f8f0034b80b1bb1c34eec7ffb66998678f33dd84787d57dbce06b1529c27c3fa1c93f7679
7
- data.tar.gz: fe3d5f5bc88807999c5fbf262eb3c56833a74a06096acbe5a8c79094a94bbacffc526fca33b2b07beacea9d19306a72ee52f30670f699bfd56614bd1a069cb56
6
+ metadata.gz: fc002e9f1f9bc09c31dd181548110da2df9e9c72b269d2042f0e5dbcb3675b8c0e7338e434ec1075227c168efd4025efba4b370fd2f9a1fe1a4eaaff33549954
7
+ data.tar.gz: 8a73593ed12c970790b818f1b83308c4aa4039f175c64c5954b78f2e7b8465f2d1e3f8e2f5e8d5c90385d58ee40356de188804d87d5244103b67ae891dc87712
data/README.md CHANGED
@@ -141,6 +141,20 @@ A form submitting `state` alongside (or instead of) `state_event` gets a
141
141
 
142
142
  ### Data repair
143
143
 
144
+ `force_state!` moves a record to a state without firing an event and saves
145
+ it. Transition callbacks are skipped, but validations and save callbacks run,
146
+ so auditing (e.g. paper_trail) still records the change. It works whether or
147
+ not the machine denies direct assignment:
148
+
149
+ ```ruby
150
+ vehicle.force_state!(:parked)
151
+ vehicle.force_state!(:off, machine: :alarm_state) # required with several machines
152
+ ```
153
+
154
+ It raises `IndexError` for an unknown state, `StateMachines::PendingStateEvent`
155
+ while an event is queued, and `ActiveRecord::RecordInvalid` when the record is
156
+ invalid.
157
+
144
158
  Raw persistence stays outside the state machine on purpose: no event is
145
159
  inferred, no callback or validation runs.
146
160
 
@@ -58,9 +58,10 @@ module StateMachines
58
58
  end
59
59
  end
60
60
 
61
- # Raised by +becomes+ while a record still has queued state machine work
62
- # (a pending event attribute or a transition prepared by validation): the
63
- # new instance would silently drop it.
61
+ # Raised by +becomes+ or +force_state!+ while a record still has queued
62
+ # state machine work (a pending event attribute or a transition prepared by
63
+ # validation): +becomes+ would silently drop it, +force_state!+ would race
64
+ # it.
64
65
  class PendingStateEvent < Error
65
66
  # @return [StateMachines::Machine] the machine with queued work
66
67
  attr_reader :machine
@@ -71,11 +72,12 @@ module StateMachines
71
72
  # @param object [ActiveRecord::Base] the record being converted
72
73
  # @param machine [StateMachines::Machine] the machine with queued work
73
74
  # @param event [Symbol, String] the queued event
74
- def initialize(object, machine, event)
75
+ # @param operation [String] the refused method
76
+ def initialize(object, machine, event, operation: 'becomes')
75
77
  @machine = machine
76
78
  @event = event
77
79
 
78
- super(object, "Cannot call becomes on #{object.class.name} while state machine #{machine.name.inspect} " \
80
+ super(object, "Cannot call #{operation} on #{object.class.name} while state machine #{machine.name.inspect} " \
79
81
  "has queued work (#{machine.attribute(:event)} = #{event.inspect}); " \
80
82
  'save the record or clear the event first.')
81
83
  end
@@ -0,0 +1,50 @@
1
+ # frozen_string_literal: true
2
+
3
+ module StateMachines
4
+ module Integrations
5
+ module ActiveRecord
6
+ # Administrative state changes outside the machine's events, mixed into
7
+ # every model owning a state machine.
8
+ module ForceState
9
+ # Moves the record to +state+ without firing an event, then saves it.
10
+ # No transition callbacks run, but validations and save callbacks do,
11
+ # so auditing (e.g. paper_trail) records the change. Works whether or
12
+ # not the machine denies direct assignment. Meant for data repair:
13
+ # regular state changes go through events.
14
+ #
15
+ # @param state [Symbol, String, nil] the target state's name
16
+ # @param machine [Symbol, String, nil] the machine's name; required
17
+ # when the model has several machines
18
+ # @return [true]
19
+ # @raise [ArgumentError] when +machine+ is missing or unknown
20
+ # @raise [IndexError] when +state+ is not a state of the machine
21
+ # @raise [StateMachines::PendingStateEvent] while an event attribute
22
+ # or a transition prepared by validation is queued
23
+ # @raise [ActiveRecord::RecordInvalid] when the record is invalid
24
+ def force_state!(state, machine: nil)
25
+ target = ForceState.machine_for(self, machine)
26
+ StateGuard.ensure_no_queued_work!(self, operation: 'force_state!')
27
+ target.write(self, :state, target.states.fetch(state).value)
28
+ save!
29
+ end
30
+
31
+ # @param record [ActiveRecord::Base] the record whose state is forced
32
+ # @param name [Symbol, String, nil] the requested machine's name
33
+ # @return [StateMachines::Machine] the machine to force
34
+ # @raise [ArgumentError] when +name+ is missing or unknown
35
+ def self.machine_for(record, name)
36
+ machines = record.class.state_machines
37
+ return machines.values.first if name.nil? && machines.size == 1
38
+
39
+ key = name&.to_sym
40
+ machines.fetch(key) do
41
+ names = machines.keys.map(&:inspect).join(', ')
42
+ raise ArgumentError, "#{record.class.name} has several state machines (#{names}); pass machine:" unless key
43
+
44
+ raise ArgumentError, "#{record.class.name} has no state machine #{key.inspect}"
45
+ end
46
+ end
47
+ end
48
+ end
49
+ end
50
+ end
@@ -330,13 +330,14 @@ module StateMachines
330
330
  verify_persistable!(record) if queued_work(record)
331
331
  end
332
332
 
333
- # @param record [ActiveRecord::Base] the record being converted
333
+ # @param record [ActiveRecord::Base] the record being converted or forced
334
+ # @param operation [String] the refused method, named in the error
334
335
  # @return [void]
335
336
  # @raise [StateMachines::PendingStateEvent] when an event attribute
336
337
  # or a prepared transition is queued
337
- def ensure_no_queued_work!(record)
338
+ def ensure_no_queued_work!(record, operation: 'becomes')
338
339
  machine, event = queued_work(record)
339
- raise PendingStateEvent.new(record, machine, event) if machine
340
+ raise PendingStateEvent.new(record, machine, event, operation: operation) if machine
340
341
  end
341
342
 
342
343
  # Gives +target+ the same state authorizations as +source+.
@@ -3,7 +3,7 @@
3
3
  module StateMachines
4
4
  module Integrations
5
5
  module ActiveRecord
6
- VERSION = '0.302.0'
6
+ VERSION = '0.304.0'
7
7
  end
8
8
  end
9
9
  end
@@ -5,6 +5,7 @@ require 'active_record'
5
5
  require 'state_machines/integrations/active_record/version'
6
6
  require 'state_machines/integrations/active_record/type/integer'
7
7
  require 'state_machines/integrations/active_record/state_guard'
8
+ require 'state_machines/integrations/active_record/force_state'
8
9
 
9
10
  module StateMachines
10
11
  module Integrations # :nodoc:
@@ -462,6 +463,7 @@ module StateMachines
462
463
  def owner_class=(klass)
463
464
  super.tap do
464
465
  klass.include(RefusalReset) unless klass < RefusalReset
466
+ klass.include(ForceState) unless klass < ForceState
465
467
  StateGuard.install(klass, attribute) if direct_assignment_denied?
466
468
  register_integer_type if integer_type_registered?
467
469
  end
@@ -1141,8 +1143,7 @@ module StateMachines
1141
1143
  # Runs state events around the machine's :save action
1142
1144
  def around_save(object, &)
1143
1145
  StateGuard.verify_before_transitions!(object)
1144
- # Pass fiber: false to avoid deadlocks with ActiveRecord's LoadInterlockAwareMonitor
1145
- object.class.state_machines.transitions(object, action, fiber: false).perform(&)
1146
+ object.class.state_machines.transitions(object, action).perform(&)
1146
1147
  end
1147
1148
 
1148
1149
  # Creates a scope for finding records *with* a particular state or
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: state_machines-activerecord
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.302.0
4
+ version: 0.304.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Abdelkader Boudih
@@ -30,14 +30,14 @@ dependencies:
30
30
  requirements:
31
31
  - - ">="
32
32
  - !ruby/object:Gem::Version
33
- version: 0.301.0
33
+ version: 0.304.0
34
34
  type: :runtime
35
35
  prerelease: false
36
36
  version_requirements: !ruby/object:Gem::Requirement
37
37
  requirements:
38
38
  - - ">="
39
39
  - !ruby/object:Gem::Version
40
- version: 0.301.0
40
+ version: 0.304.0
41
41
  - !ruby/object:Gem::Dependency
42
42
  name: state_machines-activemodel
43
43
  requirement: !ruby/object:Gem::Requirement
@@ -135,6 +135,7 @@ files:
135
135
  - lib/state_machines-activerecord.rb
136
136
  - lib/state_machines/integrations/active_record.rb
137
137
  - lib/state_machines/integrations/active_record/errors.rb
138
+ - lib/state_machines/integrations/active_record/force_state.rb
138
139
  - lib/state_machines/integrations/active_record/locale.rb
139
140
  - lib/state_machines/integrations/active_record/state_guard.rb
140
141
  - lib/state_machines/integrations/active_record/type/integer.rb