has_state_machine 1.2.0 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d16c6b958f2e470af9f3120259e802badad7fcd6b8a4ea1d004c84f64e8d09d
-  data.tar.gz: 2f9933db38477a1b1020303ab9848aa122fe7e699d153315b830144ffdbfd1a6
+  metadata.gz: 4f9619070408aa690d1e8b70c31baf787c91d949c0e28665a42af8b17ff79955
+  data.tar.gz: '099784a11f816d49d75b18432a1497688838aac08a775d15fe5d29827eb7ac38'
 SHA512:
-  metadata.gz: 35f89aad901be7f976ee42573449c0d7412a633285e41f869f50d7be3215da2752470cf5c4b1299d483605f90b8925f5baa5065729b06f2121678518beeafdb4
-  data.tar.gz: cb4e1a772fa2aa9828adfd3ab6bb548e5f489f403f4574cc464e9fa77f4633b886de5c486e4bb9b014eeb71c8ede380fab19320f8b85023e9643b38b3b9866c8
+  metadata.gz: 749b711582fc925fd8efbfcb7dcdee7dfb3f9902e945d5cc26e1f7f3737ea77f646087a117ccf9e6675444a858acb2497ae52dba0a3c8b2777628ebae33297af
+  data.tar.gz: a8cbe864ada7ab74316c55c14704ea33fa18bae5050d3a728d2f5458cb16b561419643805af0824fd7bdcca10cf42e5023e708d84f88ed1e3478a9b24bad2d43

data/README.md

@@ -1,7 +1,7 @@
 # HasStateMachine
 
 [![CI](https://github.com/beehiiv/has_state_machine/actions/workflows/ci.yml/badge.svg)](https://github.com/beehiiv/has_state_machine/actions/workflows/ci.yml)
-[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
 
 HasStateMachine uses ruby classes to make creating a finite state machine for your ActiveRecord models a breeze.
 
@@ -98,8 +98,10 @@ module Workflow
     end
 
     # after_transition_commit runs only once the transition has been
-    # committed: after the record is saved for normal transitions, and
-    # outside the transaction for transactional transitions (see below).
+    # committed to the database: after the OUTERMOST database transaction
+    # commits, or immediately after the transition when no transaction is
+    # open. It never runs if the transition or a surrounding transaction
+    # rolls back. (Requires Rails 7.2+; see Advanced Usage below.)
     after_transition_commit do
       MyJob.perform_later(object)
     end
@@ -232,6 +234,20 @@ module Workflow
 end
 ```
 
+#### `after_transition_commit` Semantics
+
+`after_transition_commit` callbacks run after the outermost database transaction commits. In detail:
+
+- If no transaction is open when `transition_to` is called, they run immediately after the transition commits.
+- If the transition happens inside an open transaction — an app-level `ActiveRecord::Base.transaction`, or a nested transition triggered from another state's `before_transition`/`after_transition` — they are deferred until that outermost transaction commits.
+- They never run if the transition fails, if `rollback_transition` is raised, or if a surrounding transaction rolls back after the transition. Multiple transitions inside one transaction each fire their callbacks after commit, in transition order.
+
+This makes `after_transition_commit` the safe place to enqueue background jobs, call external APIs, etc.: the work only happens once the new state is actually visible to other database connections.
+
+**Note on Rails versions:** deferral to an outer transaction requires Rails 7.2+. On older Rails versions the callbacks fire as soon as the transition itself completes, which may be inside an uncommitted outer transaction.
+
+**Footgun: `ActiveRecord.after_all_transactions_commit`** does not work as a substitute inside `before_transition`/`after_transition`. Rails skips non-joinable transactions when deciding whether any transaction is open, and transactional transitions run inside the gem's own non-joinable transaction — so the block yields *immediately*, while the transition is still uncommitted. Use `after_transition_commit` instead.
+
 #### Transient Transition Variables
 
 Sometimes you may may want to pass additional arguments to a state transition for additional context in your transition callbacks. To do this, add the `transients` option to the `state_options` declaration. This allows you to define any additional attributes you want to be able to pass along during a state transition to that state.

data/Rakefile

@@ -17,11 +17,11 @@ namespace :test do
 end
 
 task :test do
-  sh "bin/test"
+  sh "bin/rspec"
 end
 
 task :lint do
-  sh "bin/standardrb --no-fix"
+  sh "bin/rubocop --no-server"
 end
 
 namespace :changelog do

data/lib/has_state_machine/core_ext/string.rb

@@ -10,7 +10,9 @@ class String
   #
   # @example
   #   "some random string".transition_to("draft") #=> false
-  def transition_to(_desired_state)
+  # rubocop:disable Naming/PredicateMethod -- mirrors HasStateMachine::State#transition_to API
+  def transition_to(_desired_state, **_options)
     false
   end
+  # rubocop:enable Naming/PredicateMethod
 end

data/lib/has_state_machine/state.rb

@@ -16,8 +16,8 @@ module HasStateMachine
     define_model_callbacks :transition, only: %i[before after]
 
     ##
-    # Defines the after_transition_commit callback. It runs only after a
-    # transition has committed.
+    # Defines the after_transition_commit callback, which runs once a
+    # successful transition is committed to the database.
     define_model_callbacks :transition_commit, only: %i[after]
 
     ##
@@ -63,7 +63,7 @@ module HasStateMachine
     # @return [Boolean] whether or not the transition took place
     def transition_to(desired_state, **options)
       transitioned = false
-      options = options.transform_keys(&:to_sym)
+      options = options.symbolize_keys
       desired_state_instance = state_instance(desired_state, options)
 
       with_transition_options(options) do
@@ -78,45 +78,66 @@ module HasStateMachine
 
       transitioned
     ensure
-      (desired_state_instance&.errors || []).each do |error|
+      desired_state_instance&.errors&.each do |error|
         object.errors.add(error.attribute, error.type)
       end
     end
 
     ##
     # Makes the actual transition from one state to the next and
-    # runs the before and after transition callbacks. The
-    # after_transition_commit callbacks run after the update completes
-    # and only when it succeeds.
-    def perform_transition!
-      run_callbacks :transition_commit do
-        run_callbacks :transition do
-          object.update("#{object.state_attribute}": state)
-        end
+    # runs the before and after transition callbacks.
+    #
+    # @return [Boolean] whether or not the transition succeeded
+    def perform_transition! # rubocop:disable Naming/PredicateMethod -- public API
+      transitioned = run_callbacks :transition do
+        object.update("#{object.state_attribute}": state)
       end
+      return false unless transitioned
+
+      @previous_state = previous_state
+      enqueue_transition_commit_callbacks
+      true
     end
 
     ##
-    # Makes the actual transition from one state to the next and
-    # runs the before and after transition callbacks in a transaction
-    # to allow for roll backs. The after_transition_commit callbacks run
-    # outside the transaction and only when it commits (not on rollback).
-    def perform_transactional_transition!
-      run_callbacks :transition_commit do
-        ActiveRecord::Base.transaction(requires_new: true, joinable: false) do
-          run_callbacks :transition do
-            rollback_transition unless object.update("#{object.state_attribute}": state)
-          end
+    # Same as {#perform_transition!}, but wrapped in a transaction so
+    # callbacks can roll the transition back.
+    #
+    # @return [Boolean] whether or not the transition succeeded
+    def perform_transactional_transition! # rubocop:disable Naming/PredicateMethod -- public API
+      ActiveRecord::Base.transaction(requires_new: true, joinable: false) do
+        run_callbacks :transition do
+          rollback_transition unless object.update("#{object.state_attribute}": state)
         end
+      end
 
-        @previous_state = previous_state
+      @previous_state = previous_state
+      return false unless object.reload.public_send(object.state_attribute) == state
 
-        object.reload.public_send(object.state_attribute) == state
-      end
+      enqueue_transition_commit_callbacks
+      true
     end
 
     private
 
+    ##
+    # Runs the after_transition_commit callbacks once the outermost open
+    # transaction commits, discarding them on rollback.
+    #
+    # @note Registers on the connection's current transaction because
+    #   +ActiveRecord.after_all_transactions_commit+ ignores non-joinable
+    #   transactions (like the gem's own) and would fire immediately.
+    # @return [void]
+    def enqueue_transition_commit_callbacks
+      current_transaction = object.class.connection.current_transaction
+
+      # Rails < 7.2 has no Transaction#after_commit, so callbacks fire
+      # immediately with no deferral. Drop this guard at Rails 7.2+.
+      return run_callbacks(:transition_commit) { true } unless current_transaction.respond_to?(:after_commit)
+
+      current_transaction.after_commit { run_callbacks(:transition_commit) { true } }
+    end
+
     def rollback_transition
       raise ActiveRecord::Rollback
     end

data/lib/has_state_machine/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HasStateMachine
-  VERSION = "1.2.0"
+  VERSION = "1.2.2"
 end

data/lib/ruby_lsp/has_state_machine/addon.rb

@@ -12,12 +12,25 @@ module RubyLsp
     class Addon < ::RubyLsp::Addon
       def activate(global_state, outgoing_queue)
         @global_state = global_state
+        @model_name_cache = {}
         @rails_client = register_rails_server_addon(outgoing_queue)
+
+        rails_status = if @rails_client
+          "registered"
+        else
+          "unavailable, using naming convention only"
+        end
+
+        log(
+          outgoing_queue,
+          "Activating Has State Machine Ruby LSP add-on v#{version} (Rails integration: #{rails_status})"
+        )
       end
 
       def deactivate
         @global_state = nil
         @rails_client = nil
+        @model_name_cache = nil
       end
 
       def name
@@ -35,7 +48,8 @@ module RubyLsp
           node_context,
           dispatcher,
           index: @global_state&.index,
-          rails_client: @rails_client
+          rails_client: @rails_client,
+          model_name_cache: @model_name_cache
         )
       end
 
@@ -53,6 +67,7 @@ module RubyLsp
 
         client = rails_addon.rails_runner_client
         return unless client.respond_to?(:register_server_addon)
+        return if client.respond_to?(:connected?) && !client.connected?
 
         client.register_server_addon(File.expand_path("rails_server_addon.rb", __dir__))
         client

data/lib/ruby_lsp/has_state_machine/definition.rb

@@ -7,25 +7,37 @@ module RubyLsp
     class Definition
       SERVER_ADDON_NAME = "has_state_machine"
 
-      def initialize(response_builder, _uri, node_context, dispatcher, index: nil, rails_client: nil)
+      # AR methods that return self, so `object.reload.foo` targets the model
+      # just like `object.foo`.
+      SELF_RETURNING_METHODS = ["reload"].freeze
+
+      def initialize(response_builder, _uri, node_context, dispatcher, index: nil, rails_client: nil,
+        model_name_cache: nil)
         @response_builder = response_builder
         @node_context = node_context
         @index = index
         @rails_client = rails_client
+        @model_name_cache = model_name_cache
 
         dispatcher.register(self, :on_call_node_enter)
       end
 
       def on_call_node_enter(node)
         return unless current_target?(node)
-        return unless resolved_model_name
 
+        # Check the node shape first: resolving the model name may require a
+        # round-trip to the Rails runner, so only pay it for `object` calls.
         if object_call?(node)
+          return unless resolved_model_name
+
           push_entries(constant_entries(resolved_model_name))
         elsif object_method_call?(node)
+          return unless resolved_model_name
+
           method_name = message(node)
           entries = method_entries(resolved_model_name, method_name)
           entries = association_entries(resolved_model_name, method_name) if entries.empty?
+          entries = constant_entries(resolved_model_name) if entries.empty?
 
           push_entries(entries)
         end
@@ -33,7 +45,7 @@ module RubyLsp
 
       private
 
-      attr_reader :index, :node_context, :rails_client, :response_builder
+      attr_reader :index, :model_name_cache, :node_context, :rails_client, :response_builder
 
       def current_target?(node)
         target = node_context.node if node_context.respond_to?(:node)
@@ -77,8 +89,20 @@ module RubyLsp
       end
 
       def model_name_from_rails(workflow_namespace)
-        return unless workflow_namespace && rails_client
+        return unless workflow_namespace && rails_client_available?
+
+        # Cache hits and misses for the life of the LSP process; the set of
+        # models rarely changes mid-session. Failures raise past the cache
+        # write, so a slow-to-boot Rails runner can succeed on a later request.
+        cache = model_name_cache.to_h
+        cache.fetch(workflow_namespace) do
+          cache[workflow_namespace] = request_model_name(workflow_namespace)
+        end
+      rescue
+        nil
+      end
 
+      def request_model_name(workflow_namespace)
         result = rails_client.delegate_request(
           server_addon_name: SERVER_ADDON_NAME,
           request_name: "model_for_workflow_namespace",
@@ -86,8 +110,6 @@ module RubyLsp
         )
 
         response_name(result)
-      rescue
-        nil
       end
 
       def association_entries(model_name, association_name)
@@ -97,8 +119,17 @@ module RubyLsp
         constant_entries(association_model_name)
       end
 
+      # Delegating a request to a disconnected client (ruby-lsp-rails NullClient)
+      # never produces a response, so read_response would block forever and the
+      # convention fallback would never run.
+      def rails_client_available?
+        return false unless rails_client
+
+        !rails_client.respond_to?(:connected?) || rails_client.connected?
+      end
+
       def association_model_name(model_name, association_name)
-        return unless rails_client&.respond_to?(:association_target)
+        return unless rails_client_available? && rails_client.respond_to?(:association_target)
 
         result = rails_client.association_target(model_name: model_name, association_name: association_name)
         response_name(result)
@@ -154,6 +185,7 @@ module RubyLsp
 
       def entry_location(entry)
         return entry.location if entry.respond_to?(:location)
+
         entry.name_location if entry.respond_to?(:name_location)
       end
 
@@ -171,7 +203,14 @@ module RubyLsp
       end
 
       def object_method_call?(node)
-        message(node) && object_call?(receiver(node))
+        message(node) && object_chain?(receiver(node))
+      end
+
+      def object_chain?(node)
+        return false unless node
+        return true if object_call?(node)
+
+        SELF_RETURNING_METHODS.include?(message(node)) && object_chain?(receiver(node))
       end
 
       def object_call?(node)

data/lib/ruby_lsp/has_state_machine/rails_server_addon.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "ruby_lsp/ruby_lsp_rails/server"
+require "ruby_lsp/ruby_lsp_rails/server" unless defined?(::RubyLsp::Rails::ServerAddon)
 
 module RubyLsp
   module HasStateMachine
@@ -13,7 +13,7 @@ module RubyLsp
         with_request_error_handling(request) do
           case request
           when "model_for_workflow_namespace"
-            send_result(model_for_workflow_namespace(params.fetch("workflow_namespace")))
+            send_result(model_for_workflow_namespace(params[:workflow_namespace] || params.fetch("workflow_namespace")))
           else
             raise NotImplementedError, "Unknown request: #{request}"
           end
@@ -23,12 +23,24 @@ module RubyLsp
       private
 
       def model_for_workflow_namespace(workflow_namespace)
-        model = models_by_workflow_namespace[workflow_namespace]
+        model = conventional_model_for(workflow_namespace) || models_by_workflow_namespace[workflow_namespace]
         return unless model
 
         {name: model.name}
       end
 
+      ##
+      # Fast path: for the default "Workflow::<Model>" namespace, autoload just
+      # that one constant instead of eager loading the whole application. Only
+      # custom workflow_namespace configurations need the full scan below.
+      def conventional_model_for(workflow_namespace)
+        workflow_namespace = workflow_namespace.to_s
+        return unless workflow_namespace.start_with?("Workflow::")
+
+        model = workflow_namespace.delete_prefix("Workflow::").safe_constantize
+        model if model.try(:workflow_namespace) == workflow_namespace
+      end
+
       def models_by_workflow_namespace
         @models_by_workflow_namespace ||= active_record_models.each_with_object({}) do |model, index|
           next unless model.respond_to?(:workflow_namespace)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: has_state_machine
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.2
 platform: ruby
 authors:
 - Benjamin Hargett
@@ -31,9 +31,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.5'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -41,9 +38,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.5'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
@@ -87,7 +81,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: standard
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.74'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.74'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -129,19 +137,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '5.1'
+        version: '6.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '5.1'
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: ruby-lsp
   requirement: !ruby/object:Gem::Requirement
@@ -170,6 +178,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.3.17
+- !ruby/object:Gem::Dependency
+  name: ruby-lsp-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: base64
   requirement: !ruby/object:Gem::Requirement
@@ -268,7 +290,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Class based state machine for ActiveRecord models.
 test_files: []