igmarin/ruby-service-objects

Ruby Service Objects

Conventions

| Aspect | Rule | |--------|------| | Entry point | def self.call(...) → new(...).call | | Validation | Validate inputs at top of call; return error hash if invalid | | Error handling | rescue → log + error hash; never re-raise to caller | | Transactions | Only wrap multi-step DB operations that must be atomic | | call length | ≤20 lines; extract sub-services if longer | | Scope | Return data only (no HTTP); single responsibility per service | | SQL | sanitize_sql for any dynamic queries | | Shared logic | Extract validators to class-only services (Pattern 3) |

Required artifacts (file path, README, YARD, pragma, error log shape) are enumerated once in Output Style.

HARD-GATE: Tests Gate Implementation

EVERY service object MUST have its test written and validated BEFORE implementation.
  1. Write the spec for .call (with contexts for success, error, edge cases)
  2. Run the spec — verify it fails because the service does not exist yet
  3. ONLY THEN write the service implementation
See rspec-best-practices for the full gate cycle.

MANDATORY Response Contract

.call MUST return EXACTLY one of these two shapes — no other top-level keys, never a Boolean, raw model, or ActiveRecord object:

{ success: true,  response: { <domain_key>: <value>, ... } }
{ success: false, response: { error: { message: 'human-readable reason' } } }

When to Use Each Pattern

| Signal in the task | Pattern | |--------------------|----------| | Orchestrates multiple steps, needs instance state | Pattern 1: .call → new.call | | Processes a collection with per-item error handling | Pattern 2: Batch processing | | Stateless helper, validator, or utility — no instance state needed | Pattern 3: Class-only (static methods) | | Coordinates multiple sub-services | Pattern 4: Orchestrator delegation |

Core Patterns

1. The .call Pattern (with delegation, transaction, YARD)

module AnimalTransfers
  class TransferService
    TRANSFER_FAILED = 'Transfer could not be completed'

    # @param params [Hash] :source_shelter_id, :target_shelter_id, :tag_number
    # @return [Hash] { success: Boolean, response: Hash }
    def self.call(params)
      new(params).call
    end

    def initialize(params)
      @source_shelter_id = params[:source_shelter_id]
      @target_shelter_id = params[:target_shelter_id]
      @tag_number = params[:tag_number]
    end

    def call
      source = ShelterValidator.validate_source_shelter!(@source_shelter_id)
      target = ShelterValidator.validate_target_shelter!(@target_shelter_id)
      result = ActiveRecord::Base.transaction do
        source.decrement!(:animal_count)
        target.increment!(:animal_count)
        TransferLog.create!(source:, target:, tag_number: @tag_number)
      end
      { success: true, response: { transfer: result } }
    rescue ActiveRecord::RecordInvalid => e
      Rails.logger.error("Validation Error: #{e.message}")
      Rails.logger.error(e.backtrace.join("\n"))
      { success: false, response: { error: { message: e.message } } }
    rescue StandardError => e
      Rails.logger.error("Processing Error: #{e.message}")
      Rails.logger.error(e.backtrace.join("\n"))
      { success: false, response: { error: { message: TRANSFER_FAILED } } }
    end
  end
end

2. Batch Processing + Per-Item Rescue (Partial Success)

# Batch — each rescue block logs; outer rescue returns { success: false }
def call
  return { success: false, response: { error: { message: 'Items list cannot be empty' } } } if @items.blank?

  results = @items.each_with_object({ successful: [], failed: [] }) do |item, acc|
    validate_item!(item)
    process_item(item)
    acc[:successful] << item[:sku]
  rescue ActiveRecord::RecordNotFound => e
    Rails.logger.error("Item not found: #{e.message}")
    acc[:failed] << { sku: item[:sku], error: e.message }
  rescue StandardError => e
    Rails.logger.error("Unexpected item error: #{e.message}")
    Rails.logger.error(e.backtrace.join("\n"))
    acc[:failed] << { sku: item[:sku], error: e.message }
  end
  { success: true, response: results }
rescue StandardError => e
  Rails.logger.error("Service failed: #{e.message}")
  Rails.logger.error(e.backtrace.join("\n"))
  { success: false, response: { error: { message: PROCESSING_FAILED } } }
end

3. Class-only Services (Static Methods)

When no instance state is needed — use ONLY class methods, no initialize, no instance variables. Validators and stateless helpers should always use this pattern:

class PackageValidator
  MAX_WEIGHT_KG = 30
  MAX_LENGTH_CM = 150

  # @param dimensions [Hash] :weight_kg, :length_cm, :width_cm, :height_cm
  # @return [nil, String] nil if valid, error message otherwise
  def self.validate(dimensions)
    return 'Weight exceeds limit' if dimensions[:weight_kg] > MAX_WEIGHT_KG
    return 'Length exceeds limit' if dimensions[:length_cm] > MAX_LENGTH_CM
    nil
  end

  def self.within_limits?(dimensions)
    validate(dimensions).nil?
  end
end

4. Orchestrator Delegation (≤20-line call)

Sub-services handle their OWN rescue and return { success: false, response: { error: { message: ... } } } on failure. The orchestrator propagates early returns only — no rescue block needed:

# RULE: ≤20 lines in call — if longer, extract another sub-service
def call
  user_result = UserCreationService.call(@params)
  return user_result unless user_result[:success]

  workspace_result = WorkspaceSetupService.call(user_result[:response])
  return workspace_result unless workspace_result[:success]

  BillingService.call(workspace_result[:response])
  NotificationService.call(user_result[:response])
  { success: true, response: { user: user_result[:response] } }
end

Output Style

Every service-object task produces these artifacts:

1. Service file at app/services/<module_name>/<service_name>.rb — pragma on line 1, class wrapped in a module matching the directory name.
2. YARD on self.call — @param for every argument, @return [Hash], plus @raise for any exception class that can escape (including those rescued internally elsewhere). The self.call wrapper is documented separately from #call, even when it just delegates.
3. YARD on every other public method — same @param / @return / @raise discipline. See yard-documentation.
4. Error message constants — user-facing failure strings live in UPPER_SNAKE_CASE constants at the top of the class (e.g. TRANSFER_FAILED = 'Transfer could not be completed'), never inline inside a rescue.
5. Module README at app/services/<module_name>/README.md — copy the shape from assets/module_readme_template.md. Required even for single-service modules.
6. Spec file at spec/services/<module_name>/<service_name>_spec.rb written and failing BEFORE the implementation (see HARD-GATE).
7. English — YARD, README, and error messages in English unless the user requests otherwise.

For class-only services (Pattern 3), the rules apply to the public class methods being documented; if the class returns a non-service shape (e.g. validators returning nil / error string), document that explicitly in YARD and the README.

Integration

| Skill | When to chain | |-------|---------------| | yard-documentation | Writing/reviewing inline docs | | ruby-api-client-integration | External API integrations | | strategy-factory-null-calculator | Variant-based calculators | | rspec-service-testing | Testing service objects | | rspec-best-practices | General RSpec structure | | rails-architecture-review | Architecture review involving service extraction |

Assets

• assets/examples.md
• assets/service_skeleton.md