stepper_motor 0.1.17 → 0.1.19

data/rbi/stepper_motor.rbi

@@ -2,7 +2,7 @@
 # StepperMotor is a module for building multi-step flows where steps are sequential and only
 # ever progress forward. The building block of StepperMotor is StepperMotor::Journey
 module StepperMotor
-  VERSION = T.let("0.1.17", T.untyped)
+  VERSION = T.let("0.1.19", T.untyped)
   PerformStepJobV2 = T.let(StepperMotor::PerformStepJob, T.untyped)
   RecoverStuckJourneysJobV1 = T.let(StepperMotor::RecoverStuckJourneysJob, T.untyped)
 
@@ -24,7 +24,6 @@ module StepperMotor
   # array of the Journey subclass. When the step gets performed, the block passed to the
   # constructor will be instance_exec'd with the Journey model being the context
   class Step
-    # sord omit - no YARD type given for "seq:", using untyped
     # sord warn - ActiveSupport::Duration wasn't able to be resolved to a constant in this project
     # Creates a new step definition
     # 
@@ -38,14 +37,13 @@ module StepperMotor
     sig do
       params(
         name: T.any(String, Symbol),
-        seq: T.untyped,
         on_exception: Symbol,
         wait: T.any(Numeric, ActiveSupport::Duration),
         skip_if: T.any(TrueClass, FalseClass, NilClass, Symbol, Proc),
         step_block: T.untyped
       ).void
     end
-    def initialize(name:, seq:, on_exception: :pause!, wait: 0, skip_if: false, &step_block); end
+    def initialize(name:, on_exception: :pause!, wait: 0, skip_if: false, &step_block); end
 
     # Checks if the step should be skipped based on the skip_if condition
     # 
@@ -72,10 +70,6 @@ module StepperMotor
     sig { returns(T.any(Numeric, ActiveSupport::Duration)) }
     attr_reader :wait
 
-    # sord omit - no YARD type given for :seq, using untyped
-    sig { returns(T.untyped) }
-    attr_reader :seq
-
     class MissingDefinition < NoMethodError
     end
   end
@@ -124,6 +118,10 @@ module StepperMotor
     sig { returns(T.untyped) }
     def step_definitions; end
 
+    # _@return_ — the cancel_if conditions defined for this journey class
+    sig { returns(T::Array[StepperMotor::Conditional]) }
+    def cancel_if_conditions; end
+
     # sord duck - #to_f looks like a duck type, replacing with untyped
     # sord warn - ActiveSupport::Duration wasn't able to be resolved to a constant in this project
     # sord duck - #to_f looks like a duck type, replacing with untyped
@@ -135,7 +133,11 @@ module StepperMotor
     # 
     # _@param_ `wait` — the amount of time this step should wait before getting performed. When the journey gets scheduled, the triggering job is going to be delayed by this amount of time, and the `next_step_to_be_performed_at` attribute will be set to the current time plus the wait duration. Mutually exclusive with `after:`
     # 
-    # _@param_ `after` — the amount of time this step should wait before getting performed including all the previous waits. This allows you to set the wait time based on the time after the journey started, as opposed to when the previous step has completed. When the journey gets scheduled, the triggering job is going to be delayed by this amount of time _minus the `wait` values of the preceding steps, and the `next_step_to_be_performed_at` attribute will be set to the current time. The `after` value gets converted into the `wait` value and passed to the step definition. Mutually exclusive with `wait:`
+    # _@param_ `after` — the amount of time this step should wait before getting performed including all the previous waits. This allows you to set the wait time based on the time after the journey started, as opposed to when the previous step has completed. When the journey gets scheduled, the triggering job is going to be delayed by this amount of time _minus the `wait` values of the preceding steps, and the `next_step_to_be_performed_at` attribute will be set to the current time. The `after` value gets converted into the `wait` value and passed to the step definition. Mutually exclusive with `wait:`.
+    # 
+    # _@param_ `before_step` — the name of the step before which this step should be inserted. This allows you to control the order of steps by inserting a step before a specific existing step. The step name can be provided as a string or symbol. Mutually exclusive with `after_step:`.
+    # 
+    # _@param_ `after_step` — the name of the step after which this step should be inserted. This allows you to control the order of steps by inserting a step after a specific existing step. The step name can be provided as a string or symbol. Mutually exclusive with `before_step:`.
     # 
     # _@param_ `on_exception` — See {StepperMotor::Step#on_exception}
     # 
@@ -151,11 +153,13 @@ module StepperMotor
         name: T.nilable(String),
         wait: T.nilable(T.any(Float, T.untyped, ActiveSupport::Duration)),
         after: T.nilable(T.any(Float, T.untyped, ActiveSupport::Duration)),
+        before_step: T.nilable(T.any(String, Symbol)),
+        after_step: T.nilable(T.any(String, Symbol)),
         additional_step_definition_options: T::Hash[T.untyped, T.untyped],
         blk: T.untyped
       ).returns(StepperMotor::Step)
     end
-    def self.step(name = nil, wait: nil, after: nil, **additional_step_definition_options, &blk); end
+    def self.step(name = nil, wait: nil, after: nil, before_step: nil, after_step: nil, **additional_step_definition_options, &blk); end
 
     # sord warn - "StepperMotor::Step?" does not appear to be a type
     # Returns the `Step` object for a named step. This is used when performing a step, but can also
@@ -165,6 +169,14 @@ module StepperMotor
     sig { params(by_step_name: T.any(Symbol, String)).returns(SORD_ERROR_StepperMotorStep) }
     def self.lookup_step_definition(by_step_name); end
 
+    # Returns all step definitions that follow the given step in the journey
+    # 
+    # _@param_ `step_definition` — the step to find the following steps for
+    # 
+    # _@return_ — the following steps, or empty array if this is the last step
+    sig { params(step_definition: StepperMotor::Step).returns(T::Array[StepperMotor::Step]) }
+    def self.step_definitions_following(step_definition); end
+
     # sord omit - no YARD type given for "by_step_name", using untyped
     # sord omit - no YARD return type given, using untyped
     # Alias for the class method, for brevity
@@ -173,6 +185,18 @@ module StepperMotor
     sig { params(by_step_name: T.untyped).returns(T.untyped) }
     def lookup_step_definition(by_step_name); end
 
+    # Defines a condition that will cause the journey to cancel if satisfied.
+    # This works like Rails' `etag` - it's class-inheritable and appendable.
+    # Multiple `cancel_if` calls can be made to a Journey definition.
+    # All conditions are evaluated after setting the state to `performing`.
+    # If any condition is satisfied, the journey will cancel.
+    # 
+    # _@param_ `condition_arg` — the condition to check
+    # 
+    # _@param_ `condition_blk` — a block that will be evaluated as a condition
+    sig { params(condition_arg: T.any(TrueClass, FalseClass, Symbol, Proc, T::Array[T.untyped], Conditional), condition_blk: T.untyped).void }
+    def self.cancel_if(condition_arg = :__no_argument_given__, &condition_blk); end
+
     # Performs the next step in the journey. Will check whether any other process has performed the step already
     # and whether the record is unchanged, and will then lock it and set the state to 'performimg'.
     # 
@@ -359,6 +383,25 @@ module StepperMotor
   class BaseJob < ActiveJob::Base
   end
 
+  # A wrapper for conditional logic that can be evaluated against an object.
+  # This class encapsulates different types of conditions (booleans, symbols, callables, arrays)
+  # and provides a unified interface for checking if a condition is satisfied by a given object.
+  # It handles negation and ensures proper context when evaluating conditions.
+  class Conditional
+    # sord omit - no YARD type given for "condition", using untyped
+    # sord omit - no YARD type given for "negate:", using untyped
+    sig { params(condition: T.untyped, negate: T.untyped).void }
+    def initialize(condition, negate: false); end
+
+    # sord omit - no YARD type given for "object", using untyped
+    sig { params(object: T.untyped).returns(T::Boolean) }
+    def satisfied_by?(object); end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def validate_condition; end
+  end
+
   module TestHelper
     # Allows running a given Journey to completion, skipping across the waiting periods.
     # This is useful to evaluate all side effects of a Journey. The helper will ensure
@@ -368,9 +411,13 @@ module StepperMotor
     # 
     # _@param_ `journey` — the journey to speedrun
     # 
+    # _@param_ `time_travel` — whether to use ActiveSupport time travel (default: true) Note: When time_travel is true, this method will permanently travel time forward and will not reset it back to the original time when the method exits.
+    # 
+    # _@param_ `maximum_steps` — how many steps can we take until we assume the journey has hung and fail the test. Default value is :reasonable, which is 10x the number of steps. :unlimited allows "a ton", but can make your test hang if your logic lets a step reattempt indefinitely
+    # 
     # _@return_ — void
-    sig { params(journey: StepperMotor::Journey).returns(T.untyped) }
-    def speedrun_journey(journey); end
+    sig { params(journey: StepperMotor::Journey, time_travel: T::Boolean, maximum_steps: T.any(Symbol, Integer)).returns(T.untyped) }
+    def speedrun_journey(journey, time_travel: true, maximum_steps: :reasonable); end
 
     # Performs the named step of the journey without waiting for the time to perform the step.
     # 

data/sig/stepper_motor.rbs

@@ -22,7 +22,6 @@ module StepperMotor
   # array of the Journey subclass. When the step gets performed, the block passed to the
   # constructor will be instance_exec'd with the Journey model being the context
   class Step
-    # sord omit - no YARD type given for "seq:", using untyped
     # sord warn - ActiveSupport::Duration wasn't able to be resolved to a constant in this project
     # Creates a new step definition
     # 
@@ -35,7 +34,6 @@ module StepperMotor
     # _@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),
                       ?skip_if: (TrueClass | FalseClass | NilClass | Symbol | Proc)
@@ -62,9 +60,6 @@ module StepperMotor
     # _@return_ — how long to wait before performing the step
     attr_reader wait: (Numeric | ActiveSupport::Duration)
 
-    # sord omit - no YARD type given for :seq, using untyped
-    attr_reader seq: untyped
-
     class MissingDefinition < NoMethodError
     end
   end
@@ -112,6 +107,9 @@ module StepperMotor
     # _@see_ `Journey.step_definitions`
     def step_definitions: () -> untyped
 
+    # _@return_ — the cancel_if conditions defined for this journey class
+    def cancel_if_conditions: () -> ::Array[StepperMotor::Conditional]
+
     # sord duck - #to_f looks like a duck type, replacing with untyped
     # sord warn - ActiveSupport::Duration wasn't able to be resolved to a constant in this project
     # sord duck - #to_f looks like a duck type, replacing with untyped
@@ -123,7 +121,11 @@ module StepperMotor
     # 
     # _@param_ `wait` — the amount of time this step should wait before getting performed. When the journey gets scheduled, the triggering job is going to be delayed by this amount of time, and the `next_step_to_be_performed_at` attribute will be set to the current time plus the wait duration. Mutually exclusive with `after:`
     # 
-    # _@param_ `after` — the amount of time this step should wait before getting performed including all the previous waits. This allows you to set the wait time based on the time after the journey started, as opposed to when the previous step has completed. When the journey gets scheduled, the triggering job is going to be delayed by this amount of time _minus the `wait` values of the preceding steps, and the `next_step_to_be_performed_at` attribute will be set to the current time. The `after` value gets converted into the `wait` value and passed to the step definition. Mutually exclusive with `wait:`
+    # _@param_ `after` — the amount of time this step should wait before getting performed including all the previous waits. This allows you to set the wait time based on the time after the journey started, as opposed to when the previous step has completed. When the journey gets scheduled, the triggering job is going to be delayed by this amount of time _minus the `wait` values of the preceding steps, and the `next_step_to_be_performed_at` attribute will be set to the current time. The `after` value gets converted into the `wait` value and passed to the step definition. Mutually exclusive with `wait:`.
+    # 
+    # _@param_ `before_step` — the name of the step before which this step should be inserted. This allows you to control the order of steps by inserting a step before a specific existing step. The step name can be provided as a string or symbol. Mutually exclusive with `after_step:`.
+    # 
+    # _@param_ `after_step` — the name of the step after which this step should be inserted. This allows you to control the order of steps by inserting a step after a specific existing step. The step name can be provided as a string or symbol. Mutually exclusive with `before_step:`.
     # 
     # _@param_ `on_exception` — See {StepperMotor::Step#on_exception}
     # 
@@ -138,6 +140,8 @@ module StepperMotor
                      ?String? name,
                      ?wait: (Float | untyped | ActiveSupport::Duration)?,
                      ?after: (Float | untyped | ActiveSupport::Duration)?,
+                     ?before_step: (String | Symbol)?,
+                     ?after_step: (String | Symbol)?,
                      **::Hash[untyped, untyped] additional_step_definition_options
                    ) -> StepperMotor::Step
 
@@ -148,6 +152,13 @@ module StepperMotor
     # _@param_ `by_step_name` — the name of the step to find
     def self.lookup_step_definition: ((Symbol | String) by_step_name) -> SORD_ERROR_StepperMotorStep
 
+    # Returns all step definitions that follow the given step in the journey
+    # 
+    # _@param_ `step_definition` — the step to find the following steps for
+    # 
+    # _@return_ — the following steps, or empty array if this is the last step
+    def self.step_definitions_following: (StepperMotor::Step step_definition) -> ::Array[StepperMotor::Step]
+
     # sord omit - no YARD type given for "by_step_name", using untyped
     # sord omit - no YARD return type given, using untyped
     # Alias for the class method, for brevity
@@ -155,6 +166,17 @@ module StepperMotor
     # _@see_ `Journey.lookup_step_definition`
     def lookup_step_definition: (untyped by_step_name) -> untyped
 
+    # Defines a condition that will cause the journey to cancel if satisfied.
+    # This works like Rails' `etag` - it's class-inheritable and appendable.
+    # Multiple `cancel_if` calls can be made to a Journey definition.
+    # All conditions are evaluated after setting the state to `performing`.
+    # If any condition is satisfied, the journey will cancel.
+    # 
+    # _@param_ `condition_arg` — the condition to check
+    # 
+    # _@param_ `condition_blk` — a block that will be evaluated as a condition
+    def self.cancel_if: (?(TrueClass | FalseClass | Symbol | Proc | ::Array[untyped] | Conditional) condition_arg) -> void
+
     # Performs the next step in the journey. Will check whether any other process has performed the step already
     # and whether the record is unchanged, and will then lock it and set the state to 'performimg'.
     # 
@@ -320,6 +342,22 @@ module StepperMotor
   class BaseJob < ActiveJob::Base
   end
 
+  # A wrapper for conditional logic that can be evaluated against an object.
+  # This class encapsulates different types of conditions (booleans, symbols, callables, arrays)
+  # and provides a unified interface for checking if a condition is satisfied by a given object.
+  # It handles negation and ensures proper context when evaluating conditions.
+  class Conditional
+    # sord omit - no YARD type given for "condition", using untyped
+    # sord omit - no YARD type given for "negate:", using untyped
+    def initialize: (untyped condition, ?negate: untyped) -> void
+
+    # sord omit - no YARD type given for "object", using untyped
+    def satisfied_by?: (untyped object) -> bool
+
+    # sord omit - no YARD return type given, using untyped
+    def validate_condition: () -> untyped
+  end
+
   module TestHelper
     # Allows running a given Journey to completion, skipping across the waiting periods.
     # This is useful to evaluate all side effects of a Journey. The helper will ensure
@@ -329,8 +367,12 @@ module StepperMotor
     # 
     # _@param_ `journey` — the journey to speedrun
     # 
+    # _@param_ `time_travel` — whether to use ActiveSupport time travel (default: true) Note: When time_travel is true, this method will permanently travel time forward and will not reset it back to the original time when the method exits.
+    # 
+    # _@param_ `maximum_steps` — how many steps can we take until we assume the journey has hung and fail the test. Default value is :reasonable, which is 10x the number of steps. :unlimited allows "a ton", but can make your test hang if your logic lets a step reattempt indefinitely
+    # 
     # _@return_ — void
-    def speedrun_journey: (StepperMotor::Journey journey) -> untyped
+    def speedrun_journey: (StepperMotor::Journey journey, ?time_travel: bool, ?maximum_steps: (Symbol | Integer)) -> untyped
 
     # Performs the named step of the journey without waiting for the time to perform the step.
     # 

data/test/stepper_motor/journey/cancel_if_test.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class CancelIfTest < ActiveSupport::TestCase
+  include ActiveJob::TestHelper
+  include SideEffects::TestHelper
+
+  test "cancel_if with block condition cancels journey when true" do
+    canceling_journey = create_journey_subclass do
+      cancel_if { true }
+
+      step do
+        SideEffects.touch! "should not run"
+      end
+    end
+
+    journey = canceling_journey.create!
+    assert journey.ready?
+
+    assert_no_side_effects { journey.perform_next_step! }
+    assert journey.canceled?
+  end
+
+  test "cancel_if with block condition does not cancel journey when false" do
+    canceling_journey = create_journey_subclass do
+      cancel_if { false }
+
+      step do
+        SideEffects.touch! "should run"
+      end
+    end
+
+    journey = canceling_journey.create!
+    assert journey.ready?
+
+    assert_produced_side_effects("should run") do
+      journey.perform_next_step!
+    end
+    assert journey.finished?
+  end
+
+  test "cancel_if with boolean argument cancels journey when true" do
+    canceling_journey = create_journey_subclass do
+      cancel_if true
+
+      step do
+        SideEffects.touch! "should not run"
+      end
+    end
+
+    journey = canceling_journey.create!
+    assert journey.ready?
+
+    assert_no_side_effects { journey.perform_next_step! }
+    assert journey.canceled?
+  end
+
+  test "cancel_if with boolean argument does not cancel journey when false" do
+    canceling_journey = create_journey_subclass do
+      cancel_if false
+
+      step do
+        SideEffects.touch! "should run"
+      end
+    end
+
+    journey = canceling_journey.create!
+    assert journey.ready?
+
+    assert_produced_side_effects("should run") do
+      journey.perform_next_step!
+    end
+    assert journey.finished?
+  end
+
+  test "cancel_if with symbol argument calls method on journey" do
+    canceling_journey = create_journey_subclass do
+      cancel_if :should_cancel?
+
+      step do
+        SideEffects.touch! "should not run"
+      end
+
+      def should_cancel?
+        true
+      end
+    end
+
+    journey = canceling_journey.create!
+    assert journey.ready?
+
+    assert_no_side_effects { journey.perform_next_step! }
+    assert journey.canceled?
+  end
+
+  test "cancel_if with symbol method call in block" do
+    canceling_journey = create_journey_subclass do
+      cancel_if { should_cancel? }
+
+      step do
+        SideEffects.touch! "should not run"
+      end
+
+      def should_cancel?
+        true
+      end
+    end
+
+    journey = canceling_journey.create!
+    assert journey.ready?
+
+    assert_no_side_effects { journey.perform_next_step! }
+    assert journey.canceled?
+  end
+
+  test "cancel_if with array argument cancels when all conditions are true" do
+    canceling_journey = create_journey_subclass do
+      cancel_if [true, true]
+
+      step do
+        SideEffects.touch! "should not run"
+      end
+    end
+
+    journey = canceling_journey.create!
+    assert journey.ready?
+
+    assert_no_side_effects { journey.perform_next_step! }
+    assert journey.canceled?
+  end
+
+  test "cancel_if with array argument does not cancel when any condition is false" do
+    canceling_journey = create_journey_subclass do
+      cancel_if [true, false]
+
+      step do
+        SideEffects.touch! "should run"
+      end
+    end
+
+    journey = canceling_journey.create!
+    assert journey.ready?
+
+    assert_produced_side_effects("should run") do
+      journey.perform_next_step!
+    end
+    assert journey.finished?
+  end
+
+  test "cancel_if with proc argument evaluates proc in journey context" do
+    proc_condition = -> { true }
+
+    canceling_journey = create_journey_subclass do
+      cancel_if proc_condition
+
+      step do
+        SideEffects.touch! "should not run"
+      end
+    end
+
+    journey = canceling_journey.create!
+    assert journey.ready?
+
+    assert_no_side_effects { journey.perform_next_step! }
+    assert journey.canceled?
+  end
+
+  test "cancel_if with conditional object works correctly" do
+    conditional = StepperMotor::Conditional.new(true)
+
+    canceling_journey = create_journey_subclass do
+      cancel_if conditional
+
+      step do
+        SideEffects.touch! "should not run"
+      end
+    end
+
+    journey = canceling_journey.create!
+    assert journey.ready?
+
+    assert_no_side_effects { journey.perform_next_step! }
+    assert journey.canceled?
+  end
+
+  test "cancel_if with nil argument does not cancel journey" do
+    canceling_journey = create_journey_subclass do
+      cancel_if nil
+
+      step do
+        SideEffects.touch! "should run"
+      end
+    end
+
+    journey = canceling_journey.create!
+    assert journey.ready?
+
+    assert_produced_side_effects("should run") do
+      journey.perform_next_step!
+    end
+    assert journey.finished?
+  end
+
+  test "multiple cancel_if calls are all evaluated" do
+    canceling_journey = create_journey_subclass do
+      cancel_if false
+      cancel_if true
+
+      step do
+        SideEffects.touch! "should not run"
+      end
+    end
+
+    journey = canceling_journey.create!
+    assert journey.ready?
+
+    assert_no_side_effects { journey.perform_next_step! }
+    assert journey.canceled?
+  end
+
+  test "cancel_if conditions are evaluated after setting state to performing" do
+    canceling_journey = create_journey_subclass do
+      cancel_if { performing? }
+
+      step do
+        SideEffects.touch! "should not run"
+      end
+    end
+
+    journey = canceling_journey.create!
+    assert journey.ready?
+
+    assert_no_side_effects { journey.perform_next_step! }
+    assert journey.canceled?
+  end
+
+  test "cancel_if with no arguments and no block raises error" do
+    assert_raises(ArgumentError, "cancel_if requires either a condition argument or a block") do
+      create_journey_subclass do
+        cancel_if
+      end
+    end
+  end
+
+  test "cancel_if with both argument and block raises error" do
+    assert_raises(ArgumentError, "cancel_if accepts either a condition argument or a block, but not both") do
+      create_journey_subclass do
+        cancel_if true do
+          false
+        end
+      end
+    end
+  end
+
+  test "cancel_if conditions are class-inheritable" do
+    parent_journey = create_journey_subclass do
+      cancel_if true
+    end
+
+    child_journey = create_journey_subclass(parent_journey) do
+      step do
+        SideEffects.touch! "should not run"
+      end
+    end
+
+    journey = child_journey.create!
+    assert journey.ready?
+
+    assert_no_side_effects { journey.perform_next_step! }
+    assert journey.canceled?
+  end
+
+  test "cancel_if conditions are appendable in subclasses" do
+    parent_journey = create_journey_subclass do
+      cancel_if false
+    end
+
+    child_journey = create_journey_subclass(parent_journey) do
+      cancel_if true
+
+      step do
+        SideEffects.touch! "should not run"
+      end
+    end
+
+    journey = child_journey.create!
+    assert journey.ready?
+
+    assert_no_side_effects { journey.perform_next_step! }
+    assert journey.canceled?
+  end
+end

data/test/stepper_motor/journey/if_condition_test.rb

@@ -255,7 +255,7 @@ class IfConditionTest < ActiveSupport::TestCase
   end
 
   test "passes skip_if: parameter to step definition" do
-    step_def = StepperMotor::Step.new(name: "a_step", seq: 1, on_exception: :reattempt!)
+    step_def = StepperMotor::Step.new(name: "a_step", on_exception: :reattempt!)
     assert_skip_if_parameter = ->(**options) {
       assert options.key?(:skip_if)
       assert_equal :test_condition, options[:skip_if]

data/test/stepper_motor/journey/step_definition_test.rb

@@ -17,7 +17,7 @@ class StepDefinitionTest < ActiveSupport::TestCase
   end
 
   test "passes any additional options to the step definition" do
-    step_def = StepperMotor::Step.new(name: "a_step", seq: 1, on_exception: :reattempt!)
+    step_def = StepperMotor::Step.new(name: "a_step", on_exception: :reattempt!)
     assert_extra_arguments = ->(**options) {
       assert options.key?(:extra)
       # Return the original definition