auxiliary_rails 0.2.0 → 0.4.0

data/Gemfile.lock

@@ -1,177 +1,209 @@
 PATH
   remote: .
   specs:
-    auxiliary_rails (0.2.0)
+    auxiliary_rails (0.4.0)
+      dry-core
+      dry-initializer
       dry-initializer-rails
+      rails (>= 5.2)
       thor
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actioncable (6.0.2.1)
-      actionpack (= 6.0.2.1)
+    actioncable (7.0.3.1)
+      actionpack (= 7.0.3.1)
+      activesupport (= 7.0.3.1)
       nio4r (~> 2.0)
       websocket-driver (>= 0.6.1)
-    actionmailbox (6.0.2.1)
-      actionpack (= 6.0.2.1)
-      activejob (= 6.0.2.1)
-      activerecord (= 6.0.2.1)
-      activestorage (= 6.0.2.1)
-      activesupport (= 6.0.2.1)
+    actionmailbox (7.0.3.1)
+      actionpack (= 7.0.3.1)
+      activejob (= 7.0.3.1)
+      activerecord (= 7.0.3.1)
+      activestorage (= 7.0.3.1)
+      activesupport (= 7.0.3.1)
       mail (>= 2.7.1)
-    actionmailer (6.0.2.1)
-      actionpack (= 6.0.2.1)
-      actionview (= 6.0.2.1)
-      activejob (= 6.0.2.1)
+      net-imap
+      net-pop
+      net-smtp
+    actionmailer (7.0.3.1)
+      actionpack (= 7.0.3.1)
+      actionview (= 7.0.3.1)
+      activejob (= 7.0.3.1)
+      activesupport (= 7.0.3.1)
       mail (~> 2.5, >= 2.5.4)
+      net-imap
+      net-pop
+      net-smtp
       rails-dom-testing (~> 2.0)
-    actionpack (6.0.2.1)
-      actionview (= 6.0.2.1)
-      activesupport (= 6.0.2.1)
-      rack (~> 2.0, >= 2.0.8)
+    actionpack (7.0.3.1)
+      actionview (= 7.0.3.1)
+      activesupport (= 7.0.3.1)
+      rack (~> 2.0, >= 2.2.0)
       rack-test (>= 0.6.3)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.0, >= 1.2.0)
-    actiontext (6.0.2.1)
-      actionpack (= 6.0.2.1)
-      activerecord (= 6.0.2.1)
-      activestorage (= 6.0.2.1)
-      activesupport (= 6.0.2.1)
+    actiontext (7.0.3.1)
+      actionpack (= 7.0.3.1)
+      activerecord (= 7.0.3.1)
+      activestorage (= 7.0.3.1)
+      activesupport (= 7.0.3.1)
+      globalid (>= 0.6.0)
       nokogiri (>= 1.8.5)
-    actionview (6.0.2.1)
-      activesupport (= 6.0.2.1)
+    actionview (7.0.3.1)
+      activesupport (= 7.0.3.1)
       builder (~> 3.1)
       erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.1, >= 1.2.0)
-    activejob (6.0.2.1)
-      activesupport (= 6.0.2.1)
+    activejob (7.0.3.1)
+      activesupport (= 7.0.3.1)
       globalid (>= 0.3.6)
-    activemodel (6.0.2.1)
-      activesupport (= 6.0.2.1)
-    activerecord (6.0.2.1)
-      activemodel (= 6.0.2.1)
-      activesupport (= 6.0.2.1)
-    activestorage (6.0.2.1)
-      actionpack (= 6.0.2.1)
-      activejob (= 6.0.2.1)
-      activerecord (= 6.0.2.1)
-      marcel (~> 0.3.1)
-    activesupport (6.0.2.1)
+    activemodel (7.0.3.1)
+      activesupport (= 7.0.3.1)
+    activerecord (7.0.3.1)
+      activemodel (= 7.0.3.1)
+      activesupport (= 7.0.3.1)
+    activestorage (7.0.3.1)
+      actionpack (= 7.0.3.1)
+      activejob (= 7.0.3.1)
+      activerecord (= 7.0.3.1)
+      activesupport (= 7.0.3.1)
+      marcel (~> 1.0)
+      mini_mime (>= 1.1.0)
+    activesupport (7.0.3.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-      zeitwerk (~> 2.2)
-    ast (2.4.0)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    ast (2.4.2)
     builder (3.2.4)
-    coderay (1.1.2)
-    concurrent-ruby (1.1.5)
-    crass (1.0.5)
-    diff-lcs (1.3)
-    dry-initializer (3.0.2)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.10)
+    crass (1.0.6)
+    diff-lcs (1.5.0)
+    digest (3.1.0)
+    dry-core (0.8.1)
+      concurrent-ruby (~> 1.0)
+    dry-initializer (3.1.1)
     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)
+    erubi (1.11.0)
+    globalid (1.0.0)
+      activesupport (>= 5.0)
+    i18n (1.12.0)
       concurrent-ruby (~> 1.0)
-    jaro_winkler (1.5.4)
-    loofah (2.4.0)
+    loofah (2.18.0)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     mail (2.7.1)
       mini_mime (>= 0.1.1)
-    marcel (0.3.3)
-      mimemagic (~> 0.3.2)
-    method_source (0.9.2)
-    mimemagic (0.3.3)
-    mini_mime (1.0.2)
-    mini_portile2 (2.4.0)
-    minitest (5.13.0)
-    nio4r (2.5.2)
-    nokogiri (1.10.7)
-      mini_portile2 (~> 2.4.0)
-    parallel (1.19.1)
-    parser (2.7.0.1)
-      ast (~> 2.4.0)
-    pry (0.12.2)
-      coderay (~> 1.1.0)
-      method_source (~> 0.9.0)
-    rack (2.0.8)
-    rack-test (1.1.0)
-      rack (>= 1.0, < 3)
-    rails (6.0.2.1)
-      actioncable (= 6.0.2.1)
-      actionmailbox (= 6.0.2.1)
-      actionmailer (= 6.0.2.1)
-      actionpack (= 6.0.2.1)
-      actiontext (= 6.0.2.1)
-      actionview (= 6.0.2.1)
-      activejob (= 6.0.2.1)
-      activemodel (= 6.0.2.1)
-      activerecord (= 6.0.2.1)
-      activestorage (= 6.0.2.1)
-      activesupport (= 6.0.2.1)
-      bundler (>= 1.3.0)
-      railties (= 6.0.2.1)
-      sprockets-rails (>= 2.0.0)
+    marcel (1.0.2)
+    method_source (1.0.0)
+    mini_mime (1.1.2)
+    mini_portile2 (2.8.0)
+    minitest (5.16.3)
+    net-imap (0.2.3)
+      digest
+      net-protocol
+      strscan
+    net-pop (0.1.1)
+      digest
+      net-protocol
+      timeout
+    net-protocol (0.1.3)
+      timeout
+    net-smtp (0.3.1)
+      digest
+      net-protocol
+      timeout
+    nio4r (2.5.8)
+    nokogiri (1.13.8)
+      mini_portile2 (~> 2.8.0)
+      racc (~> 1.4)
+    parallel (1.22.1)
+    parser (3.1.2.1)
+      ast (~> 2.4.1)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    racc (1.6.0)
+    rack (2.2.4)
+    rack-test (2.0.2)
+      rack (>= 1.3)
+    rails (7.0.3.1)
+      actioncable (= 7.0.3.1)
+      actionmailbox (= 7.0.3.1)
+      actionmailer (= 7.0.3.1)
+      actionpack (= 7.0.3.1)
+      actiontext (= 7.0.3.1)
+      actionview (= 7.0.3.1)
+      activejob (= 7.0.3.1)
+      activemodel (= 7.0.3.1)
+      activerecord (= 7.0.3.1)
+      activestorage (= 7.0.3.1)
+      activesupport (= 7.0.3.1)
+      bundler (>= 1.15.0)
+      railties (= 7.0.3.1)
     rails-dom-testing (2.0.3)
       activesupport (>= 4.2.0)
       nokogiri (>= 1.6)
-    rails-html-sanitizer (1.3.0)
+    rails-html-sanitizer (1.4.3)
       loofah (~> 2.3)
-    railties (6.0.2.1)
-      actionpack (= 6.0.2.1)
-      activesupport (= 6.0.2.1)
+    railties (7.0.3.1)
+      actionpack (= 7.0.3.1)
+      activesupport (= 7.0.3.1)
       method_source
-      rake (>= 0.8.7)
-      thor (>= 0.20.3, < 2.0)
-    rainbow (3.0.0)
-    rake (13.0.1)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.1)
-      rspec-support (~> 3.9.1)
-    rspec-expectations (3.9.0)
+      rake (>= 12.2)
+      thor (~> 1.0)
+      zeitwerk (~> 2.5)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.5.0)
+    rexml (3.2.5)
+    rspec (3.11.0)
+      rspec-core (~> 3.11.0)
+      rspec-expectations (~> 3.11.0)
+      rspec-mocks (~> 3.11.0)
+    rspec-core (3.11.0)
+      rspec-support (~> 3.11.0)
+    rspec-expectations (3.11.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.1)
+      rspec-support (~> 3.11.0)
+    rspec-mocks (3.11.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.2)
-    rubocop (0.78.0)
-      jaro_winkler (~> 1.5.1)
+      rspec-support (~> 3.11.0)
+    rspec-support (3.11.0)
+    rubocop (1.20.0)
       parallel (~> 1.10)
-      parser (>= 2.6)
+      parser (>= 3.0.0.0)
       rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.9.1, < 2.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 (>= 0.68.1)
-    ruby-progressbar (1.10.1)
-    sprockets (4.0.0)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.21.0)
+      parser (>= 3.1.1.0)
+    rubocop-performance (1.14.3)
+      rubocop (>= 1.7.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    rubocop-rspec (2.11.1)
+      rubocop (~> 1.19)
+    ruby-progressbar (1.11.0)
+    strscan (3.0.4)
+    thor (1.2.1)
+    timeout (0.3.0)
+    tzinfo (2.0.5)
       concurrent-ruby (~> 1.0)
-      rack (> 1, < 3)
-    sprockets-rails (3.2.1)
-      actionpack (>= 4.0)
-      activesupport (>= 4.0)
-      sprockets (>= 3.0.0)
-    thor (1.0.1)
-    thread_safe (0.3.6)
-    tzinfo (1.2.6)
-      thread_safe (~> 0.1)
-    unicode-display_width (1.6.0)
-    websocket-driver (0.7.1)
+    unicode-display_width (2.2.0)
+    websocket-driver (0.7.5)
       websocket-extensions (>= 0.1.0)
-    websocket-extensions (0.1.4)
-    zeitwerk (2.2.2)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.6.0)
 
 PLATFORMS
   ruby
@@ -180,12 +212,12 @@ DEPENDENCIES
   auxiliary_rails!
   bundler (~> 2.0)
   pry
-  rails (>= 5.2, < 7)
   rake
   rspec (~> 3.8)
-  rubocop
+  rubocop (= 1.20.0)
   rubocop-performance
+  rubocop-rake
   rubocop-rspec
 
 BUNDLED WITH
-   2.0.2
+   2.1.4

data/README.md

@@ -11,12 +11,15 @@ Collection of classes, configs, scripts, generators for Ruby on Rails helping yo
 Add one of these lines to your application's `Gemfile`:
 
 ```ruby
-# version released to RubyGems
+# version released to RubyGems (recommended)
 gem 'auxiliary_rails'
+
 # or latest version from the repository
 gem 'auxiliary_rails', git: 'https://github.com/ergoserv/auxiliary_rails'
-# or from a specific branch of the repository
+# or from a specific branch of the GitHub repository
 gem 'auxiliary_rails', github: 'ergoserv/auxiliary_rails', branch: 'develop'
+# or from a local path (for development and testing purposes)
+gem 'auxiliary_rails', path: '../auxiliary_rails'
 ```
 
 And then execute:
@@ -29,18 +32,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
 ```
 
 ### Generators
@@ -52,14 +59,268 @@ 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
+rails generate auxiliary_rails:install_errors_controller
 
 # API resource generator
 rails generate auxiliary_rails:api_resource
 
 # Command generator
 rails generate auxiliary_rails:command
+
+# Service generator
+rails generate auxiliary_rails:service
+```
+
+### API Resources
+
+Read article [Building an API](https://github.com/ergoserv/handbook/blob/master/guides/building_api.md) for more details.
+
+Use generator to generate appropriate classes and files (Resource, Entity, Helper, Spec) for the specified end-point:
+
+```sh
+rails generate auxiliary_rails:api_resource
+```
+
+## Application
+
+### Command Objects
+
+Variation of implementation of [Command pattern](https://refactoring.guru/design-patterns/command).
+
+Read post [Command Objects - a.k.a Service Objects in Ruby on Rails - The Ergonomic Way](https://www.ergoserv.com/blog/command-objects-aka-service-objects-in-ruby-on-rails-the-ergonomic-way) for more details.
+
+```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!` and `return success!` inside `#perform` method
+    # to control exits from the command with appropriate status.
+
+    # 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
+      @user = create_user
+
+      # Use `error!` method to interrupt the flow raising an error
+      error! unless user.persistent?
+
+      send_notifications
+      # ...
+    end
+
+    # Always end the `#perform` method with `success!`.
+    # It will set the proper command's execution status.
+    success!
+  end
+
+  private
+
+  def create_user
+    User.create(email: email, password: password)
+  end
+
+  def send_notifications
+    # ...
+  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
+```
+
+### Error Objects
+
+Custom error objects.
+Read article [Error Handling](https://github.com/ergoserv/handbook/blob/master/guides/error_handling.md) for more details.
+
+```ruby
+# app/errors/application_error.rb
+class ApplicationCommand < AuxiliaryRails::Application::Error
+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/author.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)
+```
+
+### Service Modules
+
+Read [Service Modules](https://github.com/ergoserv/handbook/blob/master/guides/service_modules.md) for more details.
+
+**Service Generator**
+
+```sh
+rails generate auxiliary_rails:service
+```
+
+**Service Config** - provides a unified access to a service configs and loads the first found from:
+
+- Constant (`MyService::CONFIG`)
+- Application config file (`config/settings.yml`, see gem [`config`](https://github.com/rubyconfig/config))
+- Service config file (`config/services/my_service.yml`)
+
+```ruby
+# app/services/my_service.rb
+module MyService
+  extend AuxiliaryRails::Application::Service
+end
+
+# usage
+MyService.config.some_key
 ```
 
 ### View Helpers
@@ -67,6 +328,7 @@ rails generate auxiliary_rails:command
 ```ruby
 current_controller?(*ctrl_names)
 current_action?(*action_names)
+display_name(resource)
 ```
 
 ## Development