auxiliary_rails 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6270fee8c57097f95277b91cb770228af36551459ebd01fbbe1900ff43a5b4b3
-  data.tar.gz: 6b6e074c5751b729106fe2dcdc1f606474a95f6575eb8df0b1cbd68d54ebbe7b
+  metadata.gz: d2dca627a51fe1045de4e00f82cd2ac9dcc96df20816d7de67a8bf818180a06c
+  data.tar.gz: e5ae6c889d8ed752d382d86822410a409daaf9f14b04cbf833938af32adab6e9
 SHA512:
-  metadata.gz: 77302dee8e26ab571731ee47779f70ade277fc5c476f197259a18d321336c0952f45bb69bba62bcde6d52cba677c979ac00646cc8e8165e7288da023cabb5642
-  data.tar.gz: 450261a1b391e70b1cd7b926bb0cb4985f2f82021713041be5f6f04a403ea0b48eb9b8623ea2178c40a10533d05013067997dd15868def2a686947187af9fccc
+  metadata.gz: cabb77bb72b361996f1bd9623768d7c1af219c0f1bed3a516781493b0b77b7892bb42a3e4ffbefaabd879862fd7b3f25872a87e814e6b7aa7ec2bfc51e1e93d1
+  data.tar.gz: 07d26c7e442836147af787b33b5d6300f8e3d01c4b60a53fd31cbf0381158a7af5f16f8cb67af8d395ac8df25333cc75de8edaf8d1b0eb01e5cb1f708a1ebc43

data/.gitlab-ci.yml

@@ -0,0 +1,26 @@
+image: ruby:2.6
+
+cache:
+  paths:
+    - vendor/bundle
+    - vendor/ruby
+
+before_script:
+  - ruby -v
+  - gem install bundler --no-document
+  - bundle config set path 'vendor'
+  - bundle install --jobs $(nproc)
+
+rspec:
+  stage: test
+  script:
+    - bundle exec rspec
+
+rubocop:
+  stage: test
+  allow_failure: true
+  script:
+    - bundle exec rubocop
+
+stages:
+  - test

data/.rubocop.yml

@@ -7,13 +7,17 @@ require:
 
 AllCops:
   Exclude:
-    - vendor/bundle/**/* # fix for running on Travis CI
+    - lib/generators/auxiliary_rails/templates/**/*
+    - vendor/**/* # fix for CI
 
 #################### Layout ##############################
 
-Layout/AlignArguments:
+Layout/ArgumentAlignment:
   EnforcedStyle: with_fixed_indentation
 
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
 #################### Metrics ##############################
 
 Metrics/BlockLength:
@@ -22,6 +26,8 @@ Metrics/BlockLength:
 
 #################### RSpec ################################
 
+RSpec/ExampleLength:
+  Max: 10
 
 RSpec/MultipleExpectations:
   Max: 3
@@ -33,3 +39,6 @@ Style/Documentation:
 
 Style/FrozenStringLiteralComment:
   Enabled: false
+
+Style/NegatedIf:
+  EnforcedStyle: postfix

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2019-05-12 09:23:17 +0300 using RuboCop version 0.68.1.
+# on 2020-01-25 02:14:48 +0200 using RuboCop version 0.78.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -8,20 +8,24 @@
 
 # Offense count: 1
 # Cop supports --auto-correct.
-# Configuration parameters: AllowForAlignment, AllowBeforeTrailingComments, ForceEqualSignAlignment.
-Layout/ExtraSpacing:
+Lint/SendWithMixinArgument:
   Exclude:
-    - 'auxiliary_rails.gemspec'
+    - 'lib/auxiliary_rails/railtie.rb'
 
 # Offense count: 1
-# Cop supports --auto-correct.
-# Configuration parameters: AllowForAlignment.
-Layout/SpaceAroundOperators:
-  Exclude:
-    - 'auxiliary_rails.gemspec'
+RSpec/NestedGroups:
+  Max: 4
 
 # Offense count: 1
 # Configuration parameters: MinBodyLength.
 Style/GuardClause:
   Exclude:
     - 'auxiliary_rails.gemspec'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, AllowInnerSlashes.
+# SupportedStyles: slashes, percent_r, mixed
+Style/RegexpLiteral:
+  Exclude:
+    - 'lib/generators/auxiliary_rails/command_generator.rb'

data/.yardopts

@@ -0,0 +1,5 @@
+--title "AuxiliaryRails"
+--private --protected
+--exclude lib/generators/*
+--exclude lib/auxiliary_rails.rb
+--exclude lib/auxiliary_rails/railtie.rb

data/CHANGELOG.md

@@ -1,9 +1,26 @@
 # AuxiliaryRails Changelog
 
+## v0.3.0
+
+### Added
+- Form Objects
+- Query Objects
+- Performable concern
+- YARD docs and link to API documentation
+- Commands usage examples
+- Commands: `arguments` helper to get hash of all `param`s
+
+### Changed
+- Namespace `Application` instead of `Abstract` prefixes for classes
+- Commands migrate from `#call` to `#perform` method
+- Commands: force validations
+
+### Removed
+- RuboCop generator replaced with `rubocop-ergoserv` gem
+
 ## v0.2.0
 
 * Commands migration to `dry-initializer`
-* Commands usage examples
 
 ## v0.1.7
 
@@ -26,7 +43,7 @@
 
 ## v0.1.3
 
-* Upgrate `rubocop` gem and its configs
+* Upgrade `rubocop` gem and its configs
 * `rubocop-rspec` and `rubocop-performance` gem iteration
 * Added basic Rails application template
 * CLI with `create_rails_app` command

data/CONTRIBUTING.md

@@ -1,7 +1 @@
 # Contributing to AuxiliaryRails
-
-## Rubocop Templates
-
-### Versioning
-
-File `rubocop_auxiliary_rails_template.yml` contains a basic template of Rubocop config. After making any changes to this file the line `Version: N` should be updated and `N` (version number) should be incremented by one.

data/Gemfile.lock

@@ -1,7 +1,9 @@
 PATH
   remote: .
   specs:
-    auxiliary_rails (0.2.0)
+    auxiliary_rails (0.3.0)
+      dry-core
+      dry-initializer
       dry-initializer-rails
       thor
 
@@ -66,17 +68,19 @@ GEM
     ast (2.4.0)
     builder (3.2.4)
     coderay (1.1.2)
-    concurrent-ruby (1.1.5)
-    crass (1.0.5)
+    concurrent-ruby (1.1.6)
+    crass (1.0.6)
     diff-lcs (1.3)
-    dry-initializer (3.0.2)
+    dry-core (0.4.9)
+      concurrent-ruby (~> 1.0)
+    dry-initializer (3.0.3)
     dry-initializer-rails (3.1.1)
       dry-initializer (>= 2.4, < 4)
       rails (> 3.0)
     erubi (1.9.0)
     globalid (0.4.2)
       activesupport (>= 4.2.0)
-    i18n (1.7.0)
+    i18n (1.8.2)
       concurrent-ruby (~> 1.0)
     jaro_winkler (1.5.4)
     loofah (2.4.0)
@@ -87,20 +91,20 @@ GEM
     marcel (0.3.3)
       mimemagic (~> 0.3.2)
     method_source (0.9.2)
-    mimemagic (0.3.3)
+    mimemagic (0.3.4)
     mini_mime (1.0.2)
     mini_portile2 (2.4.0)
-    minitest (5.13.0)
+    minitest (5.14.0)
     nio4r (2.5.2)
-    nokogiri (1.10.7)
+    nokogiri (1.10.9)
       mini_portile2 (~> 2.4.0)
     parallel (1.19.1)
-    parser (2.7.0.1)
+    parser (2.7.0.4)
       ast (~> 2.4.0)
     pry (0.12.2)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
-    rack (2.0.8)
+    rack (2.2.2)
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
     rails (6.0.2.1)
@@ -144,16 +148,16 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.9.0)
     rspec-support (3.9.2)
-    rubocop (0.78.0)
+    rubocop (0.79.0)
       jaro_winkler (~> 1.5.1)
       parallel (~> 1.10)
-      parser (>= 2.6)
+      parser (>= 2.7.0.1)
       rainbow (>= 2.2.2, < 4.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 1.7)
     rubocop-performance (1.5.2)
       rubocop (>= 0.71.0)
-    rubocop-rspec (1.37.1)
+    rubocop-rspec (1.38.1)
       rubocop (>= 0.68.1)
     ruby-progressbar (1.10.1)
     sprockets (4.0.0)
@@ -167,11 +171,11 @@ GEM
     thread_safe (0.3.6)
     tzinfo (1.2.6)
       thread_safe (~> 0.1)
-    unicode-display_width (1.6.0)
+    unicode-display_width (1.6.1)
     websocket-driver (0.7.1)
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.4)
-    zeitwerk (2.2.2)
+    zeitwerk (2.3.0)
 
 PLATFORMS
   ruby
@@ -183,7 +187,7 @@ DEPENDENCIES
   rails (>= 5.2, < 7)
   rake
   rspec (~> 3.8)
-  rubocop
+  rubocop (= 0.79)
   rubocop-performance
   rubocop-rspec
 

data/README.md

@@ -29,18 +29,22 @@ Or install it yourself as:
 
 ## Usage
 
+- [API documentation](https://www.rubydoc.info/gems/auxiliary_rails)
+
 ### Rails Application Templates
 
 Install gem into the system (e.g. using `gem install auxiliary_rails`) then:
 
 ```sh
 auxiliary_rails new APP_PATH
+# or add `--develop` option to pull the most recent template from repository
+auxiliary_rails new APP_PATH --develop
 ```
 
 Or use `rails new` command specifying `--template` argument:
 
 ```sh
-rails new APP_PATH --skip-action-cable --skip-coffee --skip-test --database=postgresql --template=https://raw.githubusercontent.com/ergoserv/auxiliary_rails/develop/templates/rails/elementary.rb
+rails new APP_PATH --database=postgresql --template=https://raw.githubusercontent.com/ergoserv/auxiliary_rails/develop/templates/rails/elementary.rb --skip-action-cable --skip-coffee --skip-test --skip-webpack-install
 ```
 
 ### Generators
@@ -52,8 +56,6 @@ rails generate auxiliary_rails:install
 # Install one by one
 rails generate auxiliary_rails:install_commands
 rails generate auxiliary_rails:install_errors
-rails generate auxiliary_rails:install_rubocop
-rails generate auxiliary_rails:install_rubocop --no-specify-gems
 
 # API resource generator
 rails generate auxiliary_rails:api_resource
@@ -62,6 +64,205 @@ rails generate auxiliary_rails:api_resource
 rails generate auxiliary_rails:command
 ```
 
+### Command Objects
+
+Variation of implementation of [Command pattern](https://en.wikipedia.org/wiki/Command_pattern).
+
+```ruby
+# app/commands/application_command.rb
+class ApplicationCommand < AuxiliaryRails::Application::Command
+end
+
+# app/commands/register_user_command.rb
+class RegisterUserCommand < ApplicationCommand
+  # Define command arguments
+  # using `param` or `option` methods provided by dry-initializer
+  # https://dry-rb.org/gems/dry-initializer/3.0/
+  param :email
+  param :password
+
+  # Define the results of the command
+  # using `attr_reader` and set it as a regular instance var inside the command
+  attr_reader :user
+
+  # Regular Active Model Validations can be used to validate params
+  # https://api.rubyonrails.org/classes/ActiveModel/Validations.html
+  # Use #valid?, #invalid?, #validate! methods to engage validations
+  validates :password, length: { in: 8..32 }
+
+  # Define the only public method `#perform`
+  # where command's flow is defined
+  def perform
+    # Use `return failure!` to exit from the command with failure
+    return failure! if registration_disabled?
+
+    # Method `#transaction` is a shortcut for `ActiveRecord::Base.transaction`
+    transaction do
+      # Keep the `#perform` method short and clean, put all the steps, actions
+      # and business logic into meaningful and self-explanatory methods
+      create_user
+
+      # Use `error!` method to interrupt the flow raising an error
+      error! unless @user.persistent?
+
+      send_notification
+      # ...
+    end
+
+    # Always end the `#perform` method with `success!`
+    # this will set the proper status and allow to chain command methods.
+    success!
+  end
+
+  private
+
+  def create_user
+    @user = User.create(email: email, password: password)
+  end
+
+  def send_notification
+    # ...
+  end
+end
+
+### usage ###
+
+class RegistrationsController
+  def register
+    cmd = RegisterUserCommand.call(params[:email], params[:password])
+
+    if cmd.success?
+      redirect_to user_path(cmd.user) and return
+    else
+      @errors = cmd.errors
+    end
+
+    ### OR ###
+
+    RegisterUserCommand.call(params[:email], params[:password])
+      .on(:success) do
+        redirect_to dashboard_path and return
+      end
+      .on(:failure) do |cmd|
+        @errors = cmd.errors
+      end
+  end
+end
+```
+
+### Form Objects
+
+```ruby
+# app/forms/application_form.rb
+class ApplicationForm < AuxiliaryRails::Application::Form
+end
+
+# app/forms/company_registration_form.rb
+class CompanyRegistrationForm < ApplicationForm
+  # Define form attributes
+  attribute :company_name, :string
+  attribute :email, :string
+
+  # Define form submission results
+  attr_reader :company
+
+  # Regular Active Model Validations can be used to validate attributes
+  # https://api.rubyonrails.org/classes/ActiveModel/Validations.html
+  validates :company_name, presence: true
+  validates :email, email: true
+
+  def perform
+    # Perform business logic here
+
+    # Use `attr_reader` to expose the submission results.
+    @company = create_company
+    # Return `failure!` to indicate failure and stop execution
+    return failure! if @company.invalid?
+
+    send_notification if email.present?
+
+    # Always end with `success!` method call to indicate success
+    success!
+  end
+
+  private
+
+  def create_comany
+    Company.create(name: company_name)
+  end
+
+  def send_notification
+    # mail to: email
+  end
+end
+
+### Usage ###
+
+form = CompanyRegistrationForm.call(params[:company])
+if form.success?
+  redirect_to company_path(form.company) and return
+else
+  @errors = form.errors
+end
+```
+
+### Query Objects
+
+```ruby
+# app/queries/application_query.rb
+class ApplicationQuery < AuxiliaryRails::Application::Query
+end
+
+# app/queries/authors_query.rb
+class AuthorsQuery < ApplicationQuery
+  default_relation Author.all
+
+  option :name_like, optional: true
+  option :with_books, optional: true
+
+  def perform
+    if recent == true
+      # equivalent to `@query = @query.order(:created_at)`:
+      query order(:created_at)
+    end
+
+    if name_like.present?
+      query with_name_like(name_like)
+    end
+  end
+
+  private
+
+  def with_name_like(value)
+    where('authors.name LIKE ?', "%#{value}%")
+  end
+end
+
+# app/queries/authors_with_books_query.rb
+class AuthorsWithBooksQuery < AuthorsQuery
+  option :min_book_count, default: { 3 }
+
+  def perform
+    query joins(:books)
+      .group(:author_id)
+      .having('COUNT(books.id) > ?', min_book_count)
+  end
+end
+
+### Usage ###
+
+# it is possible to wrap query object in a scope and use as a regular scope
+# app/models/inmate.rb
+class Author < ApplicationRecord
+  scope :name_like, ->(value) { AuthorsQuery.call(name_like: value) }
+end
+
+authors = Author.name_like('Arthur')
+
+# or call query directly
+authors = AuthorsWithBooksQuery.call(min_book_count: 10)
+```
+
 ### View Helpers
 
 ```ruby