opera 0.5.0 → 0.6.0

data/benchmarks/operation_benchmark.rb

@@ -0,0 +1,385 @@
+# frozen_string_literal: true
+
+# Performance benchmark for Opera operations.
+#
+# Exercises the full execution path: step dispatch, instruction iteration,
+# context accessors, validate, transaction, success, finish_if, operation,
+# operations, within, and always -- with nested inner operations and loops to
+# simulate realistic workloads.
+#
+# Usage:
+#   ruby benchmarks/operation_benchmark.rb
+
+require 'bundler/setup'
+require 'benchmark'
+require 'opera'
+
+# ---------------------------------------------------------------------------
+# Fake transaction class (no DB, just yields)
+# ---------------------------------------------------------------------------
+FakeTransaction = Class.new do
+  def self.transaction
+    yield
+  end
+end
+
+Opera::Operation::Config.configure do |config|
+  config.transaction_class = FakeTransaction
+  config.mode = :production # skip execution traces, like real production
+end
+
+# ---------------------------------------------------------------------------
+# Leaf operation — called many times from within loops
+# ---------------------------------------------------------------------------
+LeafOperation = Class.new(Opera::Operation::Base) do
+  step :compute
+  step :output
+
+  def compute
+    context[:value] = params.fetch(:n, 1) * 2
+  end
+
+  def output
+    result.output = { value: context[:value] }
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Inner operation — calls LeafOperation in a loop
+# ---------------------------------------------------------------------------
+InnerOperation = Class.new(Opera::Operation::Base) do
+  context do
+    attr_accessor :results
+  end
+
+  step :process_batch
+  step :output
+
+  def process_batch
+    self.results = (1..params.fetch(:batch_size, 5)).map do |n|
+      LeafOperation.call(params: { n: n })
+    end
+  end
+
+  def output
+    result.output = { batch: results.map(&:output) }
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Validation-heavy operation
+# ---------------------------------------------------------------------------
+ValidationOperation = Class.new(Opera::Operation::Base) do
+  validate :schema
+
+  step :transform
+  step :output
+
+  def schema
+    # Return a successful Opera::Operation::Result (simulates dry-validation)
+    Opera::Operation::Result.new(output: params)
+  end
+
+  def transform
+    context[:transformed] = params.transform_values { |v| v.to_s.upcase }
+  end
+
+  def output
+    result.output = context[:transformed]
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Complex operation — combines everything
+# ---------------------------------------------------------------------------
+ComplexOperation = Class.new(Opera::Operation::Base) do
+  configure do |config|
+    config.transaction_class = FakeTransaction
+  end
+
+  context do
+    attr_accessor :profile, :batch_results, :validated
+  end
+
+  validate :schema
+
+  step :prepare
+  finish_if :skip_processing?
+
+  transaction do
+    step :create_record
+    step :update_record
+  end
+
+  operation :run_inner
+
+  within :with_timing do
+    step :heavy_computation
+  end
+
+  success do
+    step :notify
+    step :log_audit
+  end
+
+  step :processing_error
+
+  always :output
+
+  def schema
+    Opera::Operation::Result.new(output: params)
+  end
+
+  def prepare
+    self.validated = context[:schema_output]
+    context[:counter] = 0
+  end
+
+  def skip_processing?
+    params[:skip] == true
+  end
+
+  def create_record
+    self.profile = { id: rand(1000), name: validated[:name] }
+  end
+
+  def update_record
+    profile[:updated_at] = Time.now.to_i
+  end
+
+  def run_inner
+    InnerOperation.call(params: { batch_size: params.fetch(:batch_size, 5) })
+  end
+
+  def heavy_computation
+    # Simulate CPU work: string operations in a loop
+    50.times do |i|
+      context[:counter] += i
+      "operation-#{i}-#{context[:counter]}".hash
+    end
+  end
+
+  def notify
+    context[:notified] = true
+  end
+
+  def log_audit
+    context[:audited] = true
+  end
+
+  def processing_error
+    result.add_error(:base, 'processing failed')
+  end
+
+  def output
+    result.output = {
+      profile: profile,
+      counter: context[:counter],
+      batch: context[:run_inner_output]
+    }
+  end
+
+  def with_timing
+    yield
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Within operation — wraps steps and inner operations with a custom method
+# ---------------------------------------------------------------------------
+WithinOperation = Class.new(Opera::Operation::Base) do
+  configure do |config|
+    config.transaction_class = FakeTransaction
+  end
+
+  context do
+    attr_accessor :log, default: -> { [] }
+  end
+
+  step :prepare
+
+  within :with_connection do
+    step :query_one
+    step :query_two
+    operation :fetch_leaf
+  end
+
+  transaction do
+    within :with_lock do
+      step :write_one
+      step :write_two
+    end
+    step :write_three
+  end
+
+  step :output
+
+  def prepare
+    context[:counter] = 0
+  end
+
+  def query_one
+    context[:counter] += 1
+    log << :query_one
+  end
+
+  def query_two
+    context[:counter] += 1
+    log << :query_two
+  end
+
+  def fetch_leaf
+    LeafOperation.call(params: { n: context[:counter] })
+  end
+
+  def write_one
+    context[:counter] += 10
+    log << :write_one
+  end
+
+  def write_two
+    context[:counter] += 10
+    log << :write_two
+  end
+
+  def write_three
+    context[:counter] += 1
+    log << :write_three
+  end
+
+  def output
+    result.output = {
+      counter: context[:counter],
+      log: log,
+      leaf: context[:fetch_leaf_output]
+    }
+  end
+
+  def with_connection
+    log << :connect
+    yield
+    log << :disconnect
+  end
+
+  def with_lock
+    log << :lock
+    yield
+    log << :unlock
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Operations (plural) consumer — calls multiple inner operations
+# ---------------------------------------------------------------------------
+BatchOperation = Class.new(Opera::Operation::Base) do
+  operations :run_all
+  step :output
+
+  def run_all
+    (1..params.fetch(:count, 3)).map do |n|
+      LeafOperation.call(params: { n: n })
+    end
+  end
+
+  def output
+    result.output = context[:run_all_output]
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Always operation — exercises always steps on both success and failure paths
+# ---------------------------------------------------------------------------
+AlwaysOperation = Class.new(Opera::Operation::Base) do
+  context do
+    attr_accessor :log, default: -> { [] }
+  end
+
+  step :prepare
+  step :process
+  always :audit
+  always :cleanup
+
+  def prepare
+    log << :prepare
+    context[:value] = params.fetch(:value, 0)
+  end
+
+  def process
+    if params[:fail]
+      result.add_error(:base, 'processing failed')
+    else
+      context[:value] *= 2
+      log << :process
+    end
+  end
+
+  def audit
+    log << (result.success? ? :audit_success : :audit_failure)
+    result.output = { value: context[:value], log: log, success: result.success?, failure: result.failure? }
+  end
+
+  def cleanup
+    log << :cleanup
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Benchmark
+# ---------------------------------------------------------------------------
+ITERATIONS = 1000
+PARAMS = { name: 'benchmark', batch_size: 5 }.freeze
+BATCH_PARAMS = { count: 5 }.freeze
+VALIDATION_PARAMS = { first_name: 'Jane', last_name: 'Doe', email: 'jane@example.com' }.freeze
+WITHIN_PARAMS = {}.freeze
+ALWAYS_SUCCESS_PARAMS = { value: 21 }.freeze
+ALWAYS_FAILURE_PARAMS = { value: 21, fail: true }.freeze
+
+# Warm up
+3.times do
+  ComplexOperation.call(params: PARAMS)
+  BatchOperation.call(params: BATCH_PARAMS)
+  ValidationOperation.call(params: VALIDATION_PARAMS)
+  WithinOperation.call(params: WITHIN_PARAMS)
+  AlwaysOperation.call(params: ALWAYS_SUCCESS_PARAMS)
+  AlwaysOperation.call(params: ALWAYS_FAILURE_PARAMS)
+end
+
+puts "Opera v#{Opera::VERSION} — #{ITERATIONS} iterations each"
+puts "Ruby #{RUBY_VERSION} (#{RUBY_PLATFORM})"
+puts '-' * 60
+
+Benchmark.bm(35) do |x|
+  x.report('ComplexOperation (nested + tx):') do
+    ITERATIONS.times { ComplexOperation.call(params: PARAMS) }
+  end
+
+  x.report('BatchOperation (operations):') do
+    ITERATIONS.times { BatchOperation.call(params: BATCH_PARAMS) }
+  end
+
+  x.report('ValidationOperation (validate):') do
+    ITERATIONS.times { ValidationOperation.call(params: VALIDATION_PARAMS) }
+  end
+
+  x.report('WithinOperation (within + tx):') do
+    ITERATIONS.times { WithinOperation.call(params: WITHIN_PARAMS) }
+  end
+
+  x.report('LeafOperation (minimal):') do
+    ITERATIONS.times { LeafOperation.call(params: { n: 42 }) }
+  end
+
+  x.report('AlwaysOperation (success path):') do
+    ITERATIONS.times { AlwaysOperation.call(params: ALWAYS_SUCCESS_PARAMS) }
+  end
+
+  x.report('AlwaysOperation (failure path):') do
+    ITERATIONS.times { AlwaysOperation.call(params: ALWAYS_FAILURE_PARAMS) }
+  end
+
+  # Total operations executed in ComplexOperation run:
+  # 1 complex + 1 inner + 5 leaf = 7 operations per iteration
+  # = 7000 total operation instantiations for ComplexOperation alone
+  total_ops = ITERATIONS * 7
+  puts "\nComplexOperation spawns ~#{total_ops} total operation instances across #{ITERATIONS} calls"
+end

data/docs/examples/always.md

@@ -0,0 +1,267 @@
+# Always
+
+`always` runs a step unconditionally at the end of the operation pipeline, after all regular steps have run (or been skipped). Unlike a regular `step`, it is never skipped — not when a prior step adds an error, not when `finish!` or `finish_if` DSL is called.
+
+## Placement rules
+
+- `always` steps must appear **after all other instructions** at the top level of the operation.
+- Once an `always` is declared, only further `always` steps may follow — any other instruction (`step`, `operation`, `transaction`, `within`, etc.) raises an `ArgumentError` at class load time.
+- `always` **cannot** be used inside blocks (`transaction do`, `within do`, `success do`, `validate do`). Doing so raises an `ArgumentError` at class load time.
+
+```ruby
+# correct
+step :a
+step :b
+always :c
+always :d
+
+# raises ArgumentError — step follows always
+step :a
+always :b
+step :c
+
+# raises ArgumentError — always inside a transaction block
+transaction do
+  step :a
+  always :b  # not allowed here
+end
+```
+
+## Basic usage
+
+```ruby
+class Order::Submit < Opera::Operation::Base
+  context do
+    attr_accessor :order
+  end
+
+  dependencies do
+    attr_reader :current_account, :audit_logger
+  end
+
+  step :build
+  step :charge
+  step :send_confirmation
+  always :audit_log
+
+  def build
+    self.order = current_account.orders.build(params)
+  end
+
+  def charge
+    result.add_error(:base, 'card declined') unless order.charge!
+  end
+
+  def send_confirmation
+    # only reached when charge succeeds
+    OrderMailer.confirmation(order).deliver_later
+  end
+
+  def audit_log
+    # always runs, regardless of whether charge succeeded or failed
+    audit_logger.record(order: order, success: result.success?)
+  end
+end
+```
+
+## Inspecting result state inside an always step
+
+`result.success?` and `result.failure?` reflect the state of the operation **at the point `always` runs** — i.e. after all regular steps have executed (or been skipped due to failure). This lets you branch on the final outcome:
+
+```ruby
+class Profile::Delete < Opera::Operation::Base
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account, :notifier
+  end
+
+  step :find
+  step :destroy
+  always :notify
+
+  def find
+    self.profile = current_account.profiles.find(params[:id])
+  end
+
+  def destroy
+    result.add_error(:base, 'cannot delete') unless profile.destroy
+  end
+
+  def notify
+    if result.success?
+      notifier.call(event: :deleted, profile_id: params[:id])
+    else
+      notifier.call(event: :delete_failed, profile_id: params[:id], errors: result.errors)
+    end
+  end
+end
+```
+
+## Multiple always steps
+
+Multiple `always` steps are allowed and run in the order they are declared in:
+
+```ruby
+class Report::Generate < Opera::Operation::Base
+  dependencies do
+    attr_reader :audit_logger, :metrics
+  end
+
+  step :fetch_data
+  step :render
+  always :record_audit
+  always :record_metrics
+
+  def fetch_data
+    # ...
+  end
+
+  def render
+    # ...
+  end
+
+  def record_audit
+    audit_logger.call(success: result.success?, errors: result.errors)
+  end
+
+  def record_metrics
+    metrics.increment(result.success? ? 'report.success' : 'report.failure')
+  end
+end
+```
+
+## Operation finishes early
+
+### With finish_if
+
+`finish_if` halts execution successfully when its method returns truthy — subsequent regular steps are skipped, but `always` steps still run. Inside the always step, `result.success?` returns `true` because no errors were added:
+
+```ruby
+class Import::Run < Opera::Operation::Base
+  dependencies do
+    attr_reader :audit_logger
+  end
+
+  step :check_preconditions
+  finish_if :already_imported?
+  step :import
+  step :output
+  always :record_attempt
+
+  def check_preconditions
+    # validate source data is present
+  end
+
+  def already_imported?
+    Import.exists?(ref: params[:ref])
+  end
+
+  def import
+    Import.create!(params)
+  end
+
+  def output
+    result.output = { imported: true }
+  end
+
+  def record_attempt
+    # called whether import ran, was skipped via finish_if, or failed
+    audit_logger.call(ref: params[:ref], success: result.success?)
+  end
+end
+```
+
+### With finish!
+
+Calling `finish!` inside a step halts execution immediately and marks the operation successful. `always` steps still run afterwards:
+
+```ruby
+class Profile::Upsert < Opera::Operation::Base
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account, :audit_logger
+  end
+
+  step :find_existing
+  step :update_existing
+  step :create_new
+  step :output
+  always :audit_log
+
+  def find_existing
+    self.profile = current_account.profiles.find_by(email: params[:email])
+  end
+
+  def update_existing
+    return unless profile
+
+    profile.update!(params)
+    finish!
+  end
+
+  def create_new
+    self.profile = current_account.profiles.create!(params)
+  end
+
+  def output
+    result.output = { model: profile }
+  end
+
+  def audit_log
+    # runs whether the record was updated (finish! path), created, or failed
+    audit_logger.record(profile: profile, success: result.success?)
+  end
+end
+```
+
+## Combining with DSL blocks
+
+`always` cannot be placed inside `transaction`, `within` or `validate` blocks. Place it after those blocks at the top level:
+
+```ruby
+class Ledger::Transfer < Opera::Operation::Base
+  configure do |config|
+    config.transaction_class = ActiveRecord::Base
+  end
+
+  dependencies do
+    attr_reader :audit_logger
+  end
+
+  transaction do
+    step :debit
+    step :credit
+  end
+
+  step :output
+  always :record_attempt
+
+  def debit
+    result.add_error(:base, 'insufficient funds') unless account.debit(params[:amount])
+  end
+
+  def credit
+    account.credit(params[:amount])
+  end
+
+  def output
+    result.output = { transferred: params[:amount] }
+  end
+
+  def record_attempt
+    # runs after the transaction (and rollback, if any) has settled.
+    # result.success? / result.failure? reflect the final outcome.
+    audit_logger.call(
+      params: params,
+      success: result.success?,
+      errors: result.errors
+    )
+  end
+end
+```

data/docs/examples/basic-operation.md

@@ -0,0 +1,79 @@
+# Basic Operation
+
+A simple operation that validates input, creates a record, sends an email, and returns output.
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account, :mailer
+  end
+
+  validate :profile_schema
+
+  step :create
+  step :send_email
+  step :output
+
+  def profile_schema
+    Dry::Validation.Schema do
+      required(:first_name).filled
+    end.call(params)
+  end
+
+  def create
+    self.profile = current_account.profiles.create(params)
+  end
+
+  def send_email
+    mailer&.send_mail(profile: profile)
+  end
+
+  def output
+    result.output = { model: profile }
+  end
+end
+```
+
+## Call with valid parameters
+
+```ruby
+Profile::Create.call(params: {
+  first_name: :foo,
+  last_name: :bar
+}, dependencies: {
+  mailer: MyMailer,
+  current_account: Account.find(1)
+})
+
+#<Opera::Operation::Result:0x0000561636dced60 @errors={}, @information={}, @executions=[:profile_schema, :create, :send_email, :output], @output={:model=>#<Profile id: 30, user_id: nil, linkedin_uid: nil, picture: nil, headline: nil, summary: nil, first_name: "foo", last_name: "bar", created_at: "2020-08-14 16:04:08", updated_at: "2020-08-14 16:04:08", agree_to_terms_and_conditions: nil, registration_status: "", account_id: 1, start_date: nil, supervisor_id: nil, picture_processing: false, statistics: {}, data: {}, notification_timestamps: {}, suggestions: {}, notification_settings: {}, contact_information: []>}>
+```
+
+## Call with INVALID parameters - missing first_name
+
+```ruby
+Profile::Create.call(params: {
+  last_name: :bar
+}, dependencies: {
+  mailer: MyMailer,
+  current_account: Account.find(1)
+})
+
+#<Opera::Operation::Result:0x0000562d3f635390 @errors={:first_name=>["is missing"]}, @information={}, @executions=[:profile_schema]>
+```
+
+## Call with MISSING dependencies
+
+```ruby
+Profile::Create.call(params: {
+  first_name: :foo,
+  last_name: :bar
+}, dependencies: {
+  current_account: Account.find(1)
+})
+
+#<Opera::Operation::Result:0x007f87ba2c8f00 @errors={}, @information={}, @executions=[:profile_schema, :create, :send_email, :output], @output={:model=>#<Profile id: 33, user_id: nil, linkedin_uid: nil, picture: nil, headline: nil, summary: nil, first_name: "foo", last_name: "bar", created_at: "2019-01-03 12:04:25", updated_at: "2019-01-03 12:04:25", agree_to_terms_and_conditions: nil, registration_status: "", account_id: 1, start_date: nil, supervisor_id: nil, picture_processing: false, statistics: {}, data: {}, notification_timestamps: {}, suggestions: {}, notification_settings: {}, contact_information: []>}>
+```