heartwood-service_object

Heartwood::ServiceObject

Heartwood's service object gem provides a simple DSL for working with service objects within your Rails app.

Installation

Add this line to your application's Gemfile:

gem 'heartwood-service_object'

And then execute:

$ bundle

Or install it yourself as:

$ gem install heartwood-service_object

Usage

You can generate a new service object from the command line:

$ bundle exec rails g heartwood:service_object do_stuff

do_stuff should be replace with the name of your service. It can be written in snake case or camel case.

This example would create an empty service object file in app/services/do_stuff_service.rb. That file would specify the class name for the service object, which in this case would be DoStuffService.

Within your app, you can call the service using the call class method and passing it any options (see below).

DoStuffService.call

While call is a class method, it is mapped to pass the options to a new instance as DoStuffService.new(options).call. This is the point at which your options are set.

Therefore, while you should call the call class method on your service object, your executional code should be placed in the call instance method. (See below for a simple example.)

Options

There are three types of options which we'll refer to as attributes:

1. Required attributes
2. Optional attributes
3. Attribute with default values

Required Attributes

Required attributes use the required_attr keyword and can accept a list of all required attributes:

class DoStuffService < Heartwood::ServiceObject::Base
  required_attr :name, :email
end

You would then be required to include these attributes when calling the service.

# This will not work:
DoStuffService.call # => ArgumentError: Missing required option: name

# Instead, do this:
DoStuffService.call(name: 'Mr. F', email: '[e-mail]') # => nil

These attributes are then available anywhere in your service as the name you specified.

class DoStuffService < Heartwood::ServiceObject::Base
  required_attr :name, :email

  def call
    name
  end
end

# Call the service from elsewhere in your application:
DoStuffService.call(name: 'Mr. F', email: '[e-mail]') # => "Mr. F"

Optional Attributes

Optional attributes use the optional_attr method and take the same approach as required attributes, except an error won't be thrown when the attribute does not exist.

class DoStuffService < Heartwood::ServiceObject::Base
  optional_attr :name

  def call
    name
  end
end

# Call the service from elsewhere in your application:
DoStuffService.call(name: 'Mr. F') # => nil

Attributes with Default Values

You can also have an option with a fallback value via the attr_with_default method.

For these attributes, you'll have to use the attr_with_default method for each attribute and can not chain attributes together.

class DoStuffService < Heartwood::ServiceObject::Base
  attr_with_default :name, 'Mr. F'
  attr_with_default :email, '[e-mail]'

  def call
    name
  end
end

# Call the service from elsewhere in your application:
DoStuffService.call # => 'Mr F.'

# Setting the attribute would override the default:
DoStuffService.call(name: 'Mr. P') # => 'Mr. P'

Example

Here's an example that would create a user. It assumes there is a User class that has email, password, and name attributes.

class DoStuffService < Heartwood::ServiceObject::Base

  required_attr :email, :password

  optional_attr :name

  def call
    User.create(email: email, password: password, name: name)
  end
end

# Call the service from elsewhere in your application:
DoStuffService.call(email: '[e-mail]', password: 'password') # => #<User:0x007fb4b5ae3078>

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/seancdavis/heartwood-service_object. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Heartwood::ServiceObject project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.