rails-patterns 0.3.0 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 2318f3f2a2753ab5159fa535d0245110eca7133c
-  data.tar.gz: 6031c700f903e0a62ef3a9951f83932d590a887c
+SHA256:
+  metadata.gz: ffa6ee8fff6415c7271eb4a38172148881cdd8866d0279e59abffd452b54f591
+  data.tar.gz: a8e077bf276d9a6a3a05f345d09085561ccb5f06996b7c7a8a01f4082cf329b5
 SHA512:
-  metadata.gz: 4eabca7c85d89675918642a3f07c72effce0fccb4d709cc4d13c986cb549b9216dc7913cf2303ca464efa69c157b168f3d71301dd0422af13c738fce639e47e4
-  data.tar.gz: b3d706d159d0abedab70f3aadb818c1b977463aa37e683f8a5bd2b3d139a187e3ac72d4b18b98def990ff739ce5d5b224b9de2f03c27e5585283f4213d4479df
+  metadata.gz: d4e616146039004e697d7a2b3fc3ef89eaaaaf11779af4744a605d2102b967b8b4b9856147a1b111db5c801fde833ca19c0c5ba067a246977a14c14d7f9c2f54
+  data.tar.gz: 1e883e3cbfc21fc4e7135acc9b23dc4db7e05b2a4671cfe6d618f04b5df4d672c7ac8f76487ae34cce503fd2fdc51e2a0952dffbc66964943c85b8136a0dd509

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

@@ -1,17 +1,21 @@
 source "https://rubygems.org"
-# Add dependencies required to use your gem here.
-# Example:
-  gem "activerecord", ">= 4.2.6"
+
+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,38 +1,62 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    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)
+    actionpack (6.0.3.1)
+      actionview (= 6.0.3.1)
+      activesupport (= 6.0.3.1)
+      rack (~> 2.0, >= 2.0.8)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actionview (6.0.3.1)
+      activesupport (= 6.0.3.1)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activemodel (6.0.3.1)
+      activesupport (= 6.0.3.1)
+    activerecord (6.0.3.1)
+      activemodel (= 6.0.3.1)
+      activesupport (= 6.0.3.1)
+    activesupport (6.0.3.1)
       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)
-    builder (3.2.3)
-    coderay (1.1.1)
-    concurrent-ruby (1.0.5)
+      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.4)
+    coderay (1.1.2)
+    coercible (1.0.0)
+      descendants_tracker (~> 0.0.1)
+    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)
-    faraday (0.9.2)
+    equalizer (0.0.11)
+    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.2)
+      concurrent-ruby (~> 1.0)
+    ice_nine (0.11.2)
     juwelier (2.1.3)
       builder
       bundler (>= 1.13)
@@ -43,59 +67,83 @@ GEM
       rake
       rdoc
       semver
-    jwt (1.5.6)
-    method_source (0.8.2)
-    mime-types (2.99.3)
-    mini_portile2 (2.1.0)
-    minitest (5.10.1)
-    multi_json (1.12.1)
+    jwt (2.2.1)
+    loofah (2.5.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    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)
-    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.2)
+    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
 
 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,6 +1,14 @@
+![](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)
 
 ## Installation
 
@@ -22,6 +30,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
 
@@ -68,7 +77,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
 ```
 
@@ -77,7 +86,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
 
@@ -88,6 +97,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
@@ -157,7 +170,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
 ```
@@ -166,8 +179,172 @@ end
 
 ```ruby
 ColorsCollection.new
-CustomerEventsCollection.for(customer)
-CustomerEventsCollection.for(customer, label_method: "name")
+CustomerEventsByTypeCollection.for(customer)
+CustomerEventsByTypeCollection.for(customer, label_method: "name")
+```
+
+## Form
+
+### When to use it
+
+Form objects, just like 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/)).
+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
+
+* Forms include `ActiveModel::Validations` to support validation.
+* Forms include `Virtus.model` to support `attribute` static method with all [corresponding capabilities](https://github.com/solnic/virtus).
+* 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 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`
+* Form's fields are populated with passed-in attributes hash reverse-merged with pre-populated attributes if possible.
+* Forms provide `#as` builder method that populates internal `@form_owner` variable (can be used to store current user).
+* Forms allow defining/overriding their `#param_key` method result by using `.param_key` static method. This defaults to `#resource#model_name#param_key`.
+* Forms delegate `#persisted?` method to `#resource` if possible.
+* Forms do handle `ActionController::Parameters` as attributes hash (using `to_unsafe_h`)
+* It is recommended to wrap `#persist` method in transaction if possible and if multiple model are affected.
+
+### Examples
+
+#### Declaration
+
+```ruby
+class UserForm < Patterns::Form
+  param_key "person"
+
+  attribute :first_name, String
+  attribute :last_name, String
+  attribute :age, Integer
+  attribute :full_address, String
+  attribute :skip_notification, Boolean
+
+  validate :first_name, :last_name, presence: true
+
+  private
+
+  def persist
+    update_user and
+      update_address and
+      deliver_notification
+  end
+
+  def update_user
+    resource.update_attributes(attributes.except(:full_address, :skip_notification))
+  end
+
+  def update_address
+    resource.address.update_attributes(full_address: full_address)
+  end
+
+  def deliver_notification
+    skip_notification || UserNotifier.user_update_notification(user, form_owner).deliver
+  end
+end
+
+class ReportConfigurationForm < Patterns::Form
+  param_key "report"
+
+  attribute :include_extra_data, Boolean
+  attribute :dump_as_csv, Boolean
+  attribute :comma_separated_column_names, String
+  attribute :date_start, Date
+  attribute :date_end, Date
+
+  private
+
+  def persist
+    SendReport.call(attributes)
+  end
+end
+```
+
+#### Usage
+
+```ruby
+form = UserForm.new(User.find(1), params[:person])
+form.save
+
+form = UserForm.new(User.new, params[:person]).as(current_user)
+form.save!
+
+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
 ```
 
 ## Further reading