Operatic
A minimal standard interface for your operations.
Installation
Add Operatic to your application's Gemfile and run bundle install
.
gem 'operatic'
Usage
An Operatic class encapsulates an operation and communicates the status of the operation via its result object. As well as being either a #success?
or a #failure?
further data can be attached via #success!
, #failure!
or convenience accessors.
class SayHello
include Operatic
# Readers for attributes passed via `.call`.
attr_reader :name
# Declare convenience accessors on the result.
data_attr :message
def call
# Exit the method and mark the result as a failure.
return failure! unless name
# Mark the result as a success and attach further data.
success!(message: "Hello #{name}")
end
end
result = SayHello.call(name: 'Dave')
result.class # => Operatic::Success
result.failure? # => false
result.success? # => true
result. # => "Hello Dave"
result[:message] # => "Hello Dave"
result.to_h # => {:message=>"Hello Dave"}
result = SayHello.call
result.class # => Operatic::Failure
result.failure? # => true
result.success? # => false
result. # => nil
result[:message] # => nil
result.to_h # => {}
A Rails controller might use Operatic like this:
class HellosController < ApplicationController
def create
result = SayHello.call(name: params[:name])
if result.success?
render plain: result.
else
render :new
end
end
end
Pattern matching
An Operatic result also supports pattern matching allowing you to match over a tuple of the result class and its data:
case SayHello.call(name: 'Dave')
in [Operatic::Success, { message: }]
# Result is a success, do something with the `message` variable.
in [Operatic::Failure, _]
# Result is a failure, do something else.
end
Or match solely against its data:
case SayHello.call(name: 'Dave')
in message:
# Result has the `message` key, do something with the variable.
else
# Do something else.
end
Which might be consumed in Rails like this:
class HellosController < ApplicationController
def create
case SayHello.call(name: params[:name])
in [Operatic::Success, { message: }]
render plain:
in [Operatic::Failure, _]
render :new
end
end
end
Development
Run the tests with:
bundle exec rspec
Generate Yard documentation with:
bundle exec yardoc
License
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the Operatic project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.