Getting started with Servactory

Conventions

• Services inherit from Servactory::Base and reside in app/services. Common practice: create ApplicationService::Base as your project's base class.
• Name services by what they do, not what they accept. Use verbs. Example: UsersService::Create instead of UsersService::Creation.

Version support

Ruby/Rails	8.1	8.0	7.2	7.1	7.0	6.1	6.0	5.2	5.1	5.0
4.0	✅	✅	✅	✅	✅	❌	❌	❌	❌	❌
3.4	✅	✅	✅	✅	✅	✅	✅	✅	✅	❌
3.3	✅	✅	✅	✅	✅	✅	✅	✅	✅	❌
3.2	✅	✅	✅	✅	✅	✅	✅	✅	✅	❌
3.1	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌

Installation

Add this to Gemfile:

gem "servactory"

And execute:

bundle install

Preparation

First, prepare the base class for inheritance.

Automatically Since 2.5.0

Run the generator:

bundle exec rails g servactory:install

This creates all necessary files.

Manually

ApplicationService::Exceptions

app/services/application_service/exceptions.rb

module ApplicationService
  module Exceptions
    class Input < Servactory::Exceptions::Input; end
    class Output < Servactory::Exceptions::Output; end
    class Internal < Servactory::Exceptions::Internal; end

    class Failure < Servactory::Exceptions::Failure; end
  end
end

ApplicationService::Result Since 2.5.0

app/services/application_service/result.rb

module ApplicationService
  class Result < Servactory::Result; end
end

ApplicationService::Base

app/services/application_service/base.rb

module ApplicationService
  class Base < Servactory::Base
    configuration do
      input_exception_class ApplicationService::Exceptions::Input
      internal_exception_class ApplicationService::Exceptions::Internal
      output_exception_class ApplicationService::Exceptions::Output

      failure_class ApplicationService::Exceptions::Failure

      result_class ApplicationService::Result
    end
  end
end

First service

Create your first service:

bundle exec rails g servactory:service users_service/create first_name middle_name last_name

Generate a spec file:

bundle exec rails g servactory:rspec users_service/create first_name middle_name last_name