Piper.rb

[rubydocs]

Installation

Add this line to your application's Gemfile:

gem "piper-rb"

Usage

Super basic

The most basic element of Piper is a pipe. Just think of it as a condition step. If no keywords are used, then (in accordance to Ruby conventions) the last line of code is taken as the step's condition:

require "piper-rb"

class YourSuperbService < PiperService
  attribute :input, Types::Any

  pipe "input is Numeric" do
    input.is_a? Numeric
  end

  pipe "input is greater than 100?" do
    false

    200 == 100

    input > 100
  end

  pipe "input is less than 1000?" do
    input < 1000
  end
end

YourSuperbService.new(input: 200).call
#=> Success(true)

YourSuperbService.new(input: "asd").call
#=> Failure({:service=>#<YourSuperbService input="asd">, :object=>false, :message=>nil})

Keywords for more control

If you want to specify the condition, object to be returned and the error message, there are keywords for this:

• condition (aliase: cond)
• result_object (aliases: object, rslt)
• message (aliases: fail_message, mssg)

require "piper-rb"

class YourFineService < PiperService
  attribute :input, Types::Any

  pipe "input is Numeric" do
    message { "The input must be `Numeric`." }

    input.is_a? Numeric
  end

  pipe "input is greater than 100?" do
    cond { input > 100 }

    200 == 100
  end

  pipe "input is less than 1000?" do
    object { input }

    input < 1000
  end
end

YourFineService.new(input: 200).call
#=> Success(200)

YourFineService.new(input: "asd").call
#=> Failure({:service=>(...), :object=>false, :message=>"The input must be `Numeric`."})

You can access last step's object with last_result:

require "piper-rb"

class YourGreatService < PiperService
  attribute :input, Types::Any

  pipe "this step`s result should be passed to..." do
    input * 30
  end

  pipe "...to this step" do
    cond    { last_result == input * 30 }
    object  { last_result }
  end
end

YourGreatService.new(input: 20).call
#=> Success(600)

You can nest services, calling them in a pipe passes their result:

require "piper-rb"

class YourMajesticService < PiperService
  attribute :input, Types::Any

  pipe :nothing_to_see_here do
    true
  end

  pipe :calling_nested_service do
    YourFlamboyantService.new(nested_input: input * 20).call
  end
end

class YourFlamboyantService < PiperService
  attribute :nested_input, Types::Any

  pipe :simple_step do
    message { "I am the one who knocks!" }
    nested_input >= 300
  end

end

YourMajesticService.new(input: 20).call
#=> Success(true)

YourMajesticService.new(input: 2).call
#=> Failure({:service=>#<YourFlamboyantService nested_input=40>, :object=>false, :message=>"I am the one who knocks!"})

---

You can configure default nil behavior.

By default, pipes fail when they end in nil and do not handle exceptions. You can, of course, explicitly return true in order to make sure a pipe is successful, even if it ended in nil.

But in 0.4 you now have an option to tweak the default behavior, by using pass_nil. Bear in mind this option is inherited, so if your services inherit from, say, BaseService, then this - unless overwritten in a given service – will affect all services:

Refer to specs for more info.

require "piper-rb"

class BaseService < PiperService
  pass_nil true

  # [...]
end