auxiliary_rails 0.1.6 → 0.3.1

data/README.md

@@ -8,7 +8,7 @@ Collection of classes, configs, scripts, generators for Ruby on Rails helping yo
 
 ## Installation
 
-Add one of these lines to your application's Gemfile:
+Add one of these lines to your application's `Gemfile`:
 
 ```ruby
 # version released to RubyGems
@@ -29,31 +29,238 @@ 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
 
 ```sh
-# install everything
+# Install everything at once
 rails generate auxiliary_rails:install
 
-# install one by one
+# 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
+
+# Command generator
+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

data/auxiliary_rails.gemspec

@@ -17,15 +17,13 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/ergoserv/auxiliary_rails'
   spec.license       = 'MIT'
 
-  if spec.respond_to?(:metadata)
-    spec.metadata['homepage_uri'] = 'https://github.com/ergoserv/auxiliary_rails'
-    spec.metadata['source_code_uri'] = 'https://github.com/ergoserv/auxiliary_rails'
-    spec.metadata['changelog_uri'] = 'https://github.com/ergoserv/auxiliary_rails/blob/master/CHANGELOG.md'
-  else
-    raise 'RubyGems 2.0 or newer is required'
-  end
+  raise 'RubyGems 2.0 or newer is required' unless spec.respond_to?(:metadata)
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/releases"
 
-  spec.files         = Dir.chdir(File.expand_path(__dir__)) do
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject do |f|
       f.match(%r{^(test|spec|features)/})
     end
@@ -35,12 +33,15 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'pry'
-  spec.add_development_dependency 'rails', '~> 5.2'
-  spec.add_development_dependency 'rake', '~> 10.0'
-  spec.add_development_dependency 'rspec', '~> 3.0'
-  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec', '~> 3.8'
+  spec.add_development_dependency 'rubocop', '~> 0.80'
   spec.add_development_dependency 'rubocop-performance'
   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 'thor'
 end

data/bin/rubocop

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' 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("rubocop", "rubocop")

data/bitbucket-pipelines.yml

@@ -0,0 +1,35 @@
+image: ruby:2.6.5
+
+definitions:
+  caches:
+    bundler: vendor/bundle
+
+pipelines:
+  default:
+    - step:
+        name: Build
+        caches:
+          - bundler
+        script:
+            - gem install bundler
+            - bundle config set path vendor/bundle
+            - bundle install
+    - parallel:
+      - step:
+          name: RSpec
+          caches:
+            - bundler
+          script:
+            - gem install bundler
+            - bundle config set path vendor/bundle
+            - bundle install
+            - bundle exec rspec
+      - step:
+          name: RuboCop
+          caches:
+            - bundler
+          script:
+            - gem install bundler
+            - bundle config set path vendor/bundle
+            - bundle install
+            - bundle exec rubocop

data/lib/auxiliary_rails.rb

@@ -1,6 +1,8 @@
-require 'auxiliary_rails/abstract_error'
-require 'auxiliary_rails/abstract_command'
-require 'auxiliary_rails/railtie' if defined?(Rails)
+require 'auxiliary_rails/application/command'
+require 'auxiliary_rails/application/form'
+require 'auxiliary_rails/application/error'
+require 'auxiliary_rails/application/query'
+require 'auxiliary_rails/railtie'
 require 'auxiliary_rails/version'
 
 module AuxiliaryRails

data/lib/auxiliary_rails/application/command.rb

@@ -0,0 +1,56 @@
+require 'active_model'
+require 'auxiliary_rails/concerns/performable'
+require 'dry-initializer-rails'
+
+module AuxiliaryRails
+  module Application
+    # @abstract
+    class Command
+      extend Dry::Initializer
+      include AuxiliaryRails::Concerns::Performable
+
+      class << self
+        # @!method param(name, options = {})
+        #   Defines param using <tt>Dry::Initializer</tt> format.
+        #
+        #   @see Dry::Initializer
+        #   @see https://dry-rb.org/gems/dry-initializer/3.0/params-and-options/
+        #
+        #   @param name [Symbol]
+        #   @param options [Hash]
+
+        # @!method option(name, options = {})
+        #   Defines option using <tt>Dry::Initializer</tt> format.
+
+        #   @see Dry::Initializer
+        #   @see https://dry-rb.org/gems/dry-initializer/3.0/params-and-options/
+        #
+        #   @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
+
+        # Defines `scope` for <tt>ActiveModel::Translation</tt>
+        #
+        # @return [Symbol]
+        def i18n_scope
+          :commands
+        end
+      end
+
+      protected
+
+      # Shortcut reader for attributes defined by <tt>Dry::Initializer</tt>
+      #
+      # @return [Hash]
+      def arguments
+        self.class.dry_initializer.attributes(self)
+      end
+    end
+  end
+end

data/lib/auxiliary_rails/application/error.rb

@@ -0,0 +1,10 @@
+module AuxiliaryRails
+  module Application
+    class Error < StandardError
+      # @return [self] Creates new error object
+      def self.wrap(error)
+        new(error.message)
+      end
+    end
+  end
+end

data/lib/auxiliary_rails/application/form.rb

@@ -0,0 +1,30 @@
+require 'active_model'
+
+module AuxiliaryRails
+  module Application
+    # @abstract
+    class Form
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+      include ActiveModel::AttributeAssignment
+      include AuxiliaryRails::Concerns::Performable
+
+      class << self
+        # Defines `scope` for <tt>ActiveModel::Translation</tt>
+        #
+        # @return [Symbol]
+        def i18n_scope
+          :forms
+        end
+      end
+
+      # Indicates object persistence.
+      #
+      # In case of form as performable object that means that form
+      # was executed with success.
+      def persisted?
+        performable_status == true
+      end
+    end
+  end
+end