steel_wheel 0.5.1 → 0.6.0

data/README.md

@@ -1,7 +1,124 @@
 # SteelWheel
-[![Maintainability](https://api.codeclimate.com/v1/badges/a197758aa1cfde54f0e1/maintainability)](https://codeclimate.com/github/andriy-baran/steel_wheel/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/a197758aa1cfde54f0e1/test_coverage)](https://codeclimate.com/github/andriy-baran/steel_wheel/test_coverage)
+[![Maintainability](https://api.codeclimate.com/v1/badges/a197758aa1cfde54f0e1/maintainability)](https://codeclimate.com/github/andriy-baran/steel_wheel/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/a197758aa1cfde54f0e1/test_coverage)](https://codeclimate.com/github/andriy-baran/steel_wheel/test_coverage)
+[![Gem Version](https://badge.fury.io/rb/steel_wheel.svg)](https://badge.fury.io/rb/steel_wheel)
 
-Allows to operate on any sequence of procedures as on linked list. It means that inserting and deleting any list/element into/from similar lists is very efficient. And a rich callbacks system gives entire control over the execution. Currently there is one example implemented. It helps organize common procedures in a Rails' controlers.
+The library is a tool for building highly structured service objects.
+
+## Concepts
+
+### Stages
+We may consider any controller action as a sequence of following stages:
+1. **Input validations and preparations**
+* Describe the structure of parameters
+* Validate values, provide defaults
+2. **Querying data and preparing context**
+* Records lookups by IDs in parameters
+* Validate permissions to perform an action
+* Validate conditions (business logic requirements)
+* Inject Dependencies
+* Set up current user
+3. **Performing Action (skipped on GET requests)**
+* Updade database state
+* Enqueue jobs
+* Handle exceptions
+* Validate intermediate states
+4. **Exposing Results/Errors**
+* Presenters
+* Contextual information useful for the users
+
+### Implementation of stages
+As you can see each step has specific tasks and can be implemented as a separate object.
+
+**SteelWheel::Params (gem https://github.com/andriy-baran/easy_params)**
+* provides DSL for `params` structure definition
+* provides type coercion and default values for individual attributes
+* has ActionModel::Validation included
+* implements `http_status` method that returs HTTP error code
+
+**SteelWheel::Query**
+* has `Memery` module included
+* has ActionModel::Validation included
+* implements `http_status` method that returs HTTP error code
+
+**SteelWheel::Command**
+* has ActionModel::Validation included
+* implements `http_status` method that returs HTTP error code
+* implements `call` method that should do the stuff
+
+**SteelWheel::Response**
+* has ActionModel::Validation included
+* implements `status` method that returs HTTP error code
+* implements `success?` method that checks if there are any errors
+
+### Process
+Let's image the process that connects stages described above
+* Get an input and initialize object for params, trigger callbacks
+* Initialize object for preparing context and give it an access to previous object, trigger callbacks
+* Initialize object for performing action and give it an access to previous object, trigger callbacks
+* Initialize resulting object and give it an access to previous object,
+* Run validations, collect errros, trigger callbacks
+* If everything is ok run action and handle errors that appear during execution time.
+* If we have an error on any stage we stop validating following objects.
+
+### Callbacks
+
+We have two types of callbacks explicit and implicit
+
+### Implicit callbacks
+
+We define them via handler instance methods
+
+```ruby
+def on_params_created(params)
+  # NOOP
+end
+
+def on_query_created(query)
+  # NOOP
+end
+
+def on_command_created(command)
+  # NOOP
+end
+
+def on_response_created(command)
+  # NOOP
+end
+
+# After validation callbacks
+
+def on_failure(flow)
+  # NOOP
+end
+
+def on_success(flow)
+  # NOOP
+end
+```
+
+### Explicit callbacks
+
+We define them during instantiation of hanler by providing a block parameter
+
+```ruby
+handler = handler_class.new do |c|
+            c.params { |o| puts o }
+            c.query { |o| puts o }
+            c.command { |o| puts o }
+            c.response { |o| puts o }
+          end
+result =  handler.handle(input: { id: 1 })
+```
+In addition we can manipulate with objects directly via callback of `handle` mathod
+```ruby
+result  = handler_class.handle(input: { id: 1 }) do |c|
+            c.params.id = 12
+            c.query.user = current_user
+            c.command.request_headers = request.headers
+            c.response.prepare_presenter
+          end
+```
 
 ## Installation
 
@@ -21,9 +138,195 @@ Or install it yourself as:
 
 ## Usage
 
-[Getting started on Rails](https://github.com/andriy-baran/steel_wheel/wiki/Getting-started-on-Rails)
+Add base handler
+
+```bash
+bin/rails g steel_wheel:application_handler
+```
+
+Add specific handler
+
+```bash
+bin/rails g steel_wheel:handler products/create
+```
+This will generate `app/handlers/products/create_handler.rb`. And we can customize it
+
+```ruby
+class Products::CreateHandler < ApplicationHandler
+  define do
+    params do
+      attribute :title, string
+      attribute :weight, string
+      attribute :price, string
+
+      validates :title, :weight, :price, presence: true
+      validates :weight, allow_blank: true, format: { with: /\A[0-9]+\s[g|kg]\z/ }
+    end
 
-[Wiki](https://github.com/andriy-baran/steel_wheel/wiki)
+    query do
+      validate :product, :variant
+
+      memoize def new_product
+        Product.new(title: title)
+      end
+
+      memoize def new_variant
+        new_product.build_variant(weight: weight, price: price)
+      end
+
+      private
+
+      def product
+        errors.add(:base, :unprocessable_entity, new_product.errors.full_messages.join("\n")) if new_product.invalid?
+      end
+
+      def variant
+        errors.add(:base, :unprocessable_entity, new_variant.errors.full_messages.join("\n")) if new_variant.invalid?
+      end
+    end
+
+    command do
+      def add_to_stock!
+        PointOfSale.find_each do |pos|
+          PosProductStock.create!(pos_id: pos.id, product_id: new_product.id, on_hand: 0.0)
+        end
+      end
+
+      def call(response)
+        ::ApplicationRecord.transaction do
+          new_product.save!
+          new_variant.save!
+          add_to_stock!
+        rescue => e
+          response.errors.add(:unprocessable_entity, e.message)
+          raise ActiveRecord::Rollback
+        end
+      end
+    end
+  end
+
+  def on_success(flow)
+    flow.call
+  end
+end
+```
+Looks too long. Lets move code into separate files.
+```bash
+bin/rails g steel_wheel:params products/create
+```
+Add relative code
+```ruby
+# Base class also can be refered via
+# ApplicationHandler.main_builder.abstract_factory.params_factory.base_class
+class Products::CreateHandler
+  class Params < SteelWheel::Params
+    attribute :title, string
+    attribute :weight, string
+    attribute :price, string
+
+    validates :title, :weight, :price, presence: true
+    validates :weight, allow_blank: true, format: { with: /\A[0-9]+\s[g|kg]\z/ }
+  end
+end
+```
+Than do the same for query
+```bash
+bin/rails g steel_wheel:query products/create
+```
+Add code...
+```ruby
+# Base class also can be refered via
+# ApplicationHandler.main_builder.abstract_factory.query_factory.base_class
+class Products::CreateHandler
+  class Query < SteelWheel::Query
+    validate :product, :variant
+
+    memoize def new_product
+      Product.new(title: title)
+    end
+
+    memoize def new_variant
+      new_product.build_variant(weight: weight, price: price)
+    end
+
+    private
+
+    def product
+      errors.add(:unprocessable_entity, new_product.errors.full_messages.join("\n")) if new_product.invalid?
+    end
+
+    def variant
+      errors.add(:unprocessable_entity, new_variant.errors.full_messages.join("\n")) if new_variant.invalid?
+    end
+  end
+end
+```
+And finally command
+```bash
+bin/rails g steel_wheel:command products/create
+```
+Move code
+```ruby
+class Products::CreateHandler
+  class Command < SteelWheel::Command
+    def add_to_stock!
+      ::PointOfSale.find_each do |pos|
+        ::PosProductStock.create!(pos_id: pos.id, product_id: new_product.id, on_hand: 0.0)
+      end
+    end
+
+    def call(response)
+      ::ApplicationRecord.transaction do
+        new_product.save!
+        new_variant.save!
+        add_to_stock!
+      rescue => e
+        response.errors.add(:unprocessable_entity, e.message)
+        raise ActiveRecord::Rollback
+      end
+    end
+  end
+end
+```
+Than we can update handler
+```ruby
+# app/handlers/manage/products/create_handler.rb
+class Manage::Products::CreateHandler < ApplicationHandler
+  define do
+    params Params
+    query Query
+    command Command
+  end
+
+  def on_success(flow)
+    flow.call(flow)
+  end
+end
+```
+
+### HTTP status codes and errors handling
+
+It's important to provide a correct HTTP status when we faced some problem(s) during request handling. The library encourages developers to add the status codes when they add errors.
+```ruby
+errors.add(:unprocessable_entity, 'error')
+```
+As you know `full_messages` will produce `['Unprocessable Entity error']` to prevent this and get only error `SteelWheel::Response` has special method that makes some error keys to behave like `:base`
+```ruby
+# Default setup
+generic_validation_keys(:not_found, :forbidden, :unprocessable_entity, :bad_request, :unauthorized)
+# To override it in your app
+class SomeHandler
+  define do
+    response do
+      generic_validation_keys(:not_found, :forbidden, :unprocessable_entity, :bad_request, :unauthorized, :payment_required)
+    end
+  end
+end
+```
+In Rails 6.1 `ActiveModel::Error` was introdused and previous setup is not needed, second argument is used instead
+```ruby
+errors.add(:base, :unprocessable_entity, 'error')
+```
 
 ## Development
 

data/Rakefile

@@ -1,6 +1,12 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task default: :spec
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'bundler/setup'
 require 'steel_wheel'

data/lib/generators/steel_wheel/application_handler/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Generates operations files
+
+Example:
+    rails generate steel_wheel:application_handler
+
+    This will create:
+        app/handlers/application_handler.rb

data/lib/generators/steel_wheel/application_handler/application_handler_generator.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SteelWheel
+  class ApplicationHandlerGenerator < Rails::Generators::Base
+    source_root File.expand_path('templates', __dir__)
+
+    def copy_files
+      empty_directory Pathname.new('app/handlers')
+      template 'handler_template.rb', 'app/handlers/application_handler.rb'
+    end
+  end
+end

data/lib/generators/steel_wheel/application_handler/templates/handler_template.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class ApplicationHandler < SteelWheel::Handler
+end

data/lib/generators/steel_wheel/command/command_generator.rb

@@ -1,16 +1,16 @@
-require_relative '../generic_generator'
+# frozen_string_literal: true
 
 module SteelWheel
-  class CommandGenerator < GenericGenerator
-    setup_templates_root('command/templates')
+  class CommandGenerator < Rails::Generators::NamedBase
+    source_root File.expand_path('templates', __dir__)
 
-    on_revoke do
-      template 'command_template.rb', "app/commands/#{file_path}_command.rb"
-    end
-
-    on_invoke do
-      empty_directory Pathname.new('app/commands').join(*class_path)
-      template 'command_template.rb', "app/commands/#{file_path}_command.rb"
+    def copy_files
+      if behavior == :revoke
+        template 'command_template.rb', "app/handlers/#{file_path}_handler/command.rb"
+      elsif behavior == :invoke
+        empty_directory Pathname.new('app/commands').join(*class_path)
+        template 'command_template.rb', "app/handlers/#{file_path}_handler/command.rb"
+      end
     end
   end
 end

data/lib/generators/steel_wheel/command/templates/command_template.rb

@@ -1,3 +1,5 @@
-class <%= class_name %>Command < SteelWheel::Command
+class <%= class_name %>Handler
+  class Command < base_class_for(:command)
 
+  end
 end

data/lib/generators/steel_wheel/handler/handler_generator.rb

@@ -1,16 +1,16 @@
-require_relative '../generic_generator'
+# frozen_string_literal: true
 
 module SteelWheel
-  class HandlerGenerator < GenericGenerator
-    setup_templates_root('handler/templates')
+  class HandlerGenerator < Rails::Generators::NamedBase
+    source_root File.expand_path('templates', __dir__)
 
-    on_revoke do
-      template 'handler_template.rb', "app/handlers/#{file_path}_handler.rb"
-    end
-
-    on_invoke do
-      empty_directory Pathname.new('app/handlers').join(*class_path)
-      template 'handler_template.rb', "app/handlers/#{file_path}_handler.rb"
+    def copy_files
+      if behavior == :revoke
+        template 'handler_template.rb', "app/handlers/#{file_path}_handler.rb"
+      elsif behavior == :invoke
+        empty_directory Pathname.new('app/handlers').join(*class_path)
+        template 'handler_template.rb', "app/handlers/#{file_path}_handler.rb"
+      end
     end
   end
 end

data/lib/generators/steel_wheel/handler/templates/handler_template.rb

@@ -1,15 +1,21 @@
 class <%= class_name %>Handler < ApplicationHandler
-  params_input do
+  define do
+    params do
 
-  end
+    end
+
+    query do
+
+    end
 
-  command_stage do
-    def call
-      # NOOP
+    command do
+      def call(*)
+        # NOOP
+      end
     end
   end
 
-  def on_success
-    flow.call
+  def on_success(flow)
+    flow.call(flow)
   end
 end

data/lib/generators/steel_wheel/params/params_generator.rb

@@ -1,16 +1,16 @@
-require_relative '../generic_generator'
+# frozen_string_literal: true
 
 module SteelWheel
-  class ParamsGenerator < GenericGenerator
-    setup_templates_root('params/templates')
+  class ParamsGenerator < Rails::Generators::NamedBase
+    source_root File.expand_path('templates', __dir__)
 
-    on_revoke do
-      template 'params_template.rb', "app/params/#{file_path}_params.rb"
-    end
-
-    on_invoke do
-      empty_directory Pathname.new('app/params').join(*class_path)
-      template 'params_template.rb', "app/params/#{file_path}_params.rb"
+    def copy_files
+      if behavior == :revoke
+        template 'params_template.rb', "app/handlers/#{file_path}_handler/params.rb"
+      elsif behavior == :invoke
+        empty_directory Pathname.new('app/params').join(*class_path)
+        template 'params_template.rb', "app/handlers/#{file_path}_handler/params.rb"
+      end
     end
   end
 end

data/lib/generators/steel_wheel/params/templates/params_template.rb

@@ -1,3 +1,5 @@
-class <%= class_name %>Params < SteelWheel::Params
+class <%= class_name %>Handler
+  class Params < base_class_for(:params)
 
+  end
 end

data/lib/generators/steel_wheel/query/query_generator.rb

@@ -1,16 +1,16 @@
-require_relative '../generic_generator'
+# frozen_string_literal: true
 
 module SteelWheel
-  class CommandGenerator < GenericGenerator
-    setup_templates_root('query/templates')
+  class QueryGenerator < Rails::Generators::NamedBase
+    source_root File.expand_path('templates', __dir__)
 
-    on_revoke do
-      template 'query_template.rb', "app/queries/#{file_path}_query.rb"
-    end
-
-    on_invoke do
-      empty_directory Pathname.new('app/queries').join(*class_path)
-      template 'query_template.rb', "app/queries/#{file_path}_query.rb"
+    def copy_files
+      if behavior == :revoke
+        template 'query_template.rb', "app/handlers/#{file_path}_handler/query.rb"
+      elsif behavior == :invoke
+        empty_directory Pathname.new('app/queries').join(*class_path)
+        template 'query_template.rb', "app/handlers/#{file_path}_handler/query.rb"
+      end
     end
   end
 end

data/lib/generators/steel_wheel/query/templates/query_template.rb

@@ -1,3 +1,5 @@
-class <%= class_name %>Query < SteelWheel::Query
+class <%= class_name %>Handler
+  class Query < base_class_for(:query)
 
+  end
 end

data/lib/steel_wheel/command.rb

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+
 module SteelWheel
+  # Base class for commands
   class Command
     include Memery
     include ActiveModel::Validations
@@ -8,10 +11,13 @@ module SteelWheel
     end
 
     def http_status
-      errors.keys.first
+      return :ok if errors.empty?
+      return errors.keys.first unless defined?(ActiveModel::Error)
+
+      errors.map(&:type).first
     end
 
-    def call
+    def call(*)
       # NOOP
     end
   end