state_machines-activerecord 0.300.0 → 0.301.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: 35ebef64fc42b8b51c00b272365a7fe80b493d82b120ea2a21f9fafef0a0c640
4
- data.tar.gz: c0a5b6b98eecd70f374c16ba76a590b372edcb0225e117a34d8218418add0113
3
+ metadata.gz: 2a978e35d63388e62357e60d6a6e02776b65aa895f0dff425d00fc8da056f48f
4
+ data.tar.gz: 03bb42e39587a982d6579bc0bdba365ef0e21b2dbea825116bc217677da067a5
5
5
  SHA512:
6
- metadata.gz: d636b2fab507273bfd4c0c7b9aca089ce47803fa9de302871e0a31ce02fbeb63776c8f305d724ca1d26a896087f3cd1014c96fbdb13e747529fff2c81a9c9117
7
- data.tar.gz: 0b8b2ffd5bd9af75a42ef34d15e3b24ae21a5f638a05eb698b463bea07a537aa362898c1d507b3ebe35c778830988e0351dc50af37cae196fefe1b7cd499404f
6
+ metadata.gz: 7838106f843f19188b991d5a4ce9c62a9fd8420dd50cb6dbf651d81310dd2cbd70b986b48b857c614b20ffc082988c8422343133a23559fd95c2b5c3b755c469
7
+ data.tar.gz: 7550030858f46cfa1221c550b2a33ae3fae7b0014e90836cfa538a96472c77010642339593ed91b3497afac62b3fb9561c31a6e29b7f802a359f298102137136
data/README.md CHANGED
@@ -62,7 +62,24 @@ end
62
62
 
63
63
  ## State changes go through events
64
64
 
65
- The only way to change a record's state through the model is an event:
65
+ Opt a machine in with `direct_assignment: :deny`:
66
+
67
+ ```ruby
68
+ class Vehicle < ActiveRecord::Base
69
+ state_machine initial: :parked, direct_assignment: :deny do
70
+ event(:ignite) { transition parked: :idling }
71
+ end
72
+ end
73
+ ```
74
+
75
+ Machines without the option use
76
+ `StateMachines::Integrations::ActiveRecord.direct_assignment`, which is
77
+ `:allow` (the attribute can be written directly). Set it to `:deny` in an
78
+ initializer to opt every machine in; a machine can still pass
79
+ `direct_assignment: :allow`. The default is read when a machine is defined,
80
+ so set it before your models load.
81
+
82
+ With `:deny`, the only way to change a record's state through the model is an event:
66
83
 
67
84
  ```ruby
68
85
  vehicle.ignite # fire it
@@ -229,7 +246,7 @@ When enum integration is detected, the gem automatically:
229
246
  order = Order.create(status: :pending)
230
247
  order.pending? # => true (Rails enum method)
231
248
  order.processing? # => false (Rails enum method)
232
- order.processing! # => StateMachines::DirectStateAssignment (writes the state directly)
249
+ order.processing! # => writes the state directly; raises StateMachines::DirectStateAssignment with direct_assignment: :deny
233
250
  order.process # Fire the event instead
234
251
 
235
252
  Order.pending # Rails enum scope
@@ -5,7 +5,10 @@ require 'state_machines/integrations/active_record/errors'
5
5
  module StateMachines
6
6
  module Integrations
7
7
  module ActiveRecord
8
- # Enforces that state changes through the model are event-only.
8
+ # Enforces that state changes through the model are event-only, for
9
+ # machines declared with <tt>direct_assignment: :deny</tt> (or all
10
+ # machines when ActiveRecord.direct_assignment is +:deny+). Machines
11
+ # allowing direct assignment (the default) are left alone.
9
12
  #
10
13
  # Every write of a machine's attribute through the model (setter, mass
11
14
  # assignment, attribute alias, +record[:attr] =+, +write_attribute+) is
@@ -380,6 +383,8 @@ module StateMachines
380
383
  seen = Set.new
381
384
 
382
385
  record.class.state_machines.each_value do |machine|
386
+ next unless machine.direct_assignment_denied?
387
+
383
388
  name = guarded_name(machine)
384
389
  next unless seen.add?(name) && record._has_attribute?(name) && !machine.transient_attribute?
385
390
 
@@ -391,9 +396,11 @@ module StateMachines
391
396
  end
392
397
 
393
398
  # @return [StateMachines::Machine, nil] the first machine writing
394
- # attribute +name+
399
+ # attribute +name+ that denies direct assignment
395
400
  def machine_for(record, name)
396
- record.class.state_machines.each_value.find { |machine| guarded_name(machine) == name }
401
+ record.class.state_machines.each_value.find do |machine|
402
+ machine.direct_assignment_denied? && guarded_name(machine) == name
403
+ end
397
404
  end
398
405
 
399
406
  # @return [Array(StateMachines::Machine, Object), nil] the first
@@ -3,7 +3,7 @@
3
3
  module StateMachines
4
4
  module Integrations
5
5
  module ActiveRecord
6
- VERSION = '0.300.0'
6
+ VERSION = '0.301.0'
7
7
  end
8
8
  end
9
9
  end
@@ -112,7 +112,21 @@ module StateMachines
112
112
  #
113
113
  # == Direct state assignment
114
114
  #
115
- # State changes through the model are event-only. Writing a different
115
+ # By default the machine's attribute can be written directly. Declare
116
+ # <tt>direct_assignment: :deny</tt> to make state changes through the
117
+ # model event-only:
118
+ #
119
+ # class Vehicle < ActiveRecord::Base
120
+ # state_machine initial: :parked, direct_assignment: :deny do
121
+ # event(:ignite) { transition parked: :idling }
122
+ # end
123
+ # end
124
+ #
125
+ # The default for machines that do not set the option is
126
+ # <tt>StateMachines::Integrations::ActiveRecord.direct_assignment</tt>
127
+ # (+:allow+); set it to +:deny+ to opt every machine in.
128
+ #
129
+ # With +:deny+, state changes through the model are event-only. Writing a different
116
130
  # state directly (the attribute writer, mass assignment, an alias,
117
131
  # <tt>record[:state] =</tt>, +write_attribute+, building a record with a
118
132
  # non-initial state, or a callback doing any of these) raises
@@ -401,6 +415,10 @@ module StateMachines
401
415
  # The default options to use for state machines using this integration
402
416
  @defaults = { action: :save, use_transactions: true }
403
417
  @auto_convert_integer_state_attributes = true
418
+ @direct_assignment = :allow
419
+
420
+ # Values accepted by the +direct_assignment+ machine option
421
+ DIRECT_ASSIGNMENT_MODES = %i[allow deny].freeze
404
422
 
405
423
  # Forgets the refusal reasons recorded on a record when it is reloaded:
406
424
  # they describe attempts made against the state being discarded.
@@ -444,11 +462,37 @@ module StateMachines
444
462
  def owner_class=(klass)
445
463
  super.tap do
446
464
  klass.include(RefusalReset) unless klass < RefusalReset
447
- StateGuard.install(klass, attribute)
465
+ StateGuard.install(klass, attribute) if direct_assignment_denied?
448
466
  register_integer_type if integer_type_registered?
449
467
  end
450
468
  end
451
469
 
470
+ # How direct writes of the machine's attribute are treated: +:allow+
471
+ # (they go through untouched) or +:deny+ (state changes are
472
+ # event-only, see {StateGuard}). Set per machine with the
473
+ # +direct_assignment+ option, defaulting to
474
+ # {ActiveRecord.direct_assignment}.
475
+ #
476
+ # @return [Symbol] +:allow+ or +:deny+
477
+ # @raise [ArgumentError] when the configured value is not a known mode
478
+ def direct_assignment
479
+ @direct_assignment ||= begin
480
+ mode = integration_options.fetch(:direct_assignment) { ActiveRecord.direct_assignment }
481
+ unless DIRECT_ASSIGNMENT_MODES.include?(mode)
482
+ raise ArgumentError,
483
+ "Invalid direct_assignment: #{mode.inspect} (expected one of #{DIRECT_ASSIGNMENT_MODES.inspect})"
484
+ end
485
+
486
+ mode
487
+ end
488
+ end
489
+
490
+ # @return [Boolean] whether state changes through the model are
491
+ # event-only
492
+ def direct_assignment_denied?
493
+ direct_assignment == :deny
494
+ end
495
+
452
496
  # Check if enum integration should be enabled for this machine
453
497
  def detect_enum_integration
454
498
  return nil unless owner_class.defined_enums.key?(attribute.to_s)
@@ -948,6 +992,17 @@ module StateMachines
948
992
  class << self
949
993
  attr_accessor :auto_convert_integer_state_attributes
950
994
 
995
+ # Default +direct_assignment+ mode for machines that do not set one:
996
+ # +:allow+ (default) or +:deny+. Read when a machine is defined.
997
+ #
998
+ # @return [Symbol]
999
+ attr_accessor :direct_assignment
1000
+
1001
+ # @return [Array<Symbol>] machine options added by this integration
1002
+ def integration_options
1003
+ [:direct_assignment]
1004
+ end
1005
+
951
1006
  # Classes that inherit from ActiveRecord::Base will automatically use
952
1007
  # the ActiveRecord integration.
953
1008
  def matching_ancestors
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.300.0
4
+ version: 0.301.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Abdelkader Boudih
@@ -24,6 +24,20 @@ dependencies:
24
24
  - - ">="
25
25
  - !ruby/object:Gem::Version
26
26
  version: '8.1'
27
+ - !ruby/object:Gem::Dependency
28
+ name: state_machines
29
+ requirement: !ruby/object:Gem::Requirement
30
+ requirements:
31
+ - - ">="
32
+ - !ruby/object:Gem::Version
33
+ version: 0.301.0
34
+ type: :runtime
35
+ prerelease: false
36
+ version_requirements: !ruby/object:Gem::Requirement
37
+ requirements:
38
+ - - ">="
39
+ - !ruby/object:Gem::Version
40
+ version: 0.301.0
27
41
  - !ruby/object:Gem::Dependency
28
42
  name: state_machines-activemodel
29
43
  requirement: !ruby/object:Gem::Requirement