Add if/unless support

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Opera Changelog
 
+### 0.7.0 - Apr 30, 2026
+
+- Add `:if` / `:unless` options to `step`, `operation`, and `operations` for declarative conditional execution. Conditions accept a Symbol (method name) or a Proc/Lambda (evaluated via `instance_exec` in the operation instance scope). Skipped steps do not execute and are not recorded in `result.executions`. For `operation` / `operations`, the conventional `<method>_output` slot in context is set to `nil` when skipped, matching the historical `return Opera::Operation::Result.new` early-exit behavior. Passing both `:if` and `:unless` on the same step raises `ArgumentError` at class load time.
+
 ### 0.6.0 - Apr 15, 2026
 
 - Add `always` executor: runs its step unconditionally after all regular steps, regardless of failure or an early finish

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    opera (0.6.0)
+    opera (0.7.0)
 
 GEM
   remote: https://rubygems.org/

README.md

@@ -124,6 +124,40 @@ end
 | `within :method do ... end`               | Wraps nested steps with a custom method that must `yield`. If it doesn't yield, nested steps are skipped.                                                                                                                                                                                         |
 | `always :method`                          | Executes a step unconditionally after all regular steps, even after a failure or an early finish. Must appear at the end of the operation — only other `always` steps may follow. Cannot be used inside blocks. Use `result.success?` / `result.failure?` inside the method to branch on outcome. |
 
+### Conditional execution (`:if` / `:unless`)
+
+`step`, `operation`, and `operations` accept `:if` and `:unless` keyword
+arguments for declarative conditional execution. The condition is evaluated
+**before** the step's method is called -- if the condition is not met the
+step is skipped entirely (no method invocation, no side effects, not recorded
+in `result.executions`).
+
+The condition value can be a **Symbol** (method name on the operation) or a
+**Proc/Lambda** (evaluated via `instance_exec` in the operation instance
+scope).
+
+```ruby
+# Symbol form
+step    :notify_user,                if: :notifications_enabled?
+operation :create_internal_experience, if: :internal_experience_authorized?
+
+# Lambda form
+step      :recalculate, unless: -> { params[:skip_recalculation] }
+operation :reopen_and_reset, if: -> { profile_ids.present? }
+```
+
+When an `operation` or `operations` step is skipped, its
+`context[:<method>_output]` slot is set to `nil` (matching the historical
+`return Opera::Operation::Result.new` early-exit behavior). When a plain
+`step` is skipped, no context output is set.
+
+Passing both `:if` and `:unless` on the same step raises `ArgumentError` at
+class load time.
+
+`:if` / `:unless` are not supported on `validate`, `success`, `finish_if`,
+`transaction`, `within`, or `always` -- conditional containers and validation
+have ambiguous semantics.
+
 ### Combining instructions
 
 ```ruby

lib/opera/operation.rb

@@ -2,6 +2,7 @@
 
 require 'opera/operation/attributes_dsl'
 require 'opera/operation/builder'
+require 'opera/operation/builder/options_builder'
 require 'opera/operation/base'
 require 'opera/operation/executor'
 require 'opera/operation/instrumentation'

lib/opera/operation/builder.rb

@@ -16,15 +16,15 @@ def instructions
         end
 
         INNER_INSTRUCTIONS.each do |instruction|
-          define_method instruction do |method = nil, &blk|
+          define_method instruction do |method = nil, **opts, &blk|
             if instructions.any? { |i| i[:kind] == :always }
               raise ArgumentError,
                     "`#{instruction}` cannot appear after `always`. " \
                     'All `always` steps must be at the end of the operation.'
             end
 
             check_method_availability!(method) if method
-            instructions.concat(InnerBuilder.new.send(instruction, method, &blk))
+            instructions.concat(InnerBuilder.new.send(instruction, method, **opts, &blk))
           end
         end
 
@@ -43,19 +43,13 @@ def initialize(&block)
         end
 
         INNER_INSTRUCTIONS.each do |instruction|
-          define_method instruction do |method = nil, &blk|
-            instructions << if !blk.nil?
-                              {
-                                kind: instruction,
-                                label: method,
-                                instructions: InnerBuilder.new(&blk).instructions
-                              }
-                            else
-                              {
-                                kind: instruction,
-                                method: method
-                              }
-                            end
+          define_method instruction do |method = nil, **opts, &blk|
+            entry = if blk
+                      { kind: instruction, label: method, instructions: InnerBuilder.new(&blk).instructions }
+                    else
+                      { kind: instruction, method: method }
+                    end
+            instructions << entry.merge(OptionsBuilder.build(opts))
           end
         end
 

lib/opera/operation/builder/options_builder.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Opera
+  module Operation
+    module Builder
+      # Parses keyword options passed to a Builder instruction (`step`,
+      # `operation`, `transaction`, etc.) into a normalized hash that is merged
+      # into the instruction entry.
+      #
+      # Currently understands `:if` and `:unless`. New options can be added by
+      # extending ALLOWED_OPTIONS and the build logic.
+      class OptionsBuilder
+        ALLOWED_OPTIONS = %i[if unless].freeze
+
+        def self.build(opts)
+          return {} if opts.empty?
+
+          unknown = opts.keys - ALLOWED_OPTIONS
+          raise ArgumentError, "Unknown option(s): #{unknown.inspect}. Allowed: #{ALLOWED_OPTIONS}" if unknown.any?
+
+          { predicate: build_predicate(opts) }.compact
+        end
+
+        # Translates `:if` / `:unless` (Symbol or Proc) into a single Proc that
+        # returns true when the step should run. Returns nil when neither is
+        # given. Raises if both are given.
+        def self.build_predicate(opts)
+          return nil unless opts[:if] || opts[:unless]
+          raise ArgumentError, 'Cannot use both :if and :unless on the same step' if opts[:if] && opts[:unless]
+
+          cond = opts[:if] || opts[:unless]
+          body = cond.is_a?(Symbol) ? proc { send(cond) } : cond
+          opts.key?(:if) ? body : proc { !instance_exec(&body) }
+        end
+      end
+    end
+  end
+end

lib/opera/operation/executor.rb

@@ -41,6 +41,11 @@ def execute_step(instruction)
 
       # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity
       def evaluate_instruction(instruction)
+        if instruction[:predicate] && !condition_met?(instruction)
+          add_instruction_output(instruction, nil) if %i[operation operations].include?(instruction[:kind])
+          return
+        end
+
         case instruction[:kind]
         when :step
           Instructions::Executors::Step.new(operation).call(instruction)
@@ -66,6 +71,14 @@ def evaluate_instruction(instruction)
       end
       # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity
 
+      # Evaluates the `:predicate` Proc stored on a conditionable instruction.
+      # The predicate is built at class-load time from `:if` / `:unless` and
+      # already encodes the negation for `:unless`, so the executor only needs
+      # to call it in the operation instance scope.
+      def condition_met?(instruction)
+        operation.instance_exec(&instruction[:predicate])
+      end
+
       def result
         operation.result
       end

lib/opera/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Opera
-  VERSION = '0.6.0'
+  VERSION = '0.7.0'
 end