hexx 5.4.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fa67c0939cdf123932cc4357f1cdb143559287a7
-  data.tar.gz: d31b064fcc971a2162bd995555d38971c29bf8d7
+  metadata.gz: 2e8768af29b2a06a1eec7ae917896144373edf4e
+  data.tar.gz: 33b14d58fda376b285b3674a69efc05fcf0ad3d9
 SHA512:
-  metadata.gz: cc793326fe14ff8c7fe62a5d46c9912a3175773702c44de92dda5e1bff5f30913ff56e646852523995874f1cf281018097bd3181da6ce292058c59f24ce29d73
-  data.tar.gz: bcfbc983fa5c1fdfd8eba166baaf47f4239707358eed3527ce7d2eee44617c6b2853a13b8c790c0c37a0ba6429cbc3ba0177c5b9ccf66f289acc2dff7fbf81f4
+  metadata.gz: 688a02c4e5b617233bd222451e44580e4974e0ba93a54ae6532ba160a01aa37c4bbd67d0db3ee12b22a19567502947a6b7cb29cf79883a23b476093a1e8f67c3
+  data.tar.gz: 32504f32691f79843f70416690f75c70f9679e8517659d3cec6ff62029365341673d017a1555e1de2137e1b80ca314a9e9fec6cd8917a2de1f9801100f089b31

data/README.rdoc

@@ -7,16 +7,25 @@
 {<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]
 
-The module provides a base service objects class and some features for the
-domain models (entities).
+The base library for domain models.
 
-Provides:
-* +Service+ base class for decoupling a domain business logics from a controller
-* +Models+ module for extending domain models.
+== API
 
-The module is expected to be used in PORO domain. For usage in active record
-domains consider { hexx-active_record }[https://github.com/nepalez/hexx-active_record]
-gem instead.
+Includes classes and modules as below:
+<tt>Hexx::Service</tt>:: The base class for service objects.
+<tt>Hexx::Service::Message</tt>:: The message provided by service objects.
+<tt>Hexx::Null</tt>:: The Null object.
+<tt>Hexx::Coercible</tt>:: The module that makes model attributes coercible.
+<tt>Hexx::Configurable</tt>:: The module to convert a core domain module to the
+                              dependency injection framework.
+<tt>Hexx::Dependable</tt>:: The module provides +depends_on+ class helper methodto
+                            to implement the setter dependency injection.
+
+The module is expected to be used in PORO domains for Ruby MRI 2.1+.
+
+For usage in active record bases domains consider the
+{ hexx-active_record }[https://github.com/nepalez/hexx-active_record]
+gem extension.
 
 == Installation
 
@@ -32,47 +41,172 @@ Or install it yourself as:
 
     $ gem install hexx
 
-== Pattern
+== Usage
+
+=== Hexx::Configurable
+
+Adds the +configure+ and +depends_on+ helpers to the module to convert it
+to the {dependency injection container}[http://en.m.wikipedia.org/wiki/Dependency_injection].
+
+Extend the base class of the gem and declare the module dependencies from
+outer classes and modules with the +depend_on+ helper:
+
+  # lib/my_gem.rb
+  module MyGem
+    extend Hexx::Configurable
+
+    depend_on :get_item, :add_item
+  end
+
+Inject the dependencies in the gem config with the +configure+ wrapper:
+
+  # config/dependencies.rb
+  MyGem.configure do |c|
+    c.get_item = OuterModule::Services::Get
+    c.add_item = OuterModule::Services::Add
+  end
+
+Use the dependencies somewhere inside the code of the gem:
+
+  MyGem.get_item # => OuterModule::Services::Get
+
+=== Hexx::Coercible
+
+Adds the +attr_coerced+ class helper method to the PORO model.
+
+Provide a value object that accepts <tt>0..1</tt> arguments.
+
+  # app/attributes/coercer.rb
+  class Coercer < MultiByte::Chars
+    def self.new(source = nil)
+      return unless source
+    end
+
+    def initialize(source)
+      # ...
+    end
+  end
+
+Extend the model with a +Coercible+ module and declare its attributes
+with the +attr_coerced+ helper.
+
+  # app/models/some_model.rb
+  class SomeModel
+    extend Hexx::Coercible
+
+    attr_coerced :name, type: Coercer
+  end
+
+Both the getter and setter will return the coerced value, provided by
+the +Coercer+ class.
+
+  object = SomeModel.new name: "Ivo"
+  object.name
+  # #<Coercer @wrapped_string="Ivo" >
+
+Be careful when designing a coercer class. Its constructor should accept both
+the raw value ("Ivo") and the coerced one (#<Coercer @wrapped_string = "Ivo">).
+This is needed because the coercer works twofold - it coerces both the
+setter and getter. The getter coercer will take the coerced value.
+
+This feature is added for comparison with +ActiveRecord+ attributes coersion
+where the getter is given with stored raw values (a string etc.)
 
-Service objects decouple business logics from:
+*Note*: The coercer from +hexx+ gem itself won't work for +ActiveRecord+ models.
+Use the +hexx-active_record+ gem instead. The gem extends the +Coercible+ model
+so that the +attr_coerced+ reloads +ActiveRecord+ attributes properly.
 
-* Domain _models_ (entities).
-* Delivery mechanism _controllers_ (such as Rails framework).
+=== Hexx::Service
 
-To follow object oriented architecture Hexx services exploit the
-*Observer* (Listener) pattern via { Wisper }[https://github.com/krisleech/wisper]
-gem.
+Inherit services from the <tt>Hexx::Service</tt> class.
 
-Some examples of this pattern implementation are available at the
-{ wisper gem wiki }[https://github.com/krisleech/wisper/wiki].
+The class implements a set of patterns:
 
-=== Service
+* The {Service object pattern}[http://blog.codeclimate.com/blog/2012/10/17/7-ways-to-decompose-fat-activerecord-models/] used to decouple business logics from both the models and  web delivery mechanism (such as +Rails+).
+* The {Observer pattern}[http://reefpoints.dockyard.com/2013/08/20/design-patterns-observer-pattern.html] to follow the {Tell, don't ask}[http://martinfowler.com/bliki/TellDontAsk.html] design princible.
+  The pattern is implemented with the help of {wisper}[http://www.github.com/krisleech/wisper] gem by Kris Leech.
+* The {Setter-based dependency injection}[http://brandonhilkert.com/blog/a-ruby-refactor-exploring-dependency-injection-options/] to decouple the service from another services it uses.
 
 A typical service object is shown below:
 
+  # app/services/add_item.rb
   require 'hexx'
-
   class AddItem < Hexx::Service
 
-    # whitelists parameters and defines corresponding attributes.
+    # Injects the dependency from the service for getting an item.
+    # Provides default implementation for the dependency, that could be
+    # redefined later (in a test suite etc.).
+    depends_on :get_item, default: GetItem
+
+    # Whitelists parameters and defines corresponding attributes.
+    # For example, the #name attribute is avalable.
     allow_params :name
 
-    # defines some validation using ActiveModel::Validations helpers.
+    # Defines some validation using ActiveModel::Validations helpers.
     validate :name, presence: true
 
-    # runs a service
+    # Runs a service
     def run
-      # re-raises StandardErrors as Hexx::Service::Invalid
-      escape { MyModel.save! }
-    rescue => err # Hexx::Service::Invalid only
+      run!
+    rescue Found
+      # Publishes notification in case the item exists.
+      publish :found, item
+    rescue => err
       publish :error, err.messages
     else
-      publish :success
+      # The notification to be published if the #run! raises nothing.
+      publish :added, item
+    end
+
+    private
+
+    attr_accessor :item
+
+    # Errors to be raised by the #run! method call and captured in a #run.
+    class Found < StandardError; end
+
+    # The sequence of the service steps. Any step can raise error to
+    # be rescued in #run with publishing a corresponding notification.
+    def run!
+      find_item
+      add_item
     end
-  end
 
-Usage of the service (in a Rails controller):
+    def find_item
+      # The method runs another service and listens to its notifications
+      # via private callback methods available to that service only.
+      # The callback names should start from given prefix (:on_item_).
+      run_service get_item, :on_item, name: name
+    end
+
+    # The callback to listen to :found notification of the 'get_item' service.
+    def on_item_found(item, *)
+      @item = item
+      # Adds the Hexx::Message object of type "error" to the +messages+ array.
+      # The :not_found key will be translated in context of current service:
+      # {locale}.activemodule.messages.models.add_item.not_found
+      add_message "error", :not_found
+      fail Found # goes to publishing a result
+    end
+
+    # The callback to listen to :error notification of the 'get_item' service.
+    # that is expected to publish a list of error messages.
+    def on_item_error(*, messages)
+      # The helper raises Hexx::Service::Invalid exception where the messages
+      # are added to. The exception will be rescued by the #run method.
+      on_error(messages)
+    end
+
+    def add_item
+      # The escape re-raises any error as the Hexx::Service::Invalid
+      # with the array of Hexx::Service::Message messages.
+      escape { @item = Item.create! name: name }
+    end
+  end
 
+A typical usage of the service (in a Rails controller):
+  
+  # app/controllers/items_controller.rb
   class ItemsController < ActionController::Base
 
     # Creates an item with given name
@@ -88,87 +222,83 @@ Usage of the service (in a Rails controller):
       render "created", status: 201
     end
 
+    # Responds with 304 (not changed)
+    def on_found(*)
+      render nothing: true, status: 304
+    end
+
     # Publishes an error messages
     def on_error(messages)
       @messages = messages
-      render "error"
+      render "error", status: 422
     end
   end
 
 The controller knows nothing about the action itself. It only needs to
-sort out a request and send it to a corresponding service.
+send the request to a corresponding service and sort out the notifications.
 
-Any controller action does one thing only.
+=== Hexx::Service::Message
 
-* +create+ action sorts out requests.
-* both +on_success+ and +on_created+ listens to services and report their
-  results back to client.
+The messages published by the service has two attributes: +type+ and +text+.
 
-=== Models and Entities
+  message = Hexx::Service::Message.new type: :error, text: "some error message"
+  message.type # => "error"
+  message.text # => "some error message"
 
-The module also defines <tt>Hexx::Models</tt> module to extend domain models
-(entities). This allows coercion of attributes with +attr_coerced+ helper:
+Inside a service use the +add_message+ to add message to the +messages+ array:
 
-  class User
-    extend Hexx::Models
-    attr_coerced  :name, type: ActiveSupport::Multibyte::Chars
-  end
+  add_message "error", "text"
+  messages # => [#<Hexx::Service::Message @type="error", @text="text" >]
 
-  user = User.new name: "Ivan"
-  
-  user.name
-  # => "Ivan"
-  
-  user.name.class
-  # => ActiveSupport::Multibyte::Chars
+=== Hexx::Null
 
-The method redefines both getter and setter and can be used for value
-preparation:
+The class implements the {Null object}[http://robots.thoughtbot.com/rails-refactoring-example-introduce-null-object] pattern. The object:
 
-  class StrippedString < String
-    def initialize(value)
-      super value.strip
-    end
-  end
+* responds like +nil+ to +<=>+, +eq?+, +nil?+, +false?+, +true?+, +to_s+,
+  +to_i+, +to_f+, +to_c+, +to_r+, +to_nil+
+* responds with +self+ to any other method call
 
-  class User
-    extend Hexx::Models
-    attr_coerced :name, type: StrippedString
-  end
+Providing {this problem}[http://devblog.avdi.org/2011/05/30/null-objects-and-falsiness/],  use double bang in logical expressions:
 
-  user = User.name " Ivan  "
-  user.name # => "Ivan"
+  # Though:
+  Hexx::Null && true   # => true
+  
+  # But:
+  !!Hexx::Null && true # => false
 
-== Dependencies
+=== Hexx::Dependable
 
-The module provides methods +depends_on+ and +config+ to create
-dependency injection framework.
+This module is a part of <tt>Hexx::Service</tt> that provides
+setter dependency declaration +depends_on+.
 
-Declare gem dependencies (external classes and modules).
+Extend the class and declare the dependency with optional default
+implementation:
 
-  # lib/my_gem.rb
-  module MyGem
-    extend Hexx::Dependencies
-    depends_on :get_item, :add_item
+  class MyClass
+    extend Hexx::Dependable
+
+    depends_on :another_class, default: AhotherClass
+    depends_on :one_more_class
   end
 
-Inject gem dependencies:
+Now the dependency can be injected afterwards:
 
-  # config/my_gem.rb
-  MyGem.configure do |config|
-    config.get_item = AnotherGem::Services::Get   # as a constant
-    config.add_item = "AnotherGem::Services::Add" # as a name of a constant
-  end
+  object = MyClass
 
-Use them somewhere in a code:
+  # The default implementation
+  object.another_class # => AnotherClass
 
-  MyGem.get_item # => AnotherGem::Services::Get
-  MyGem.add_item # => AnotherGem::Services::Add   # the name is constantized
+  # Inject another implementation
+  object.another_class = NewClass
+  object.another_class # => NewClass
 
-== Relevant Links
+  # Reset it to default
+  object.another_class = nil
+  object.another_class # => AnotherClass
 
-* Matt Wynne's talk {Hexagonal Rails}[http://www.confreaks.com/videos/977-goruco2012-hexagonal-rails]
-* { wisper }[http://www.github.com/krisleech/wisper] gem by Kris Leech.
+  # Implementation is needed
+  object.one_more_class
+  # fails with a NotImplementedError
 
 == License
 

data/Rakefile

@@ -19,6 +19,5 @@ task :check do
   system "coveralls report"
   system "rubocop"
   system "inch --pedantic"
-  system "metric_fu --no-cane --no-churn --no-rails-best-practices " \
-         "--no-hotspots --no-reek"
+  system "metric_fu --no-cane --no-saikuro --no-roodi --no-hotspots --no-stats"
 end

data/lib/hexx.rb

@@ -5,6 +5,7 @@ require "wisper"
 # Loading gem code (the order is essential).
 root = File.expand_path "../hexx", __FILE__
 Dir[
+  "#{ root }/helpers/*.rb",
   "#{ root }/models/**/*.rb",
   "#{ root }/service/**/*.rb",
   "#{ root }/**/*.rb"

data/lib/hexx/{models.rb → coercible.rb}

@@ -10,7 +10,7 @@ module Hexx
   #   require_relative "attributes/string"
   #
   #   class User
-  #     extend Hexx::Models
+  #     extend Hexx::Coercible
   #     attr_coerced :name, type: ActiveSupport::Multibyte::Chars
   #   end
   #
@@ -18,26 +18,24 @@ module Hexx
   #   user = User.new name: "Иоанн"
   #   user.name
   #   # => #<ActiveSupport::Multibyte::Chars @wrapped_string = "Иоанн">
-  module Models
+  module Coercible
 
     private
 
+    # @api hide
+    def self.extended(klass)
+      klass.send :extend, Configurable
+      klass.send :depends_on, :coersion, default: Helpers::Coersion
+    end
+
     # @!method attr_coerced(*names, options)
     # Coerced the attribute(s) with given type.
-    # @example (see Hexx::Models)
+    # @example (see Hexx::Coercible)
     # @param [Array<Symbol, String>] names The list of attributes to be coerced.
     # @param [Hash] options The coersion options.
     # @option options [Class] :type The class for coersion.
     def attr_coerced(*names, type:)
-      names.each { |name| coercer.new(self, name, type).coerce }
-    end
-
-    # @api hide
-    # Applied coercer for attributes.
-    # @note The method is reloaded in the 'hexx-active_record' gem to allow
-    #   coersion of ActiveRecord models' attributes.
-    def coercer
-      @coercer ||= BaseCoercer
+      names.flatten.each { |name| coersion.add self, name, type }
     end
   end
 end

data/lib/hexx/configurable.rb

@@ -0,0 +1,101 @@
+# encoding: utf-8
+
+module Hexx
+
+  # Contains methods to declare and inject module dependencies.
+  #
+  # Allows to provide DJ framework for the gem.
+  #
+  # @example
+  #   # Declare the dependencies for the gem root module
+  #
+  #   # lib/my_gem.rb
+  #   module MyGem
+  #     extend Hexx::Configurable
+  #     self.depends_on :get_item, :add_item
+  #     self.depends_on :delete_item, default: DeleteItem
+  #   end
+  #
+  #   # Inject dependencies (as a constant or its name)
+  #
+  #   # config/my_gem.rb
+  #   MyGem.configure do |config|
+  #     config.get_item = AnotherGem::Services::Get
+  #     config.add_item
+  #   end
+  #
+  #   # Use dependency in the module code (models, services, etc.)
+  #   # When the dependency hasn't been set, fails with +NotImplementedError+
+  #
+  #   MyGem.get_item # => AnotherGem::Services::Get
+  #   MyGem.get_item # => DeleteItem
+  #   MyGem.add_item # fails with a NotImplementedError
+  module Configurable
+
+    # Yields a block and gives it self
+    #
+    # @example
+    #   module MyGem
+    #     extend Hexx::Configurable
+    #   end
+    #
+    #   MyGem.configure do |config|
+    #     c # => MyGem
+    #   end
+    #
+    # @yield The block.
+    # @yieldparam [Hexx::Configurable] +self+.
+    def configure
+      yield(self)
+    end
+
+    # @!method depends_on(*names, options)
+    # Declares a dependency getter and setter.
+    #
+    # @example
+    #   module MyGem
+    #     extend Hexx::Configurable
+    #     self.depends_on :some_class
+    #   end
+    #
+    #   MyGem.some_class = String
+    #   # => "String"
+    #   MyGem.some_class # => String
+    #
+    #   MyGem.some_class = "String"
+    #   # => "String"
+    #   MyGem.some_class # => String
+    #
+    #   MyGem.some_class = :String
+    #   # => "String"
+    #   MyGem.some_class # => String
+    #
+    # @example Dependencies can be declared by a plain list of names
+    #   module MyGem
+    #     extend Hexx::Configurable
+    #     self.depends_on :some_class, "another_class"
+    #   end
+    #
+    # @example Dependencies can be declared by an array of names
+    #   module MyGem
+    #     extend Hexx::Configurable
+    #     self.depends_on %w(some_class another_class)
+    #   end
+    #
+    # @example A dependency can have default implementation
+    #   module MyGem
+    #     extend Hexx::Configurable
+    #     self.depends_on :item, default: Item
+    #   end
+    #
+    # @param [Array<String, Symbol>] names The list of names for dependencies.
+    # @param [Hash] options The list of options for dependency declaration.
+    # @option options [Module, nil] :default (nil) The default implementation
+    #   for the dependency.
+    def depends_on(*names, default: nil)
+      names.flatten.each do |name|
+        Helpers::ModuleDependency.add self, name, default
+      end
+    end
+  end
+end