brule 0.0.2 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bd5036cc83ccf0a96b4140382d2e2653fc06e0d82f302b32c81f1c709c5f5d5
-  data.tar.gz: 12e045f88777df92fe435b7a0c0afda4bda6d2c737722f5932519a9d955086f5
+  metadata.gz: 669938141fcd377863b801be38726843c5f1ed81737754e76178923298794541
+  data.tar.gz: aa7e4e0b3c4a84f0ab2c449518097e3519d8ede931f350119946d7beeed11ea0
 SHA512:
-  metadata.gz: 95c5b969619e184e19286eab6738d923bdeb2acbe2c81ccf59c178333f1ce99ef0b1bdc237644652fdc40e28bce346ee5d85ed849ff23c13377d714339b2a1aa
-  data.tar.gz: bc9dcfd653ebe89004d28db445607a37ad3f844dee96f3fedad93007293d1add45a40fdc44042025162263b2b2564a26347ec90d3c595594bb017276c837bdc1
+  metadata.gz: 2e68b2077b6c133989d430b4b8226aea8b06dda3264b0e92892ec2684265350fcc969a9737d290cf32683c50cedee0699331a35c28830cd00b01872272aaf32f
+  data.tar.gz: 44da1bdbecb77ae14b17230997ce3b3b5a47c623ebf86a44836bd8a245f2f12644d152edb2f50f47834e99eed3f5cd2c7dbc072319dab7b9403891cfac16adce

data/README.md

@@ -0,0 +1,127 @@
+This project aims at providing a set of tools to build complex and evolving
+business rules. It helps when:
+
+* You decided to split the computation into smaller parts working together.
+* You need to keep old versions of the rules working.
+* You want to persist the rules leading to a result.
+* You want to make your tests independent from your production data.
+* You want to introspect the computation of a result.
+
+![Test](https://github.com/nicoolas25/brule-rb/workflows/Test/badge.svg?branch=master)
+
+## How does it work
+
+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
+whole to produce a single result.
+
+An _engine_ respond to `#call`, taking a `context` in argument. It produces a
+_result_ that is extracted from the _context_ by the `#result` method. Before
+doing that, the engine apply its _rules_.
+
+![Engine](https://github.com/nicoolas25/brule-rb/blob/master/docs/img/engine.png?raw=true)
+
+Each rule have two methods: `#trigger?` and `#apply`. `#apply` runs only when
+`trigger?` is true. `#apply` writes stuff to the context for other rules and
+for the engine to produce the result. Rules can be initialized with a
+_configuration_.
+
+![Rule](https://github.com/nicoolas25/brule-rb/blob/master/docs/img/rule.png?raw=true)
+
+
+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.
+
+## How does it look
+
+[Here](https://nicoolas25.github.io/brule-rb/examples/elephant_carpaccio.html)
+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.
+
+[This](https://nicoolas25.github.io/brule-rb/examples/elephant_carpaccio.html)
+is the smallest example and the _best_ one to refer to. More examples are
+available:
+
+- [Elephant Carpaccio](https://nicoolas25.github.io/brule-rb/examples/elephant_carpaccio.html)
+- [Car rental](https://nicoolas25.github.io/brule-rb/examples/car_rental.html)
+- [Studio rental](https://nicoolas25.github.io/brule-rb/examples/studio_rental.html)
+- [Promo code](https://nicoolas25.github.io/brule-rb/examples/promo_code.html) (WIP)
+
+## What does it bring to the table
+
+If you compare [this approach](https://nicoolas25.github.io/brule-rb/examples/elephant_carpaccio.html)
+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,7 @@
 # frozen_string_literal: true
 
 module Brule
-  autoload :Context, 'brule/context'
   autoload :Engine, 'brule/engine'
-  autoload :Result, 'brule/result'
   autoload :Rule, 'brule/rule'
+  autoload :Utils, 'brule/utils'
 end

data/lib/brule/engine.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Brule
+  class Engine
+    attr_reader :context, :rules
+
+    def initialize(rules:)
+      @rules = rules
+      @history = {}
+    end
+
+    def call(context = {})
+      @history = {}
+      @context = context
+      snapshot!(tag: :initial)
+      @rules.each { |rule| apply(rule) }
+      result
+    end
+
+    def history(key:)
+      @history.map { |tag, content| [tag, content.fetch(key, nil)] }
+    end
+
+    def to_hash
+      { 'engine_class' => self.class.name, 'rules' => @rules.map(&:to_hash) }
+    end
+
+    def self.from_hash(hash)
+      engine_class = Object.const_get(hash.fetch('engine_class'))
+      rules = hash.fetch('rules').map do |rule_hash|
+        rule_class = Object.const_get(rule_hash.fetch('rule_class'))
+        rule_class.from_hash(rule_hash)
+      end
+      engine_class.new(rules: rules)
+    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.to_tag)
+    end
+  end
+end

data/lib/brule/rule.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Brule
+  Rule = Struct.new(:config) do
+    attr_accessor :context
+
+    def trigger?
+      true
+    end
+
+    def apply
+      raise NotImplementedError
+    end
+
+    def to_tag
+      self
+    end
+
+    def to_hash
+      config_hash = block_given? ? yield(config) : config&.to_hash
+      { 'rule_class' => self.class.name, 'config' => config_hash }
+    end
+
+    def self.from_hash(hash)
+      raise ArgumentError unless hash.fetch('rule_class') == name
+
+      config_hash = hash.fetch('config')
+      new(block_given? ? yield(config_hash) : config_hash)
+    end
+
+    def self.context_reader(*keys)
+      keys.each do |key|
+        define_method(key) { context.fetch(key) }
+      end
+    end
+
+    def self.context_writer(*keys)
+      keys.each do |key|
+        define_method("#{key}=") { |value| context[key] = value }
+      end
+    end
+
+    def self.context_accessor(*keys)
+      context_reader(*keys)
+      context_writer(*keys)
+    end
+
+    def self.config_reader(*keys)
+      keys.each do |key|
+        define_method(key) { config.fetch(key) }
+      end
+    end
+  end
+end

data/lib/brule/utils.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Brule
+  module Utils
+    autoload :Either, 'brule/utils/either'
+  end
+end

data/lib/brule/utils/either.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module Brule
+  module Utils
+    class Either < Brule::Rule
+      TooManyMatches = Class.new(StandardError)
+      NoMatchFound = Class.new(StandardError)
+
+      extend Forwardable
+
+      def_delegators :only_match, :apply, :trigger?, :to_tag
+
+      config_reader 'rules'
+
+      def to_hash
+        super do |config|
+          config.to_hash.tap do |config_hash|
+            config_hash['rules'] = config.fetch('rules').map(&:to_hash)
+          end
+        end
+      end
+
+      def self.from_hash(*)
+        super do |config_hash|
+          config_hash.tap do |config|
+            config['rules'] = config_hash.fetch('rules').map do |rule_hash|
+              rule_class = Object.const_get(rule_hash.fetch('rule_class'))
+              rule_class.from_hash(rule_hash)
+            end
+          end
+        end
+      end
+
+      private
+
+      def only_match
+        matches = rules.select do |rule|
+          rule.context = context
+          rule.trigger?
+        end
+
+        if matches.size >= 2
+          raise TooManyMatches, "Rules #{matches.join(', ')} are all a match"
+        end
+
+        if matches.empty?
+          raise NoMatchFound, "No rules from #{rules.join(', ')} is a match"
+        end
+
+        matches.first
+      end
+    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.4.1
 platform: ruby
 authors:
 - Nicolas Zermati
@@ -38,14 +38,75 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.32'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.32'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: simplecov-lcov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
 description: 
 email: ''
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/brule.rb
-homepage: https://rubygems.org/gems/brule
+- lib/brule/engine.rb
+- lib/brule/rule.rb
+- lib/brule/utils.rb
+- lib/brule/utils/either.rb
+homepage: https://github.com/nicoolas25/brule-rb
 licenses:
 - MIT
 metadata: {}