opera 0.5.0 → 0.6.0

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"}]>
+```

data/docs/examples/success-blocks.md

@@ -0,0 +1,68 @@
+# Success Blocks
+
+Steps inside a `success` block continue executing even if they return `false`. Errors added inside a success block **do** stop execution of subsequent non-success steps. Use success blocks for side effects that shouldn't halt the pipeline on falsy returns (e.g., sending emails, logging).
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account, :mailer
+  end
+
+  validate :profile_schema
+
+  success :populate
+
+  step :create
+  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 populate
+    context[:attributes] = {}
+    context[:valid] = false
+  end
+
+  def create
+    self.profile = current_account.profiles.create(params)
+  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 output
+
+```ruby
+Profile::Create.call(params: {
+  first_name: :foo,
+  last_name: :bar
+}, dependencies: {
+  current_account: Account.find(1)
+})
+#<Opera::Operation::Result:0x007fd0248e5638 @errors={"mailer"=>["Missing dependency"]}, @information={}, @executions=[:profile_schema, :populate, :create, :update, :send_email, :output], @output={:model=>#<Profile id: 40, user_id: nil, linkedin_uid: nil, picture: nil, headline: nil, summary: nil, first_name: "foo", last_name: "bar", created_at: "2019-01-03 12:21:35", updated_at: "2019-01-02 12:21:35", 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/transactions.md

@@ -0,0 +1,227 @@
+# Transactions
+
+Wrap multiple steps in a database transaction. If any step adds an error or raises an exception, the transaction is rolled back.
+
+## Configuration
+
+Set the transaction class either globally or per-operation:
+
+```ruby
+# Global
+Opera::Operation::Config.configure do |config|
+  config.transaction_class = ActiveRecord::Base
+  config.transaction_method = :transaction     # default
+  config.transaction_options = { requires_new: true }  # optional
+end
+
+# Per-operation
+class MyOperation < Opera::Operation::Base
+  configure do |config|
+    config.transaction_class = Profile
+  end
+end
+```
+
+## Failing transaction
+
+When a step inside a transaction fails, the entire transaction is rolled back:
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  configure do |config|
+    config.transaction_class = Profile
+  end
+
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account, :mailer
+  end
+
+  validate :profile_schema
+
+  transaction do
+    step :create
+    step :update
+  end
+
+  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 update
+    profile.update(example_attr: :Example)
+  end
+
+  def send_email
+    return true unless mailer
+
+    mailer.send_mail(profile: profile)
+  end
+
+  def output
+    result.output = { model: profile }
+  end
+end
+```
+
+### Example with non-existing attribute
+
+```ruby
+Profile::Create.call(params: {
+  first_name: :foo,
+  last_name: :bar
+}, dependencies: {
+  mailer: MyMailer,
+  current_account: Account.find(1)
+})
+
+D, [2020-08-14T16:13:30.946466 #2504] DEBUG -- :   Account Load (0.5ms)  SELECT  "accounts".* FROM "accounts" WHERE "accounts"."deleted_at" IS NULL AND "accounts"."id" = $1 LIMIT $2  [["id", 1], ["LIMIT", 1]]
+D, [2020-08-14T16:13:30.960254 #2504] DEBUG -- :    (0.2ms)  BEGIN
+D, [2020-08-14T16:13:30.983981 #2504] DEBUG -- :   SQL (0.7ms)  INSERT INTO "profiles" ("first_name", "last_name", "created_at", "updated_at", "account_id") VALUES ($1, $2, $3, $4, $5) RETURNING "id"  [["first_name", "foo"], ["last_name", "bar"], ["created_at", "2020-08-14 16:13:30.982289"], ["updated_at", "2020-08-14 16:13:30.982289"], ["account_id", 1]]
+D, [2020-08-14T16:13:30.986233 #2504] DEBUG -- :    (0.2ms)  ROLLBACK
+D, [2020-08-14T16:13:30.988231 #2504] DEBUG -- :    unknown attribute 'example_attr' for Profile. (ActiveModel::UnknownAttributeError)
+```
+
+## Passing transaction
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  configure do |config|
+    config.transaction_class = Profile
+  end
+
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account, :mailer
+  end
+
+  validate :profile_schema
+
+  transaction do
+    step :create
+    step :update
+  end
+
+  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 update
+    profile.update(updated_at: 1.day.ago)
+  end
+
+  def send_email
+    return true unless mailer
+
+    mailer.send_mail(profile: profile)
+  end
+
+  def output
+    result.output = { model: profile }
+  end
+end
+```
+
+### Example with updating timestamp
+
+```ruby
+Profile::Create.call(params: {
+  first_name: :foo,
+  last_name: :bar
+}, dependencies: {
+  mailer: MyMailer,
+  current_account: Account.find(1)
+})
+D, [2020-08-17T12:10:44.842392 #2741] DEBUG -- :   Account Load (0.7ms)  SELECT  "accounts".* FROM "accounts" WHERE "accounts"."deleted_at" IS NULL AND "accounts"."id" = $1 LIMIT $2  [["id", 1], ["LIMIT", 1]]
+D, [2020-08-17T12:10:44.856964 #2741] DEBUG -- :    (0.2ms)  BEGIN
+D, [2020-08-17T12:10:44.881332 #2741] DEBUG -- :   SQL (0.7ms)  INSERT INTO "profiles" ("first_name", "last_name", "created_at", "updated_at", "account_id") VALUES ($1, $2, $3, $4, $5) RETURNING "id"  [["first_name", "foo"], ["last_name", "bar"], ["created_at", "2020-08-17 12:10:44.879684"], ["updated_at", "2020-08-17 12:10:44.879684"], ["account_id", 1]]
+D, [2020-08-17T12:10:44.886168 #2741] DEBUG -- :   SQL (0.6ms)  UPDATE "profiles" SET "updated_at" = $1 WHERE "profiles"."id" = $2  [["updated_at", "2020-08-16 12:10:44.883164"], ["id", 47]]
+D, [2020-08-17T12:10:44.898132 #2741] DEBUG -- :    (10.3ms)  COMMIT
+#<Opera::Operation::Result:0x0000556528f29058 @errors={}, @information={}, @executions=[:profile_schema, :create, :update, :send_email, :output], @output={:model=>#<Profile id: 47, user_id: nil, linkedin_uid: nil, picture: nil, headline: nil, summary: nil, first_name: "foo", last_name: "bar", created_at: "2020-08-17 12:10:44", updated_at: "2020-08-16 12:10:44", 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: []>}>
+```
+
+## Using finish! inside a transaction
+
+Calling `finish!` inside a transaction stops execution without rolling back -- the transaction commits successfully:
+
+```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 :build_record
+  step :create
+  step :send_email
+  step :output
+
+  def profile_schema
+    Dry::Validation.Schema do
+      required(:first_name).filled
+    end.call(params)
+  end
+
+  def build_record
+    self.profile = current_account.profiles.build(params)
+    self.profile.force_name_validation = true
+  end
+
+  def create
+    self.profile = profile.save
+    finish!
+  end
+
+  def send_email
+    return true unless mailer
+
+    mailer.send_mail(profile: profile)
+  end
+
+  def output
+    result.output(model: profile)
+  end
+end
+```
+
+### Call
+
+```ruby
+result = Profile::Create.call(params: {
+  first_name: :foo,
+  last_name: :bar
+}, dependencies: {
+  current_account: Account.find(1)
+})
+
+#<Opera::Operation::Result:0x007fc2c59a8460 @errors={}, @information={}, @executions=[:profile_schema, :build_record, :create]>
+```

data/docs/examples/validations.md

@@ -0,0 +1,139 @@
+# Validations
+
+Opera supports `Dry::Validation::Result` and `Opera::Operation::Result` as return types from validate steps. Validations accumulate errors -- all validations run even if earlier ones fail, so the caller gets all errors at once.
+
+## Example with sanitizing parameters
+
+```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
+      configure { config.input_processor = :sanitizer }
+
+      required(:first_name).filled
+    end.call(params)
+  end
+
+  def create
+    self.profile = current_account.profiles.create(context[:profile_schema_output])
+  end
+
+  def send_email
+    return true unless mailer
+
+    mailer.send_mail(profile: profile)
+  end
+
+  def output
+    result.output = { model: profile }
+  end
+end
+```
+
+```ruby
+Profile::Create.call(params: {
+  first_name: :foo,
+  last_name: :bar
+}, dependencies: {
+  mailer: MyMailer,
+  current_account: Account.find(1)
+})
+
+# NOTE: Last name is missing in output model
+#<Opera::Operation::Result:0x000055e36a1fab78 @errors={}, @information={}, @executions=[:profile_schema, :create, :send_email, :output], @output={:model=>#<Profile id: 44, user_id: nil, linkedin_uid: nil, picture: nil, headline: nil, summary: nil, first_name: "foo", last_name: nil, created_at: "2020-08-17 11:07:08", updated_at: "2020-08-17 11:07: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: []>}>
+```
+
+## Example with old (ActiveModel) validations
+
+```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 :build_record
+  step :old_validation
+  step :create
+  step :send_email
+  step :output
+
+  def profile_schema
+    Dry::Validation.Schema do
+      required(:first_name).filled
+    end.call(params)
+  end
+
+  def build_record
+    self.profile = current_account.profiles.build(params)
+    self.profile.force_name_validation = true
+  end
+
+  def old_validation
+    return true if profile.valid?
+
+    result.add_information(missing_validations: "Please check dry validations")
+    result.add_errors(profile.errors.messages)
+
+    false
+  end
+
+  def create
+    profile.save
+  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:0x0000560ebc9e7a98 @errors={}, @information={}, @executions=[:profile_schema, :build_record, :old_validation, :create, :send_email, :output], @output={:model=>#<Profile id: 41, user_id: nil, linkedin_uid: nil, picture: nil, headline: nil, summary: nil, first_name: "foo", last_name: "bar", created_at: "2020-08-14 19:15:12", updated_at: "2020-08-14 19:15:12", 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
+
+```ruby
+Profile::Create.call(params: {
+  first_name: :foo
+}, dependencies: {
+  mailer: MyMailer,
+  current_account: Account.find(1)
+})
+
+#<Opera::Operation::Result:0x0000560ef76ba588 @errors={:last_name=>["can't be blank"]}, @information={:missing_validations=>"Please check dry validations"}, @executions=[:build_record, :old_validation]>
+```