light-services 2.2 → 3.0.0

data/docs/service-rendering.md

@@ -0,0 +1,222 @@
+# Service Rendering
+
+This recipe provides a clean way to render service results and errors in your Rails controllers, reducing boilerplate and ensuring consistent API responses.
+
+## The Problem
+
+Without a helper, controller actions become repetitive:
+
+```ruby
+class PostsController < ApplicationController
+  def create
+    service = Post::Create.run(service_args(attributes: params[:post]))
+
+    if service.success?
+      render json: service.post, status: :created
+    else
+      render json: { errors: service.errors.to_h }, status: :unprocessable_entity
+    end
+  end
+
+  def update
+    service = Post::Update.run(service_args(record: @post, attributes: params[:post]))
+
+    if service.success?
+      render json: service.post
+    else
+      render json: { errors: service.errors.to_h }, status: :unprocessable_entity
+    end
+  end
+
+  # ... same pattern repeated for every action
+end
+```
+
+## The Solution
+
+Create a `render_service` helper that handles success and failure automatically.
+
+## Implementation
+
+### Basic Helper
+
+Add this to your `ApplicationController`:
+
+```ruby
+class ApplicationController < ActionController::API
+  private
+
+  def render_service(service, success_status: :ok, error_status: :unprocessable_entity)
+    if service.success?
+      yield(service) if block_given?
+      render json: service_response(service), status: success_status
+    else
+      render json: { errors: service.errors.to_h }, status: error_status
+    end
+  end
+
+  def service_response(service)
+    # Returns the first output that is set
+    service.class.outputs.each do |name, _|
+      value = service.public_send(name)
+      return value unless value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+    
+    {}
+  end
+end
+```
+
+### Usage
+
+```ruby
+class PostsController < ApplicationController
+  def create
+    render_service Post::Create.run(service_args(attributes: params[:post])), 
+                   success_status: :created
+  end
+
+  def update
+    render_service Post::Update.run(service_args(record: @post))
+  end
+
+  def destroy
+    render_service Post::Destroy.run(service_args(record: @post))
+  end
+end
+```
+
+## Advanced Implementation
+
+### With Custom Response Building
+
+```ruby
+class ApplicationController < ActionController::API
+  private
+
+  def render_service(service, **options)
+    if service.success?
+      render_service_success(service, options)
+    else
+      render_service_failure(service, options)
+    end
+  end
+
+  def render_service_success(service, options)
+    status = options[:success_status] || :ok
+    
+    response = if options[:response]
+      options[:response]
+    elsif options[:output]
+      service.public_send(options[:output])
+    else
+      auto_detect_response(service)
+    end
+
+    render json: response, status: status
+  end
+
+  def render_service_failure(service, options)
+    status = options[:error_status] || :unprocessable_entity
+    
+    render json: {
+      errors: service.errors.to_h,
+      warnings: service.warnings.to_h
+    }.compact, status: status
+  end
+
+  def auto_detect_response(service)
+    service.class.outputs.each do |name, _|
+      value = service.public_send(name)
+      return value unless value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+    
+    { success: true }
+  end
+end
+```
+
+### Usage with Options
+
+```ruby
+class PostsController < ApplicationController
+  def create
+    service = Post::Create.run(service_args(attributes: params[:post]))
+    
+    render_service service,
+                   success_status: :created,
+                   output: :post
+  end
+
+  def bulk_create
+    service = Post::BulkCreate.run(service_args(items: params[:posts]))
+    
+    render_service service,
+                   success_status: :created,
+                   response: { posts: service.posts, count: service.posts.count }
+  end
+end
+```
+
+## With Serializers
+
+If you're using a serializer library (like Alba, Blueprinter, or ActiveModel::Serializers):
+
+```ruby
+class ApplicationController < ActionController::API
+  private
+
+  def render_service(service, serializer: nil, **options)
+    if service.success?
+      response = auto_detect_response(service)
+      response = serializer.new(response).to_h if serializer && response
+      
+      render json: response, status: options[:success_status] || :ok
+    else
+      render json: { errors: service.errors.to_h }, 
+             status: options[:error_status] || :unprocessable_entity
+    end
+  end
+end
+```
+
+```ruby
+class PostsController < ApplicationController
+  def show
+    service = Post::Find.run(service_args(id: params[:id]))
+    render_service service, serializer: PostSerializer
+  end
+end
+```
+
+## Handling Different Error Types
+
+```ruby
+def render_service(service, **options)
+  if service.success?
+    render_service_success(service, options)
+  else
+    status = determine_error_status(service, options)
+    render json: { errors: service.errors.to_h }, status: status
+  end
+end
+
+private
+
+def determine_error_status(service, options)
+  return options[:error_status] if options[:error_status]
+  
+  # Map specific error keys to HTTP statuses
+  return :not_found if service.errors[:record]&.any?
+  return :forbidden if service.errors[:authorization]&.any?
+  return :unauthorized if service.errors[:authentication]&.any?
+  
+  :unprocessable_entity
+end
+```
+
+## What's Next?
+
+Learn how to integrate Pundit authorization with Light Services:
+
+[Next: Pundit Authorization](pundit-authorization.md)

data/docs/steps.md

@@ -0,0 +1,337 @@
+# Steps
+
+Steps are the core components of a service, each representing a unit of work executed in sequence when the service is called.
+
+## TL;DR
+
+- Define steps using the `step` keyword within the service class
+- Use `if` and `unless` options for conditional steps
+- Inherit steps from parent classes
+- Inject steps into the execution flow with `before` and `after` options
+- Ensure cleanup steps run with the `always: true` option (unless `done!` was called)
+- Use a `run` method as a simple alternative for single-step services
+
+```ruby
+class GeneralParserService < ApplicationService
+  step :create_browser, unless: :browser
+  step :parse_content
+  step :quit_browser, always: true
+end
+
+class ParsePage < GeneralParserService
+  step :parse_additional_content, after: :parse_content
+end
+```
+
+## Define Steps
+
+Steps are declared using the `step` keyword in your service class.
+
+```ruby
+class User::Charge < ApplicationService
+  step :authorize
+  step :charge
+  step :send_email_receipt
+
+  private
+
+  def authorize
+    # ...
+  end
+
+  def charge
+    # ...
+  end
+
+  def send_email_receipt
+    # ...
+  end
+end
+```
+
+## Conditional Steps
+
+Steps can be conditional, executed based on specified conditions using the `if` or `unless` keywords.
+
+```ruby
+class User::Charge < ApplicationService
+  step :authorize
+  step :charge
+  step :send_email_receipt, if: :send_receipt?
+
+  # ...
+
+  def send_receipt?
+    rand(2).zero?
+  end
+end
+```
+
+This feature works well with argument predicates.
+
+```ruby
+class User::Charge < ApplicationService
+  arg :send_receipt, type: [TrueClass, FalseClass], default: true
+
+  step :send_email_receipt, if: :send_receipt?
+
+  # ...
+end
+```
+
+### Using Procs for Conditions
+
+You can also use Procs (lambdas) for inline conditions:
+
+```ruby
+class User::Charge < ApplicationService
+  arg :amount, type: Float
+
+  step :apply_discount, if: -> { amount > 100 }
+  step :charge
+  step :send_large_purchase_alert, if: -> { amount > 1000 }
+
+  # ...
+end
+```
+
+{% hint style="info" %}
+Using Procs can make simple conditions more readable, but for complex logic, prefer extracting to a method.
+{% endhint %}
+
+## Inheritance
+
+Steps are inherited from parent classes, making it easy to build upon existing services.
+
+```ruby
+# UpdateRecordService
+class UpdateRecordService < ApplicationService
+  arg :record, type: ApplicationRecord
+  arg :attributes, type: Hash
+
+  step :authorize
+  step :update_record
+end
+```
+
+```ruby
+# User::Update inherited from UpdateRecordService
+class User::Update < UpdateRecordService
+  # Arguments and steps are inherited from UpdateRecordService
+end
+```
+
+## Injecting Steps into Execution Flow
+
+Steps can be injected at specific points in the execution flow using `before` and `after` options.
+
+Let's enhance the previous example by adding a step to send a notification after updating the record.
+
+```ruby
+# User::Update inherited from UpdateRecordService
+class User::Update < UpdateRecordService
+  step :log_action, before: :authorize
+  step :send_notification, after: :update_record
+
+  private
+
+  def log_action
+    # ...
+  end
+
+  def send_notification
+    # ...
+  end
+end
+```
+
+Combine this with `if` and `unless` options for more control.
+
+```ruby
+step :send_notification, after: :update_record, if: :send_notification?
+```
+
+{% hint style="info" %}
+By default, if neither `before` nor `after` is specified, the step is added at the end of the execution flow.
+{% endhint %}
+
+## Always Running Steps
+
+To ensure certain steps run regardless of previous step outcomes (errors, warnings, failed validations), use the `always: true` option. This is particularly useful for cleanup tasks, error logging, etc.
+
+Note: if `done!` was called, the service exits early and `always: true` steps will **not** run.
+
+```ruby
+class ParsePage < ApplicationService
+  arg :url, type: String
+
+  step :create_browser
+  step :parse_content
+  step :quit_browser, always: true
+
+  private
+
+  attr_accessor :browser
+
+  def create_browser
+    self.browser = Watir::Browser.new
+  end
+
+  def parse_content
+    # ...
+  end
+
+  def quit_browser
+    browser&.quit
+  end
+end
+```
+
+## Early Exit with `done!`
+
+Use `done!` to stop executing remaining steps without adding an error. This is useful when you've completed the service's goal early and don't need to run subsequent steps.
+
+```ruby
+class User::FindOrCreate < ApplicationService
+  arg :email, type: String
+
+  step :find_existing_user
+  step :create_user
+  step :send_welcome_email
+
+  output :user
+
+  private
+
+  def find_existing_user
+    self.user = User.find_by(email:)
+    done! if user # Skip remaining steps if user already exists
+  end
+
+  def create_user
+    self.user = User.create!(email:)
+  end
+
+  def send_welcome_email
+    # Only runs for newly created users
+    Mailer.welcome(user).deliver_later
+  end
+end
+```
+
+You can check if `done!` was called using `done?`:
+
+```ruby
+def some_step
+  done!
+  
+  # This code still runs within the same step
+  puts "Done? #{done?}" # => "Done? true"
+end
+
+def next_step
+  # This step will NOT run because done! was called
+end
+```
+
+{% hint style="info" %}
+`done!` stops subsequent steps from running, including steps marked with `always: true`. Code after `done!` within the same step method will still execute.
+{% endhint %}
+
+## Removing Inherited Steps
+
+When inheriting from a parent service, you can remove steps using `remove_step`:
+
+```ruby
+class UpdateRecordService < ApplicationService
+  step :authorize
+  step :validate
+  step :update_record
+  step :send_notification
+end
+
+class InternalUpdate < UpdateRecordService
+  # Remove authorization for internal system updates
+  remove_step :authorize
+  remove_step :send_notification
+end
+```
+
+## Using `run` Method as a Simple Alternative
+
+For simple services that don't need multiple steps, you can define a `run` method instead of using the `step` DSL. If no steps are defined, Light Services will automatically use the `run` method as a single step.
+
+```ruby
+class User::SendWelcomeEmail < ApplicationService
+  arg :user, type: User
+
+  private
+
+  def run
+    Mailer.welcome(user).deliver_later
+  end
+end
+```
+
+This is equivalent to:
+
+```ruby
+class User::SendWelcomeEmail < ApplicationService
+  arg :user, type: User
+
+  step :run
+
+  private
+
+  def run
+    Mailer.welcome(user).deliver_later
+  end
+end
+```
+
+### Inheritance with `run` Method
+
+The `run` method works with inheritance. If a parent service defines a `run` method, child services will inherit it:
+
+```ruby
+class BaseNotificationService < ApplicationService
+  arg :message, type: String
+
+  private
+
+  def run
+    send_notification(message)
+  end
+
+  def send_notification(msg)
+    raise NotImplementedError
+  end
+end
+
+class SlackNotification < BaseNotificationService
+  private
+
+  def send_notification(msg)
+    SlackClient.post(msg)
+  end
+end
+
+class EmailNotification < BaseNotificationService
+  private
+
+  def send_notification(msg)
+    Mailer.notify(msg).deliver_later
+  end
+end
+```
+
+{% hint style="info" %}
+If a service has no steps defined and no `run` method (including from parent classes), a `Light::Services::NoStepsError` will be raised when the service is executed.
+{% endhint %}
+
+# What's Next?
+
+Next step is to learn about outputs. Outputs are the results of a service, returned upon completion of service execution.
+
+[Next: Outputs](outputs.md)
+

data/docs/summary.md

@@ -0,0 +1,19 @@
+# Table of contents
+
+* [Light Services](README.md)
+* [Quickstart](quickstart.md)
+* [Concepts](concepts.md)
+* [Arguments](arguments.md)
+* [Steps](steps.md)
+* [Outputs](outputs.md)
+* [Context](context.md)
+* [Errors](errors.md)
+* [Callbacks](callbacks.md)
+* [Configuration](configuration.md)
+* [Testing](testing.md)
+* [Rails Generators](generators.md)
+* [Best Practices](best-practices.md)
+* [Recipes](recipes.md)
+  * [CRUD](crud.md)
+  * [Service Rendering](service-rendering.md)
+  * [Pundit Authorization](pundit-authorization.md)