auxiliary_rails 0.3.1 → 0.4.0

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:
@@ -56,17 +59,35 @@ 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_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://en.wikipedia.org/wiki/Command_pattern).
+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
@@ -81,8 +102,8 @@ class RegisterUserCommand < ApplicationCommand
   param :email
   param :password
 
-  # Define the results of the command
-  # using `attr_reader` and set it as a regular instance var inside the command
+  # 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
@@ -90,9 +111,11 @@ class RegisterUserCommand < ApplicationCommand
   # 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
+  # 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?
 
@@ -100,27 +123,27 @@ class RegisterUserCommand < ApplicationCommand
     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
+      @user = create_user
 
       # Use `error!` method to interrupt the flow raising an error
-      error! unless @user.persistent?
+      error! unless user.persistent?
 
-      send_notification
+      send_notifications
       # ...
     end
 
-    # Always end the `#perform` method with `success!`
-    # this will set the proper status and allow to chain command methods.
+    # Always end the `#perform` method with `success!`.
+    # It will set the proper command's execution status.
     success!
   end
 
   private
 
   def create_user
-    @user = User.create(email: email, password: password)
+    User.create(email: email, password: password)
   end
 
-  def send_notification
+  def send_notifications
     # ...
   end
 end
@@ -150,6 +173,17 @@ class RegistrationsController
 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
@@ -252,7 +286,7 @@ end
 ### Usage ###
 
 # it is possible to wrap query object in a scope and use as a regular scope
-# app/models/inmate.rb
+# app/models/author.rb
 class Author < ApplicationRecord
   scope :name_like, ->(value) { AuthorsQuery.call(name_like: value) }
 end
@@ -263,11 +297,38 @@ authors = Author.name_like('Arthur')
 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
 
 ```ruby
 current_controller?(*ctrl_names)
 current_action?(*action_names)
+display_name(resource)
 ```
 
 ## Development

data/auxiliary_rails.gemspec

@@ -8,9 +8,11 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Dmitry Babenko', 'ErgoServ']
   spec.email         = ['dmitry@ergoserv.com', 'hello@ergoserv.com']
 
-  spec.summary       = 'AuxiliaryRails provides extra layers and utils ' \
-    'for helping to build solid and clean Ruby on Rails applications'
-  spec.description   = <<~DESC
+  spec.summary = <<~DESC
+    AuxiliaryRails provides extra layers and utils
+    for helping to build solid and clean Ruby on Rails applications
+  DESC
+  spec.description = <<~DESC
     AuxiliaryRails is a collection of classes, configs, scripts,
     generators for Ruby on Rails helping you get things done, better.
   DESC
@@ -31,17 +33,20 @@ Gem::Specification.new do |spec|
   spec.executables   = ['auxiliary_rails']
   spec.require_paths = ['lib']
 
+  spec.required_ruby_version = '>= 2.5'
+
   spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'pry'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec', '~> 3.8'
-  spec.add_development_dependency 'rubocop', '~> 0.80'
+  spec.add_development_dependency 'rubocop', '1.20.0'
   spec.add_development_dependency 'rubocop-performance'
+  spec.add_development_dependency 'rubocop-rake'
   spec.add_development_dependency 'rubocop-rspec'
 
   spec.add_runtime_dependency 'dry-core'
   spec.add_runtime_dependency 'dry-initializer'
   spec.add_runtime_dependency 'dry-initializer-rails'
-  spec.add_runtime_dependency 'rails', '>= 5.2', '< 7'
+  spec.add_runtime_dependency 'rails', '>= 5.2'
   spec.add_runtime_dependency 'thor'
 end

data/bin/rspec

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/lib/auxiliary_rails/application/command.rb

@@ -28,12 +28,9 @@ module AuxiliaryRails
         #   @param name [Symbol]
         #   @param options [Hash]
 
-        # Initializes command with <tt>args</tt> and runs <tt>#call</tt> method.
-        #
-        # @return [self]
-        def call(*args)
-          new(*args).call
-        end
+        # @!method call(*args, **kws)
+        #   @see AuxiliaryRails::Corcerns::Callable
+        #   @return [self]
 
         # Defines `scope` for <tt>ActiveModel::Translation</tt>
         #

data/lib/auxiliary_rails/application/error.rb

@@ -1,10 +1,50 @@
 module AuxiliaryRails
   module Application
-    class Error < StandardError
-      # @return [self] Creates new error object
-      def self.wrap(error)
-        new(error.message)
+    # @abstract
+    class Error < RuntimeError
+      attr_accessor :context
+      attr_reader :exception, :severity
+
+      class << self
+        def i18n_scope
+          "errors.#{name.underscore}"
+        end
+
+        # @return [self] Wraps exception into a new Application Error object
+        def wrap(exception, context: {}, severity: nil)
+          new(exception.message, context: context, exception: exception, severity: severity)
+        end
       end
+
+      def initialize(message = nil, context: {}, exception: nil, severity: nil)
+        super message
+
+        self.context = default_context.merge(context || {})
+        self.exception = exception
+        self.severity = severity&.to_sym || default_severity
+      end
+
+      def default_context
+        {}
+      end
+
+      def default_severity
+        :error
+      end
+
+      def friendly_message
+        I18n.t(:default,
+          scope: self.class.i18n_scope,
+          default: 'We are sorry, but something went wrong.')
+      end
+
+      def report
+        raise NotImplementedError
+      end
+
+      protected
+
+      attr_writer :exception, :severity
     end
   end
 end

data/lib/auxiliary_rails/application/form.rb

@@ -1,4 +1,5 @@
 require 'active_model'
+require 'auxiliary_rails/concerns/performable'
 
 module AuxiliaryRails
   module Application

data/lib/auxiliary_rails/application/query.rb

@@ -1,30 +1,34 @@
+require 'auxiliary_rails/concerns/callable'
 require 'auxiliary_rails/concerns/errorable'
 require 'dry/core/class_attributes'
 require 'dry-initializer'
 
 module AuxiliaryRails
   module Application
+    # @abstract
     class Query
       extend Dry::Core::ClassAttributes
       extend Dry::Initializer
+      include AuxiliaryRails::Concerns::Callable
       include AuxiliaryRails::Concerns::Errorable
 
       defines :default_relation
 
-      option :relation, default: proc { nil }
-
-      def self.call(*args)
-        new(*args).call
-      end
+      option :relation, default: proc {}
 
       def call
         ensure_proper_relation_types!
 
         perform
 
+        if !queriable_object?(query)
+          error!('Invalid class of resulted query')
+        end
+
         query
       end
 
+      # @abstract
       def perform
         raise NotImplementedError
       end
@@ -41,7 +45,7 @@ module AuxiliaryRails
 
       private
 
-      # rubocop:disable Metrics/AbcSize, Style/GuardClause
+      # rubocop:disable Style/GuardClause
       def ensure_proper_relation_types!
         if self.class.default_relation.nil?
           error!('Undefined `default_relation`')
@@ -53,7 +57,7 @@ module AuxiliaryRails
           error!('Invalid class of `relation` option')
         end
       end
-      # rubocop:enable Metrics/AbcSize, Style/GuardClause
+      # rubocop:enable Style/GuardClause
 
       def queriable_object?(object)
         object.is_a?(ActiveRecord::Relation)

data/lib/auxiliary_rails/application/service.rb

@@ -0,0 +1,42 @@
+require 'active_support/concern'
+require 'active_support/ordered_options'
+
+module AuxiliaryRails
+  module Application
+    module Service
+      def self.included(klass)
+        raise AuxiliaryRails::Error,
+          "Use `extend` insted of `include` for #{self} in #{klass}"
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def config
+        return @config if @config.present?
+
+        # load from constant
+        if const_defined?(:CONFIG)
+          return @config = ActiveSupport::OrderedOptions.new.update(const_get(:CONFIG))
+        end
+
+        service_name = name.underscore
+
+        # load from service config file
+        if Rails.root.join("config/services/#{service_name}.yml").exist?
+          return @config = Rails.application.config_for("services/#{service_name}")
+        end
+
+        # load from application config
+        if Object.const_defined?(:Config) && Config.respond_to?(:const_name)
+          app_config = Object.const_get(Config.const_name)
+          if app_config.dig(:services, service_name).present?
+            return @config = app_config[:services][service_name]
+          end
+        end
+
+        raise AuxiliaryRails::Error,
+          "Unable to find suitable config for #{name} module"
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+    end
+  end
+end

data/lib/auxiliary_rails/concerns/callable.rb

@@ -0,0 +1,23 @@
+module AuxiliaryRails
+  module Concerns
+    module Callable
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Initializes object and runs <tt>#call</tt> method.
+        #
+        # @return [self]
+        def call(*args, **kws)
+          new(*args, **kws).call
+        end
+      end
+
+      # @abstract
+      def call
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/auxiliary_rails/concerns/errorable.rb

@@ -1,22 +1,22 @@
 module AuxiliaryRails
   module Concerns
     module Errorable
-      # extend ActiveSupport::Concern
+      extend ActiveSupport::Concern
 
-      def error!(message = nil)
-        message ||= "`#{self.class}` raised error."
-        raise error_class, message
-      end
-
-      if defined?(ApplicationError)
-        def error_class
-          ApplicationError
-        end
-      else
+      class_methods do
         def error_class
-          AuxiliaryRails::Application::Error
+          if Object.const_defined?(:ApplicationError)
+            ApplicationError
+          else
+            AuxiliaryRails::Application::Error
+          end
         end
       end
+
+      def error!(message = nil)
+        message ||= "`#{self.class}` raised error."
+        raise self.class.error_class, message
+      end
     end
   end
 end

data/lib/auxiliary_rails/concerns/performable.rb

@@ -1,4 +1,5 @@
 require 'active_support/concern'
+require 'auxiliary_rails/concerns/callable'
 require 'auxiliary_rails/concerns/errorable'
 
 module AuxiliaryRails
@@ -6,14 +7,9 @@ module AuxiliaryRails
     module Performable
       extend ActiveSupport::Concern
       include ActiveModel::Validations
+      include AuxiliaryRails::Concerns::Callable
       include AuxiliaryRails::Concerns::Errorable
 
-      class_methods do
-        def call(*args)
-          new(*args).call
-        end
-      end
-
       def call(options = {})
         ensure_empty_status!
 
@@ -58,24 +54,15 @@ module AuxiliaryRails
       # Provides ability to execude block of the code depending on
       # command execution status
       #
-      # @param status [Symol] Desired command status
-      # @param &_block Code to be executed if status matches
+      # @param status [Symbol] Desired command status
+      # @param &block Code to be executed if status matches
       # @return [self]
-      def on(status, &_block)
-        ensure_execution!
-
-        return self unless status?(status)
-
-        yield(self) if block_given?
+      def on(status, &block)
+        yield(self) if status?(status) && block
 
         self
       end
 
-      # Shortcut for <tt>ActiveRecord::Base.transaction</tt>
-      def transaction(&block)
-        ActiveRecord::Base.transaction(&block) if block_given?
-      end
-
       protected
 
       attr_accessor :performable_status
@@ -123,6 +110,11 @@ module AuxiliaryRails
         self.performable_status = :success
         self
       end
+
+      # Shortcut for <tt>ActiveRecord::Base.transaction</tt>
+      def transaction(&block)
+        ActiveRecord::Base.transaction(&block) if block
+      end
     end
   end
 end

data/lib/auxiliary_rails/railtie.rb

@@ -1,9 +1,10 @@
+require 'rails/railtie'
 require 'auxiliary_rails/view_helpers'
 
 module AuxiliaryRails
   class Railtie < Rails::Railtie
     initializer 'auxiliary_rails.view_helpers' do
-      ActionView::Base.send :include, ViewHelpers
+      ActionView::Base.include ViewHelpers
     end
   end
 end

data/lib/auxiliary_rails/version.rb

@@ -1,3 +1,3 @@
 module AuxiliaryRails
-  VERSION = '0.3.1'.freeze
+  VERSION = '0.4.0'.freeze
 end

data/lib/auxiliary_rails/view_helpers/display_helper.rb

@@ -0,0 +1,30 @@
+module AuxiliaryRails
+  module ViewHelpers
+    module DisplayHelper
+      DISPLAY_NAME_METHODS = %i[
+        display_name
+        name
+        title
+        full_name
+        username
+        email
+      ].freeze
+
+      def display_name(resource)
+        return if resource.nil?
+
+        DISPLAY_NAME_METHODS.each do |method_name|
+          if resource.respond_to?(method_name)
+            return resource.public_send(method_name)
+          end
+        end
+
+        if resource.respond_to?(:model_name) && resource.respond_to?(:id)
+          return "#{resource.model_name.human} ##{resource.id}"
+        end
+
+        resource.to_s
+      end
+    end
+  end
+end

data/lib/auxiliary_rails/view_helpers.rb

@@ -1,5 +1,9 @@
+require 'auxiliary_rails/view_helpers/display_helper'
+
 module AuxiliaryRails
   module ViewHelpers
+    include DisplayHelper
+
     def current_controller?(*ctrl_names)
       ctrl_names.include?(params[:controller])
     end

data/lib/auxiliary_rails.rb

@@ -1,7 +1,9 @@
 require 'auxiliary_rails/application/command'
-require 'auxiliary_rails/application/form'
 require 'auxiliary_rails/application/error'
+require 'auxiliary_rails/application/form'
+require 'auxiliary_rails/application/service'
 require 'auxiliary_rails/application/query'
+
 require 'auxiliary_rails/railtie'
 require 'auxiliary_rails/version'
 

data/lib/generators/auxiliary_rails/install_errors_controller_generator.rb

@@ -0,0 +1,31 @@
+require 'rails'
+
+module AuxiliaryRails
+  class InstallErrorsControllerGenerator < ::Rails::Generators::Base
+    source_root File.expand_path('templates/errors_controller', __dir__)
+
+    VIEW_TEMPLATES = %w[show not_found unacceptable].freeze
+
+    def copy_controller_file
+      copy_file 'errors_controller_template.rb',
+        'app/controllers/errors_controller.rb'
+    end
+
+    def copy_view_files
+      VIEW_TEMPLATES.each do |tempate_name|
+        copy_file "#{tempate_name}_template.html.erb",
+          "app/views/errors/#{tempate_name}.html.erb"
+      end
+    end
+
+    def add_route
+      route "match '/404', to: 'errors#not_found', via: :all"
+      route "match '/422', to: 'errors#unacceptable', via: :all"
+      route "match '/500', to: 'errors#show', via: :all"
+    end
+
+    def add_exceptions_app_config
+      application 'config.exceptions_app = routes'
+    end
+  end
+end

data/lib/generators/auxiliary_rails/install_generator.rb

@@ -5,6 +5,7 @@ module AuxiliaryRails
     def install
       generate 'auxiliary_rails:install_commands'
       generate 'auxiliary_rails:install_errors'
+      generate 'auxiliary_rails:install_errors_controller'
     end
   end
 end