stepper_motor 0.1.15 → 0.1.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c62f05b7bc2c994345697f0d403fc6faeaf491c3efa883bfdfe9c3dc7595d52a
-  data.tar.gz: 6fbf7c140444e906ef178af631023022994707c4cf282d954e681c5f6fe07bc1
+  metadata.gz: 4b94d7f405351309bd1fbda83b352031795cbee87aad100d412d847e3d03543c
+  data.tar.gz: 59ecde85caacac0c7e65f6a0c527676bac4700b84fa39ce55443e81592023738
 SHA512:
-  metadata.gz: f95cd7b0eebf80306a14d04f5ce3cd229e0b4e5ee4aa7fc5f12d902ee027b2d97294ecce7bc0a15e56e8490ea9f4724becc6f817dc6bcc9f10667767292c6b85
-  data.tar.gz: e44253c904ab4cf471216352cdc0ec85790532ecb66d9d401d24a9ee85673c42af6d2aa4301be67824344bd0f1864fc34121713db6499f841765a3e6a3ea602b
+  metadata.gz: 5305f1f98eb8b8c630e45309280fae524ec458d15a75362e647a36e22fd29ca0fe1a7ecbbba186ed60f33b64b7b6b875e66878280e21a6a3196473652b82f098
+  data.tar.gz: 2e6db70cf8ad6b844c4d7a38eab6f087f785b1a112f446844e25d6d943bffd3f3b71da6bd7baa69c7249a7978a5538d2572235b3f90475b01af8be0d07074cfd

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.1.16] - 2025-06-20
+
+- Add `skip!` flow control method to skip the current (or next) step and move on to the subsequent step, or finish the journey.
+- Rename `if:` parameter to `skip_if:` for better clarity. The `if:` parameter is still supported for brevity.
+
 ## [0.1.15] - 2025-06-20
 
 - Add `if:` condition allowing steps to be skipped. The `if:` can be a boolean, a callable or a symbol for a method name. The method should be on the Journey.

data/lib/stepper_motor/journey/flow_control.rb

@@ -27,6 +27,55 @@ module StepperMotor::Journey::FlowControl
     throw :abort_step if @current_step_definition
   end
 
+  # 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!
+    if @current_step_definition
+      # Called within a step - set flag to skip current step
+      @skip_current_step = true
+      throw :abort_step if @current_step_definition
+    else
+      # Called outside of a step - skip next scheduled step
+      with_lock do
+        raise "skip! can only be used on journeys in the `ready` state, but was in #{state.inspect}" unless ready?
+
+        current_step_name = next_step_name
+        current_step_definition = lookup_step_definition(current_step_name)
+
+        unless current_step_definition
+          logger.warn { "no step definition found for #{current_step_name} - finishing journey" }
+          finished!
+          update!(previous_step_name: current_step_name, next_step_name: nil)
+          return
+        end
+
+        current_step_seq = current_step_definition.seq
+        next_step_definition = step_definitions[current_step_seq + 1]
+
+        if next_step_definition
+          # There are more steps after this one - schedule the next step
+          logger.info { "skipping scheduled step #{current_step_name}, will continue to #{next_step_definition.name}" }
+          set_next_step_and_enqueue(next_step_definition)
+          ready!
+        else
+          # This is the last step - finish the journey
+          logger.info { "skipping scheduled step #{current_step_name}, finishing journey" }
+          finished!
+          update!(previous_step_name: current_step_name, next_step_name: nil)
+        end
+      end
+    end
+  end
+
   # 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/lib/stepper_motor/journey.rb

@@ -78,12 +78,35 @@ module StepperMotor
     #    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 on_exception[Symbol] See {StepperMotor::Step#on_exception}
+    # @param skip_if[TrueClass,FalseClass,Symbol,Proc] 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[TrueClass,FalseClass,Symbol,Proc] 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 only be performed if the condition returns a truthy value.
+    #    The step will be performed if the condition returns a truthy value. and skipped otherwise. Inverse of `skip_if`.
     # @param additional_step_definition_options[Hash] Any remaining options get passed to `StepperMotor::Step.new` as keyword arguments.
     # @return [StepperMotor::Step] the step definition that has been created
-    def self.step(name = nil, wait: nil, after: nil, on_exception: :pause!, if: true, **additional_step_definition_options, &blk)
+    def self.step(name = nil, wait: nil, after: nil, **additional_step_definition_options, &blk)
+      # Handle the if: alias for backward compatibility
+      if additional_step_definition_options.key?(:if) && additional_step_definition_options.key?(:skip_if)
+        raise StepConfigurationError, "Either skip_if: or if: can be specified, but not both"
+      end
+      if additional_step_definition_options.key?(:if)
+        if_condition = additional_step_definition_options.delete(:if)
+        # Convert if: to skip_if: by negating either the actual value or the return value of the callable
+        # if: truthy means perform, skip_if: truthy means "skip"
+        additional_step_definition_options[:skip_if] = case if_condition
+        when true, false, nil
+          !if_condition
+        when Symbol
+          # For symbols, we need to create a proc that negates the result
+          -> { !send(if_condition) }
+        else
+          # For callables, we need to create a proc that negates the result
+          -> { !instance_exec(&if_condition) }
+        end
+      end
+
       wait = if wait && after
         raise StepConfigurationError, "Either wait: or after: can be specified, but not both"
       elsif !wait && !after
@@ -100,8 +123,8 @@ module StepperMotor
         raise StepConfigurationError, <<~MSG
           Step #{step_definitions.length + 1} of #{self} has no explicit name,
           and no block with step definition has been provided. Without a name the step
-          must be defined with a block to execute. If you want an instance method to be
-          executed as a step, pass the name of the method as the name of the step.
+          must be defined with a block to execute. If you want an instance method of
+          this Journey to be used as the step, pass the name of the method as the name of the step.
         MSG
       end
 
@@ -112,7 +135,7 @@ module StepperMotor
       raise StepConfigurationError, "Step named #{name.inspect} already defined" if known_step_names.include?(name)
 
       # Create the step definition
-      StepperMotor::Step.new(name: name, wait: wait, seq: step_definitions.length, on_exception:, if: binding.local_variable_get(:if), **additional_step_definition_options, &blk).tap do |step_definition|
+      StepperMotor::Step.new(name: name, wait: wait, seq: step_definitions.length, **additional_step_definition_options, &blk).tap do |step_definition|
         # As per Rails docs: you need to be aware when using class_attribute with mutable structures
         # as Array or Hash. In such cases, you don't want to do changes in place. Instead use setters.
         # See https://apidock.com/rails/v7.1.3.2/Class/class_attribute
@@ -232,6 +255,22 @@ module StepperMotor
         logger.info { "will reattempt #{current_step_name} in #{@reattempt_after} seconds" }
         set_next_step_and_enqueue(@current_step_definition, wait: @reattempt_after)
         ready!
+      elsif @skip_current_step
+        # The step asked to be skipped
+        current_step_seq = @current_step_definition.seq
+        next_step_definition = step_definitions[current_step_seq + 1]
+
+        if next_step_definition
+          # There are more steps after this one - schedule the next step
+          logger.info { "skipping current step #{current_step_name}, will continue to #{next_step_definition.name}" }
+          set_next_step_and_enqueue(next_step_definition)
+          ready!
+        else
+          # This is the last step - finish the journey
+          logger.info { "skipping current step #{current_step_name}, finishing journey" }
+          finished!
+          update!(previous_step_name: current_step_name, next_step_name: nil)
+        end
       elsif finished?
         logger.info { "was marked finished inside the step" }
         update!(previous_step_name: current_step_name, next_step_name: nil)
@@ -250,6 +289,7 @@ module StepperMotor
       # and not via background jobs (which reload the model). This should actually be solved
       # using some object that contains the state of the action later, but for now - the dirty approach is fine.
       @reattempt_after = nil
+      @skip_current_step = nil
       @current_step_definition = nil
       # Re-raise the exception, now that we have persisted the Journey according to the recovery policy
       if ex_rescued_at_perform

data/lib/stepper_motor/step.rb

@@ -24,36 +24,38 @@ class StepperMotor::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 if[TrueClass,FalseClass,NilClass,Symbol,Proc] condition to check before performing the step. If a boolean is provided,
+  #   * `: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[TrueClass,FalseClass,NilClass,Symbol,Proc] 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:, seq:, on_exception:, wait: 0, if: true, &step_block)
+  def initialize(name:, seq:, on_exception: :pause!, wait: 0, skip_if: false, &step_block)
     @step_block = step_block
     @name = name.to_s
     @wait = wait
     @seq = seq
     @on_exception = on_exception # TODO: Validate?
-    @if_condition = binding.local_variable_get(:if) # Done this way because `if` is a reserved keyword
+    @skip_if_condition = skip_if
 
-    # Validate the if condition
-    if ![true, false, nil].include?(@if_condition) && !@if_condition.is_a?(Symbol) && !@if_condition.respond_to?(:call)
-      raise ArgumentError, "if: condition must be a boolean, nil, Symbol or a callable object, but was a #{@if_condition.inspect}"
+    # Validate the skip_if condition
+    if ![true, false, nil].include?(@skip_if_condition) && !@skip_if_condition.is_a?(Symbol) && !@skip_if_condition.respond_to?(:call)
+      raise ArgumentError, "skip_if: condition must be a boolean, nil, Symbol or a callable object, but was a #{@skip_if_condition.inspect}"
     end
   end
 
-  # Checks if the step should be performed based on the if condition
+  # Checks if the step should be skipped based on the skip_if condition
   #
   # @param journey[StepperMotor::Journey] the journey to check the condition for
-  # @return [Boolean] true if the step should be performed, false otherwise
-  def should_perform?(journey)
-    case @if_condition
+  # @return [Boolean] true if the step should be skipped, false otherwise
+  def should_skip?(journey)
+    case @skip_if_condition
     when true, false, nil
-      !!@if_condition
+      !!@skip_if_condition
     when Symbol
-      journey.send(@if_condition) # Allow private methods
+      journey.send(@skip_if_condition) # Allow private methods
     else
-      journey.instance_exec(&@if_condition)
+      journey.instance_exec(&@skip_if_condition)
     end
   end
 
@@ -65,9 +67,9 @@ class StepperMotor::Step
   #   journey will be called
   # @return void
   def perform_in_context_of(journey)
-    # Return early should the `if` condition be false
-    if !should_perform?(journey)
-      journey.logger.info { "skipping as if: condition was falsey or returned false" }
+    # Return early should the `skip_if` condition be truthy
+    if should_skip?(journey)
+      journey.logger.info { "skipping as skip_if: condition was truthy" }
       return
     end
 
@@ -99,7 +101,7 @@ class StepperMotor::Step
     # Act according to the set policy. The basic 2 for the moment are :reattempt! and :cancel!,
     # and can be applied by just calling the methods on the passed journey
     case @on_exception
-    when :reattempt!, :cancel!, :pause!
+    when :reattempt!, :cancel!, :pause!, :skip!
       catch(:abort_step) { journey.public_send(@on_exception) }
     else
       # Leave the journey hanging in the "performing" state

data/lib/stepper_motor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StepperMotor
-  VERSION = "0.1.15"
+  VERSION = "0.1.16"
 end

data/manual/MANUAL.md

@@ -427,9 +427,9 @@ class Erasure < StepperMotor::Journey
 end
 ```
 
-### Conditional steps with `if:`
+### Conditional steps with `skip_if:`
 
-You can make steps conditional by using the `if:` parameter. This allows you to skip steps based on runtime conditions. The `if:` parameter accepts:
+You can make steps conditional by using the `skip_if:` parameter. This allows you to skip steps based on runtime conditions. The `skip_if:` parameter accepts:
 
 * A symbol (method name) that returns a boolean.
 * A callable (lambda or proc) that returns a boolean. It will be `instance_exec`d in the context of the Journey.
@@ -437,15 +437,17 @@ You can make steps conditional by using the `if:` parameter. This allows you to
 
 When a step's condition evaluates to `false`, the step is skipped and the journey continues to the next step. If there are no more steps, the journey finishes.
 
+> **Note:** The `if:` parameter is also supported as an alias for `skip_if:` for backward compatibility, but `skip_if:` is the preferred parameter name.
+
 #### Using method names as conditions
 
 ```ruby
 class UserOnboardingJourney < StepperMotor::Journey
-  step :send_welcome_email, if: :should_send_welcome? do
+  step :send_welcome_email, skip_if: :should_send_welcome? do
     WelcomeMailer.welcome(hero).deliver_later
   end
 
-  step :send_premium_offer, if: :is_premium_user? do
+  step :send_premium_offer, skip_if: :is_premium_user? do
     PremiumOfferMailer.exclusive_offer(hero).deliver_later
   end
 
@@ -471,7 +473,7 @@ You can use lambdas or procs for more dynamic conditions. They will be `instance
 
 ```ruby
 class OrderProcessingJourney < StepperMotor::Journey
-  step :send_confirmation, if: -> { hero.email.present? } do
+  step :send_confirmation, skip_if: -> { hero.email.present? } do
     OrderConfirmationMailer.confirm(hero).deliver_later
   end
 
@@ -487,11 +489,11 @@ You can use literal boolean values to conditionally include or exclude steps:
 
 ```ruby
 class FeatureFlagJourney < StepperMotor::Journey
-  step :new_feature_step, if: Rails.application.config.new_feature_enabled do
+  step :new_feature_step, skip_if: Rails.application.config.new_feature_enabled do
     NewFeatureService.process(hero)
   end
 
-  step :legacy_step, if: ENV["PERFORM_LEGACY_STEP"] do  # This step will never execute
+  step :legacy_step, skip_if: ENV["PERFORM_LEGACY_STEP"] do  # This step will never execute
     LegacyService.process(hero)
   end
 
@@ -548,23 +550,32 @@ stateDiagram-v2
 
 ## Flow control within steps
 
-Inside a step, you currently can use the following flow control methods:
+You currently can use the following flow control methods, both when a step is performing and on a Journey fetched from the database:
 
 * `cancel!` - cancel the Journey immediately. It will be persisted and moved into the `canceled` state.
 * `reattempt!` - reattempt the Journey immediately, triggering it asynchronously. It will be persisted
     and returned into the `ready` state. You can specify the `wait:` interval, which may deviate from
-    the wait time defined for the current step
+    the wait time defined for the current step. `reattepmt!` cannot be used outside of steps!
 * `pause!` - pause the Journey either within a step or outside of one. This moves the Journey into the `paused` state.
     In that state, the journey is still considered unique-per-hero (you won't be able to create an identical Journey)
     but it will not be picked up by the scheduled step jobs. Should it get picked up, the step will not be performed.
     You have to explicitly `resume!` the Journey to make it `ready` - once you do, a new job will be scheduled to
     perform the step.
+* `skip!` - skip either the step currently being performed or the step scheduled to be taken next, 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.
 
 > [!IMPORTANT]  
-> Flow control methods use `throw` when they are called from inside a step. Unlike Rails `render` or `redirect` that require an explicit
-> `return`, the code following a `reattempt!` or `cancel!` within the same scope will not be executed, so those methods may only be called once within a particular scope.
+> Flow control methods use `throw` when they are called during step execution. Unlike Rails `render` or `redirect` that require an explicit
+> `return`, the code following a `reattempt!` or `cancel!` within the same scope will not be executed inside steps, so those methods may only be called once within a particular scope.
 
-You can't call those methods outside of the context of a performing step, and an exception is going to be raised if you do.
+Most of those methods do the right thing both inside steps and outside step execution. The only exception is `reattempt!`.
+
+> [!IMPORTANT]  
+> `reattempt!` only works inside of steps.
 
 ## Transactional semantics within steps
 

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.15", T.untyped)
+  VERSION = T.let("0.1.16", T.untyped)
   PerformStepJobV2 = T.let(StepperMotor::PerformStepJob, T.untyped)
   RecoverStuckJourneysJobV1 = T.let(StepperMotor::RecoverStuckJourneysJob, T.untyped)
 
@@ -32,28 +32,28 @@ 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_ `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.
+    # _@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.
     sig do
       params(
         name: T.any(String, Symbol),
         seq: T.untyped,
         on_exception: Symbol,
         wait: T.any(Numeric, ActiveSupport::Duration),
-        if: T.any(TrueClass, FalseClass, NilClass, Symbol, Proc),
+        skip_if: T.any(TrueClass, FalseClass, NilClass, Symbol, Proc),
         step_block: T.untyped
       ).void
     end
-    def initialize(name:, seq:, on_exception:, wait: 0, if: true, &step_block); end
+    def initialize(name:, seq:, on_exception: :pause!, wait: 0, skip_if: false, &step_block); end
 
-    # Checks if the step should be performed based on the if condition
+    # 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 performed, false otherwise
+    # _@return_ — true if the step should be skipped, false otherwise
     sig { params(journey: StepperMotor::Journey).returns(T::Boolean) }
-    def should_perform?(journey); end
+    def should_skip?(journey); end
 
     # Performs the step on the passed Journey, wrapping the step with the required context.
     # 
@@ -139,7 +139,9 @@ module StepperMotor
     # 
     # _@param_ `on_exception` — See {StepperMotor::Step#on_exception}
     # 
-    # _@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 only be performed if the condition returns a truthy value.
+    # _@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.
     # 
@@ -149,13 +151,11 @@ 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)),
-        on_exception: Symbol,
-        if: T.any(TrueClass, FalseClass, Symbol, Proc),
         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, on_exception: :pause!, if: true, **additional_step_definition_options, &blk); end
+    def self.step(name = nil, wait: nil, after: 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
@@ -248,6 +248,20 @@ module StepperMotor
     sig { params(wait: T.untyped).returns(T.untyped) }
     def reattempt!(wait: nil); end
 
+    # 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
+    sig { returns(T.untyped) }
+    def skip!; end
+
     # 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:
     # 
@@ -299,6 +313,20 @@ module StepperMotor
       sig { params(wait: T.untyped).returns(T.untyped) }
       def reattempt!(wait: nil); end
 
+      # 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
+      sig { returns(T.untyped) }
+      def skip!; end
+
       # 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/sig/stepper_motor.rbs

@@ -30,23 +30,23 @@ 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_ `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.
+    # _@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,
+                      ?on_exception: Symbol,
                       ?wait: (Numeric | ActiveSupport::Duration),
-                      ?if: (TrueClass | FalseClass | NilClass | Symbol | Proc)
+                      ?skip_if: (TrueClass | FalseClass | NilClass | Symbol | Proc)
                     ) -> void
 
-    # Checks if the step should be performed based on the if condition
+    # 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 performed, false otherwise
-    def should_perform?: (StepperMotor::Journey journey) -> bool
+    # _@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.
     # 
@@ -127,7 +127,9 @@ module StepperMotor
     # 
     # _@param_ `on_exception` — See {StepperMotor::Step#on_exception}
     # 
-    # _@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 only be performed if the condition returns a truthy value.
+    # _@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.
     # 
@@ -136,8 +138,6 @@ module StepperMotor
                      ?String? name,
                      ?wait: (Float | untyped | ActiveSupport::Duration)?,
                      ?after: (Float | untyped | ActiveSupport::Duration)?,
-                     ?on_exception: Symbol,
-                     ?if: (TrueClass | FalseClass | Symbol | Proc),
                      **::Hash[untyped, untyped] additional_step_definition_options
                    ) -> StepperMotor::Step
 
@@ -218,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:
     # 
@@ -264,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/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

data/test/stepper_motor/journey/if_condition_test.rb

@@ -8,14 +8,14 @@ class IfConditionTest < ActiveSupport::TestCase
   include SideEffects::TestHelper
   include StepperMotor::TestHelper
 
-  test "supports if: with symbol condition that returns true" do
+  test "supports skip_if: with symbol condition that returns false (performs step)" do
     journey_class = create_journey_subclass do
-      step :one, if: :should_run do
+      step :one, skip_if: :should_skip do
         SideEffects.touch!("step executed")
       end
 
-      def should_run
-        true
+      def should_skip
+        false
       end
     end
 
@@ -26,9 +26,9 @@ class IfConditionTest < ActiveSupport::TestCase
     assert journey.finished?
   end
 
-  test "supports if: with symbol condition that returns false" do
+  test "supports skip_if: with symbol condition that returns true (skips step)" do
     journey_class = create_journey_subclass do
-      step :one, if: :should_run do
+      step :one, skip_if: :should_skip do
         SideEffects.touch!("step executed")
       end
 
@@ -36,8 +36,8 @@ class IfConditionTest < ActiveSupport::TestCase
         SideEffects.touch!("second step executed")
       end
 
-      def should_run
-        false
+      def should_skip
+        true
       end
     end
 
@@ -47,9 +47,9 @@ class IfConditionTest < ActiveSupport::TestCase
     refute SideEffects.produced?("step executed")
   end
 
-  test "supports if: with block condition that returns true" do
+  test "supports skip_if: with block condition that returns false (performs step)" do
     journey_class = create_journey_subclass do
-      step :one, if: -> { hero.present? } do
+      step :one, skip_if: -> { hero.nil? } do
         SideEffects.touch!("step executed")
       end
     end
@@ -61,9 +61,9 @@ class IfConditionTest < ActiveSupport::TestCase
     assert journey.finished?
   end
 
-  test "supports if: with block condition that returns false" do
+  test "supports skip_if: with block condition that returns true (skips step)" do
     journey_class = create_journey_subclass do
-      step :one, if: -> { hero.nil? } do
+      step :one, skip_if: -> { hero.present? } do
         SideEffects.touch!("step executed")
       end
 
@@ -78,9 +78,9 @@ class IfConditionTest < ActiveSupport::TestCase
     refute SideEffects.produced?("step executed")
   end
 
-  test "supports if: with block condition that accesses journey instance variables" do
+  test "supports skip_if: with block condition that accesses journey instance variables" do
     journey_class = create_journey_subclass do
-      step :one, if: -> { @condition_met } do
+      step :one, skip_if: -> { @condition_met } do
         SideEffects.touch!("step executed")
       end
 
@@ -90,7 +90,7 @@ class IfConditionTest < ActiveSupport::TestCase
 
       def initialize(*args)
         super
-        @condition_met = false
+        @condition_met = true
       end
     end
 
@@ -100,24 +100,24 @@ class IfConditionTest < ActiveSupport::TestCase
     refute SideEffects.produced?("step executed")
   end
 
-  test "supports if: with block condition that can be changed during journey execution" do
+  test "supports skip_if: with block condition that can be changed during journey execution" do
     journey_class = create_journey_subclass do
-      step :one, if: -> { @condition_met } do
+      step :one, skip_if: -> { @condition_met } do
         SideEffects.touch!("first step executed")
       end
 
       step :two do
         SideEffects.touch!("second step executed")
-        @condition_met = true
+        @condition_met = false
       end
 
-      step :three, if: -> { @condition_met } do
+      step :three, skip_if: -> { @condition_met } do
         SideEffects.touch!("third step executed")
       end
 
       def initialize(*args)
         super
-        @condition_met = false
+        @condition_met = true
       end
     end
 
@@ -128,9 +128,9 @@ class IfConditionTest < ActiveSupport::TestCase
     refute SideEffects.produced?("first step executed")
   end
 
-  test "skips step when if: condition is false and continues to next step" do
+  test "skips step when skip_if: condition is true and continues to next step" do
     journey_class = create_journey_subclass do
-      step :one, if: :false_condition do
+      step :one, skip_if: :true_condition do
         SideEffects.touch!("first step executed")
       end
 
@@ -142,8 +142,8 @@ class IfConditionTest < ActiveSupport::TestCase
         SideEffects.touch!("third step executed")
       end
 
-      def false_condition
-        false
+      def true_condition
+        true
       end
     end
 
@@ -154,14 +154,14 @@ class IfConditionTest < ActiveSupport::TestCase
     refute SideEffects.produced?("first step executed")
   end
 
-  test "skips step when if: condition is false and finishes journey if no more steps" do
+  test "skips step when skip_if: condition is true and finishes journey if no more steps" do
     journey_class = create_journey_subclass do
-      step :one, if: :false_condition do
+      step :one, skip_if: :true_condition do
         SideEffects.touch!("step executed")
       end
 
-      def false_condition
-        false
+      def true_condition
+        true
       end
     end
 
@@ -170,9 +170,9 @@ class IfConditionTest < ActiveSupport::TestCase
     refute SideEffects.produced?("step executed")
   end
 
-  test "supports if: with literal true" do
+  test "supports skip_if: with literal false (performs step)" do
     journey_class = create_journey_subclass do
-      step :one, if: true do
+      step :one, skip_if: false do
         SideEffects.touch!("step executed")
       end
     end
@@ -184,9 +184,9 @@ class IfConditionTest < ActiveSupport::TestCase
     assert journey.finished?
   end
 
-  test "supports if: with literal false" do
+  test "supports skip_if: with literal true (skips step)" do
     journey_class = create_journey_subclass do
-      step :one, if: false do
+      step :one, skip_if: true do
         SideEffects.touch!("step executed")
       end
 
@@ -201,9 +201,9 @@ class IfConditionTest < ActiveSupport::TestCase
     refute SideEffects.produced?("step executed")
   end
 
-  test "supports if: with literal false and finishes journey if no more steps" do
+  test "supports skip_if: with literal true and finishes journey if no more steps" do
     journey_class = create_journey_subclass do
-      step :one, if: false do
+      step :one, skip_if: true do
         SideEffects.touch!("step executed")
       end
     end
@@ -213,7 +213,7 @@ class IfConditionTest < ActiveSupport::TestCase
     refute SideEffects.produced?("step executed")
   end
 
-  test "defaults to true when if: is not specified" do
+  test "defaults to false when skip_if: is not specified" do
     journey_class = create_journey_subclass do
       step :one do
         SideEffects.touch!("step executed")
@@ -227,9 +227,9 @@ class IfConditionTest < ActiveSupport::TestCase
     assert journey.finished?
   end
 
-  test "treats nil as false in if condition" do
+  test "treats nil as false in skip_if condition (performs step)" do
     journey_class = create_journey_subclass do
-      step :one, if: nil do
+      step :one, skip_if: nil do
         SideEffects.touch!("step executed")
       end
 
@@ -240,44 +240,113 @@ class IfConditionTest < ActiveSupport::TestCase
 
     journey = journey_class.create!
     speedrun_journey(journey)
+    assert SideEffects.produced?("step executed")
     assert SideEffects.produced?("second step executed")
-    refute SideEffects.produced?("step executed")
   end
 
-  test "treats nil as false and finishes journey if no more steps" do
+  test "raises ArgumentError when skip_if: condition is neither symbol nor callable" do
+    assert_raises(ArgumentError) do
+      create_journey_subclass do
+        step :one, skip_if: "not a symbol or callable" do
+          # noop
+        end
+      end
+    end
+  end
+
+  test "passes skip_if: parameter to step definition" do
+    step_def = StepperMotor::Step.new(name: "a_step", seq: 1, on_exception: :reattempt!)
+    assert_skip_if_parameter = ->(**options) {
+      assert options.key?(:skip_if)
+      assert_equal :test_condition, options[:skip_if]
+      # Return the original definition
+      step_def
+    }
+
+    StepperMotor::Step.stub :new, assert_skip_if_parameter do
+      create_journey_subclass do
+        step :test_step, skip_if: :test_condition do
+          # noop
+        end
+      end
+    end
+  end
+
+  # Backward compatibility tests for if: parameter
+  test "supports if: with symbol condition that returns true (performs step, backward compatibility)" do
     journey_class = create_journey_subclass do
-      step :one, if: nil do
+      step :one, if: :should_run do
         SideEffects.touch!("step executed")
       end
+
+      def should_run
+        true
+      end
+    end
+
+    journey = journey_class.create!
+    assert_produced_side_effects("step executed") do
+      journey.perform_next_step!
+    end
+    assert journey.finished?
+  end
+
+  test "supports if: with symbol condition that returns false (skips step, backward compatibility)" do
+    journey_class = create_journey_subclass do
+      step :one, if: :should_run do
+        SideEffects.touch!("step executed")
+      end
+
+      step :two do
+        SideEffects.touch!("second step executed")
+      end
+
+      def should_run
+        false
+      end
     end
 
     journey = journey_class.create!
     speedrun_journey(journey)
+    assert SideEffects.produced?("second step executed")
     refute SideEffects.produced?("step executed")
   end
 
-  test "raises ArgumentError when if: condition is neither symbol nor callable" do
-    assert_raises(ArgumentError) do
-      create_journey_subclass do
-        step :one, if: "not a symbol or callable" do
-          # noop
-        end
+  test "supports if: with literal true (performs step, backward compatibility)" do
+    journey_class = create_journey_subclass do
+      step :one, if: true do
+        SideEffects.touch!("step executed")
       end
     end
+
+    journey = journey_class.create!
+    assert_produced_side_effects("step executed") do
+      journey.perform_next_step!
+    end
+    assert journey.finished?
   end
 
-  test "passes if: parameter to step definition" do
-    step_def = StepperMotor::Step.new(name: "a_step", seq: 1, on_exception: :reattempt!)
-    assert_if_parameter = ->(**options) {
-      assert options.key?(:if)
-      assert_equal :test_condition, options[:if]
-      # Return the original definition
-      step_def
-    }
+  test "supports if: with literal false (skips step, backward compatibility)" do
+    journey_class = create_journey_subclass do
+      step :one, if: false do
+        SideEffects.touch!("step executed")
+      end
+
+      step :two do
+        SideEffects.touch!("second step executed")
+      end
+    end
+
+    journey = journey_class.create!
+    speedrun_journey(journey)
+    assert SideEffects.produced?("second step executed")
+    refute SideEffects.produced?("step executed")
+  end
 
-    StepperMotor::Step.stub :new, assert_if_parameter do
+  test "raises error when both skip_if: and if: are specified" do
+    assert_raises(StepperMotor::StepConfigurationError) do
       create_journey_subclass do
-        step :test_step, if: :test_condition do
+        step :one, skip_if: :condition1, if: :condition2 do
           # noop
         end
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stepper_motor
 version: !ruby/object:Gem::Version
-  version: 0.1.15
+  version: 0.1.16
 platform: ruby
 authors:
 - Julik Tarkhanov