stepper_motor 0.1.12 → 0.1.16

data/sig/stepper_motor.rbs

@@ -30,14 +30,24 @@ module StepperMotor
     # 
     # _@param_ `wait` — the amount of time to wait before entering the step
     # 
-    # _@param_ `on_exception` — the action to take if an exception occurs when performing the step. The possible values are: * `:cancel!` - cancels the Journey and re-raises the exception. The Journey will be persisted before re-raising. * `:reattempt!` - reattempts the Journey and re-raises the exception. The Journey will be persisted before re-raising.
+    # _@param_ `on_exception` — the action to take if an exception occurs when performing the step. The possible values are: * `:cancel!` - cancels the Journey and re-raises the exception. The Journey will be persisted before re-raising. * `:reattempt!` - reattempts the Journey and re-raises the exception. The Journey will be persisted before re-raising. * `:pause!` - pauses the Journey and re-raises the exception. The Journey will be persisted before re-raising. * `:skip!` - skips the current step and proceeds to the next step, or finishes the journey if it's the last step.
+    # 
+    # _@param_ `skip_if` — condition to check before performing the step. If a boolean is provided, it will be used directly. If nil is provided, it will be treated as false. If a symbol is provided, it will call the method on the Journey. If a block is provided, it will be executed with the Journey as context. The step will only be performed if the condition returns a truthy value.
     def initialize: (
                       name: (String | Symbol),
                       seq: untyped,
-                      on_exception: Symbol,
-                      ?wait: (Numeric | ActiveSupport::Duration)
+                      ?on_exception: Symbol,
+                      ?wait: (Numeric | ActiveSupport::Duration),
+                      ?skip_if: (TrueClass | FalseClass | NilClass | Symbol | Proc)
                     ) -> void
 
+    # Checks if the step should be skipped based on the skip_if condition
+    # 
+    # _@param_ `journey` — the journey to check the condition for
+    # 
+    # _@return_ — true if the step should be skipped, false otherwise
+    def should_skip?: (StepperMotor::Journey journey) -> bool
+
     # Performs the step on the passed Journey, wrapping the step with the required context.
     # 
     # _@param_ `journey` — the journey to perform the step in. If a `step_block` is passed in, it is going to be executed in the context of the journey using `instance_exec`. If only the name of the step has been provided, an accordingly named public method on the journey will be called
@@ -117,6 +127,10 @@ module StepperMotor
     # 
     # _@param_ `on_exception` — See {StepperMotor::Step#on_exception}
     # 
+    # _@param_ `skip_if` — condition to check before performing the step. If a symbol is provided, it will call the method on the Journey. If a block is provided, it will be executed with the Journey as context. The step will be skipped if the condition returns a truthy value.
+    # 
+    # _@param_ `if` — condition to check before performing the step. If a symbol is provided, it will call the method on the Journey. If a block is provided, it will be executed with the Journey as context. The step will be performed if the condition returns a truthy value. and skipped otherwise. Inverse of `skip_if`.
+    # 
     # _@param_ `additional_step_definition_options` — Any remaining options get passed to `StepperMotor::Step.new` as keyword arguments.
     # 
     # _@return_ — the step definition that has been created
@@ -124,8 +138,7 @@ module StepperMotor
                      ?String? name,
                      ?wait: (Float | untyped | ActiveSupport::Duration)?,
                      ?after: (Float | untyped | ActiveSupport::Duration)?,
-                     ?on_exception: Symbol,
-                     **untyped additional_step_definition_options
+                     **::Hash[untyped, untyped] additional_step_definition_options
                    ) -> StepperMotor::Step
 
     # sord warn - "StepperMotor::Step?" does not appear to be a type
@@ -205,6 +218,19 @@ module StepperMotor
     # _@return_ — void
     def reattempt!: (?wait: untyped) -> untyped
 
+    # Is used to skip the current step and proceed to the next step in the journey. This is useful when you want to
+    # conditionally skip a step based on some business logic without canceling the entire journey. For example,
+    # you might want to skip a reminder email step if the user has already taken the required action.
+    # 
+    # If there are more steps after the current step, `skip!` will schedule the next step to be performed.
+    # If the current step is the last step in the journey, `skip!` will finish the journey.
+    # 
+    # `skip!` may be called within a step or outside of a step for journeys in the `ready` state.
+    # When called outside of a step, it will skip the next scheduled step and proceed to the following step.
+    # 
+    # _@return_ — void
+    def skip!: () -> untyped
+
     # Is used to pause a Journey at any point. The "paused" state is similar to the "ready" state, except that "perform_next_step!" on the
     # journey will do nothing - even if it is scheduled to be performed. Pausing a Journey can be useful in the following situations:
     # 
@@ -251,6 +277,19 @@ module StepperMotor
       # _@return_ — void
       def reattempt!: (?wait: untyped) -> untyped
 
+      # Is used to skip the current step and proceed to the next step in the journey. This is useful when you want to
+      # conditionally skip a step based on some business logic without canceling the entire journey. For example,
+      # you might want to skip a reminder email step if the user has already taken the required action.
+      # 
+      # If there are more steps after the current step, `skip!` will schedule the next step to be performed.
+      # If the current step is the last step in the journey, `skip!` will finish the journey.
+      # 
+      # `skip!` may be called within a step or outside of a step for journeys in the `ready` state.
+      # When called outside of a step, it will skip the next scheduled step and proceed to the following step.
+      # 
+      # _@return_ — void
+      def skip!: () -> untyped
+
       # Is used to pause a Journey at any point. The "paused" state is similar to the "ready" state, except that "perform_next_step!" on the
       # journey will do nothing - even if it is scheduled to be performed. Pausing a Journey can be useful in the following situations:
       # 

data/stepper_motor.gemspec

@@ -37,6 +37,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "minitest"
   spec.add_development_dependency "rails", "~> 7.0"
   spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "mysql2"
+  spec.add_development_dependency "pg"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "standard", "~> 1.50.0", "< 2.0"
   spec.add_development_dependency "magic_frozen_string_literal"

data/test/dummy/config/database.mysql2.yml

@@ -0,0 +1,14 @@
+default: &default
+  adapter: mysql2
+  database: stepper_motor_dummy_<%= Rails.env %>
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+  username: root
+  password: constabulary
+  timeout: 5000
+
+development:
+  <<: *default
+test:
+  <<: *default
+production:
+  <<: *default

data/test/dummy/config/database.postgres.yml

@@ -0,0 +1,14 @@
+default: &default
+  adapter: postgres
+  database: stepper_motor_dummy_<%= Rails.env %>
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+  username: root
+  password: constabulary
+  timeout: 5000
+
+development:
+  <<: *default
+test:
+  <<: *default
+production:
+  <<: *default

data/test/dummy/config/database.sqlite3.yml

@@ -0,0 +1,32 @@
+# SQLite. Versions 3.8.0 and up are supported.
+#   gem install sqlite3
+#
+#   Ensure the SQLite 3 gem is defined in your Gemfile
+#   gem "sqlite3"
+#
+default: &default
+  adapter: sqlite3
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+  timeout: 5000
+
+development:
+  <<: *default
+  database: storage/development.sqlite3
+
+# Warning: The database defined as "test" will be erased and
+# re-generated from your development database when you run "rake".
+# Do not set this db to the same as development or production.
+test:
+  <<: *default
+  database: storage/test.sqlite3
+
+
+# SQLite3 write its data on the local filesystem, as such it requires
+# persistent disks. If you are deploying to a managed service, you should
+# make sure it provides disk persistence, as many don't.
+#
+# Similarly, if you deploy your application as a Docker container, you must
+# ensure the database is located in a persisted volume.
+production:
+  <<: *default
+  # database: path/to/persistent/storage/production.sqlite3

data/test/dummy/config/initializers/stepper_motor.rb

@@ -9,7 +9,7 @@
 #
 # and add its cycle job into your recurring jobs table. For example, for solid_queue:
 #
-#   stepper_motor_houseleeping:
+#   run_stepper_motor_scheduling_cycle:
 #     schedule: "*/30 * * * *" # Every 30 minutes
 #     class: "StepperMotor::CyclicScheduler::RunSchedulingCycleJob"
 #

data/test/dummy/db/migrate/20250609221201_stepper_motor_migration_005.rb

@@ -0,0 +1,58 @@
+class StepperMotorMigration005 < ActiveRecord::Migration[7.2]
+  def up
+    unless mysql?
+      say "Skipping migration as it is only used with MySQL (mysql2 or trilogy)"
+      return
+    end
+
+    # Add generated column that combines the state, type, hero_id, and hero_type
+    # The column will be NULL if any of the components is NULL
+    execute <<-SQL
+      ALTER TABLE stepper_motor_journeys
+      ADD COLUMN journey_uniq_col_generated VARCHAR(255) GENERATED ALWAYS AS (
+        CASE 
+          WHEN state IN ('ready', 'performing', 'paused') 
+          AND allow_multiple = 0 
+          AND type IS NOT NULL 
+          AND hero_id IS NOT NULL 
+          AND hero_type IS NOT NULL
+          THEN CONCAT(type, ':', hero_id, ':', hero_type)
+          ELSE NULL
+        END
+      ) STORED
+    SQL
+
+    # Add unique index on the generated column with MySQL-specific name
+    add_index :stepper_motor_journeys, :journey_uniq_col_generated, 
+              unique: true, 
+              name: :idx_journeys_one_per_hero_mysql_generated
+
+    # Remove old indexes that include 'ready', 'performing', and 'paused' states
+    remove_index :stepper_motor_journeys, name: :idx_journeys_one_per_hero_with_paused
+  end
+
+  def down
+    unless mysql?
+      say "Skipping migration as it is only used with MySQL (mysql2 or trilogy)"
+      return
+    end
+
+    # Remove the generated column and its index
+    remove_index :stepper_motor_journeys, name: :idx_journeys_one_per_hero_mysql_generated
+    remove_column :stepper_motor_journeys, :journey_uniq_col_generated
+
+    # Recreate old indexes
+    quoted_false = connection.quote(false)
+    add_index :stepper_motor_journeys, [:type, :hero_id, :hero_type], 
+              where: "allow_multiple = '#{quoted_false}' AND state IN ('ready', 'performing', 'paused')", 
+              unique: true, 
+              name: :idx_journeys_one_per_hero_with_paused
+  end
+
+  private
+
+  def mysql?
+    adapter = connection.adapter_name.downcase
+    adapter == "mysql2" || adapter == "trilogy"
+  end
+end

data/test/dummy/db/schema.rb

@@ -10,8 +10,8 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[7.2].define(version: 2025_05_28_141038) do
-  create_table "stepper_motor_journeys", force: :cascade do |t|
+ActiveRecord::Schema[7.2].define(version: 2025_06_09_221201) do
+  create_table "stepper_motor_journeys", charset: "utf8mb4", collation: "utf8mb4_uca1400_ai_ci", force: :cascade do |t|
     t.string "type", null: false
     t.string "state", default: "ready"
     t.string "hero_type"
@@ -25,12 +25,13 @@ ActiveRecord::Schema[7.2].define(version: 2025_05_28_141038) do
     t.datetime "created_at", null: false
     t.datetime "updated_at", null: false
     t.string "idempotency_key"
+    t.virtual "journey_uniq_col_generated", type: :string, as: "case when `state` in ('ready','performing','paused') and `allow_multiple` = 0 and `type` is not null and `hero_id` is not null and `hero_type` is not null then concat(`type`,':',`hero_id`,':',`hero_type`) else NULL end", stored: true
     t.index ["hero_type", "hero_id"], name: "index_stepper_motor_journeys_on_hero_type_and_hero_id"
-    t.index ["next_step_to_be_performed_at"], name: "index_stepper_motor_journeys_on_next_step_to_be_performed_at", where: "state = 'ready' /*application='Dummy'*/"
-    t.index ["type", "hero_id", "hero_type"], name: "idx_journeys_one_per_hero_with_paused", unique: true, where: "allow_multiple = '0' AND state IN ('ready', 'performing', 'paused') /*application='Dummy'*/"
+    t.index ["journey_uniq_col_generated"], name: "idx_journeys_one_per_hero_mysql_generated", unique: true
+    t.index ["next_step_to_be_performed_at"], name: "index_stepper_motor_journeys_on_next_step_to_be_performed_at"
     t.index ["type", "hero_type", "hero_id"], name: "index_stepper_motor_journeys_on_type_and_hero_type_and_hero_id"
     t.index ["type"], name: "index_stepper_motor_journeys_on_type"
-    t.index ["updated_at"], name: "index_stepper_motor_journeys_on_updated_at", where: "state = 'canceled' OR state = 'finished' /*application='Dummy'*/"
-    t.index ["updated_at"], name: "stuck_journeys_index", where: "state = 'performing' /*application='Dummy'*/"
+    t.index ["updated_at"], name: "index_stepper_motor_journeys_on_updated_at"
+    t.index ["updated_at"], name: "stuck_journeys_index"
   end
 end

data/test/stepper_motor/journey/exception_handling_test.rb

@@ -3,6 +3,8 @@
 require "test_helper"
 
 class ExceptionHandlingTest < ActiveSupport::TestCase
+  include SideEffects::TestHelper
+
   # See below.
   self.use_transactional_tests = false
 
@@ -46,6 +48,61 @@ class ExceptionHandlingTest < ActiveSupport::TestCase
     assert faulty_journey.canceled?
   end
 
+  test "with :skip!, skips the failing step and continues to next step" do
+    faulty_journey_class = create_journey_subclass do
+      step on_exception: :skip! do
+        raise CustomEx, "Something went wrong"
+      end
+
+      step do
+        SideEffects.touch! "second step"
+      end
+    end
+
+    faulty_journey = faulty_journey_class.create!
+    assert faulty_journey.ready?
+
+    assert_raises(CustomEx) { faulty_journey.perform_next_step! }
+
+    assert faulty_journey.persisted?
+    refute faulty_journey.changed?
+    assert faulty_journey.ready?
+
+    # The second step should now be scheduled
+    assert_produced_side_effects("second step") do
+      faulty_journey.perform_next_step!
+    end
+    assert faulty_journey.finished?
+  end
+
+  test "with :skip! on last step, skips the failing step and finishes the journey" do
+    faulty_journey_class = create_journey_subclass do
+      step do
+        SideEffects.touch! "first step"
+      end
+
+      step on_exception: :skip! do
+        raise CustomEx, "Something went wrong"
+      end
+    end
+
+    faulty_journey = faulty_journey_class.create!
+    assert faulty_journey.ready?
+
+    # Perform first step
+    assert_produced_side_effects("first step") do
+      faulty_journey.perform_next_step!
+    end
+    assert faulty_journey.ready?
+
+    # The second step should be skipped due to exception
+    assert_raises(CustomEx) { faulty_journey.perform_next_step! }
+
+    assert faulty_journey.persisted?
+    refute faulty_journey.changed?
+    assert faulty_journey.finished?
+  end
+
   test "pauses the journey by default at the failig step" do
     faulty_journey_class = create_journey_subclass do
       step do

data/test/stepper_motor/journey/flow_control_test.rb

@@ -75,4 +75,168 @@ class FlowControlTest < ActiveSupport::TestCase
 
     assert_no_side_effects { journey.perform_next_step! }
   end
+
+  test "can skip a step and continue to next step" do
+    skipping_journey = create_journey_subclass do
+      step do
+        SideEffects.touch! "before skipping"
+        skip!
+        SideEffects.touch! "after skipping"
+      end
+
+      step do
+        SideEffects.touch! "second step"
+      end
+    end
+
+    journey = skipping_journey.create!
+    assert journey.ready?
+
+    # First step should be skipped
+    assert_produced_side_effects("before skipping") do
+      assert_did_not_produce_side_effects("after skipping") do
+        journey.perform_next_step!
+      end
+    end
+    assert journey.ready?
+
+    # Second step should be performed
+    assert_produced_side_effects("second step") do
+      journey.perform_next_step!
+    end
+    assert journey.finished?
+  end
+
+  test "can skip the last step and finish the journey" do
+    skipping_journey = create_journey_subclass do
+      step do
+        SideEffects.touch! "first step"
+      end
+
+      step do
+        SideEffects.touch! "before skipping last"
+        skip!
+        SideEffects.touch! "after skipping last"
+      end
+    end
+
+    journey = skipping_journey.create!
+    assert journey.ready?
+
+    # First step should be performed normally
+    assert_produced_side_effects("first step") do
+      journey.perform_next_step!
+    end
+    assert journey.ready?
+
+    # Last step should be skipped and journey should finish
+    assert_produced_side_effects("before skipping last") do
+      assert_did_not_produce_side_effects("after skipping last") do
+        journey.perform_next_step!
+      end
+    end
+    assert journey.finished?
+  end
+
+  test "skip! can be called outside of a step for ready journeys" do
+    skipping_journey = create_journey_subclass do
+      step do
+        SideEffects.touch! "first step"
+      end
+
+      step do
+        SideEffects.touch! "second step"
+      end
+    end
+
+    journey = skipping_journey.create!
+    assert journey.ready?
+
+    # Skip the first step from outside
+    journey.skip!
+    assert journey.ready?
+
+    # The second step should now be scheduled
+    assert_produced_side_effects("second step") do
+      journey.perform_next_step!
+    end
+    assert journey.finished?
+  end
+
+  test "skip! outside of step raises error for non-ready journeys" do
+    skipping_journey = create_journey_subclass do
+      step do
+        SideEffects.touch! "step completed"
+      end
+    end
+
+    journey = skipping_journey.create!
+    journey.pause!
+    assert journey.paused?
+
+    assert_raises(RuntimeError, "skip! can only be used on journeys in the `ready` state") do
+      journey.skip!
+    end
+  end
+
+  test "skip! outside of step can finish journey when skipping last step" do
+    skipping_journey = create_journey_subclass do
+      step do
+        SideEffects.touch! "first step"
+      end
+
+      step do
+        SideEffects.touch! "last step"
+      end
+    end
+
+    journey = skipping_journey.create!
+    assert journey.ready?
+
+    # Perform first step
+    assert_produced_side_effects("first step") do
+      journey.perform_next_step!
+    end
+    assert journey.ready?
+
+    # Skip the last step from outside
+    journey.skip!
+    assert journey.finished?
+  end
+
+  test "skip! outside of step handles missing step definitions gracefully" do
+    skipping_journey = create_journey_subclass do
+      step do
+        SideEffects.touch! "step completed"
+      end
+    end
+
+    journey = skipping_journey.create!
+    assert journey.ready?
+
+    # Manually set a non-existent next step
+    journey.update!(next_step_name: "non_existent_step")
+
+    # Skip should handle this gracefully and finish the journey
+    journey.skip!
+    assert journey.finished?
+  end
+
+  test "skip! aborts the current step execution" do
+    skipping_journey = create_journey_subclass do
+      step do
+        SideEffects.touch! "before skip"
+        skip!
+        SideEffects.touch! "after skip"
+      end
+    end
+
+    journey = skipping_journey.create!
+
+    assert_produced_side_effects("before skip") do
+      assert_did_not_produce_side_effects("after skip") do
+        journey.perform_next_step!
+      end
+    end
+  end
 end