rails-patterns 0.6.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 0a30afb3f25ef523a75a54887fc9ff48f7567ac8
-  data.tar.gz: b3d71af078c2287b6c1f6e16bc140d267879b49b
+SHA256:
+  metadata.gz: acffaa9187d107e66c029e063f1d9cd5fbb2a3f16af7c2f747f166bc3bafab64
+  data.tar.gz: '014944374d20b4e6113c2946e25c963aaebd5841dad52cf960f85896c29930e5'
 SHA512:
-  metadata.gz: 2bb36981deb575dd7e900bb41c14d89e230c60ea67896b87643ed332923cf13b32880599111c672d0591f01836fc81d2e87381337ec100d304fdf726e93f67ac
-  data.tar.gz: debed57e679b131544e8b7c76f95944f0128570f71f3959187fbce79081a2848a9c2e8cfdbc257855df15f3d80b2c717c94d958428d0d23ad472825e1bf23d92
+  metadata.gz: def79504af62d2295806ab1a6e35261ad413d9205cfe36c41d4ae110068cfb5afe267aee4b194dbe2199616ca2ca976d6ffc63d5ca2166875b73d80c1e3fc9df
+  data.tar.gz: 84033ea6eb230ddf0436bda70889f4f62d46bb734d490635f564232b00bd199cdca595729e0eddae5055679e6575debcc19ed0385236e47b01b253510c86df8c

data/.github/workflows/ruby.yml

@@ -0,0 +1,33 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [ '2.5', '2.6', '2.7' ]
+    name: RSpec for Ruby version ${{ matrix.ruby }}
+    steps:
+      - uses: actions/checkout@v2
+      - uses: supercharge/redis-github-action@1.1.0
+      - name: Set up Ruby
+        uses: actions/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - run: gem install bundler
+      - run: bundle install
+      - run: bundle exec rspec

data/Gemfile

@@ -3,16 +3,19 @@ source "https://rubygems.org"
 gem "activerecord", ">= 4.2.6"
 gem "actionpack", ">= 4.2.6"
 gem "virtus"
+gem "ruby2_keywords"
 
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.
 
 group :development do
   gem "rspec"
-  gem "bundler", "~> 1.0"
-  gem "juwelier", "~> 2.1.0"
+  gem "bundler", "~> 2.0"
+  gem "juwelier"
 end
 
 group "test" do
   gem "pry-rails"
+  gem "rspec_junit_formatter"
+  gem "redis"
 end

data/Gemfile.lock

@@ -1,87 +1,95 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (5.1.4)
-      actionview (= 5.1.4)
-      activesupport (= 5.1.4)
-      rack (~> 2.0)
+    actionpack (6.0.3.2)
+      actionview (= 6.0.3.2)
+      activesupport (= 6.0.3.2)
+      rack (~> 2.0, >= 2.0.8)
       rack-test (>= 0.6.3)
       rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.0.2)
-    actionview (5.1.4)
-      activesupport (= 5.1.4)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actionview (6.0.3.2)
+      activesupport (= 6.0.3.2)
       builder (~> 3.1)
       erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.0.3)
-    activemodel (5.1.4)
-      activesupport (= 5.1.4)
-    activerecord (5.1.4)
-      activemodel (= 5.1.4)
-      activesupport (= 5.1.4)
-      arel (~> 8.0)
-    activesupport (5.1.4)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activemodel (6.0.3.2)
+      activesupport (= 6.0.3.2)
+    activerecord (6.0.3.2)
+      activemodel (= 6.0.3.2)
+      activesupport (= 6.0.3.2)
+    activesupport (6.0.3.2)
       concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (~> 0.7)
+      i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
-    addressable (2.5.2)
-      public_suffix (>= 2.0.2, < 4.0)
-    arel (8.0.0)
+      zeitwerk (~> 2.2, >= 2.2.2)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
     axiom-types (0.1.1)
       descendants_tracker (~> 0.0.4)
       ice_nine (~> 0.11.0)
       thread_safe (~> 0.3, >= 0.3.1)
-    builder (3.2.3)
+    builder (3.2.4)
     coderay (1.1.2)
     coercible (1.0.0)
       descendants_tracker (~> 0.0.1)
-    concurrent-ruby (1.0.5)
-    crass (1.0.3)
+    concurrent-ruby (1.1.6)
+    crass (1.0.6)
     descendants_tracker (0.0.4)
       thread_safe (~> 0.3, >= 0.3.1)
     diff-lcs (1.3)
     equalizer (0.0.11)
-    erubi (1.7.0)
-    faraday (0.12.2)
+    erubi (1.9.0)
+    faraday (1.3.0)
+      faraday-net_http (~> 1.0)
       multipart-post (>= 1.2, < 3)
-    git (1.3.0)
-    github_api (0.18.2)
+      ruby2_keywords
+    faraday-net_http (1.0.1)
+    git (1.8.1)
+      rchardet (~> 1.8)
+    github_api (0.19.0)
       addressable (~> 2.4)
       descendants_tracker (~> 0.0.4)
-      faraday (~> 0.8)
+      faraday (>= 0.8, < 2)
       hashie (~> 3.5, >= 3.5.2)
       oauth2 (~> 1.0)
-    hashie (3.5.7)
-    highline (1.7.10)
-    i18n (0.9.1)
+    hashie (3.6.0)
+    highline (2.0.3)
+    i18n (1.8.3)
       concurrent-ruby (~> 1.0)
     ice_nine (0.11.2)
-    juwelier (2.1.3)
+    juwelier (2.4.9)
       builder
-      bundler (>= 1.13)
-      git (>= 1.2.5)
+      bundler
+      git
       github_api
-      highline (>= 1.6.15)
-      nokogiri (>= 1.5.10)
+      highline
+      kamelcase (~> 0)
+      nokogiri
+      psych
       rake
       rdoc
-      semver
-    jwt (1.5.6)
-    loofah (2.1.1)
+      semver2
+    jwt (2.2.3)
+    kamelcase (0.0.2)
+      semver2 (~> 3)
+    loofah (2.6.0)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     method_source (0.9.0)
-    mini_portile2 (2.3.0)
-    minitest (5.11.1)
-    multi_json (1.13.1)
+    mini_portile2 (2.5.3)
+    minitest (5.14.1)
+    multi_json (1.15.0)
     multi_xml (0.6.0)
-    multipart-post (2.0.0)
-    nokogiri (1.8.1)
-      mini_portile2 (~> 2.3.0)
-    oauth2 (1.4.0)
-      faraday (>= 0.8, < 0.13)
-      jwt (~> 1.0)
+    multipart-post (2.1.1)
+    nokogiri (1.11.7)
+      mini_portile2 (~> 2.5.0)
+      racc (~> 1.4)
+    oauth2 (1.4.7)
+      faraday (>= 0.8, < 2.0)
+      jwt (>= 1.0, < 3.0)
       multi_json (~> 1.3)
       multi_xml (~> 0.5)
       rack (>= 1.2, < 3)
@@ -90,17 +98,21 @@ GEM
       method_source (~> 0.9.0)
     pry-rails (0.3.6)
       pry (>= 0.10.4)
-    public_suffix (3.0.1)
-    rack (2.0.3)
-    rack-test (0.8.2)
+    psych (4.0.1)
+    public_suffix (4.0.6)
+    racc (1.5.2)
+    rack (2.2.3)
+    rack-test (1.1.0)
       rack (>= 1.0, < 3)
     rails-dom-testing (2.0.3)
       activesupport (>= 4.2.0)
       nokogiri (>= 1.6)
-    rails-html-sanitizer (1.0.3)
-      loofah (~> 2.0)
-    rake (12.3.0)
-    rdoc (6.0.1)
+    rails-html-sanitizer (1.3.0)
+      loofah (~> 2.3)
+    rake (13.0.3)
+    rchardet (1.8.0)
+    rdoc (6.3.1)
+    redis (4.1.4)
     rspec (3.7.0)
       rspec-core (~> 3.7.0)
       rspec-expectations (~> 3.7.0)
@@ -113,16 +125,20 @@ GEM
     rspec-mocks (3.7.0)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.7.0)
-    rspec-support (3.7.0)
-    semver (1.0.1)
+    rspec-support (3.7.1)
+    rspec_junit_formatter (0.3.0)
+      rspec-core (>= 2, < 4, != 2.12.0)
+    ruby2_keywords (0.0.2)
+    semver2 (3.4.2)
     thread_safe (0.3.6)
-    tzinfo (1.2.4)
+    tzinfo (1.2.7)
       thread_safe (~> 0.1)
     virtus (1.0.5)
       axiom-types (~> 0.1)
       coercible (~> 1.0)
       descendants_tracker (~> 0.0, >= 0.0.3)
       equalizer (~> 0.0, >= 0.0.9)
+    zeitwerk (2.3.0)
 
 PLATFORMS
   ruby
@@ -130,11 +146,14 @@ PLATFORMS
 DEPENDENCIES
   actionpack (>= 4.2.6)
   activerecord (>= 4.2.6)
-  bundler (~> 1.0)
-  juwelier (~> 2.1.0)
+  bundler (~> 2.0)
+  juwelier
   pry-rails
+  redis
   rspec
+  rspec_junit_formatter
+  ruby2_keywords
   virtus
 
 BUNDLED WITH
-   1.15.1
+   2.1.4

data/README.md

@@ -1,12 +1,15 @@
+![](https://github.com/Selleo/pattern/workflows/Ruby/badge.svg)
+
 # Pattern
 
-A collection of lightweight, standardized, rails-oriented patterns.
+A collection of lightweight, standardized, rails-oriented patterns used by [RubyOnRails Developers @ Selleo](https://selleo.com/ruby-on-rails)
 
 - [Query - complex querying on active record relation](#query)
 - [Service - useful for handling processes involving multiple steps](#service)
 - [Collection - when in need to add a method that relates to the collection as whole](#collection)
 - [Form - when you need a place for callbacks, want to replace strong parameters or handle virtual/composite resources](#form)
 - [Calculation - when you need a place for calculating a simple value (numeric, array, hash) and/or cache it](#calculation)
+- [Rule and Ruleset - when you need a place for conditional logic](#rule-and-ruleset)
 
 ## Installation
 
@@ -21,13 +24,14 @@ gem "rails-patterns"
 Then `bundle install`
 
 ## Query
- 
+
 ### When to use it
 
-One should consider using query objects pattern when in need to perform complex querying on active record relation. 
-Usually one should avoid using scopes for such purpose. 
+One should consider using query objects pattern when in need to perform complex querying on active record relation.
+Usually one should avoid using scopes for such purpose.
 As a rule of thumb, if scope interacts with more than one column and/or joins in other tables, it should be moved to query object.
 Also whenever a chain of scopes is to be used, one should consider using query object too.
+Some more information on using query objects can be found in [this article](https://medium.com/@blazejkosmowski/essential-rubyonrails-patterns-part-2-query-objects-4b253f4f4539).
 
 ### Assumptions and rules
 
@@ -74,7 +78,7 @@ RecentlyActivatedUsersQuery.call(date_range: Date.today.beginning_of_day..Date.t
 RecentlyActivatedUsersQuery.call(User.without_test_users, date_range: Date.today.beginning_of_day..Date.today.end_of_day)
 
 class User < ApplicationRecord
-  scope :recenty_activated, RecentlyActivatedUsersQuery
+  scope :recently_activated, RecentlyActivatedUsersQuery
 end
 ```
 
@@ -83,7 +87,7 @@ end
 ### When to use it
 
 Service objects are commonly used to mitigate problems with model callbacks that interact with external classes ([read more...](http://samuelmullen.com/2013/05/the-problem-with-rails-callbacks/)).
-Service objects are also useful for handling processes involving multiple steps. E.g. a controller that performs more than one operation on its subject (usually a model instance) is a possible candidate for Extract ServiceObject (or Extract FormObject) refactoring. In many cases service object can be used as scaffolding for [replace method with object refactoring](https://sourcemaking.com/refactoring/replace-method-with-method-object).
+Service objects are also useful for handling processes involving multiple steps. E.g. a controller that performs more than one operation on its subject (usually a model instance) is a possible candidate for Extract ServiceObject (or Extract FormObject) refactoring. In many cases service object can be used as scaffolding for [replace method with object refactoring](https://sourcemaking.com/refactoring/replace-method-with-method-object). Some more information on using services can be found in [this article](https://medium.com/selleo/essential-rubyonrails-patterns-part-1-service-objects-1af9f9573ca1).
 
 ### Assumptions and rules
 
@@ -94,9 +98,9 @@ Service objects are also useful for handling processes involving multiple steps.
 * It is recommended for `#call` method to be the only public method of service object (besides state readers)
 * It is recommended to name service object classes after commands (e.g. `ActivateUser` instead of `UserActivation`)
 
-### Other 
+### Other
 
-A bit higher level of abstraction is provided by [business_process gem](https://github.com/Selleo/business_process). 
+A bit higher level of abstraction is provided by [business_process gem](https://github.com/Selleo/business_process).
 
 ### Examples
 
@@ -188,7 +192,7 @@ Form objects, just like service objects, are commonly used to mitigate problems
 Form objects can also be used as replacement for `ActionController::StrongParameters` strategy, as all writable attributes are re-defined within each form.
 Finally form objects can be used as wrappers for virtual (with no model representation) or composite (saving multiple models at once) resources.
 In the latter case this may act as replacement for `ActiveRecord::NestedAttributes`.
-In some cases FormObject can be used as scaffolding for [replace method with object refactoring](https://sourcemaking.com/refactoring/replace-method-with-method-object).
+In some cases FormObject can be used as scaffolding for [replace method with object refactoring](https://sourcemaking.com/refactoring/replace-method-with-method-object). Some more information on using form objects can be found in [this article](https://medium.com/selleo/essential-rubyonrails-patterns-form-objects-b199aada6ec9).
 
 ### Assumptions and rules
 
@@ -344,6 +348,93 @@ TotalCurrentRevenue.calculate
 AverageDailyRevenue.result
 ```
 
+## Rule and Ruleset
+
+### When to use it
+
+Rule objects provide a place for dislocating/extracting conditional logic.
+
+Use it when:
+- given complex condition is duplicated in multiple places in your codebase
+- part of condition logic can be reused in some other place
+- there is a need to instantiate condition itself for some reason (i.e. to represent it in the interface)
+- responsibility of your class is blurred by complex conditional logic, and as a result...
+- ...tests for your class require multiple condition branches / nested contexts
+
+### Assumptions and rules
+
+* Rule has `#satisfied?`, `#applicable?`, `#not_applicable?` and `#forceable?` methods available.
+* Rule has to implement at least `#satisfied?` method. `#not_applicable?` and `#forceable?` are meant to be overridable.
+* `#forceable?` makes sense in scenario where condition is capable of being force-satisfied regardless if its actually satisfied or not. Is `true` by default.
+* Override `#not_applicable?` when method is applicable only under some specific conditions. Is `false` by default.
+* Rule requires a subject as first argument.
+* Multiple rules and rulesets can be combined into new ruleset as both share same interface and can be used interchangeably (composite pattern).
+
+#### Forcing rules
+
+On some occasions there is a situation in which some condition should be overridable.
+Let's say we may want send shipping notification even though given order was not paid for and under regular circumstances such notification should not be sent.
+In this case, while regular logic with some automated process would not trigger delivery, an action triggered by user from UI could do it, by passing `force: true` option to `#satisified?` methods.
+
+It might be good idea to test for `#forceable?` on the UI level to control visibility of such link/button.
+
+Overriding `#forceable` can be useful to prevent some edge cases, i.e. `ContactInformationProvidedRule` might check if customer for given order has provided any contact means by which a notification could be delivered.
+If not, ruleset containing such rule (and the rule itself) would not be "forceable" and UI could reflect that by querying `#forceable?`.
+
+#### Regular and strong rulesets
+
+While regular `Ruleset` can be satisfied or forced if any of its rules in not applicable, the
+`StrongRuleset` is not satisfied and not "forceable" if any of its rules is not applicable.
+
+#### `#not_applicable?` vs `#applicable?`
+
+It might be surprising that is is the negated version of the `#applicable?` predicate methods that is overridable.
+However, from the actual usage perspective, it usually easier to conceptually define when condition makes no sense than other way around.
+
+### Examples
+
+#### Declaration
+
+```ruby
+class OrderIsSentRule < Patterns::Rule
+  def satisfied?
+    subject.sent?
+  end
+end
+
+class OrderIsPaidRule < Patterns::Rule
+  def satisfied?
+    subject.paid?
+  end
+
+  def forceable?
+    true
+  end
+end
+
+OrderCompletedNotificationRuleset = Class.new(Patterns::Ruleset)
+OrderCompletedNotificationRuleset.
+  add_rule(:order_is_sent_rule).
+  add_rule(:order_is_paid_rule)
+```
+
+#### Usage
+
+```ruby
+OrderIsPaidRule.new(order).satisfied?
+OrderCompletedNotificationRuleset.new(order).satisfied?
+
+ResendOrderNotification.call(order) if OrderCompletedNotificationRuleset.new(order).satisfied?(force: true)
+```
+
 ## Further reading
 
 * [7 ways to decompose fat active record models](http://blog.codeclimate.com/blog/2012/10/17/7-ways-to-decompose-fat-activerecord-models/)
+
+## About Selleo
+
+![selleo](https://raw.githubusercontent.com/Selleo/selleo-resources/master/public/github_footer.png)
+
+Software development teams with an entrepreneurial sense of ownership at their core delivering great digital products and building culture people want to belong to. We are a community of engaged co-workers passionate about crafting impactful web solutions which transform the way our clients do business.
+
+All names and logos for [Selleo](https://selleo.com/about) are trademark of Selleo Labs Sp. z o.o. (formerly Selleo Sp. z o.o. Sp.k.)

data/Rakefile

@@ -21,6 +21,7 @@ Juwelier::Tasks.new do |gem|
   gem.description = "A collection of lightweight, standardized, rails-oriented patterns."
   gem.email = "b.kosmowski@selleo.com"
   gem.authors = ["Stevo"]
+  gem.required_ruby_version = ">= 2.5.0"
 
   # dependencies defined in Gemfile
 end

data/VERSION

@@ -1 +1 @@
-0.6.0
+0.10.0

data/lib/patterns/calculation.rb

@@ -1,3 +1,5 @@
+require 'digest'
+
 module Patterns
   class Calculation
     class_attribute :cache_expiry_every
@@ -7,8 +9,8 @@ module Patterns
       @subject = args.first
     end
 
-    def self.result(*args)
-      new(*args).cached_result
+    def self.result(*args, &block)
+      new(*args).cached_result(&block)
     end
 
     class << self
@@ -20,9 +22,13 @@ module Patterns
       self.cache_expiry_every = period
     end
 
-    def cached_result
-      Rails.cache.fetch(cache_key, expires_in: cache_expiry_period, force: cache_expiry_period.blank?) do
-        result
+    def cached_result(&block)
+      if cache_expiry_period.blank?
+        result(&block)
+      else
+        Rails.cache.fetch(cache_key, expires_in: cache_expiry_period) do
+          result(&block)
+        end
       end
     end
 
@@ -35,7 +41,15 @@ module Patterns
     end
 
     def cache_key
-      "#{self.class.name}_#{[subject, options].hash}"
+      "#{self.class.name}_#{hash_of(subject, options)}"
+    end
+
+    def self.hash_of(*args)
+      Digest::SHA1.hexdigest(args.map(&:to_s).join(':'))
+    end
+
+    def hash_of(*args)
+      self.class.hash_of(*args)
     end
 
     def cache_expiry_period

data/lib/patterns/rule.rb

@@ -0,0 +1,27 @@
+module Patterns
+  class Rule
+    def initialize(subject)
+      @subject = subject
+    end
+
+    def satisfied?
+      raise NotImplementedError
+    end
+
+    def not_applicable?
+      false
+    end
+
+    def applicable?
+      !not_applicable?
+    end
+
+    def forceable?
+      true
+    end
+
+    private
+
+    attr_reader :subject
+  end
+end

data/lib/patterns/ruleset.rb

@@ -0,0 +1,71 @@
+module Patterns
+  class Ruleset
+    class EmptyRuleset < StandardError; end
+
+    class << self
+      attr_accessor :rule_names
+    end
+
+    def self.rules
+      (rule_names || []).map do |rule_name|
+        rule_name.to_s.classify.constantize
+      end
+    end
+
+    def self.add_rule(rule_name)
+      self.rule_names ||= []
+      self.rule_names << rule_name.to_sym
+      self
+    end
+
+    def initialize(subject = nil)
+      raise EmptyRuleset if self.class.rules.empty?
+
+      @rules = self.class.rules.map { |rule| rule.new(subject) }
+    end
+
+    def satisfied?(force: false)
+      rules.all? do |rule|
+        rule.satisfied? ||
+          rule.not_applicable? ||
+          (force && rule.forceable?)
+      end
+    end
+
+    def not_satisfied?
+      !satisfied?
+    end
+
+    def applicable?
+      !not_applicable?
+    end
+
+    def not_applicable?
+      rules.all?(&:not_applicable?)
+    end
+
+    def forceable?
+      rules.all? do |rule|
+        rule.forceable? ||
+          rule.not_applicable? ||
+          rule.satisfied?
+      end
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      rules.each do |rule_or_ruleset|
+        if rule_or_ruleset.is_a?(Ruleset)
+          rule_or_ruleset.each(&block)
+        else
+          yield rule_or_ruleset
+        end
+      end
+    end
+
+    private
+
+    attr_reader :rules
+  end
+end

data/lib/patterns/service.rb

@@ -1,13 +1,17 @@
+require 'ruby2_keywords'
+
 module Patterns
   class Service
     attr_reader :result
 
-    def self.call(*args)
-      new(*args).tap do |service|
-        service.instance_variable_set(
-          "@result",
-          service.call
-        )
+    class << self
+      ruby2_keywords def call(*args)
+        new(*args).tap do |service|
+          service.instance_variable_set(
+            "@result",
+            service.call
+          )
+        end
       end
     end
 

data/lib/patterns/strong_ruleset.rb

@@ -0,0 +1,21 @@
+# StrongRuleset is not satisfied and not forceable if any of rules is not applicable
+
+module Patterns
+  class StrongRuleset < Ruleset
+    def satisfied?(force: false)
+      rules.all? do |rule|
+        (rule.applicable? && rule.satisfied?) || (force && rule.forceable?)
+      end
+    end
+
+    def not_applicable?
+      rules.any?(&:not_applicable?)
+    end
+
+    def forceable?
+      rules.all? do |rule|
+        (rule.applicable? && rule.forceable?) || rule.satisfied?
+      end
+    end
+  end
+end

data/lib/rails-patterns.rb

@@ -4,3 +4,6 @@ require "patterns/service"
 require "patterns/collection"
 require "patterns/calculation"
 require "patterns/form"
+require "patterns/rule"
+require "patterns/ruleset"
+require "patterns/strong_ruleset"