hexx 1.1.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d65195d201714af776e125147d354a379dac49f6
-  data.tar.gz: 8cae2ca8e5922850e7287688dee8997c3f7a0576
+  metadata.gz: eaee6ebce4becce87383d4a646ad52738b07094e
+  data.tar.gz: 843858ce7dd021925a335bcf78fe36c038605161
 SHA512:
-  metadata.gz: 627cba9adf41b1c286efe70c45edcc347a440bc1866453ca8ccb01bee057cbbf1a5e14a3be9c4e6203d1d304b411eb659e1357490db1740173847bf96338731b
-  data.tar.gz: 65bdbf6099b498c3600f18c2034e49d3d6f4064ec5a6dcd124efc0cba29125e912d113d1f0cff1a569fd67166e55225a75887d2bdc00bcae1109abb0a9cf2861
+  metadata.gz: ec5ff9a06822630f60489fdaaea9a5ab20f01b6a130d7bfd9431a225a1f86597462adcb0d6e00ef0fb399bcf6c9c88c626d0b59c51458060ab65160e6ac45c6e
+  data.tar.gz: c15800df267a557a08d00945ada1ea176349cf47eee331d6c94282fd8587f295daa82a6d786946cfea191d4e0d01301e8f2d6fd3e4efdbb9ccc76df080dce3f2

data/.rubocop.yml

@@ -22,7 +22,13 @@ Style/Documentation:
   Exclude:
     - 'spec/**/*'
 
-Style/EmptyLinesAroundBody:
+Style/EmptyLinesAroundClassBody:
+  Enabled: false
+
+Style/EmptyLinesAroundMethodBody:
+  Enabled: false
+
+Style/EmptyLinesAroundModuleBody:
   Enabled: false
 
 Style/EmptyLineBetweenDefs:

data/README.rdoc

@@ -7,18 +7,18 @@
 {<img src="http://img.shields.io/coveralls/nepalez/hexx.svg?style=flat" alt="Coverage Status" />}[https://coveralls.io/r/nepalez/hexx]
 {<img src="http://img.shields.io/badge/license-MIT-blue.svg?style=flat" alt="License" />}[https://github.com/nepalez/hexx/blob/master/LICENSE.rdoc]
 
-A part of framework for rapid Rails API development following the hexagonal
-architecture.
+The module provides a base service objects class and some features for the
+domain models (entities).
 
 Provides:
-* +UseCase+ base class for decoupling a domain business logics from a controller
-* Thor generators for scaffolding use cases, controllers and routes.
+* +Service+ base class for decoupling a domain business logics from a controller
+* +Models+ module for extending domain models.
 
 == Installation
 
 Add this line to your application's Gemfile:
 
-    gem "hexx"
+    gem "hexx", "~> 2.0"
 
 And then execute:
 
@@ -28,217 +28,113 @@ Or install it yourself as:
 
     $ gem install hexx
 
-== Usage
+== A pattern
 
-Controllers are expected to serve as a thin delivery layer between a client
-and a use case. They should only orchestrate interactions of use case with its
-listeners: the controller itself, mailers and other outer services.
+Service objects decouple business logics from both:
+* Domain _models_ (entities).
+* Delivery mechanism _controllers_ (such as Rails framework).
 
-In a typical case the controller should constist from:
+Following object oriented architecture service objects exploit the
+**Observer** (Listener) pattern, using the
+{ Wisper }[https://github.com/krisleech/wisper] gem. A service doesn't
+return their result to caller but notifies its subscribers instead.
 
-* actions serving as <b>outer ports</b> to client, listening to routes and
-  calling corresponding use cases
-* methods servinge as <b>inner ports</b> called by use case notifications
-  (see wisper[https://github.com/krisleech/wisper.git] for more details).
+Some examples of this pattern implementation are available at the
+{ wisper gem wiki }[https://github.com/krisleech/wisper/wiki].
 
-=== Use case
+=== Service
+
+A typical service object is shown below:
 
-  # app/my_project/use_cases/get_item.rb
   require 'hexx'
 
-  module MyProject
-    class GetItem < Hexx::Base
+  class GetItem < Hexx::Service
 
-      # whitelists parameters taken by an initializer
-      allow_params :id
+    # whitelists parameters and defines corresponding attributes.
+    allow_params :name
 
-      # runs some validation (on the basis of ActiveModel::Validations)
-      validate :id, presence: true
+    # defines some validation using ActiveModel::Validations helpers.
+    validate :name, presence: true
 
-      # runs a use case
-      def run!
-        validate!
-        # provide case-specific business rules
-      end
-    end
-  end
+    # runs a service
+    def run
 
-=== Rails controller
-
-  # app/controllers/my_project/rails/api/v1/items_controller.rb
-  require 'my_project'
-  require 'rails'
-
-  module MyProject
-    module Rails
-      module Api
-        module V1
-          class ItemsController < ActionController::Base
-
-          # An action (outer port) of the controller
-          def show
-            use_case = GetItem.new params.allow(:id)
-            # subscribes the controller for listening to the use case
-            # notifications via the controller's inner ports.
-            use_case.subscribe self
-            use_case.run
-          end
-
-          # Inner port to be called by a use case
-          def found(item)
-            render json: { success: true, item: item }, status: 200
-          end
-        end
+      # runs some 
+      transaction
+        MyModel.save! name: name # name is defined by allow_params helper.
+        publish :success         # notifies its listeners.
       end
     end
   end
 
-<i>Note the module above is not +my_project+, but +my_project-rails+
-(a delivery mechanism for +my_project+).</i>
+Usage of the service (in a Rails controller):
 
-=== Models and Entities
-
-The module also defines module <tt>Hexx::Models</tt> for including to
-entities or active_record models. It defines a +validate!+ method:
+  class ItemsController < ActionController::Base
 
-  class User < ActiveRecord::Base
-    include Hexx::Models
-  end
+    # Creates an item with given name
+    def show
+      service = GetItem.new params.allow(:name)
+      service.subscribe self, prefix: :on
+      service.run
+    end
 
-  User.new.validate!
-  # => raises Hexx::RecordInvalid error if the record isn't valid.
+    # Publishes a success message
+    def success
+      render "created"
+    end
 
-It also redefines +attr_accessor+, +attr_reader+ and +attr_writer+ helpers
-to allow attribute coercion.
+    # Publishes an error messages
+    def error(messages)
+      @messages = messages
+      render "error"
+    end
 
-  require "attributes/string"
+Note the controller knows nothing about the action itself. It responsible only
+for selection of proper service and responding to its results.
 
-  class User < ActiveRecord::Base
-    include Hexx::Models
+Also note any controller action does one thing only. The +show+ action
+are requested by a client. The +on_success+ and +on_error+ are called by
+a service and reports to a client.
 
-    attr_accessor :name, type: Attributes::String
-  end
+=== Models and Entities
 
-This coerces the name with an Attributes::String class object as if its
-setter and getter were:
+The module also defines module <tt>Hexx::Models</tt> to extend domain models
+(entities). This allows coercion of model attributes with +attr_coerced+ helper:
 
-  def name=(value)
-    super Attributes::String.new(value)
+  class User
+    extend Hexx::Models
+    attr_coerced  :name, type: ActiveSupport::Multibyte::Chars
   end
 
-  def name
-    Attributes::String.new(super)
-  end
-
-== Generators
-
-The module contains generators, written on the basis of the Thor, namely:
-
-* request specs (acceptance tests);
-* controllers with their specs (unit tests)
-* routing specs (unit tests);
-* domain specs (acceptance tests for use cases and models);
-* use_cases with their specs (unit tests);
-
-The scaffolded specs contains examples for writing tests rapidly following
-some conventions.
-
-=== Request spec (acceptance test for the API)
-
-Request specs used to test API from a user view - by sending requests
-and checkign their results. Their should be written on the basis of
-API blueprint. Their shouldn't check the internal states of application, such
-as models, use_cases etc.
-
-Task is called with 1 argument, that consists from two parts divided by colon:
-
-* request type (get, post etc.)
-* requests relative address
-
-Example:
-
-  $ hexx request get:items/{id}
-  # => spec/requests/my_module/api/v1/get_items_id_spec.rb
-
-API namespace (those /my_module/api/v1) will be added by default.
-
-=== Controller action with a corresponding route
+  user = User.new name: "Ivan"
+  
+  user.name
+  # => "Ivan"
+  
+  user.name.class
+  # => ActiveSupport::Multibyte::Chars
 
-A scaffolder provides tests for both a controller and its router. It
-also scaffolds a controller action itself. The router action should be
-added manually.
+The method defines (or redefines) both attribute getter and setter. You can use
+it to transform values by default:
 
-Except for the requests specs (above) the controller spec is an unit test
-that checks outer and inner controller action in isolation from both
-router and a use case. It only checks that outer actions calls proper use cases,
-and inner actions returns proper responce to a user.
-
-Task is called with 3 argumets:
-
-* name of the controller
-* request type and action name, divided by colon
-* name of the use case for the action
-
-Example:
-
-  $ hexx controller items get:show get_item
-  # => spec/routing/my_module/api/v1/items_routing_spec.rb
-  # => spec/controllers/my_module/api/v1/items_controller_spec.rb
-  # => app/controllers/my_module/api/v1/items_controller.rb
-
-==== Acceptance spec for the domain
-
-The domain spec checks the inner part of the domain (use_cases and models) as
-a whole. Because the domain interacts with outer word through the use cases
-only, the acceptance test should call use_cases and check its results.
-It should not check inner states of the domain (models, entities, repositories,
-databases etc.)
-
-Task is called with 1 argument:
-
-* name of the use_case.
-
-Example:
-
-  $ hexx domain get_item
-  # => spec/my_module/domain/get_item_spec.rb
-
-==== UseCase
-
-The unit tests for checking a use_case in isolation.
-
-Task is called with 1 argument:
-
-* name of the use_case.
-
-Example:
-
-  $ hexx use_case get_item
-  # => spec/my_module/use_cases/get_item_spec.rb
-  # => app/my_module/use_cases/get_item.rb
-
-==== Dependency
-
-Scaffolds the external dependency setting with a corresponding specs.
-
-Task is called with 1 argument:
-
-* name of the dependency.
+  class StrippedString < String
+    def initialize(value)
+      super value.strip
+    end
+  end
 
-Example:
+  class User
+    extend Hexx::Models
+    attr_coerced :name, type: StrippedString
+  end
 
-  $hexx dependency some_module
-  # => spec/my_module_spec.rb
-  # => lib/my_module.rb
+  user = User.name " Ivan  "
+  user.name # => "Ivan"
 
 == Relevant Links
 
 1:: Matt Wynne's talk {Hexagonal Rails}[http://www.confreaks.com/videos/977-goruco2012-hexagonal-rails]
 
-== Changelog
-
-To review changes between versions see the {CHANGELOG}[CHANGELOG.rdoc].
-
 == License
 
 The project is distributed under the {MIT LICENSE}[LICENSE.rdoc].

data/Rakefile

@@ -4,34 +4,20 @@ rescue LoadError
   puts "You must `gem install bundler` and `bundle install` to run rake tasks"
 end
 
-begin
-  require "rdoc/task"
-rescue LoadError
-  require "rdoc/rdoc"
-  require "rake/rdoctask"
-  RDoc::Task = Rake::RDocTask
-end
-
-RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = "rdoc"
-  rdoc.title    = "Hexx"
-  rdoc.options << "--line-numbers"
-  rdoc.rdoc_files.include("README.rdoc")
-  rdoc.rdoc_files.include("lib/**/*.rb")
-end
-
 Bundler::GemHelper.install_tasks
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
+
 task :default do
-  sh "bundle exec rspec spec"
+  system "bundle exec rspec spec"
 end
 
-task full: [:default] do
-  sh "rubocop"
-  sh "metric_fu"
-  sh "inch"
+task :check do
+  system "coveralls report"
+  system "rubocop"
+  system "inch --pedantic"
+  system "metric_fu"
 end

data/lib/hexx/models/base_coercer.rb

@@ -0,0 +1,36 @@
+module Hexx
+  module Models
+
+    # Coerces PORO attribute's getter and setter with given type.
+    class BaseCoercer < Struct.new(:klass, :name, :type)
+
+      # Coerces class attribute's getter and setter.
+      def coerce
+        coerce_setter
+        coerce_getter
+      end
+
+      private
+
+      def coerce_setter
+        klass.class_eval(
+          "def #{ name };
+            #{ type_name }.new(@#{ name });
+          end"
+        )
+      end
+
+      def coerce_getter
+        klass.class_eval(
+          "def #{ name }=(value);
+            @#{ name } = #{ type_name }.new(value);
+          end"
+        )
+      end
+
+      def type_name
+        @type_name ||= type.name
+      end
+    end
+  end
+end

data/lib/hexx/models.rb

@@ -1,74 +1,29 @@
-require "active_support"
+require "hexx/models/base_coercer"
 
 module Hexx
 
-  # Contains +attr_coerced+ public class method.
+  # Declares the +.attr_coerced+ private class method.
   #
-  # Include the module into the Rails model:
+  # @example
   #
   #   require "hexx"
   #   require_relative "attributes/string"
   #
-  #   class User < ActiveRecord::Base
-  #     include Hexx::Models
-  #
-  #     # coerces attributes
-  #     attr_coerced :name, login, type: Attributes::String
+  #   class User
+  #     extend Hexx::Models
+  #     attr_coerced :name, type: ActiveSupport::Multibyte::Chars
   #   end
   #
   module Models
-    extend ActiveSupport::Concern
-
-    # Model class helpers for attributes coercion.
-    module ClassMethods
-
-      def attr_coerced(*names, type:)
-        names.each { |name| _attr_coerced(name, type) }
-      end
-
-      private
 
-      def _attr_coerced(name, type)
-        if ancestors.map(&:name).include? "ActiveRecord::Base"
-          coerce_activerecord_reader name, type
-          coerce_activerecord_writer name, type
-        else
-          coerce_simple_reader name, type
-          coerce_simple_writer name, type
-        end
-      end
+    private
 
-      def coerce_simple_reader(name, type)
-        class_eval(
-          "def #{ name };
-            #{ type.name }.new(@#{ name });
-          end"
-        )
-      end
-
-      def coerce_simple_writer(name, type)
-        class_eval(
-          "def #{ name }=(value);
-            @#{ name } = #{ type.name }.new(value);
-          end"
-        )
-      end
-
-      def coerce_activerecord_reader(name, type)
-        class_eval(
-          "def #{ name };
-            #{ type.name }.new read_attribute(:#{ name });
-          end"
-        )
-      end
+    def attr_coerced(*names, type:)
+      names.each { |name| coercer.new(self, name, type).coerce }
+    end
 
-      def coerce_activerecord_writer(name, type)
-        class_eval(
-          "def #{ name }=(value);
-            write_attribute :#{ name }, #{ type.name }.new(value);
-          end"
-        )
-      end
+    def coercer
+      @coercer ||= BaseCoercer
     end
   end
 end

data/lib/hexx/service/invalid.rb

@@ -0,0 +1,48 @@
+module Hexx
+  class Service
+
+    # Exception to be raised by invalid services.
+    class Invalid < ::RuntimeError
+
+      # An invalid service object with error messages.
+      attr_reader :service
+
+      # Initializes the exception.
+      #
+      # @example
+      #     fail Hexx::Service::Invalid.new(service)
+      #
+      # Params:
+      # +service+:: a Hexx::Service object containing error messages.
+      #
+      def initialize(service)
+        @service = service
+        fail ArgumentError unless self.service.is_a? Hexx::Service
+      end
+
+      # Returns a default text message for the exception.
+      #
+      # @example
+      #     error = Hexx::Service::Invalid.new service
+      #     error.message # => "Service invalid: #<Hexx::Service... >"
+      #
+      def message
+        "Service invalid: #{ service.inspect }"
+      end
+
+      # Returns a list of <tt>Hexx::Service::Message</tt> messages of
+      # +error+ type.
+      #
+      # @example
+      #     error = Hexx::Service::Invalid.new service
+      #     error.messages            # => [#<Hexx::Message... >, ...]
+      #     error.messages.first.type # => "error"
+      #
+      def messages
+        service.errors.values.flatten.map do |text|
+          Message.new type: "error", text: text
+        end
+      end
+    end
+  end
+end

data/lib/hexx/service/message.rb

@@ -0,0 +1,57 @@
+module Hexx
+  class Service
+
+    # A message to be returned by services.
+    class Message
+      include Comparable
+
+      # A stringified type and a text of the message.
+      attr_reader :type, :text
+
+      # Initializes the message.
+      #
+      # @example
+      #     Message.new type: "success", text: "Object created!"
+      #
+      # Params:
+      # <tt>:type</tt>:: string/symbolic message type (:error, :info, :success).
+      # <tt>:text</tt>:: message text.
+      #
+      def initialize(type:, text:)
+        @type, @text = type.to_s, text.to_s
+      end
+
+      # Extracts error messages from ActiveRecord or ActiveModel objects.
+      #
+      # @example
+      #     Message.from(object) # => [#<Hexx::Service::Message ...>]
+      #
+      # Params:
+      # +object+:: an object to extract messages from.
+      #
+      def self.from(object)
+        object.errors.values.flatten.map do |text|
+          new type: "error", text: text
+        end
+      end
+
+      # Compares two messages by type and text.
+      def ==(other)
+        return false unless other.is_a? self.class
+        [type, text] == [other.type, other.text]
+      end
+
+      # Orders messages by type and text.
+      #
+      # @example
+      #     ab = Message.new(type: "a", text: "b")
+      #     ba = Message.new(type: "b", text: "a")
+      #     ab < ba # => true
+      #
+      def <=>(other)
+        fail ArgumentError unless other.is_a? self.class
+        [type, text] <=> [other.type, other.text]
+      end
+    end
+  end
+end

data/lib/hexx/service/messages.rb

@@ -0,0 +1,34 @@
+require "hexx/service/message"
+
+module Hexx
+  class Service
+
+    # Declares methods for creation messages by a service:
+    #
+    # <tt>t(text, options = {})</tt>:: translates text in the service's scope.
+    # <tt>messages</tt>:: returns an array of service's messages.
+    # <tt>add_message(type, text, options = {})</tt>:: adds a message to array.
+    #
+    module Messages
+
+      private
+
+      # Translates given key in current service's scope.
+      def t(key, options = {})
+        return key unless key.is_a? Symbol
+        scope = %w(activemodel messages models) << self.class.name.underscore
+        I18n.t key, options.merge(scope: scope)
+      end
+
+      # Returns the array of service's messages.
+      def messages
+        @messages ||= []
+      end
+
+      # Adds the translated message to the messages array.
+      def add_message(type, text, options = {})
+        messages << Message.new(type: type, text: t(text, options))
+      end
+    end
+  end
+end