statesman 13.2.0 → 13.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffe7ee5f3aa4787fccd4c325c42bd892dc475edaaabc45a4a67155ebe41d41c1
-  data.tar.gz: 1794e00cf99c34e3d84a680f409a92d2430d0ed4964d3145f7f0539d7c54ec09
+  metadata.gz: 5de6588300b8aa3559f3ef4691e865c8b4571b029029671704aa8249b6fccb48
+  data.tar.gz: 2b70040b208dfa076b5633640668f5b964a148cd7d6ea4e1cd7a6671dc29e5cd
 SHA512:
-  metadata.gz: 7fc095f7cdfec543802c1e367af567d63e8abea8e57c01bc0b1fc1a6d661ea3b187e0d9ed91457c2eecf109286879ef7bd5bf45e3fa80a44777cb326486f9007
-  data.tar.gz: e3c342d10b68eccd5d4f145079c70537582f7923cf5cf7a9c0724fb58553476ca3d4e319c993929840e7ee2d2dbfedf1634e40160647429ea7cf194574275b79
+  metadata.gz: 33129e2eb00defefabd11b7edcf85efb709eed969c68897fc2b321927e8b7b47a7e4abf474365ab4ed9b9b5916e06937752a312520e205650427992de93adf2e
+  data.tar.gz: 0c33cba64756fc17cb293c0efbd3dd752d7741c8fb7469407ce1e5eb51df59a4c3ff9b989e433ed5220716c6c378a97331e7cb4ffb64fe97dbd9521be6dd2877

data/CHANGELOG.md

@@ -5,6 +5,13 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v13.3.0 4th August 2026
+
+### Added
+
+- `Statesman::Adapters::ConfigureCachedCurrentState`, a model mixin to maintain a denormalised current-state column on the parent model without a separate join or query, via `configure_cached_current_state`. The write happens inside the `ActiveRecord` storage adapter itself (shared by every `Machine` subclass and every adapter instance for a model), so it also works for models driven by several different machine classes chosen dynamically (e.g. per scheme), and fires reliably under `mysql_gaplock_protection`. Exposes the configured column via `Model.cached_state_column_name` for generic tooling. Only updates via real `transition_to!` calls - a transition row created directly, bypassing the machine, does not update the cache. The initial-state seed on create only applies if the column is nil, so a record explicitly created into a given state (e.g. a test factory) keeps that value.
+- `configure_state_machine` now exposes `transition_class` and `initial_state` as class readers.
+
 ## v13.2.0 29th July 2026
 
 ### Added

data/README.md

@@ -617,6 +617,63 @@ Model.in_state(:state_1).or(
 )
 ```
 
+### Caching the current state
+
+If you find yourself frequently needing the current state without wanting to
+join or query the transitions table,
+`Statesman::Adapters::ConfigureCachedCurrentState` can maintain a
+denormalised column on the parent model for you:
+
+```ruby
+class MyModel < ActiveRecord::Base
+  extend Statesman::Adapters::TypeSafeActiveRecordQueries
+  include Statesman::Adapters::ConfigureCachedCurrentState
+
+  configure_state_machine transition_class: MyModelTransition,
+                          initial_state: :initial
+  configure_cached_current_state
+end
+```
+
+This sets the column (`cached_current_state` by default) to the initial state
+when a record is created — unless it's already been explicitly set (e.g. a
+test factory building a record straight into a given state), in which case
+that value is left alone — and updates it via `update_columns` whenever
+`transition_to!` successfully persists a new `most_recent` transition.
+Including the module by itself does nothing — the write is only wired up once
+`configure_cached_current_state` is called.
+
+The write happens inside the `ActiveRecord` storage adapter itself, right
+after a transition is persisted as the new `most_recent` row, rather than via
+an ActiveRecord callback on `transition_class`. That single code path is
+shared by every `Machine` subclass and by every adapter instance for a model,
+so it fires reliably even under Statesman's `mysql_gaplock_protection` config
+— where the `most_recent` flip happens via a raw SQL `UPDATE` that bypasses
+ActiveRecord callbacks entirely.
+
+One consequence: a transition row created directly on `transition_class`,
+bypassing the machine (e.g. `parent.transitions.create!(...)` in a test or
+backfill), does not update the cache — only real transitions performed
+through `transition_to!` do.
+
+Two further options are available:
+
+- `column:` — use a column name other than `cached_current_state`.
+- `touch_updated_at:` — also bump `updated_at` on the parent when the cached
+  column changes (defaults to `false`).
+
+Because the write happens in the shared adapter code rather than against a
+specific `Machine` subclass, this also works for models driven by several
+different machine classes chosen dynamically (e.g. per scheme). It always
+runs before any of a machine's own `after_transition` callbacks, since it
+happens as part of persisting the transition, before Statesman invokes its
+own callbacks.
+
+`configure_cached_current_state` also defines `Model.cached_state_column_name`,
+returning the configured column, for generic tooling that needs to introspect
+or repair the cached column (e.g. a cache-repair rake task working across
+several models).
+
 ## Frequently Asked Questions
 
 ### Storing the state on the model object

data/lib/statesman/adapters/active_record.rb

@@ -108,6 +108,8 @@ module Statesman
             transition.save!
           end
 
+          maintain_cached_current_state(transition)
+
           @last_transition = transition
           @observer.execute(:after, from, to, transition)
           add_after_commit_callback(from, to, transition)
@@ -116,6 +118,30 @@ module Statesman
         transition
       end
 
+      # Writes the cached current state column configured via
+      # Statesman::Adapters::ConfigureCachedCurrentState#configure_cached_current_state,
+      # if the parent model opted in. Done here, rather than via an ActiveRecord
+      # callback on transition_class, so it fires reliably even under
+      # mysql_gaplock_protection - where most_recent is flipped to true via a raw SQL
+      # UPDATE that bypasses ActiveRecord callbacks entirely (see above). This method
+      # always runs after most_recent has been set on `transition` (in both branches
+      # above), and before the machine's own after_transition callbacks are invoked.
+      def maintain_cached_current_state(transition)
+        model_class = parent_model.class
+        return unless model_class.respond_to?(:cached_state_column_name)
+
+        column = model_class.cached_state_column_name
+        unless model_class.column_names.include?(column.to_s)
+          raise ArgumentError,
+                "cache_current_state_column: #{column.inspect} is not a column " \
+                "on #{model_class.name}"
+        end
+
+        attributes = { column => transition.to_state }
+        attributes[:updated_at] = Time.current if model_class.cached_current_state_touch_updated_at?
+        parent_model.update_columns(attributes)
+      end
+
       def default_transition_attributes(from, to, metadata)
         attributes = {
           to_state: to,

data/lib/statesman/adapters/active_record_queries.rb

@@ -33,6 +33,18 @@ module Statesman
         ClassMethods.new(**args)
       end
 
+      # Finds the has_many association on model that targets transition_class -
+      # matching by klass rather than by name, since callers (e.g.
+      # ConfigureCachedCurrentState) may not know what the association was named.
+      def self.transition_reflection_for(model, transition_class)
+        model.reflect_on_all_associations(:has_many).find do |reflection|
+          reflection.klass == transition_class
+        end || raise(
+          MissingTransitionAssociation,
+          "Could not find has_many association between #{model} and #{transition_class}.",
+        )
+      end
+
       class ClassMethods < Module
         def initialize(**args)
           @args = args
@@ -41,7 +53,13 @@ module Statesman
         def included(base)
           ensure_inheritance(base) if base.respond_to?(:subclasses) && base.subclasses.any?
 
-          query_builder = QueryBuilder.new(base, **@args)
+          query_builder = QueryBuilder.new(
+            base,
+            transition_class: @args[:transition_class],
+            initial_state: @args[:initial_state],
+            most_recent_transition_alias: @args[:most_recent_transition_alias],
+            transition_name: @args[:transition_name],
+          )
 
           base.define_singleton_method(:most_recent_transition_join) do
             query_builder.most_recent_transition_join
@@ -126,13 +144,7 @@ module Statesman
         end
 
         def transition_reflection
-          model.reflect_on_all_associations(:has_many).each do |value|
-            return value if value.klass == transition_class
-          end
-
-          raise MissingTransitionAssociation,
-                "Could not find has_many association between #{self.class} " \
-                "and #{transition_class}."
+          ActiveRecordQueries.transition_reflection_for(model, transition_class)
         end
 
         def model_primary_key

data/lib/statesman/adapters/configure_cached_current_state.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Statesman
+  module Adapters
+    # Include on an ActiveRecord model configured with
+    # Statesman::Adapters::TypeSafeActiveRecordQueries#configure_state_machine (only
+    # transition_class: is required) to cache the current state on a column on the
+    # model. Including this module does nothing on its own - the model must also call
+    # `configure_cached_current_state` to wire up the write, which also exposes the
+    # configured column name via `cached_state_column_name`, for generic tooling that
+    # needs to introspect or repair the cached column (e.g. a cache-repair rake task).
+    #
+    # The write itself happens inside Statesman::Adapters::ActiveRecord#create_transition
+    # (see `maintain_cached_current_state` there), not via a callback registered by this
+    # module - that single code path is shared by every Machine subclass and every
+    # storage adapter instance for a model, so this works even when a model is driven by
+    # several different machine classes (e.g. chosen dynamically per scheme), and it
+    # fires reliably under Statesman's mysql_gaplock_protection config, where the DB-level
+    # most_recent flip happens via a raw SQL UPDATE that bypasses ActiveRecord callbacks
+    # entirely.
+    #
+    # Caveat: because the write only happens as part of `transition_to!` (via the
+    # adapter), a transition row created directly on transition_class - bypassing the
+    # machine entirely, e.g. `parent.transitions.create!(...)` - does not update the
+    # cache. Only real transitions performed through the machine do.
+    #
+    # The initial-state seed on create only applies when the column is nil - if it's
+    # already been explicitly set (e.g. a test factory building a record straight into a
+    # given state, without a real transition history), that value is left alone.
+    module ConfigureCachedCurrentState
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def configure_cached_current_state(column: :cached_current_state, touch_updated_at: false)
+          unless respond_to?(:transition_class) && transition_class
+            raise ArgumentError,
+                  "transition_class: must be configured via configure_state_machine " \
+                  "before calling configure_cached_current_state"
+          end
+
+          initial = initial_state
+
+          define_singleton_method(:cached_state_column_name) { column }
+          define_singleton_method(:cached_current_state_touch_updated_at?) { touch_updated_at }
+
+          before_create do
+            next unless respond_to?(:"#{column}=")
+            next unless send(column).nil?
+
+            send(:"#{column}=", initial.to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/statesman/adapters/type_safe_active_record_queries.rb

@@ -15,6 +15,9 @@ module Statesman
             transition_name: try(:transition_name),
           ),
         )
+
+        define_singleton_method(:initial_state) { initial_state }
+        define_singleton_method(:transition_class) { transition_class }
       end
     end
   end

data/lib/statesman/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Statesman
-  VERSION = "13.2.0"
+  VERSION = "13.3.0"
 end

data/lib/statesman.rb

@@ -16,6 +16,8 @@ module Statesman
              "statesman/adapters/active_record_queries"
     autoload :TypeSafeActiveRecordQueries,
              "statesman/adapters/type_safe_active_record_queries"
+    autoload :ConfigureCachedCurrentState,
+             "statesman/adapters/configure_cached_current_state"
   end
   require "statesman/railtie" if defined?(::Rails::Railtie)
 

data/spec/statesman/adapters/configure_cached_current_state_spec.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+describe Statesman::Adapters::ConfigureCachedCurrentState, :active_record do
+  before do
+    prepare_model_table
+    prepare_transitions_table
+
+    Statesman.configure do
+      storage_adapter(Statesman::Adapters::ActiveRecord)
+    end
+
+    MyActiveRecordModel.extend Statesman::Adapters::TypeSafeActiveRecordQueries
+    MyActiveRecordModel.send(:include, described_class)
+  end
+
+  after do
+    Statesman.configure { storage_adapter(Statesman::Adapters::Memory) }
+    MyActiveRecordModel.reset_callbacks(:create)
+  end
+
+  def configure(**args)
+    MyActiveRecordModel.configure_state_machine(
+      transition_class: MyActiveRecordModelTransition,
+      initial_state: :initial,
+      **args,
+    )
+  end
+
+  describe "including the module without calling configure_cached_current_state" do
+    it "does not add any callbacks" do
+      configure
+
+      expect { MyActiveRecordModel.create }.
+        to_not change(MyActiveRecordModelTransition, :count)
+    end
+  end
+
+  describe ".configure_cached_current_state" do
+    it "raises if transition_class was not configured" do
+      klass = Class.new
+      klass.send(:extend, Statesman::Adapters::TypeSafeActiveRecordQueries)
+      klass.send(:include, described_class)
+
+      expect { klass.configure_cached_current_state }.
+        to raise_error(ArgumentError, /transition_class/)
+    end
+
+    it "sets the column to the initial state on create" do
+      configure
+      MyActiveRecordModel.configure_cached_current_state
+
+      model = MyActiveRecordModel.create
+
+      expect(model.cached_current_state).to eq("initial")
+    end
+
+    it "does not override an explicitly-set column value on create" do
+      configure
+      MyActiveRecordModel.configure_cached_current_state
+
+      model = MyActiveRecordModel.create(cached_current_state: "succeeded")
+
+      expect(model.reload.cached_current_state).to eq("succeeded")
+    end
+
+    it "updates the column on every transition" do
+      configure
+      MyActiveRecordModel.configure_cached_current_state
+
+      model = MyActiveRecordModel.create
+      model.state_machine.transition_to!(:succeeded)
+
+      expect(model.reload.cached_current_state).to eq("succeeded")
+    end
+
+    it "writes via update_columns, not updating updated_at by default" do
+      configure
+      MyActiveRecordModel.configure_cached_current_state
+
+      model = MyActiveRecordModel.create
+      original_updated_at = model.updated_at
+
+      Timecop.travel(1.hour.from_now) do
+        model.state_machine.transition_to!(:succeeded)
+      end
+
+      expect(model.reload.updated_at).to be_within(1.second).of(original_updated_at)
+    end
+
+    it "touches updated_at when touch_updated_at is true" do
+      configure
+      MyActiveRecordModel.configure_cached_current_state(touch_updated_at: true)
+
+      model = MyActiveRecordModel.create
+      original_updated_at = model.updated_at
+
+      Timecop.travel(1.hour.from_now) do
+        model.state_machine.transition_to!(:succeeded)
+      end
+
+      expect(model.reload.updated_at).to be > original_updated_at
+    end
+
+    it "respects a custom column" do
+      MyActiveRecordModel.connection.add_column(:my_active_record_models, :cached_state, :string)
+      MyActiveRecordModel.reset_column_information
+
+      configure
+      MyActiveRecordModel.configure_cached_current_state(column: :cached_state)
+
+      model = MyActiveRecordModel.create
+      model.state_machine.transition_to!(:succeeded)
+
+      expect(model.reload.cached_state).to eq("succeeded")
+    end
+
+    it "exposes the configured column name via cached_state_column_name" do
+      configure
+      MyActiveRecordModel.configure_cached_current_state(column: :cached_state)
+
+      expect(MyActiveRecordModel.cached_state_column_name).to eq(:cached_state)
+    end
+
+    it "raises at transition time if the configured column doesn't exist" do
+      configure
+      MyActiveRecordModel.configure_cached_current_state(column: :not_a_real_column)
+
+      model = MyActiveRecordModel.create
+
+      expect { model.state_machine.transition_to!(:succeeded) }.
+        to raise_error(ArgumentError, /not_a_real_column/)
+    end
+
+    it "does not update the cache for a transition row created directly, bypassing the machine" do
+      configure
+      MyActiveRecordModel.configure_cached_current_state
+
+      model = MyActiveRecordModel.create
+      model.my_active_record_model_transitions.create!(to_state: "succeeded", sort_key: 1, most_recent: true)
+
+      expect(model.reload.cached_current_state).to eq("initial")
+    end
+
+    it "runs before the machine's own after_transition callbacks" do
+      seen_cached_state = nil
+      MyStateMachine.after_transition { |parent, _t| seen_cached_state = parent.cached_current_state }
+
+      configure
+      MyActiveRecordModel.configure_cached_current_state
+
+      model = MyActiveRecordModel.create
+      model.state_machine.transition_to!(:succeeded)
+
+      expect(seen_cached_state).to eq("succeeded")
+    ensure
+      MyStateMachine.class_eval { callbacks[:after] = [] }
+    end
+
+    context "with a model driven by more than one machine class (no single state_machine_class)" do
+      it "still updates the cache" do
+        configure
+        MyActiveRecordModel.configure_cached_current_state
+
+        model = MyActiveRecordModel.create
+        # Simulate a different machine class than `state_machine` normally uses - the
+        # cache write happens in the shared adapter code, not per Machine subclass, so
+        # it doesn't matter which machine class drove the transition.
+        other_machine = MyStateMachine.new(model, transition_class: MyActiveRecordModelTransition)
+        other_machine.transition_to!(:failed)
+
+        expect(model.reload.cached_current_state).to eq("failed")
+      end
+    end
+  end
+end

data/spec/statesman/adapters/type_safe_active_record_queries_spec.rb

@@ -203,4 +203,16 @@ describe Statesman::Adapters::TypeSafeActiveRecordQueries, :active_record do
   context "using configuration method" do
     it_behaves_like "testing methods"
   end
+
+  context "transition_class" do
+    it "is exposed as a class method" do
+      MyActiveRecordModel.send(:extend, described_class)
+      MyActiveRecordModel.configure_state_machine(
+        transition_class: MyActiveRecordModelTransition,
+        initial_state: :initial,
+      )
+
+      expect(MyActiveRecordModel.transition_class).to eq(MyActiveRecordModelTransition)
+    end
+  end
 end

data/spec/support/active_record.rb

@@ -61,6 +61,7 @@ class CreateMyActiveRecordModelMigration < MIGRATION_CLASS
   def change
     create_table :my_active_record_models do |t|
       t.string :current_state
+      t.string :cached_current_state
       t.timestamps null: false
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statesman
 version: !ruby/object:Gem::Version
-  version: 13.2.0
+  version: 13.3.0
 platform: ruby
 authors:
 - GoCardless
@@ -43,6 +43,7 @@ files:
 - lib/statesman/adapters/active_record.rb
 - lib/statesman/adapters/active_record_queries.rb
 - lib/statesman/adapters/active_record_transition.rb
+- lib/statesman/adapters/configure_cached_current_state.rb
 - lib/statesman/adapters/memory.rb
 - lib/statesman/adapters/memory_transition.rb
 - lib/statesman/adapters/type_safe_active_record_queries.rb
@@ -64,6 +65,7 @@ files:
 - spec/statesman/adapters/active_record_queries_spec.rb
 - spec/statesman/adapters/active_record_spec.rb
 - spec/statesman/adapters/active_record_transition_spec.rb
+- spec/statesman/adapters/configure_cached_current_state_spec.rb
 - spec/statesman/adapters/memory_spec.rb
 - spec/statesman/adapters/memory_transition_spec.rb
 - spec/statesman/adapters/shared_examples.rb