state_machines-activerecord 0.302.0 → 0.303.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: ffdd74d11d1cc866bd04554ef02a5942e9f84aced876586aa6015f9f686c1189
4
+ data.tar.gz: 0c3ad8ad2e0e57c23099c75eb0e8553505721630bb49608c58c513e9ce46391e
5
5
  SHA512:
6
- metadata.gz: 1af35637c8e020ccdf292d27e9ef1ed40f3dd50d3dc17a027bf35a4f8f0034b80b1bb1c34eec7ffb66998678f33dd84787d57dbce06b1529c27c3fa1c93f7679
7
- data.tar.gz: fe3d5f5bc88807999c5fbf262eb3c56833a74a06096acbe5a8c79094a94bbacffc526fca33b2b07beacea9d19306a72ee52f30670f699bfd56614bd1a069cb56
6
+ metadata.gz: 5b2bf0430eae8f198ee3c616790d862d1c55c238fb27449598abaaea7754df4356ca028ddf2be3ae15b3668993e2c86c4661795f6c72a261f0ce20444f594ef6
7
+ data.tar.gz: 1da6b7ad4b6f9a60235ea1de68d154e01dec66c1b0cc8ddb99cf9ca7301205799b1318de9da31b3783320dc945953bcf521e2064a3284b4fba18bdc12bb09ba9
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.303.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
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.303.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Abdelkader Boudih
@@ -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