rails-patterns 0.4.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: af39ea7538e043642610c2ea2ff35a9fa5c8a0e7
-  data.tar.gz: ff3231a21b94a92280acf664497a40b3039f7140
+SHA256:
+  metadata.gz: 738d61388a1488705037348a76d42d69b4b92a83cdd6753a2d14d061768302a1
+  data.tar.gz: 9dcc97a76fa682b76ff8910e4146da62eff304c3a7f511343e31d7b8ed222c36
 SHA512:
-  metadata.gz: c3653e8ce337a6225ad14162600f8b2a462321fcca8595f8f1463920935749e17b48d3f7359530dff528bc7ff3f7175ddaa23b7ac1203903ff42b296bfb8c51d
-  data.tar.gz: 37f4e6cb0fc581140dfee9372386b9d37b77a092d63d798fb98d8617475ac249d2e8f49aa9d8092ae5630e3de5e48a0aa6677ed7d62e89429a788c9fb51e44f2
+  metadata.gz: 9961fcdafa85dca7ef1a91641c4867fa348cdeb20a30abda8e8a91ab3a33c9d3ae456d57a2761615c127bf656b793c8bda94e7cc21371a42bd413e57336babfc
+  data.tar.gz: 7a570f8a7836ff4a3404525d41323697850c46c4dae447512ab517acf036799afd7c14a57028f374a5cea8aa8b489d134e32a3bd8278563039242d33546a8f0a

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 "bundler", "~> 2.0"
   gem "juwelier", "~> 2.1.0"
 end
 
 group "test" do
   gem "pry-rails"
+  gem "rspec_junit_formatter"
+  gem "redis"
 end

data/Gemfile.lock

@@ -1,59 +1,61 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (5.0.2)
-      actionview (= 5.0.2)
-      activesupport (= 5.0.2)
-      rack (~> 2.0)
-      rack-test (~> 0.6.3)
+    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.0.2)
-      activesupport (= 5.0.2)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actionview (6.0.3.2)
+      activesupport (= 6.0.3.2)
       builder (~> 3.1)
-      erubis (~> 2.7.0)
+      erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.0.3)
-    activemodel (5.0.2)
-      activesupport (= 5.0.2)
-    activerecord (5.0.2)
-      activemodel (= 5.0.2)
-      activesupport (= 5.0.2)
-      arel (~> 7.0)
-    activesupport (5.0.2)
+      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.4.0)
-    arel (7.1.4)
+      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)
-    coderay (1.1.1)
+    builder (3.2.4)
+    coderay (1.1.2)
     coercible (1.0.0)
       descendants_tracker (~> 0.0.1)
-    concurrent-ruby (1.0.5)
+    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)
-    erubis (2.7.0)
-    faraday (0.9.2)
+    erubi (1.9.0)
+    faraday (0.17.3)
       multipart-post (>= 1.2, < 3)
-    git (1.3.0)
-    github_api (0.16.0)
-      addressable (~> 2.4.0)
+    git (1.7.0)
+      rchardet (~> 1.8)
+    github_api (0.18.2)
+      addressable (~> 2.4)
       descendants_tracker (~> 0.0.4)
-      faraday (~> 0.8, < 0.10)
-      hashie (>= 3.4)
-      mime-types (>= 1.16, < 3.0)
+      faraday (~> 0.8)
+      hashie (~> 3.5, >= 3.5.2)
       oauth2 (~> 1.0)
-    hashie (3.5.5)
-    highline (1.7.8)
-    i18n (0.8.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)
       builder
@@ -65,63 +67,68 @@ GEM
       rake
       rdoc
       semver
-    jwt (1.5.6)
-    loofah (2.0.3)
+    jwt (2.2.1)
+    loofah (2.6.0)
+      crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
-    method_source (0.8.2)
-    mime-types (2.99.3)
-    mini_portile2 (2.1.0)
-    minitest (5.10.1)
-    multi_json (1.12.1)
+    method_source (0.9.0)
+    mini_portile2 (2.4.0)
+    minitest (5.14.1)
+    multi_json (1.14.1)
     multi_xml (0.6.0)
-    multipart-post (2.0.0)
-    nokogiri (1.7.1)
-      mini_portile2 (~> 2.1.0)
-    oauth2 (1.3.1)
-      faraday (>= 0.8, < 0.12)
-      jwt (~> 1.0)
+    multipart-post (2.1.1)
+    nokogiri (1.10.9)
+      mini_portile2 (~> 2.4.0)
+    oauth2 (1.4.4)
+      faraday (>= 0.8, < 2.0)
+      jwt (>= 1.0, < 3.0)
       multi_json (~> 1.3)
       multi_xml (~> 0.5)
       rack (>= 1.2, < 3)
-    pry (0.10.4)
+    pry (0.11.3)
       coderay (~> 1.1.0)
-      method_source (~> 0.8.1)
-      slop (~> 3.4)
+      method_source (~> 0.9.0)
     pry-rails (0.3.6)
       pry (>= 0.10.4)
-    rack (2.0.1)
-    rack-test (0.6.3)
-      rack (>= 1.0)
-    rails-dom-testing (2.0.2)
-      activesupport (>= 4.2.0, < 6.0)
-      nokogiri (~> 1.6)
-    rails-html-sanitizer (1.0.3)
-      loofah (~> 2.0)
-    rake (12.0.0)
-    rdoc (5.1.0)
-    rspec (3.5.0)
-      rspec-core (~> 3.5.0)
-      rspec-expectations (~> 3.5.0)
-      rspec-mocks (~> 3.5.0)
-    rspec-core (3.5.4)
-      rspec-support (~> 3.5.0)
-    rspec-expectations (3.5.0)
+    public_suffix (4.0.5)
+    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.3.0)
+      loofah (~> 2.3)
+    rake (13.0.1)
+    rchardet (1.8.0)
+    rdoc (6.2.1)
+    redis (4.1.4)
+    rspec (3.7.0)
+      rspec-core (~> 3.7.0)
+      rspec-expectations (~> 3.7.0)
+      rspec-mocks (~> 3.7.0)
+    rspec-core (3.7.1)
+      rspec-support (~> 3.7.0)
+    rspec-expectations (3.7.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.5.0)
-    rspec-mocks (3.5.0)
+      rspec-support (~> 3.7.0)
+    rspec-mocks (3.7.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.5.0)
-    rspec-support (3.5.0)
+      rspec-support (~> 3.7.0)
+    rspec-support (3.7.1)
+    rspec_junit_formatter (0.3.0)
+      rspec-core (>= 2, < 4, != 2.12.0)
+    ruby2_keywords (0.0.2)
     semver (1.0.1)
-    slop (3.6.0)
     thread_safe (0.3.6)
-    tzinfo (1.2.3)
+    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
@@ -129,11 +136,14 @@ PLATFORMS
 DEPENDENCIES
   actionpack (>= 4.2.6)
   activerecord (>= 4.2.6)
-  bundler (~> 1.0)
+  bundler (~> 2.0)
   juwelier (~> 2.1.0)
   pry-rails
+  redis
   rspec
+  rspec_junit_formatter
+  ruby2_keywords
   virtus
 
 BUNDLED WITH
-   1.14.6
+   2.1.4

data/README.md

@@ -1,11 +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 a whole](#collection)
+- [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
 
@@ -27,6 +31,7 @@ One should consider using query objects pattern when in need to perform complex
 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
 
@@ -73,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
 ```
 
@@ -82,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.
+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
 
@@ -93,6 +98,10 @@ 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 
+
+A bit higher level of abstraction is provided by [business_process gem](https://github.com/Selleo/business_process). 
+
 ### Examples
 
 #### Declaration
@@ -162,7 +171,7 @@ class CustomerEventsByTypeCollection < Patterns::Collection
     subject.
     events.
     group_by(&:type).
-    transform_values{ |event| event.public_send(options.fetch(:label_method, "description")) }
+    transform_values{ |events| events.map{ |e| e.public_send(options.fetch(:label_method, "description")) }}
   end
 end
 ```
@@ -183,6 +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). 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
 
@@ -191,7 +201,7 @@ In the latter case this may act as replacement for `ActiveRecord::NestedAttribut
 * Forms can be initialized using `.new`.
 * Forms accept optional resource object as first constructor argument.
 * Forms accept optional attributes hash as latter constructor argument.
-* forms have to implement `#persist` method that returns falsey (if failed) or truthy (if succeeded) value.
+* Forms have to implement `#persist` method that returns falsey (if failed) or truthy (if succeeded) value.
 * Forms provide access to first constructor argument using `#resource`.
 * Forms are saved using their `#save` or `#save!` methods.
 * Forms will attempt to pre-populate their fields using `resource#attributes` and public getters for `resource`
@@ -269,6 +279,154 @@ ReportConfigurationForm.new
 ReportConfigurationForm.new({ include_extra_data: true, dump_as_csv: true })
 ```
 
+## Calculation
+
+### When to use it
+
+Calculation objects provide a place to calculate simple values (i.e. numeric, arrays, hashes), especially when calculations require interacting with multiple classes, and thus do not fit into any particular one.
+Calculation objects also provide simple abstraction for caching their results.
+
+### Assumptions and rules
+
+* Calculations have to implement `#result` method that returns any value (result of calculation).
+* Calculations do provide `.set_cache_expiry_every` method, that allows defining caching period.
+* When `.set_cache_expiry_every` is not used, result is not being cached.
+* Calculations return result by calling any of following methods: `.calculate`, `.result_for` or `.result`.
+* First argument passed to calculation is accessible by `#subject` private method.
+* Arguments hash passed to calculation is accessible by `#options` private method.
+* Caching takes into account arguments passed when building cache key.
+* To build cache key, `#cache_key` of each argument value is used if possible.
+* By default `Rails.cache` is used as cache store.
+
+### Examples
+
+#### Declaration
+
+```ruby
+class AverageHotelDailyRevenue < Patterns::Calculation
+  set_cache_expiry_every 1.day
+
+  private
+
+  def result
+    reservations.sum(:price) / days_in_year
+  end
+
+  def reservations
+    Reservation.where(
+      date: (beginning_of_year..end_of_year),
+      hotel_id: subject.id
+    )
+  end
+
+  def days_in_year
+    end_of_year.yday
+  end
+
+  def year
+    options.fetch(:year, Date.current.year)
+  end
+
+  def beginning_of_year
+    Date.new(year).beginning_of_year
+  end
+
+  def end_of_year
+    Date.new(year).end_of_year
+  end
+end
+```
+
+#### Usage
+
+```ruby
+hotel = Hotel.find(123)
+AverageHotelDailyRevenue.result_for(hotel)
+AverageHotelDailyRevenue.result_for(hotel, year: 2015)
+
+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 < Rule
+  def satisfied?
+    subject.sent?
+  end
+end
+
+class OrderIsPaidRule < Rule
+  def satisfied?
+    subject.paid?
+  end
+
+  def forceable?
+    true
+  end
+end
+
+OrderCompletedNotificationRuleset = Class.new(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/)