opera 0.5.0 → 0.5.1

data/benchmarks/operation_benchmark.rb

@@ -0,0 +1,330 @@
+# 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, and within -- 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 :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 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
+
+# ---------------------------------------------------------------------------
+# 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
+
+# Warm up
+3.times do
+  ComplexOperation.call(params: PARAMS)
+  BatchOperation.call(params: BATCH_PARAMS)
+  ValidationOperation.call(params: VALIDATION_PARAMS)
+  WithinOperation.call(params: WITHIN_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
+
+  # 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/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: []>}>
+```

data/docs/examples/context-params-dependencies.md

@@ -0,0 +1,122 @@
+# Context, Params & Dependencies
+
+Opera provides typed accessor blocks for managing state within an operation.
+
+## context
+
+Mutable hash for passing data between steps. Supports `attr_reader`, `attr_writer`, and `attr_accessor`.
+
+```ruby
+context do
+  attr_accessor :profile
+  attr_accessor :account, default: -> { Account.new }
+  attr_reader :schema_output
+end
+```
+
+- `attr_accessor` defines getter and setter methods that read/write to the `context` hash
+- `attr_reader` defines only a getter
+- `default` accepts a lambda, evaluated lazily on first access when the key is missing
+
+```ruby
+context do
+  attr_accessor :profile, :account
+end
+
+step :fetch_profile
+step :update_profile
+
+def fetch_profile
+  self.profile = ProfileFetcher.call  # sets context[:profile]
+end
+
+def update_profile
+  profile.update!(name: 'John')  # reads profile from context[:profile]
+end
+```
+
+## params
+
+Immutable hash received in the `call` method. Only supports `attr_reader`.
+
+```ruby
+params do
+  attr_reader :activity, :requester
+end
+```
+
+## dependencies
+
+Immutable hash received in the `call` method. Only supports `attr_reader`.
+
+```ruby
+dependencies do
+  attr_reader :current_account, :mailer
+end
+```
+
+## context_reader with defaults
+
+Use `context_reader` to read step outputs from the context hash:
+
+```ruby
+context_reader :schema_output
+
+validate :schema  # context = { schema_output: { id: 1 } }
+step :do_something
+
+def do_something
+  puts schema_output  # outputs: { id: 1 }
+end
+```
+
+Use `default` to provide a fallback value when the key is missing:
+
+```ruby
+context_reader :profile, default: -> { Profile.new }
+
+step :fetch_profile
+step :do_something
+
+def fetch_profile
+  return if App.http_disabled?
+
+  context[:profile] = ProfileFetcher.call
+end
+
+def update_profile
+  profile.name = 'John'
+  profile.save!
+end
+```
+
+## Best practices
+
+**Good** -- Use `context_reader` for step outputs and shared state:
+
+```ruby
+context_reader :schema_output
+```
+
+**Bad** -- Don't use `context_reader` with `default` for transient objects that aren't stored in context:
+
+```ruby
+# BAD: suggests serializer is part of persistent state
+context_reader :serializer, default: -> { ProfileSerializer.new }
+```
+
+**Better** -- Use private methods for transient dependencies:
+
+```ruby
+step :output
+
+def output
+  self.result = serializer.to_json({...})
+end
+
+private
+
+def serializer
+  ProfileSerializer.new
+end
+```

data/docs/examples/finish-if.md

@@ -0,0 +1,67 @@
+# Finish If
+
+`finish_if` evaluates a method and stops execution (successfully) if the method returns a truthy value. Subsequent steps are skipped, but the operation is considered successful.
+
+```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
+  finish_if :profile_create_only
+  step :update
+
+  success do
+    step :send_email
+    step :output
+  end
+
+  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 profile_create_only
+    dependencies[:create_only].present?
+  end
+
+  def update
+    profile.update(updated_at: 1.day.ago)
+  end
+
+  # NOTE: We can add an error in this step and it won't break the execution
+  def send_email
+    result.add_error('mailer', 'Missing dependency')
+    mailer&.send_mail(profile: profile)
+  end
+
+  def output
+    result.output = { model: context[:profile] }
+  end
+end
+```
+
+## Example
+
+```ruby
+Profile::Create.call(params: {
+  first_name: :foo,
+  last_name: :bar
+}, dependencies: {
+  create_only: true,
+  current_account: Account.find(1)
+})
+#<Opera::Operation::Result:0x007fd0248e5638 @errors={}, @information={}, @executions=[:profile_schema, :create, :profile_create_only], @output={}>
+```

data/docs/examples/inner-operations.md

@@ -0,0 +1,94 @@
+# Inner Operations
+
+## Single operation
+
+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`.
+
+```ruby
+class Profile::Find < Opera::Operation::Base
+  step :find
+
+  def find
+    result.output = Profile.find(params[:id])
+  end
+end
+
+class Profile::Create < Opera::Operation::Base
+  validate :profile_schema
+
+  operation :find
+
+  step :create
+
+  step :output
+
+  def profile_schema
+    Dry::Validation.Schema do
+      optional(:id).filled
+    end.call(params)
+  end
+
+  def find
+    Profile::Find.call(params: params, dependencies: dependencies)
+  end
+
+  def create
+    return if context[:find_output]
+    puts 'not found'
+  end
+
+  def output
+    result.output = { model: context[:find_output] }
+  end
+end
+```
+
+### Example with inner operation doing the find
+
+```ruby
+Profile::Create.call(params: {
+  id: 1
+}, dependencies: {
+  current_account: Account.find(1)
+})
+#<Opera::Operation::Result:0x007f99b25f0f20 @errors={}, @information={}, @executions=[:profile_schema, :find, :create, :output], @output={:model=>{:id=>1, :user_id=>1, :linkedin_uid=>nil, ...}}>
+```
+
+## Multiple operations
+
+Use `operations` when a method returns an array of `Opera::Operation::Result` objects. If any of the inner operations fail, all their errors are collected and execution stops.
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  step :validate
+  step :create
+
+  def validate; end
+
+  def create
+    result.output = { model: "Profile #{Kernel.rand(100)}" }
+  end
+end
+
+class Profile::CreateMultiple < Opera::Operation::Base
+  operations :create_multiple
+
+  step :output
+
+  def create_multiple
+    (0..params[:number]).map do
+      Profile::Create.call
+    end
+  end
+
+  def output
+    result.output = context[:create_multiple_output]
+  end
+end
+```
+
+```ruby
+Profile::CreateMultiple.call(params: { number: 3 })
+
+#<Opera::Operation::Result:0x0000564189f38c90 @errors={}, @information={}, @executions=[{:create_multiple=>[[:validate, :create], [:validate, :create], [:validate, :create], [:validate, :create]]}, :output], @output=[{:model=>"Profile 1"}, {:model=>"Profile 7"}, {:model=>"Profile 69"}, {:model=>"Profile 92"}]>
+```