opera 0.5.0 → 0.6.0

data/docs/examples/within.md

@@ -0,0 +1,166 @@
+# Within
+
+`within` wraps one or more steps with a method you define on the operation. The method must `yield` to execute the nested steps. If it does not yield, the nested steps are skipped. Normal break conditions (errors, `finish!`) still apply inside the block.
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account
+  end
+
+  step :build
+
+  within :read_from_replica do
+    step :check_duplicate
+    step :validate_quota
+  end
+
+  step :create
+  step :output
+
+  def build
+    self.profile = current_account.profiles.build(params)
+  end
+
+  def check_duplicate
+    result.add_error(:base, 'already exists') if Profile.exists?(email: params[:email])
+  end
+
+  def validate_quota
+    result.add_error(:base, 'quota exceeded') if current_account.profiles.count >= 100
+  end
+
+  def create
+    profile.save!
+  end
+
+  def output
+    result.output = { model: profile }
+  end
+
+  private
+
+  def read_from_replica(&block)
+    ActiveRecord::Base.connected_to(role: :reading, &block)
+  end
+end
+```
+
+## Inline usage
+
+The wrapper method can also be used inline inside any step method when you need the wrapper for only part of that method's logic:
+
+```ruby
+def some_step
+  value = read_from_replica { Profile.count }
+  result.output = { count: value }
+end
+
+private
+
+def read_from_replica(&block)
+  ActiveRecord::Base.connected_to(role: :reading, &block)
+end
+```
+
+## Mixing step and operation inside within
+
+`within` can wrap any combination of `step` and `operation` instructions. All of them execute inside the wrapper, and their outputs are available in context afterwards as usual.
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account, :quota_checker
+  end
+
+  within :read_from_replica do
+    step :check_duplicate
+    operation :fetch_quota
+  end
+
+  step :create
+  step :output
+
+  def check_duplicate
+    result.add_error(:base, 'already exists') if Profile.exists?(email: params[:email])
+  end
+
+  def fetch_quota
+    quota_checker.call(params: params)
+  end
+
+  def create
+    self.profile = current_account.profiles.create(params)
+  end
+
+  def output
+    result.output = { model: profile, quota: context[:fetch_quota_output] }
+  end
+
+  private
+
+  def read_from_replica(&block)
+    ActiveRecord::Base.connected_to(role: :reading, &block)
+  end
+end
+```
+
+## Nesting within inside a transaction
+
+`within` can be placed inside a `transaction` block alongside other instructions. If any step or operation inside `within` fails, the error propagates up and the transaction is rolled back as normal.
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  configure do |config|
+    config.transaction_class = ActiveRecord::Base
+  end
+
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account, :quota_checker, :audit_logger
+  end
+
+  transaction do
+    within :read_from_replica do
+      step :check_duplicate
+      operation :fetch_quota
+    end
+    operation :write_audit_log
+  end
+
+  step :output
+
+  def check_duplicate
+    result.add_error(:base, 'already exists') if Profile.exists?(email: params[:email])
+  end
+
+  def fetch_quota
+    quota_checker.call(params: params)
+  end
+
+  def write_audit_log
+    audit_logger.call(params: params)
+  end
+
+  def output
+    result.output = { quota: context[:fetch_quota_output] }
+  end
+
+  private
+
+  def read_from_replica(&block)
+    ActiveRecord::Base.connected_to(role: :reading, &block)
+  end
+end
+```

data/lib/opera/operation/builder.rb

@@ -3,7 +3,8 @@
 module Opera
   module Operation
     module Builder
-      INSTRUCTIONS = %I[validate transaction step success finish_if operation operations within].freeze
+      INSTRUCTIONS = %I[validate transaction step success finish_if operation operations within always].freeze
+      INNER_INSTRUCTIONS = (INSTRUCTIONS - %I[always]).freeze
 
       def self.included(base)
         base.extend(ClassMethods)
@@ -14,12 +15,23 @@ module Opera
           @instructions ||= []
         end
 
-        INSTRUCTIONS.each do |instruction|
+        INNER_INSTRUCTIONS.each do |instruction|
           define_method instruction do |method = nil, &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))
           end
         end
+
+        def always(method)
+          check_method_availability!(method)
+          instructions << { kind: :always, method: method }
+        end
       end
 
       class InnerBuilder
@@ -30,7 +42,7 @@ module Opera
           instance_eval(&block) if block_given?
         end
 
-        INSTRUCTIONS.each do |instruction|
+        INNER_INSTRUCTIONS.each do |instruction|
           define_method instruction do |method = nil, &blk|
             instructions << if !blk.nil?
                               {
@@ -46,6 +58,12 @@ module Opera
                             end
           end
         end
+
+        def always(_method)
+          raise ArgumentError,
+                '`always` cannot be used inside a block (transaction, within, success, validate). ' \
+                'Place `always` steps at the top level of the operation, after all other instructions.'
+        end
       end
     end
   end

data/lib/opera/operation/config.rb

@@ -17,7 +17,7 @@ module Opera
         @instrumentation_class = self.class.instrumentation_class
 
         @mode = self.class.mode || DEVELOPMENT_MODE
-        @reporter = custom_reporter || self.class.reporter
+        @reporter = self.class.reporter
 
         validate!
       end
@@ -26,10 +26,6 @@ module Opera
         yield self
       end
 
-      def custom_reporter
-        Rails.application.config.x.reporter.presence if defined?(Rails)
-      end
-
       private
 
       def validate!
@@ -47,7 +43,7 @@ module Opera
         end
 
         def development_mode?
-          mode == DEFAULT_MODE
+          mode == DEVELOPMENT_MODE
         end
 
         def production_mode?

data/lib/opera/operation/executor.rb

@@ -20,12 +20,22 @@ module Opera
       end
 
       def evaluate_instructions(instructions = [])
-        instruction_copy = Marshal.load(Marshal.dump(instructions))
+        instructions.each do |instruction|
+          next if instruction[:kind] != :always && break_condition
 
-        while instruction_copy.any?
-          instruction = instruction_copy.shift
           evaluate_instruction(instruction)
-          break if break_condition
+        end
+      end
+
+      # Executes the operation method named in the instruction, instruments it,
+      # and records the execution. This is the shared primitive that all executors
+      # use to invoke a step method without mutating the instruction hash.
+      def execute_step(instruction)
+        method = instruction[:method]
+
+        Instrumentation.new(operation).instrument(name: "##{method}", level: :step) do
+          result.add_execution(method) unless production_mode?
+          operation.send(method)
         end
       end
 
@@ -48,6 +58,8 @@ module Opera
           Instructions::Executors::FinishIf.new(operation).call(instruction)
         when :within
           Instructions::Executors::Within.new(operation).call(instruction)
+        when :always
+          Instructions::Executors::Always.new(operation).call(instruction)
         else
           raise(UnknownInstructionError, "Unknown instruction #{instruction[:kind]}")
         end

data/lib/opera/operation/instructions/executors/always.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Opera
+  module Operation
+    module Instructions
+      module Executors
+        class Always < Executor
+          def call(instruction)
+            execute_step(instruction)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opera/operation/instructions/executors/finish_if.rb

@@ -6,8 +6,7 @@ module Opera
       module Executors
         class FinishIf < Executor
           def call(instruction)
-            instruction[:kind] = :step
-            operation.finish! if super
+            operation.finish! if execute_step(instruction)
           end
         end
       end

data/lib/opera/operation/instructions/executors/operation.rb

@@ -6,8 +6,7 @@ module Opera
       module Executors
         class Operation < Executor
           def call(instruction)
-            instruction[:kind] = :step
-            operation_result = super
+            operation_result = execute_step(instruction)
             save_information(operation_result)
 
             if operation_result.success?

data/lib/opera/operation/instructions/executors/operations.rb

@@ -9,8 +9,7 @@ module Opera
 
           # rubocop:disable Metrics/MethodLength
           def call(instruction)
-            instruction[:kind] = :step
-            operations_results = super
+            operations_results = execute_step(instruction)
 
             case operations_results
             when Array

data/lib/opera/operation/instructions/executors/step.rb

@@ -6,12 +6,7 @@ module Opera
       module Executors
         class Step < Executor
           def call(instruction)
-            method = instruction[:method]
-
-            Instrumentation.new(operation).instrument(name: "##{method}", level: :step) do
-              operation.result.add_execution(method) unless production_mode?
-              operation.send(method)
-            end
+            execute_step(instruction)
           end
         end
       end

data/lib/opera/operation/instructions/executors/success.rb

@@ -6,8 +6,11 @@ module Opera
       module Executors
         class Success < Executor
           def call(instruction)
-            instruction[:kind] = :step
-            super
+            if instruction[:instructions]
+              evaluate_instructions(instruction[:instructions])
+            else
+              execute_step(instruction)
+            end
           end
 
           def break_condition

data/lib/opera/operation/instructions/executors/validate.rb

@@ -12,8 +12,7 @@ module Opera
           private
 
           def evaluate_instruction(instruction)
-            instruction[:kind] = :step
-            validation_result = super
+            validation_result = execute_step(instruction)
 
             case validation_result
             when Opera::Operation::Result

data/lib/opera/operation/instructions/executors/within.rb

@@ -13,7 +13,7 @@ module Opera
             raise ArgumentError, 'within requires a block with at least one instruction' if nested_instructions.nil?
 
             operation.send(wrapper_method) do
-              super
+              evaluate_instructions(nested_instructions)
             end
           end
         end

data/lib/opera/operation.rb

@@ -15,6 +15,7 @@ require 'opera/operation/instructions/executors/operation'
 require 'opera/operation/instructions/executors/operations'
 require 'opera/operation/instructions/executors/step'
 require 'opera/operation/instructions/executors/within'
+require 'opera/operation/instructions/executors/always'
 
 module Opera
   module Operation

data/lib/opera/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opera
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - ProFinda Development Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-14 00:00:00.000000000 Z
+date: 2026-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-validation
@@ -73,9 +73,19 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- benchmarks/operation_benchmark.rb
 - bin/console
 - bin/setup
 - docker-compose.yml
+- docs/examples/always.md
+- docs/examples/basic-operation.md
+- docs/examples/context-params-dependencies.md
+- docs/examples/finish-if.md
+- docs/examples/inner-operations.md
+- docs/examples/success-blocks.md
+- docs/examples/transactions.md
+- docs/examples/validations.md
+- docs/examples/within.md
 - lib/opera.rb
 - lib/opera/errors.rb
 - lib/opera/operation.rb
@@ -84,6 +94,7 @@ files:
 - lib/opera/operation/builder.rb
 - lib/opera/operation/config.rb
 - lib/opera/operation/executor.rb
+- lib/opera/operation/instructions/executors/always.rb
 - lib/opera/operation/instructions/executors/finish_if.rb
 - lib/opera/operation/instructions/executors/operation.rb
 - lib/opera/operation/instructions/executors/operations.rb