stepper_motor 0.1.17 → 0.1.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae300e62a2208dff5b41284cf55703bd14bf28605a05daa4a86d40d915a42259
-  data.tar.gz: c7d192edf6a455761303ae83647d8e755111cd847c7fb3a1c3ca8d094ed6ca72
+  metadata.gz: b27839f0ee5621c5da6e694e2ee3e790f9f4b96383d05bf5ebbfc0a7ddf99928
+  data.tar.gz: 60bf0af4da25cf6f6c7ef2d835bcbd717ec662215da2bf14aea50da6949dc316
 SHA512:
-  metadata.gz: 634c4e138fab066753a07bc4627b898dfb2e41ae082e0eb9722dc8fcdad5941a3009f867ec8e2d520aaeebbb8981d583e24bf05ef6f7b7aa667f1950f810401f
-  data.tar.gz: cea004de19c142606872fae194bf8079a02ccfc5cebe7d59c04f6d2bcba55255b990d5e16778acdc439918af0ae02ddd5162331435a0fb5c504adbbbf019a58e
+  metadata.gz: 275d2ba0cc4ff6710f3d87189853f9836a767bfea6e56ac6a635135f7aa8e8043038f3cff1b28fd3b548ea06dd65392b37adb4f6d5aa4a310e7e7d95f53cb444
+  data.tar.gz: dd3f67919bf6daca240b6eb32d4c83ca720fc8ae9f2b7e9c571a7913e2e640840c7f1dc4c497f5114f14694b0a413ccdba758330c418844a3adc77b5312289ce

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.1.19] - 2025-06-25
+
+- With `speedrun_journey`, allow configuring the maximum number of steps - for testing journeys
+  that iterate or reattempt a lot.
+- With `speedrun_journey`, use time travel by default
+- Allow steps to be placed relative to other steps using `before_step:` and `after_step:` keyword arguments
+- Use just-in-time index lookup instead of `Step#seq`
+
+## [0.1.18] - 2025-06-20
+
+- Add `cancel_if` at Journey class level for blanket journey cancellation conditions. This makes it very easy to abort journeys across multiple steps.
+
 ## [0.1.17] - 2025-06-20
 
 - Mandate Ruby 3.1+ because we are using 3.x syntax and there are shenanigans with sqlite3 gem version and locking. Compatibility with 2.7 can be assured but is too much hassle at the moment.

data/lib/stepper_motor/conditional.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module StepperMotor
+  # 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
+    def initialize(condition, negate: false)
+      @condition = condition
+      @negate = negate
+      validate_condition
+    end
+
+    def satisfied_by?(object)
+      result = case @condition
+      when Array
+        @condition.all? { |c| Conditional.new(c).satisfied_by?(object) }
+      when Symbol
+        !!object.send(@condition)
+      when Conditional
+        @condition.satisfied_by?(object)
+      else
+        if @condition.respond_to?(:call)
+          !!object.instance_exec(&@condition)
+        else
+          !!@condition
+        end
+      end
+
+      @negate ? !result : result
+    end
+
+    private
+
+    def validate_condition
+      unless [true, false, nil].include?(@condition) || @condition.is_a?(Symbol) || @condition.is_a?(Array) || @condition.is_a?(Conditional) || @condition.respond_to?(:call)
+        raise ArgumentError, "condition must be a boolean, nil, Symbol, Array, Conditional or a callable object, but was a #{@condition.inspect}"
+      end
+    end
+  end
+end

data/lib/stepper_motor/journey/flow_control.rb

@@ -58,8 +58,7 @@ module StepperMotor::Journey::FlowControl
           return
         end
 
-        current_step_seq = current_step_definition.seq
-        next_step_definition = step_definitions[current_step_seq + 1]
+        next_step_definition = self.class.step_definitions_following(current_step_definition).first
 
         if next_step_definition
           # There are more steps after this one - schedule the next step

data/lib/stepper_motor/journey.rb

@@ -47,6 +47,9 @@ module StepperMotor
     # @return [Array<StepperMotor::Step>] the step definitions defined so far
     class_attribute :step_definitions, default: []
 
+    # @return [Array<StepperMotor::Conditional>] the cancel_if conditions defined for this journey class
+    class_attribute :cancel_if_conditions, default: []
+
     belongs_to :hero, polymorphic: true, optional: true
 
     STATES = %w[ready paused performing canceled finished]
@@ -76,7 +79,13 @@ module StepperMotor
     #    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:`
+    #    Mutually exclusive with `wait:`.
+    # @param before_step[String,Symbol,nil] 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[String,Symbol,nil] 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[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.
@@ -86,32 +95,41 @@ module StepperMotor
     #    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, **additional_step_definition_options, &blk)
+    def self.step(name = nil, wait: nil, after: nil, before_step: nil, after_step: 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) }
+        # Convert if: to skip_if:
+        additional_step_definition_options[:skip_if] = StepperMotor::Conditional.new(additional_step_definition_options.delete(:if), negate: true)
+      end
+
+      # Validate before_step and after_step parameters
+      if before_step && after_step
+        raise StepConfigurationError, "Either before_step: or after_step: can be specified, but not both"
+      end
+
+      # Validate that referenced steps exist
+      if before_step
+        referenced_step = lookup_step_definition(before_step)
+        unless referenced_step
+          raise StepConfigurationError, "Step named #{before_step.inspect} not found for before_step: parameter"
         end
       end
 
-      wait = if wait && after
+      if after_step
+        referenced_step = lookup_step_definition(after_step)
+        unless referenced_step
+          raise StepConfigurationError, "Step named #{after_step.inspect} not found for after_step: parameter"
+        end
+      end
+
+      wait = if wait && after&.respond_to?(:to_f)
         raise StepConfigurationError, "Either wait: or after: can be specified, but not both"
-      elsif !wait && !after
+      elsif !wait && (!after || !after.respond_to?(:to_f))
         0
-      elsif after
+      elsif after&.respond_to?(:to_f)
         accumulated = step_definitions.map(&:wait).sum
         after - accumulated
       else
@@ -135,12 +153,27 @@ 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, **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
+      step_definition = StepperMotor::Step.new(name: name, wait: wait, **additional_step_definition_options, &blk)
+
+      # Determine insertion position based on before_step or after_step parameters
+      if before_step
+        target_step = lookup_step_definition(before_step)
+        target_index = step_definitions.index(target_step)
+        new_step_definitions = step_definitions.dup
+        new_step_definitions.insert(target_index, step_definition)
+        self.step_definitions = new_step_definitions
+      elsif after_step
+        target_step = lookup_step_definition(after_step)
+        target_index = step_definitions.index(target_step)
+        new_step_definitions = step_definitions.dup
+        new_step_definitions.insert(target_index + 1, step_definition)
+        self.step_definitions = new_step_definitions
+      else
+        # Default behavior: append to the end
         self.step_definitions = step_definitions + [step_definition]
       end
+
+      step_definition
     end
 
     # Returns the `Step` object for a named step. This is used when performing a step, but can also
@@ -152,6 +185,16 @@ module StepperMotor
       step_definitions.find { |d| d.name.to_s == by_step_name.to_s }
     end
 
+    # Returns all step definitions that follow the given step in the journey
+    #
+    # @param step_definition[StepperMotor::Step] the step to find the following steps for
+    # @return [Array<StepperMotor::Step>] the following steps, or empty array if this is the last step
+    def self.step_definitions_following(step_definition)
+      current_index = step_definitions.index(step_definition)
+      return [] unless current_index
+      step_definitions[(current_index + 1)..]
+    end
+
     # Alias for the class attribute, for brevity
     #
     # @see Journey.step_definitions
@@ -166,6 +209,41 @@ module StepperMotor
       self.class.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 [TrueClass, FalseClass, Symbol, Proc, Array, Conditional] the condition to check
+    # @param condition_blk [Proc] a block that will be evaluated as a condition
+    # @return [void]
+    def self.cancel_if(condition_arg = :__no_argument_given__, &condition_blk)
+      # Check if neither argument nor block is provided
+      if condition_arg == :__no_argument_given__ && !condition_blk
+        raise ArgumentError, "cancel_if requires either a condition argument or a block"
+      end
+
+      # Check if both argument and block are provided
+      if condition_arg != :__no_argument_given__ && condition_blk
+        raise ArgumentError, "cancel_if accepts either a condition argument or a block, but not both"
+      end
+
+      # Select the condition: positional argument takes precedence if not sentinel
+      condition = if condition_arg != :__no_argument_given__
+        condition_arg
+      else
+        condition_blk
+      end
+
+      conditional = StepperMotor::Conditional.new(condition)
+
+      # 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
+      self.cancel_if_conditions = cancel_if_conditions + [conditional]
+    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'.
     #
@@ -188,6 +266,14 @@ module StepperMotor
         performing!
         after_locking_for_step(next_step_name)
       end
+
+      # Check cancel_if conditions after setting state to performing
+      if cancel_if_conditions.any? { |conditional| conditional.satisfied_by?(self) }
+        logger.info { "cancel_if condition satisfied, canceling journey" }
+        cancel!
+        return
+      end
+
       current_step_name = next_step_name
 
       if current_step_name
@@ -257,8 +343,7 @@ module StepperMotor
         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]
+        next_step_definition = self.class.step_definitions_following(@current_step_definition).first
 
         if next_step_definition
           # There are more steps after this one - schedule the next step
@@ -274,7 +359,7 @@ module StepperMotor
       elsif finished?
         logger.info { "was marked finished inside the step" }
         update!(previous_step_name: current_step_name, next_step_name: nil)
-      elsif (next_step_definition = step_definitions[@current_step_definition.seq + 1])
+      elsif (next_step_definition = self.class.step_definitions_following(@current_step_definition).first)
         logger.info { "will continue to #{next_step_definition.name}" }
         set_next_step_and_enqueue(next_step_definition)
         ready!
@@ -302,8 +387,7 @@ module StepperMotor
 
     # @return [ActiveSupport::Duration]
     def time_remaining_until_final_step
-      current_step_seq = @current_step_definition&.seq || -1
-      subsequent_steps = step_definitions.select { |definition| definition.seq > current_step_seq }
+      subsequent_steps = @current_step_definition ? self.class.step_definitions_following(@current_step_definition) : step_definitions
       seconds_remaining = subsequent_steps.map { |definition| definition.wait.to_f }.sum
       seconds_remaining.seconds # Convert to ActiveSupport::Duration
     end

data/lib/stepper_motor/step.rb

@@ -13,9 +13,6 @@ class StepperMotor::Step
   # @return [Numeric,ActiveSupport::Duration] how long to wait before performing the step
   attr_reader :wait
 
-  # @private
-  attr_reader :seq
-
   # Creates a new step definition
   #
   # @param name[String,Symbol] the name of the Step
@@ -30,18 +27,12 @@ class StepperMotor::Step
   #   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: :pause!, wait: 0, skip_if: false, &step_block)
+  def initialize(name:, 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?
-    @skip_if_condition = skip_if
-
-    # 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
+    @skip_if_condition = StepperMotor::Conditional.new(skip_if)
   end
 
   # Checks if the step should be skipped based on the skip_if condition
@@ -49,14 +40,7 @@ class StepperMotor::Step
   # @param journey[StepperMotor::Journey] the journey to check the condition for
   # @return [Boolean] true if the step should be skipped, false otherwise
   def should_skip?(journey)
-    case @skip_if_condition
-    when true, false, nil
-      !!@skip_if_condition
-    when Symbol
-      journey.send(@skip_if_condition) # Allow private methods
-    else
-      journey.instance_exec(&@skip_if_condition)
-    end
+    @skip_if_condition.satisfied_by?(journey)
   end
 
   # Performs the step on the passed Journey, wrapping the step with the required context.

data/lib/stepper_motor/test_helper.rb

@@ -8,14 +8,39 @@ module StepperMotor::TestHelper
   # has neither canceled nor finished, an exception will be raised.
   #
   # @param journey[StepperMotor::Journey] the journey to speedrun
+  # @param time_travel[Boolean] 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[Symbol,Integer] 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(journey)
+  def speedrun_journey(journey, time_travel: true, maximum_steps: :reasonable)
     journey.save!
-    n_steps = journey.step_definitions.length
+    n_steps = case maximum_steps
+    when :reasonable
+      journey.step_definitions.length * 10
+    when :unlimited
+      0xFFFF
+    when Integer
+      maximum_steps
+    else
+      raise ArgumentError, "maximum_steps may be :reasonable, :unlimited or an Integer, was #{maximum_steps.inspect}"
+    end
+
     n_steps.times do
       journey.reload
       break if journey.canceled? || journey.finished?
-      journey.update(next_step_to_be_performed_at: Time.current)
+
+      if time_travel
+        # Use time travel to move slightly ahead of the time when the next step should be performed
+        next_step_time = journey.next_step_to_be_performed_at
+        travel_to(next_step_time + 1.second)
+      else
+        # Update the journey's timestamp to bypass waiting periods
+        journey.update(next_step_to_be_performed_at: Time.current)
+      end
       journey.perform_next_step!
     end
     journey.reload

data/lib/stepper_motor/version.rb

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

data/lib/stepper_motor.rb

@@ -13,6 +13,7 @@ module StepperMotor
 
   autoload :Journey, File.dirname(__FILE__) + "/stepper_motor/journey.rb"
   autoload :Step, File.dirname(__FILE__) + "/stepper_motor/step.rb"
+  autoload :Conditional, File.dirname(__FILE__) + "/stepper_motor/conditional.rb"
 
   autoload :BaseJob, File.dirname(__FILE__) + "/stepper_motor/base_job.rb"
   autoload :PerformStepJob, File.dirname(__FILE__) + "/stepper_motor/perform_step_job.rb"

data/manual/MANUAL.md

@@ -27,7 +27,9 @@ So, stepper_motor aims to give you "just enough of Temporal-like functionality"
 
 ## A brief introduction to stepper_motor
 
-stepper_motor is built around the concept of a `Journey`. A `Journey` [is a sequence of steps happening to a `hero`](https://en.wikipedia.org/wiki/Hero%27s_journey) - once launched, the journey will run until it either finishes or cancels. A `Journey` is just an `ActiveRecord` model, with all the persistence methods you already know and use.
+stepper_motor is built around the concept of a `Journey`. A `Journey` [is a sequence of steps happening to a `hero`](https://en.wikipedia.org/wiki/Hero%27s_journey) - once launched, the journey will run until it either finishes or cancels. But also - a `Journey` is an `ActiveRecord` model, with all the persistence methods you already know and use. Every `Journey` has a speficic identity - its primary key, just like any other database row, and carries state information.
+
+A `Journey` changes states during asynchronous invocations, and can lay dormant for months until the time comes to take the next step.
 
 Steps are defined inside the Journey subclasses as blocks, and they run in the context of that subclass' instance. The following constraints apply:
 
@@ -40,7 +42,7 @@ The `step` blocks get executed in the context of the `Journey` model instance. T
 
 The steps are performed asynchronously, via ActiveJob. When a Journey is created, it gets scheduled for its initial step. The job then gets picked up by the ActiveJob queue worker (whichever you are using) and triggers the step on the `Journey`. If the journey decides to continue to the next step, it schedules another ActiveJob for itself with the step name and other details necessary.
 
-No state is carried inside the job.
+No state is carried inside the job - both the state transition management and the steps are handled by the `Journey` itself.
 
 ## Installation
 
@@ -70,7 +72,7 @@ class SignupJourney < StepperMotor::Journey
   end
 end
 
-class SignupController
+class SignupController < ApplicationController
   def create
     # ...your other business actions
     SignupJourney.create!(hero: current_user)
@@ -371,23 +373,54 @@ step :two do
 end
 ```
 
-You have a `Journey` which is about to start step `one`. When the step gets performed, stepper_motor will do a lookup to find _the next step in order of definition._ In this case the step will be step `two`, so the name of that step will be saved with the `Journey`. Imagine you then edit the code to add an extra step between those:
+Your existing `Journey` is already primed to perform step `two`. However, a `Journey` which is about to perform step `one` will now set `one_bis` as the next step to perform. This allows limited reordering and editing of `Journey` definitions after they have already begun.
+
+### Step ordering with `before_step:` and `after_step:`
+
+You can control the order of steps by inserting them before or after specific existing steps using the `before_step:` and `after_step:` parameters. This is useful when you want to add steps in the middle of a sequence without manually reordering all the steps.
+
+The step names can be provided as strings or symbols, and only one of `before_step:` or `after_step:` can be specified:
 
 ```ruby
-step :one do
-  # perform some action
-end
+class UserOnboardingJourney < StepperMotor::Journey
+  step :send_welcome_email do
+    WelcomeMailer.welcome(hero).deliver_later
+  end
 
-step :one_bis do
-  # some compliance action
-end
+  step :send_premium_offer, after: 2.days do
+    PremiumOfferMailer.exclusive_offer(hero).deliver_later
+  end
 
-step :two do
-  # perform some other action
+  # Insert a compliance check before the premium offer
+  step :compliance_check, before_step: "send_premium_offer" do
+    ComplianceService.verify_eligibility(hero)
+  end
+
+  # Insert a reminder after the welcome email
+  step :send_reminder, after_step: "send_welcome_email", wait: 1.day do
+    ReminderMailer.follow_up(hero).deliver_later
+  end
+
+  step :complete_onboarding, after: 7.days do
+    hero.update!(onboarding_completed_at: Time.current)
+  end
 end
 ```
+This approach is particularly useful when extending journey classes through inheritance, as you can insert steps relative to steps defined in the parent class.
+Should you ever get confused and find yourself in need to retrace your steps, call `UserOnboardingJourney.step_definitions.map(&:name)`:
 
-Your existing `Journey` is already primed to perform step `two`. However, a `Journey` which is about to perform step `one` will now set `one_bis` as the next step to perform. This allows limited reordering and editing of `Journey` definitions after they have already begun.
+```ruby
+UserOnboardingJourney.step_definitions.map(&:name)
+# => ["send_welcome_email", "send_reminder", "compliance_check", "send_premium_offer", "complete_onboarding"]
+```
+
+This will show you the exact order in which steps will be executed. In this case:
+
+1. `send_welcome_email`
+2. `send_reminder` (inserted after `send_welcome_email`)
+3. `compliance_check` (inserted before `send_premium_offer`)
+4. `send_premium_offer`
+5. `complete_onboarding`
 
 ### Using instance methods as steps
 
@@ -515,6 +548,123 @@ It is possible to store instance variables on the `Journey` instance, but they d
 > This means that the volatile state such as instance variables is not going to be available between steps. Always assume that
 > the `Journey` you are inside of does not have any instance variables set by previous steps and has just been freshly loaded from the database.
 
+### Blanket step conditions with `cancel_if`
+
+In addition to conditional steps that can be skipped, you can define blanket conditions that apply to all steps in a journey using `cancel_if`. These conditions are evaluated after the journey's state is set to `performing` but before any step execution begins. If any `cancel_if` condition is satisfied, the entire journey is canceled immediately.
+
+`cancel_if` works like Rails' `etag` - it's class-inheritable and appendable. You can call `cancel_if` multiple times in a journey definition, and all conditions will be evaluated.
+
+#### Using blocks with `cancel_if`
+
+The most common way to use `cancel_if` is with a block that gets evaluated in the context of the journey:
+
+```ruby
+class UserOnboardingJourney < StepperMotor::Journey
+  cancel_if { hero.deactivated? }
+  cancel_if { hero.account_closed? }
+
+  step :send_welcome_email do
+    WelcomeMailer.welcome(hero).deliver_later
+  end
+
+  step :send_premium_offer, wait: 2.days do
+    PremiumOfferMailer.exclusive_offer(hero).deliver_later
+  end
+
+  step :complete_onboarding, wait: 7.days do
+    hero.update!(onboarding_completed_at: Time.current)
+  end
+end
+```
+
+In this example, if the user becomes deactivated or closes their account at any point during the onboarding journey, the entire journey will be canceled and no further steps will be executed.
+
+#### Using positional arguments with `cancel_if`
+
+You can also pass conditions directly as arguments to `cancel_if`:
+
+```ruby
+class PaymentProcessingJourney < StepperMotor::Journey
+  cancel_if :payment_canceled?
+  cancel_if { hero.amount > 10000 }  # Cancel if amount exceeds limit
+
+  step :validate_payment do
+    PaymentValidator.validate(hero)
+  end
+
+  step :process_payment do
+    PaymentProcessor.charge(hero)
+  end
+
+  step :send_confirmation do
+    PaymentConfirmationMailer.confirm(hero).deliver_later
+  end
+
+  private
+
+  def payment_canceled?
+    hero.canceled_at.present?
+  end
+end
+```
+
+#### Supported condition types
+
+`cancel_if` accepts the same types of conditions as `skip_if`:
+
+* **Symbols**: Method names that return a boolean
+* **Blocks**: Callable blocks that return a boolean
+* **Booleans**: Literal `true` or `false` values
+* **Arrays**: Arrays of conditions (all must be true)
+* **Procs/Lambdas**: Callable objects
+* **Conditional objects**: `StepperMotor::Conditional` instances
+* **Nil**: Treated as `false` (doesn't cancel)
+
+#### Multiple `cancel_if` conditions
+
+You can define multiple `cancel_if` conditions, and any one of them being satisfied will cancel the journey:
+
+```ruby
+class EmailCampaignJourney < StepperMotor::Journey
+  cancel_if { hero.unsubscribed? }
+  cancel_if { hero.bounced? }
+  cancel_if { hero.complained? }
+  cancel_if { hero.deactivated? }
+
+  step :send_initial_email do
+    CampaignMailer.initial(hero).deliver_later
+  end
+
+  step :send_follow_up, wait: 3.days do
+    CampaignMailer.follow_up(hero).deliver_later
+  end
+
+  step :send_final_reminder, wait: 7.days do
+    CampaignMailer.final_reminder(hero).deliver_later
+  end
+end
+```
+
+#### Inheritance and appendability
+
+`cancel_if` conditions are class-inheritable and appendable, just like Rails' `etag`:
+
+```ruby
+class BaseJourney < StepperMotor::Journey
+  cancel_if { hero.deactivated? }
+end
+
+class PremiumUserJourney < BaseJourney
+  cancel_if { hero.subscription_expired? }  # Adds to parent's conditions
+
+  step :send_premium_content do
+    PremiumContentMailer.send_content(hero).deliver_later
+  end
+end
+```
+
+In this example, `PremiumUserJourney` will cancel if either the user is deactivated (from the parent class) or if their subscription has expired (from the child class).
+
 
 ### Waiting for the start of the step
 
@@ -531,6 +681,25 @@ end
 
 The `wait:` parameter defines the amount of time computed **from the moment the Journey gets created or the previous step is completed.**
 
+## Execution model: assume that everything is async
+
+stepper_motor is built on the assumption that steps should be able to execute asynchronously. This is a **very important** design trait which has a number of implications:
+
+* You will almost never have the same `self` for a Journey between multiple steps
+* Any instance variables you set inside a step will get discarded and will not be available in a subsequent step
+* Any step may want to reattempt itself at an arbitrary point in the future. Any stack variables or local state will be discarded.
+
+This is deliberate and intentional. At the moment, stepper_motor does not have any built-in primitives for executing multiple steps inline. The `speedrun_journey`
+helper used in tests is going to `reload` your Journey between step entries, to allow for any state changes to be blown away - but it is not going to reset any instance variables.
+
+A good way to think about it is: every step execution happens:
+
+* On a different machine
+* In a different thread
+* In a different database transaction
+* In the context of a different Journey instance
+* Potentially - after a long time has passed since the previous attempt or previous step
+
 ## Journey states
 
 The Journeys are managed using a state machine, which stepper_motor completely coordinates for you. The states are as follows: