opera 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d601d62d89303ad4efaa6ab156894bdcd247964977f3bb23fd43f2236cdf7655
-  data.tar.gz: 42c7cb409cec7f9dc66cd63dd723d39170cc5c02c5704e79d886869570b7775e
+  metadata.gz: ae5c55f72cf9337e2974bc15f8a834d8e2ec8517f092dcd62c986ebcfe81ef22
+  data.tar.gz: f89c957b5c457d1a3981523dffdc608778a4b3d7e5baeb1c2cbbe10a0f0aacb1
 SHA512:
-  metadata.gz: 3725001498c05f07eae31e1f85e9801833820a1f4a4c8175e9fff13977390c6aaad4da5d3787b669fe7ddf4f84fd65752857f16bc0c84d822a3bff97b10b7467
-  data.tar.gz: 50a96d11c1f419bfc82934403793814029f088ba2b48d8df9083ee3f5383937dc95cc312339c1ce8619fc1358bd9e2b23aac3124aca6e4b61269fd5efacb93ae
+  metadata.gz: 9371d589bfa9d5d24cf67d1cbd065aa0622a7e768901fa0430c4510c64934b0a1b13c679cf044554facf9dc53684d597aed3e2ed228b96236642f1edba2b8978
+  data.tar.gz: c6810a27ce251b4c1db8cf5f2884e49ffd74467d7fb8015d536cef79c646bd1b393401009075515c21a72b64aa036bbe73710b14f93b2ffb3ded561d0ba516e4

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Opera Changelog
 
+### 0.7.1 - Sep 07, 2026
+
+- Automatically define a `<method>_output` reader for every `operation` / `operations` instruction, so the output of an inner operation is readable in later steps without a manual `context { attr_reader :<method>_output }` declaration. The reader returns the value stored at `context[:<method>_output]`, which remains accessible directly as before. If a reader with that name is already declared before the instruction (following the convention of declaring `context` / `params` / `dependencies` above the DSL steps), the manual one is kept and no automatic reader is created.
+
+### 0.7.0 - Apr 30, 2026
+
+- Add `:if` / `:unless` options to all instructions except `always` (`validate`, `transaction`, `step`, `success`, `finish_if`, `operation`, `operations`, `within`) for declarative conditional execution. Conditions accept a Symbol (method name) or a Proc/Lambda (evaluated via `instance_exec` in the operation instance scope). Skipped instructions do not execute and are not recorded in `result.executions`; for block instructions (`transaction`, `within`) the whole block, including nested instructions, is skipped. 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 instruction 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

data/Gemfile.lock

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

data/README.md

@@ -124,6 +124,38 @@ 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`)
+
+The `:if` and `:unless` keyword arguments provide declarative conditional
+execution. They are supported on `validate`, `transaction`, `step`, `success`,
+`finish_if`, `operation`, `operations`, and `within` (every instruction except
+`always`). For block instructions (`transaction`, `within`), a falsy condition
+skips the whole block, including its nested instructions.
+
+The condition is evaluated **before** the instruction runs -- if the condition
+is not met the instruction 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?
+
+# Lambda form
+step :recalculate, unless: -> { params[:skip_recalculation] }
+```
+
+When an `operation` or `operations` instruction is skipped, its
+`context[:<method>_output]` slot is set to `nil` (matching the historical
+`return Opera::Operation::Result.new` early-exit behavior). For other
+instructions no context output is set.
+
+Passing both `:if` and `:unless` on the same instruction raises `ArgumentError`
+at class load time.
+
 ### Combining instructions
 
 ```ruby

data/docs/examples/inner-operations.md

@@ -4,6 +4,8 @@
 
 Use `operation` to call another Opera operation from within a step. The method must return an `Opera::Operation::Result`. If the inner operation fails, errors are propagated and execution stops. If it succeeds, its output is stored in context as `:<method_name>_output`.
 
+Opera also defines a `<method_name>_output` reader automatically, so you can access the output directly in later steps without declaring `context { attr_reader :<method_name>_output }` yourself. Both `context[:<method_name>_output]` and the reader return the same value.
+
 ```ruby
 class Profile::Find < Opera::Operation::Base
   step :find
@@ -33,12 +35,13 @@ class Profile::Create < Opera::Operation::Base
   end
 
   def create
-    return if context[:find_output]
+    # `find_output` is the auto-generated reader for `operation :find`
+    return if find_output
     puts 'not found'
   end
 
   def output
-    result.output = { model: context[:find_output] }
+    result.output = { model: find_output }
   end
 end
 ```
@@ -82,7 +85,8 @@ class Profile::CreateMultiple < Opera::Operation::Base
   end
 
   def output
-    result.output = context[:create_multiple_output]
+    # `create_multiple_output` is the auto-generated reader for `operations :create_multiple`
+    result.output = create_multiple_output
   end
 end
 ```

data/lib/opera/operation/builder/options_builder.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Opera
+  module Operation
+    module Builder
+      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
+
+        def self.build_predicate(opts)
+          return nil unless opts[:if] || opts[:unless]
+          raise ArgumentError, 'Cannot use :if and :unless together' if opts[:if] && opts[:unless]
+
+          cond = opts[:if] || opts[:unless]
+          condition_proc = cond.is_a?(Symbol) ? proc { send(cond) } : cond
+          opts.key?(:if) ? condition_proc : proc { !instance_exec(&condition_proc) }
+        end
+      end
+    end
+  end
+end

data/lib/opera/operation/builder.rb

@@ -5,6 +5,7 @@ module Opera
     module Builder
       INSTRUCTIONS = %I[validate transaction step success finish_if operation operations within always].freeze
       INNER_INSTRUCTIONS = (INSTRUCTIONS - %I[always]).freeze
+      OUTPUT_INSTRUCTIONS = %I[operation operations].freeze
 
       def self.included(base)
         base.extend(ClassMethods)
@@ -16,7 +17,7 @@ module Opera
         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`. " \
@@ -24,7 +25,8 @@ module Opera
             end
 
             check_method_availability!(method) if method
-            instructions.concat(InnerBuilder.new.send(instruction, method, &blk))
+            define_output_reader(method) if method && OUTPUT_INSTRUCTIONS.include?(instruction)
+            instructions.concat(InnerBuilder.new.send(instruction, method, **opts, &blk))
           end
         end
 
@@ -32,6 +34,13 @@ module Opera
           check_method_availability!(method)
           instructions << { kind: :always, method: method }
         end
+
+        def define_output_reader(method)
+          reader = :"#{method}_output"
+          return unless instance_methods(false).none?(reader)
+
+          context { attr_reader(reader) }
+        end
       end
 
       class InnerBuilder
@@ -43,19 +52,13 @@ module Opera
         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
 

data/lib/opera/operation/executor.rb

@@ -41,6 +41,11 @@ module Opera
 
       # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity
       def evaluate_instruction(instruction)
+        if instruction[:predicate] && !operation.instance_exec(&instruction[:predicate])
+          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)

data/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'

data/lib/opera/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opera
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.1
 platform: ruby
 authors:
 - ProFinda Development Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-16 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-validation
@@ -92,6 +92,7 @@ files:
 - lib/opera/operation/attributes_dsl.rb
 - lib/opera/operation/base.rb
 - lib/opera/operation/builder.rb
+- lib/opera/operation/builder/options_builder.rb
 - lib/opera/operation/config.rb
 - lib/opera/operation/executor.rb
 - lib/opera/operation/instructions/executors/always.rb