action_handler 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2cb17f485ca9bcfe1a0d3f8ccf1273d5a11dc0ab00f8fc24e46c4696f2c85d41
+  data.tar.gz: 2a19b8f23d01be2202a3c4bc91797d25e94afeaa318e3c54f7f4f3c62ea2c2d6
+SHA512:
+  metadata.gz: e24ba8bc134de0cdec88fba626866666439db82f928dcda58cc6626bed09785ff99b938d2934eccee81651bfe8569daf49bba85c8fb2196bacffccc4f46d6435
+  data.tar.gz: 9b5269ec69e02c98fbffa7e3221a5c89ad6699443e36a34f5d7747c26c84e5687e6695ffaaaf87a7053345d1666b3a2c96c5ebf9ea75056c5442a9523fcbc293

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 1970 ryym
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,131 @@
+# Action Handler
+
+[![CircleCI](https://circleci.com/gh/ryym/action_handler.svg?style=svg)](https://circleci.com/gh/ryym/action_handler)
+
+ActionHandler is a Rails plugin that helps you write controller functionalities in clean and testable way.
+
+## What is a handler?
+
+A handler is a controller-like class. Each public method can be an action method.
+But unlike controllers, handlers inherit few methods by default.
+Intead of using super class methods such as `params`, `sessions`, you can take them as arguments.
+And you need to represent a response (data for views) as a single return value,
+instead of assiging multiple instance variables.
+
+```ruby
+# Example
+class UsersHandler
+  include ActionHandler::Equip # (optional)
+
+  def initialize(ranking: RankingService.new)
+    @ranking = ranking
+  end
+
+  # Get request information via arguments.
+  def index(params, cookies)
+    puts "cookies: #{cookies}"
+
+    users = User.order(:id).page(params[:page])
+    ranks = @ranking.generate(users)
+
+    # Return a hash. It will be passed to controller's `render`.
+    { locals: { users: users, ranks: ranks } }
+  end
+
+  # Define custom argument.
+  arg(:user_id) do |ctrl|
+    ctrl.params[:id]
+  end
+
+  def show(user_id, format)
+    user = User.find(user_id)
+
+    # `render` is available as well. It just returns a given hash.
+    if format == :html
+      render locals: { user: user }
+    else
+      render json: user
+    end
+  end
+
+  # ...
+end
+```
+
+## Features
+
+### Clean and clear structure
+
+- In handlers, action methods take necessary inputs as arguments and
+  return output as a return value.
+  So easy to read and test.
+- Handler is just a class, so you can set up any dependencies via `initialize` method.
+
+### Automatic arguments injection
+
+- ActionHandler automatically injects common controller properties (`params`, `request`, etc)
+  just by declaring them as action method's arguments.
+- You can define custom injectable arguments as well.
+
+Note that this feature is heavily inspired by [ActionArgs](https://github.com/asakusarb/action_args).
+
+## Motivation
+
+- Testability is important as much or more than test itself.
+- Prefer clarity and simplicity over code shortness and easiness, for future maintainability.
+
+## Getting Started
+
+Installation:
+
+```bash
+gem install action_handler
+```
+
+A simplest handler is a plain class with no super classes.
+
+```ruby
+class UsersHandler
+  def index(params)
+    users = User.order(:id).page(params[:page])
+    { locals: { users: users } }
+  end
+
+  def show(params)
+    user = User.find(params[:id])
+    { locals: { user: user } }
+  end
+end
+```
+
+To use this handler, register it in a controller.
+
+```ruby
+class UsersController < ApplicationController
+  include ActionHandler::Controller
+
+  use_handler { UsersHandler.new }
+end
+```
+
+This makes the controller implement same name action methods.
+Now you can define routes to this controller as usual.
+
+```ruby
+resources :users, only: %i[index show]
+```
+
+
+Though you can use plain handler classes, usually you need to include `ActionHandler::Equip` module
+to use basic controller functionalities like `redirect_to` or custom arguments.
+
+## Guides
+
+See [Wiki][wiki] for detailed guides.
+
+[wiki]: https://github.com/ryym/action_handler/wiki
+
+TODO:
+
+- Currently Unsupported controller features
+- Where should handlers be placed?

data/lib/action_handler/args/default.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ActionHandler
+  module Args
+    # Args::Default is a default arguments supplier for handler methods.
+    class Default
+      %i[params request response cookies flash session logger].each do |key|
+        define_method(key) do |ctrl|
+          ctrl.send(key)
+        end
+      end
+
+      def reset_session(ctrl)
+        ctrl.method(:reset_session)
+      end
+
+      def format(ctrl)
+        ctrl.request.format
+      end
+    end
+  end
+end

data/lib/action_handler/args/params.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ActionHandler
+  module Args
+    class Params
+      def initialize(*names, **nested_params)
+        names.each do |name|
+          define_singleton_method(name) do |ctrl|
+            ctrl.params[name]
+          end
+        end
+
+        nested_params.each do |name, fields|
+          define_singleton_method(name) do |ctrl|
+            ctrl.params.require(name).permit(*fields)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action_handler/args.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'action_handler/args/params'
+
+module ActionHandler
+  module Args
+    module_function def from_hash(name_to_proc)
+      klass = Class.new do
+        name_to_proc.each do |name, proc|
+          define_method(name, &proc)
+        end
+      end
+
+      klass.new
+    end
+  end
+end

data/lib/action_handler/args_maker.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ActionHandler
+  class ArgsMaker
+    # TODO: Support optional arguments and keyword arguments.
+
+    def make_args(parameters, supplier, context: nil)
+      supplier_args = [context].compact
+      parameters.inject([]) do |values, (_, name)|
+        unless supplier.respond_to?(name)
+          raise ArgumentError, "parameter #{name} is not defined in #{supplier}"
+        end
+
+        values << supplier.send(name, *supplier_args)
+      end
+    end
+  end
+end

data/lib/action_handler/call.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ActionHandler
+  class Call
+    attr_reader :method_name
+    attr_reader :args
+
+    def initialize(method_name, args = [])
+      raise ArgumentError, 'args must be an array' unless args.is_a?(Array)
+
+      @method_name = method_name.to_sym
+      @args = args.freeze
+    end
+
+    def call_with(receiver)
+      receiver.send(method_name, *args)
+    end
+
+    # overrides
+    def ==(other)
+      other.is_a?(ActionHandler::Call) &&
+        method_name == other.method_name &&
+        args == other.args
+    end
+
+    # overrides
+    def hash
+      [method_name, args].hash
+    end
+  end
+end

data/lib/action_handler/config.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ActionHandler
+  CONFIG_VAR_NAME = :@_action_handler_config
+
+  class Config
+    def self.get(handler_class)
+      handler_class.instance_variable_get(CONFIG_VAR_NAME)
+    end
+
+    def self.set(handler_class, config)
+      raise ArgumentError, 'invalid config' unless config.is_a?(self)
+
+      handler_class.instance_variable_set(CONFIG_VAR_NAME, config)
+    end
+
+    attr_reader :as_controller
+    attr_reader :action_methods
+    attr_reader :args_suppliers
+    attr_reader :custom_args
+
+    def initialize
+      @as_controller = nil
+      @action_methods = nil
+      @args_suppliers = []
+      @custom_args = {} # { method_name: proc }
+    end
+
+    def as_controller=(block)
+      raise ArgumentError, 'must be proc' unless block.is_a?(Proc)
+
+      @as_controller = block
+    end
+
+    def action_methods=(names)
+      raise ArgumentError, 'must be array' unless names.is_a?(Array)
+
+      @action_methods = names
+    end
+
+    def add_args_supplier(supplier)
+      @args_suppliers.push(supplier)
+    end
+
+    def add_arg(name, &block)
+      @custom_args[name] = block
+    end
+  end
+end

data/lib/action_handler/controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'action_handler/installer'
+
+module ActionHandler
+  module Controller
+    def self.included(ctrl_class)
+      ctrl_class.extend ActionHandler::ControllerExtension
+    end
+  end
+
+  module ControllerExtension
+    def use_handler
+      handler = yield
+      ActionHandler::Installer.new.install(handler, self)
+    end
+  end
+end

data/lib/action_handler/equip.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'action_handler/call'
+require 'action_handler/args/default'
+
+module ActionHandler
+  # Equip implements most basic functionality of controller for handler.
+  module Equip
+    # Return the argument as is, because the actual rendering
+    # is done in a controller. This just makes returning values more easy.
+    # Without this:
+    #
+    #   { status: :ok, json: user.to_json }
+    #
+    # With this (no braces):
+    #
+    #   render status: :ok, json: user.to_json
+    def render(props)
+      props
+    end
+
+    def redirect_to(*args)
+      ActionHandler::Call.new(:redirect_to, args)
+    end
+
+    def urls
+      Rails.application.routes.url_helpers
+    end
+
+    def self.included(handler_class)
+      ActionHandler::Config.set(handler_class, ActionHandler::Config.new)
+      handler_class.extend ActionHandler::HandlerExtension
+      handler_class.args ActionHandler::Args::Default.new
+    end
+  end
+
+  module HandlerExtension
+    def as_controller(&block)
+      ActionHandler::Config.get(self).as_controller = block
+    end
+
+    def action_methods(*method_names)
+      ActionHandler::Config.get(self).action_methods = method_names
+    end
+
+    def args(*suppliers)
+      raise '`args` does not accept block. Use `arg` to define custom argument' if block_given?
+
+      config = ActionHandler::Config.get(self)
+      suppliers.each do |supplier|
+        config.add_args_supplier(supplier)
+      end
+    end
+
+    def args_params(*names)
+      ActionHandler::Config.get(self).add_args_supplier(
+        ActionHandler::Args::Params.new(*names),
+      )
+    end
+
+    def arg(name, &block)
+      unless block_given?
+        raise '`arg` requires block. Use `args` to register arguments supplier object'
+      end
+
+      ActionHandler::Config.get(self).add_arg(name, &block)
+    end
+  end
+end

data/lib/action_handler/installer.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'action_handler/args_maker'
+require 'action_handler/response_evaluator'
+
+module ActionHandler
+  class Installer
+    attr_reader :args_maker
+    attr_reader :res_evaluator
+
+    def initialize(
+      args_maker: ActionHandler::ArgsMaker.new,
+      res_evaluator: ActionHandler::ResponseEvaluator.new
+    )
+      @args_maker = args_maker
+      @res_evaluator = res_evaluator
+    end
+
+    def install(handler, ctrl_class)
+      config = ActionHandler::Config.get(handler.class) || ActionHandler::Config.new
+
+      ctrl_class.class_eval(&config.as_controller) if config.as_controller
+
+      actions = action_methods(handler, config)
+      args_supplier = args_supplier(config)
+
+      actions.each do |name|
+        installer = self
+        ctrl_class.send(:define_method, name) do
+          method = handler.method(name)
+          args = installer.args_maker.make_args(
+            method.parameters,
+            args_supplier,
+            context: self,
+          )
+          res = method.call(*args)
+          installer.res_evaluator.evaluate(self, res)
+        end
+      end
+    end
+
+    private def action_methods(handler, config)
+      config.action_methods || own_public_methods(handler)
+    end
+
+    private def args_supplier(config)
+      args_hash = {}
+
+      config.args_suppliers.each do |supplier|
+        own_public_methods(supplier).each do |name|
+          args_hash[name] = supplier.method(name)
+        end
+      end
+
+      args_hash = args_hash.merge(config.custom_args)
+      ActionHandler::Args.from_hash(args_hash)
+    end
+
+    # List all public methods except super class methods.
+    private def own_public_methods(obj)
+      methods = obj.public_methods
+      obj.class.ancestors.drop(1).inject(methods) do |ms, sp|
+        ms - sp.instance_methods
+      end
+    end
+  end
+end

data/lib/action_handler/response_evaluator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActionHandler
+  # ResponseEvaluator evaluates and converts handler return values.
+  class ResponseEvaluator
+    def evaluate(ctrl, res)
+      case res
+      when Hash
+        ctrl.render(res)
+      when ActionHandler::Call
+        res.call_with(ctrl)
+      end
+    end
+  end
+end

data/lib/action_handler/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActionHandler
+  VERSION = '0.0.0'
+end

data/lib/action_handler.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'action_handler/config'
+require 'action_handler/args'
+require 'action_handler/controller'
+require 'action_handler/equip'
+
+module ActionHandler
+  # Enable to autoload handlers defined in a controller file.
+  # Rails autoloading works only if the constant is defined in
+  # a file matching its name. So if `FooHandler` is defined in
+  # `foo_controller.rb`, it cannot be autoloaded.
+  # (https://guides.rubyonrails.org/autoloading_and_reloading_constants.html)
+  #
+  # So this hooks const_missing and load the corresponding controller.
+  # If the controller exists, its handler will be loaded as well.
+  #
+  # Currently this supports only the handlers defined in the top level scope.
+  module_function def autoload_handlers_from_controller_file
+    unless defined? Rails
+      raise 'Rails is not defined. This method is supposed to use in Rails environment.'
+    end
+
+    return if @hook_registered
+
+    @hook_registered = true
+
+    # Perhaps this warning is a RuboCop's bug.
+    # rubocop:disable Lint/NestedMethodDefinition
+    def Object.const_missing(name)
+      # rubocop:enable Lint/NestedMethodDefinition
+
+      return super unless name =~ /\A[a-zA-Z0-9_]+Handler\z/
+      return super if name == :ActionHandler
+
+      # Try to autoload the corresponding controller.
+      prefix = name.to_s.sub(/Handler\z/, '')
+      begin
+        const_get("::#{prefix}Controller")
+      rescue NameError
+        super
+      end
+
+      # Return the handler if loaded.
+      return const_get(name) if Object.const_defined?(name)
+
+      # Otherwise raise the NameError.
+      super
+    end
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: action_handler
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- ryym
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-11-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rspec_junit_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.60'
+description: Makes your controllers more unit-testable.
+email:
+- ryym.64@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- lib/action_handler.rb
+- lib/action_handler/args.rb
+- lib/action_handler/args/default.rb
+- lib/action_handler/args/params.rb
+- lib/action_handler/args_maker.rb
+- lib/action_handler/call.rb
+- lib/action_handler/config.rb
+- lib/action_handler/controller.rb
+- lib/action_handler/equip.rb
+- lib/action_handler/installer.rb
+- lib/action_handler/response_evaluator.rb
+- lib/action_handler/version.rb
+homepage: https://github.com/ryym/action_handler
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Rails controller alternative
+test_files: []