brule 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c5f4dc5b794023937b44626faefd5feb047030cad7dd4a6b1fa5ccb42624af3
-  data.tar.gz: 2be8c8844cbba6594cfe3d758ee69410aa2ff4df92288c42b6526a667c8969f7
+  metadata.gz: 13f788107d09cf82f121f314df0fd7247e808d4895a369afc56315aceaa21e84
+  data.tar.gz: 92d514d8305373969d48069d5627432d8d13e136ae0f38f1a94b1368ebbfb63c
 SHA512:
-  metadata.gz: b40a40a8b365cdd628d4382fd3a092905c43f4cc34e036eea47036cf41379a46ec806bef50abb98bc8a0b499ab19a0413a328a13199bd50b15e1130b39cf9b89
-  data.tar.gz: 73a0f66735eabb08f486df0760f9383e098ec11ea7630d73597c20e6e0c21fc5b1a4f84e54c395774e8afa46366383bee2d1050d6f5bf97388f2490f2a7ba15d
+  metadata.gz: fba662d4ee2caaffba41aba4368069c1ab1aab6730fcd0b84a73a7158a799e1e34149eac0f7e37627a56bf9c16ea0f4af26298e0ef15ce0a76df0487ddbcf895
+  data.tar.gz: 4f798d703d68a4e109b19c69469e1c86c2d16762ba45bb3cacc5cbf8ec3fe61ea64d57e1d942428d488655ea24068a541f79875071d2b3578f66d13bec02432b

data/README.md

@@ -22,7 +22,9 @@ 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.
+The idea is very similar to function composition or Rack's middlewares. It is a
+layering abstraction where each layer works for the next layers in order for the
+stack to produce a single value.
 
 ## How does it look
 
@@ -43,50 +45,51 @@ require "brule"
 module Pricing
   class Engine < Brule::Engine
     def result
-      context[:price]
+      context.fetch(:price)
     end
   end
 
   class OrderTotal < Brule::Rule
+    config_reader :unit_price, :item_count
+    context_writer :price
+
     def apply
-      context[:price] = context[:unit_price] * context[:item_count]
+      self.price = unit_price * item_count
     end
   end
 
   class Discount < Brule::Rule
+    config_reader :rates
+    context_accessor :price, :discount_rate, :discount_amount
+
     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,
-      )
+      self.discount_rate = applicable_discount.last
+      self.discount_amount = (price * discount_rate).ceil
+      self.price = price - discount_amount
     end
 
     private
 
     def applicable_discount
-      config[:rates]
+      rates
         .sort_by { |order_value, _| order_value * -1 }
-        .find    { |order_value, _| order_value <= context[:price] }
+        .find    { |order_value, _| order_value <= context.fetch(:price) }
     end
   end
 
   class StateTax < Brule::Rule
+    config_reader :rates
+    context_reader :state
+    context_accessor :price, :state_tax
+
     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,
-      )
+      tax_rate = rates.fetch(state)
+      self.state_tax = (price * tax_rate).ceil
+      self.price = price + state_tax
     end
   end
 end
@@ -136,10 +139,78 @@ engine.context.fetch_values(
 
 # Access the history
 engine.history(key: :price)   # => [
+                              # =>   [:initial,                                nil],
                               # =>   [#<struct Pricing::OrderTotal ...>, 10_000_00],
                               # =>   [#<struct Pricing::Discount ...>,    9_000_00],
                               # =>   [#<struct Pricing::StateTax ...>,    9_720_00],
                               # => ]
 ```
 
+## What does it bring to the table
+
+If you compare this approach with a simple method like this one:
+
+```ruby
+require "bigdecimal"
+require "bigdecimal/util"
+
+STATE_TAXES = {
+  "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,
+}
+
+DISCOUNT_RATES = [
+  [ 50_000_00, "0.15".to_d ],
+  [ 10_000_00, "0.10".to_d ],
+  [  7_000_00, "0.07".to_d ],
+  [  5_000_00, "0.05".to_d ],
+  [  1_000_00, "0.03".to_d ],
+  [         0, "0.00".to_d ],
+]
+
+def pricing(item_count, unit_price, state)
+  price = item_count * unit_price
+  discount_rate = DISCOUNT_RATES.find { |limit, _| limit <= price }.last
+  state_tax = STATE_TAXES.fetch(state)
+  price * (1 - discount_rate) * (1 + state_tax)
+end
+```
+
+... then you'll find significant differences:
+
+* Over-abstraction versus under-abstraction
+  * 1st example uses the layering abstraction provided by the gem
+  * 2nd example uses nothing, [YAGNI][yagni]
+* Generalization vs specialization
+  * 1st approach is more generic and could handle changes
+  * 2nd approach is more specialized and would require a rewrite
+* Complexity versus brievety
+  * 1st example is more verbose and thus is harder to grasp
+  * 2nd example is more concise and fits in the head
+* Configuration versus constants
+  * 1st example relies on rule's configuration
+  * 2nd example relies on `STATE_TAXES` and `DISCOUNT_RATES`
+* Observability vs black-box
+  * 1st example allows to provide more information (`state_tax` and so on)
+  * 2nd example only gives a single result
+* Data-independent versus hard-coded values
+  * 1st example considers as much logic as possible as data
+  * 2nd example mixes data and logic together (with hidden dependencies and assumptions)
+* Temporal extensibility or versionning
+  * 1st example can compute the price using different rules
+    * Without discounts or with different discount rate per client
+    * With tax rates from on year or another
+  * 2nd example will have to introduce options, or even different methods
+* Testability
+  * 1st example could be tested at various levels without any mocks
+  * 2nd example have to mock hidden dependencies from the implementation
+
+Overall, it is about finding the right level of abtsraction. This tiny framework
+helps you by providing you a little abstraction. Even if you're not using this
+gem directly, it can give you some ideas behind it.
+
 [elephant]: https://docs.google.com/document/d/1Ls6pTmhY_LV8LwFiboUXoFXenXZl0qVZWPZ8J4uoqpI/edit#
+[yagni]: https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it

data/lib/brule.rb

@@ -1,8 +1,98 @@
 # frozen_string_literal: true
 
+require 'forwardable'
+
 module Brule
-  autoload :Context, 'brule/context'
-  autoload :Engine, 'brule/engine'
-  autoload :Result, 'brule/result'
-  autoload :Rule, 'brule/rule'
+  module RuleHelpers
+    def context_reader(*symbols)
+      symbols.each do |symbol|
+        define_method(symbol) { context.fetch(symbol) }
+      end
+    end
+
+    def context_writer(*symbols)
+      symbols.each do |symbol|
+        define_method("#{symbol}=") { |value| context[symbol] = value }
+      end
+    end
+
+    def context_accessor(*symbols)
+      context_reader(*symbols)
+      context_writer(*symbols)
+    end
+
+    def config_reader(*symbols)
+      symbols.each do |symbol|
+        define_method(symbol) { config.fetch(symbol) }
+      end
+    end
+  end
+
+  Rule = Struct.new(:config) do
+    extend RuleHelpers
+
+    attr_accessor :context
+
+    def trigger?
+      true
+    end
+
+    def apply
+      raise NotImplementedError
+    end
+  end
+
+  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
+  end
+
+  class Engine
+    attr_reader :context
+
+    def initialize(rules:)
+      @rules = rules
+      @history = {}
+    end
+
+    def call(context = {})
+      @history = {}
+      @context = Context.wrap(context)
+      snapshot!(tag: :initial)
+      @rules.each { |rule| apply(rule) }
+      result
+    end
+
+    def history(key:)
+      @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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brule
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Nicolas Zermati
@@ -46,10 +46,7 @@ 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
+homepage: https://github.com/nicoolas25/brule-rb
 licenses:
 - MIT
 metadata: {}

data/lib/brule/context.rb

@@ -1,24 +0,0 @@
-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

@@ -1,37 +0,0 @@
-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

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