brule 0.0.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bd5036cc83ccf0a96b4140382d2e2653fc06e0d82f302b32c81f1c709c5f5d5
-  data.tar.gz: 12e045f88777df92fe435b7a0c0afda4bda6d2c737722f5932519a9d955086f5
+  metadata.gz: 4c5f4dc5b794023937b44626faefd5feb047030cad7dd4a6b1fa5ccb42624af3
+  data.tar.gz: 2be8c8844cbba6594cfe3d758ee69410aa2ff4df92288c42b6526a667c8969f7
 SHA512:
-  metadata.gz: 95c5b969619e184e19286eab6738d923bdeb2acbe2c81ccf59c178333f1ce99ef0b1bdc237644652fdc40e28bce346ee5d85ed849ff23c13377d714339b2a1aa
-  data.tar.gz: bc9dcfd653ebe89004d28db445607a37ad3f844dee96f3fedad93007293d1add45a40fdc44042025162263b2b2564a26347ec90d3c595594bb017276c837bdc1
+  metadata.gz: b40a40a8b365cdd628d4382fd3a092905c43f4cc34e036eea47036cf41379a46ec806bef50abb98bc8a0b499ab19a0413a328a13199bd50b15e1130b39cf9b89
+  data.tar.gz: 73a0f66735eabb08f486df0760f9383e098ec11ea7630d73597c20e6e0c21fc5b1a4f84e54c395774e8afa46366383bee2d1050d6f5bf97388f2490f2a7ba15d

data/README.md

@@ -0,0 +1,145 @@
+This project aims at providing a set of tools to build somehow complex
+business processes or rules. It helps when:
+
+* You decided to split the process into smaller parts working together.
+* You need to keep the rules evolving while maintaining the old versions.
+* You want to persist the rules that lead to the result of a process.
+* You want to make your tests independent from your production data.
+* You want to introspect what lead to the result of a process.
+
+## How does it work
+
+If you use this gem, you'll have a couple of premade elements to build and test
+an _engine_ that, given a set of _rules_ and a _context_ will produce a
+_result_.
+
+A typical usage for this kind of engine is to use it to compute the price of a
+service or a good. But, this is not limited to that use-case as an engine
+would be able to produce any kind of results.
+
+An _engine_ orchestrate _rules_ in a way that they would produce enough
+information for the engine to assemble a _result_. The rules are arranged in an
+ordered sequence and are picked depending on the _context_. Each rule will write
+in the context too.
+
+The idea is very similar to function composition or Rack's middlewares.
+
+## How does it look
+
+Here is an example from the [Elephant Carpaccio][elephant] kata. The specs are:
+
+> Accept 3 inputs from the user:
+>
+> * How many items
+> * Price per item
+> * 2-letter state code
+>
+> Output the total price. Give a discount based on the total price, add state
+> tax based on the state and the discounted price.
+
+```ruby
+require "brule"
+
+module Pricing
+  class Engine < Brule::Engine
+    def result
+      context[:price]
+    end
+  end
+
+  class OrderTotal < Brule::Rule
+    def apply
+      context[:price] = context[:unit_price] * context[:item_count]
+    end
+  end
+
+  class Discount < Brule::Rule
+    def trigger?
+      !applicable_discount.nil?
+    end
+
+    def apply
+      order_value, discount_rate = applicable_discount
+      price = context[:price]
+      discount_amount = (price * discount_rate).ceil
+      context.merge!(
+        price: price - discount_amount,
+        discount_rate: discount_rate,
+        discount_amount: discount_amount,
+      )
+    end
+
+    private
+
+    def applicable_discount
+      config[:rates]
+        .sort_by { |order_value, _| order_value * -1 }
+        .find    { |order_value, _| order_value <= context[:price] }
+    end
+  end
+
+  class StateTax < Brule::Rule
+    def apply
+      price, state = context.fetch_values(:price, :state)
+      tax_rate = config[:rates].fetch(state)
+      state_tax = (price * tax_rate).ceil
+      context.merge!(
+        price: price + state_tax,
+        state_tax: state_tax,
+      )
+    end
+  end
+end
+
+require "bigdecimal"
+require "bigdecimal/util"
+
+engine = Pricing::Engine.new(
+  rules: [
+    Pricing::OrderTotal.new,
+    Pricing::Discount.new(
+      rates: [
+        [  1_000_00, "0.03".to_d ],
+        [  5_000_00, "0.05".to_d ],
+        [  7_000_00, "0.07".to_d ],
+        [ 10_000_00, "0.10".to_d ],
+        [ 50_000_00, "0.15".to_d ],
+      ],
+    ),
+    Pricing::StateTax.new(
+      rates: {
+        "UT" => "0.0685".to_d,
+        "NV" => "0.0800".to_d,
+        "TX" => "0.0625".to_d,
+        "AL" => "0.0400".to_d,
+        "CA" => "0.0825".to_d,
+      },
+    ),
+  ],
+)
+
+result = engine.call(
+  item_count: 100,
+  unit_price: 100_00,
+  state: "NV",
+)
+
+# Access the main result
+result                        # => 9_720_00 ($9,720.00)
+
+# Access the context
+engine.context.fetch_values(
+  :discount_rate,             # =>      0.1 (10%)
+  :discount_amount,           # => 1_000_00 ($1,000.00)
+  :state_tax,                 # =>   720_00 ($720.00)
+)
+
+# Access the history
+engine.history(key: :price)   # => [
+                              # =>   [#<struct Pricing::OrderTotal ...>, 10_000_00],
+                              # =>   [#<struct Pricing::Discount ...>,    9_000_00],
+                              # =>   [#<struct Pricing::StateTax ...>,    9_720_00],
+                              # => ]
+```
+
+[elephant]: https://docs.google.com/document/d/1Ls6pTmhY_LV8LwFiboUXoFXenXZl0qVZWPZ8J4uoqpI/edit#

data/lib/brule/context.rb

@@ -0,0 +1,24 @@
+require 'forwardable'
+
+module Brule
+  class Context
+    extend Forwardable
+
+    def_delegators :@content, :fetch, :fetch_values, :key?, :[]=, :merge!
+
+    def self.wrap(context)
+      context.is_a?(self) ? context : new(context)
+    end
+
+    def initialize(hash = {})
+      @content = hash
+    end
+
+    def initialize_copy(orig)
+      super
+      @content = orig.instance_variable_get(:@content).dup
+    end
+
+    alias [] fetch
+  end
+end

data/lib/brule/engine.rb

@@ -0,0 +1,37 @@
+module Brule
+  class Engine
+    attr_reader :context
+
+    def initialize(rules:)
+      @rules = rules
+    end
+
+    def call(context = {})
+      @history = {}
+      @context = Context.wrap(context)
+      snapshot!(tag: :initial)
+      @rules.each { |rule| apply(rule) }
+      result
+    end
+
+    def history(key:)
+      return [] unless defined?(@history)
+
+      @history.map { |tag, content| [tag, content.fetch(key, nil)] }
+    end
+
+    private
+
+    def snapshot!(tag:)
+      @history[tag] = @context.dup
+    end
+
+    def apply(rule)
+      rule.context = @context
+      return unless rule.trigger?
+
+      rule.apply
+      snapshot!(tag: rule)
+    end
+  end
+end

data/lib/brule/rule.rb

@@ -0,0 +1,13 @@
+module Brule
+  Rule = Struct.new(:config) do
+    attr_accessor :context
+
+    def trigger?
+      true
+    end
+
+    def apply
+      raise NotImplementedError
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brule
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Nicolas Zermati
@@ -44,7 +44,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/brule.rb
+- lib/brule/context.rb
+- lib/brule/engine.rb
+- lib/brule/rule.rb
 homepage: https://rubygems.org/gems/brule
 licenses:
 - MIT