Prezzo 
Toolbox to create complex pricing models
Installation
Add this line to your application's Gemfile:
gem "prezzo"And then execute:
$ bundle
Or install it yourself as:
$ gem install prezzo
Usage
Prezzo::Context
The Prezzo::Context is a source of data for your calculators. Basically, it receives a hash of params and it validates its content, in order to make the calculations safe.
e.g.:
module Uber
class Context
include Prezzo::Context
CATEGORIES = ["UberX", "UberXL", "UberBlack"].freeze
validations do
required(:category).filled(included_in?: CATEGORIES)
required(:distance).filled(:float?)
required(:total_cars).filled(:int?)
required(:available_cars).filled(:int?)
end
end
end
context = Uber::Context.new(category: "UberBlack", ...)
# when valid
context.valid?
#=> true
# when invalid
context.valid?
#=> false
context.errors
# { distance: ["must be a float"]}Prezzo::Calculator
The Prezzo::Calculator is a simple interface for injecting dependencies on your calculators and calculating the price. Basically, it makes it possible to receive the context, an Hash of parameters containing the necessary information to calculate your price or a Prezzo::Context.
e.g.:
require "prezzo"
module Uber
class PricePerDistanceCalculator
include Prezzo::Calculator
def calculate
price_per_kilometer * distance
end
def price_per_kilometer
1.30
end
def distance
context.fetch(:distance)
end
end
end
context = Uber::Context.new(distance: 10.0)
Uber::PricePerDistanceCalculator.new(context).calculate
#=> 20.0Context Validation
If you initialize the context with a hash, it will skip the validation, however, any object that responds to .valid? will attempt a validation, and it will fail if valid? returns false.
Prezzo::Composable
The Prezzo::Composable module is an abstraction that provides a nice way of injecting other calculators define how the price will be composed with all of those calculators.
e.g.:
require "prezzo"
module Uber
class RidePriceCalculator
include Prezzo::Calculator
include Prezzo::Composable
composed_by base_fare: BaseFareCalculator,
price_per_distance: PricePerDistanceCalculator,
def calculate
base_fare + price_per_distance
end
end
end
context = Uber::Context.new(distance: 10.0)
Uber::RidePriceCalculator.new(context).calculate
#=> 47.3Prezzo::Explainable
The Prezzo::Explainable module is an abstraction that provides a nice way of representing how the price was composed.
e.g.:
require "prezzo"
module Uber
class RidePriceCalculator
include Prezzo::Calculator
include Prezzo::Composable
include Prezzo::Explainable
composed_by base_fare: BaseFareCalculator,
price_per_distance: PricePerDistanceCalculator,
explain_with :base_fare, :price_per_distance
def calculate
base_fare + price_per_distance
end
end
end
context = Uber::Context.new(distance: 10.0)
Uber::RidePriceCalculator.new(context).explain
#=> { total: 25.6, components: { base_fare: 4.3, price_per_distance: 21.3 } }Multiline explain_with
explain_with can be splitted into several lines.
class RidePriceCalculator
include Prezzo::Explainable
explain_with :base_fare
explain_with :price_per_distance
end
explain_with with the recursive: false option
class FooCalculator
include Prezzo::Calculator
include Prezzo::Explainable
explain_with :bar, :baz
def calculate
bar + baz
end
def bar
10
end
def baz
20
end
end
class QuxCalculator
include Prezzo::Calculator
include Prezzo::Composable
include Prezzo::Explainable
composed_by foo: FooCalculator
explain_with :foo, recursive: false
def calculate
foo + 5
end
endQuxCalculator#explain now produces
{
total: 35,
components: {
foo: 30
}
}but not
{
total: 35,
components: {
foo: {
total: 30,
components: {
bar: 10,
baz: 20
}
}
}
}Check the full Uber pricing for more complete example with many calculators and factors.
Development
After checking out the repo, run make to install dependencies. Then, run make spec to run the tests. You can also run make console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run make install. To release a new version, update the version number in version.rb, and then run make release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
Contributing
Please consider reading out Contributing Guide.
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.