hexx 6.0.3 → 7.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 861d8373aad89fc2f9409572c87782223dd042e4
-  data.tar.gz: 40061fbf81bdf2ff8f57679e328d71c944260a71
+  metadata.gz: 79228f50ba0633896a58f7e29909a69db9084327
+  data.tar.gz: 796d2e839958e2e93faf062bda2678d514d06c6e
 SHA512:
-  metadata.gz: 509e8e294856e4f6509c0d68a188533f33646152b1567114d60943fe84e3ab98ec5d21d55aad33e8a3c38706fd875fef57ff0eb9e37605727e3f0d1d3f081896
-  data.tar.gz: b3f38e5997f22130d83050d1a137110424a4dfee5d7544311f0ec75c9fb8524accb0566bc8d99fe2f780f06443b9f915bab6b845fd55c27888c550873c354015
+  metadata.gz: 2bf8701306d0e731b6ef3789bdbcb4e3e5540985e769694cadc218693eb7516946912467a9489b68758a889143e5962e489f5d67f13d576e5dabe02330916e36
+  data.tar.gz: e202c8efe9ad52e3cff511cfc9934f73e46057d1db467c4979b7afb895e2918a86c63fcfabd40dd7e801e6ff4e1f60c53acea6550bbda965304dae54d70afc2b

data/.rubocop.yml

@@ -55,6 +55,9 @@ Style/SpecialGlobalVars:
 Style/StringLiterals:
   EnforcedStyle: double_quotes
 
+Stype/SingleSpaceBeforeFirstArg:
+  Enabled: false
+
 Style/TrivialAccessors:
   Exclude:
     - 'spec/**/*'

data/README.rdoc

@@ -13,7 +13,7 @@ The base library for domain models.
 
 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::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
@@ -125,7 +125,6 @@ The class implements a set of patterns:
 * 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:
 
@@ -133,11 +132,6 @@ A typical service object is shown below:
   require 'hexx'
   class AddItem < Hexx::Service
 
-    # 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
@@ -162,8 +156,12 @@ A typical service object is shown below:
 
     attr_accessor :item
 
-    # Errors to be raised by the #run! method call and captured in a #run.
-    class Found < StandardError; end
+    # Declares specific exceptions to be raised by the #run! method
+    # and processed by the #run differently.
+    #
+    # All other exceptions will be re-raised as Hexx::Service::Invalid
+    # and processed by publishing the :error notification.
+    raises :Found
 
     # The sequence of the service steps. Any step can raise error to
     # be rescued in #run with publishing a corresponding notification.
@@ -176,7 +174,7 @@ A typical service object is shown below:
       # 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
+      run_service GetItem, :on_item, name: name
     end
 
     # The callback to listen to :found notification of the 'get_item' service.
@@ -199,7 +197,7 @@ A typical service object is shown below:
 
     def add_item
       # The escape re-raises any error as the Hexx::Service::Invalid
-      # with the array of Hexx::Service::Message messages.
+      # with the array of Hexx::Message messages.
       escape { @item = Item.create! name: name }
     end
   end
@@ -237,68 +235,85 @@ A typical usage of the service (in a Rails controller):
 The controller knows nothing about the action itself. It only needs to
 send the request to a corresponding service and sort out the notifications.
 
-=== Hexx::Service::Message
+=== Hexx::Message
 
 The messages published by the service has two attributes: +type+ and +text+.
 
-  message = Hexx::Service::Message.new type: :error, text: "some error message"
+  message = Hexx::Message.new type: :error, text: "some error message"
   message.type # => "error"
   message.text # => "some error message"
 
 Inside a service use the +add_message+ to add message to the +messages+ array:
 
   add_message "error", "text"
-  messages # => [#<Hexx::Service::Message @type="error", @text="text" >]
+  messages # => [#<Hexx::Message @type="error", @text="text" >]
 
-=== Hexx::Null
+=== Hexx::Dependable
 
-The class implements the {Null object}[http://robots.thoughtbot.com/rails-refactoring-example-introduce-null-object] pattern. The object:
+The module provides the +depends_on+ class helper for {setter-based dependency injection}[http://brandonhilkert.com/blog/a-ruby-refactor-exploring-dependency-injection-options/]. It allows decoupling the service from another services it uses.
 
-* responds like +nil+ to <tt><=></tt>, +eq?+, +nil?+, +false?+, +true?+, +to_s+,
-  +to_i+, +to_f+, +to_c+, +to_r+, +to_nil+
-* responds with +self+ to any other method call
+Extend the service class and declare the dependencies with an optional default
+implementation (see example above):
 
-Providing {this problem}[http://devblog.avdi.org/2011/05/30/null-objects-and-falsiness/],  use double negation in logical expressions:
+  class AddItem < Hexx::Service
+    extend Hexx::Dependable
 
-  # Though:
-  Hexx::Null && true   # => true
-  
-  # But:
-  !!Hexx::Null && true # => false
+    depends_on :get_item, default: GetItem
 
-=== Hexx::Dependable
+    # ...
 
-This module is a part of <tt>Hexx::Service</tt> that provides
-setter dependency declaration +depends_on+.
+    def find_item
+      run_service get_item, :on_item, name: name
+    end
+  end
 
-Extend the class and declare the dependency with optional default
-implementation:
+Now the dependency can be injected afterwards:
 
-  class MyClass
-    extend Hexx::Dependable
+  # The default implementation
+  service = AddItem.new
+  service.get_item # => GetItem
 
-    depends_on :another_class, default: AhotherClass
-    depends_on :one_more_class
-  end
+  # Change it to other implementation
+  service.get_item = FindItem
+  service.get_item # => FindItem
 
-Now the dependency can be injected afterwards:
+  # Reset it to default by assigning +nil+
+  service.get_item = nil
+  service.get_item # => GetItem
 
-  object = MyClass
+It is possible to test a service in isolation from its dependencies.
 
-  # The default implementation
-  object.another_class # => AnotherClass
+  # spec/services/my_service_spec.rb
+  describe AddService do
+
+    describe "#run" do
+
+      # Mock a service objects to publish expected notifications
+      let(:object) { Hexx::Service }
+      before { allow(object).to receive(:run) { publish :not_found } }
+
+      # Inject a class dependency
+      before { service.get_item = class_double "Hexx::Service", new: object }
+
+      # ...
+    end
+  end
+
+=== Hexx::Null
+
+The class implements the {Null object}[http://robots.thoughtbot.com/rails-refactoring-example-introduce-null-object] pattern. The object:
 
-  # Inject another implementation
-  object.another_class = NewClass
-  object.another_class # => NewClass
+* responds like +nil+ to <tt><=></tt>, +eq?+, +nil?+, +false?+, +true?+, +to_s+,
+  +to_i+, +to_f+, +to_c+, +to_r+, +to_nil+
+* responds with +self+ to any other method call
 
-  # Reset it to default
-  object.another_class = nil
-  object.another_class # => AnotherClass
+Providing {this problem}[http://devblog.avdi.org/2011/05/30/null-objects-and-falsiness/],  use double negation in logical expressions:
 
-  # Implementation is needed
-  object.one_more_class
-  # fails with a NotImplementedError
+  # Though:
+  Hexx::Null && true   # => true
+  
+  # But:
+  !!Hexx::Null && true # => false
 
 == License
 

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 }/creators/*.rb",
   "#{ root }/helpers/*.rb",
   "#{ root }/models/**/*.rb",
   "#{ root }/service/**/*.rb",

data/lib/hexx/coercible.rb

@@ -35,9 +35,9 @@ module Hexx
     # @api hide
     # The method returns a coercion creator for PORO object only.
     # To be reloaded for ActiveRecord models
-    # @return [Class] attribute coercion (Hexx::Helpers::Coercion by default)
+    # @return [Class] attribute coercion (Hexx::Creators::Coercion by default)
     def coercion
-      Hexx::Helpers::Coercion
+      Hexx::Creators::Coercion
     end
   end
 end

data/lib/hexx/configurable.rb

@@ -94,7 +94,7 @@ module Hexx
     #   for the dependency.
     def depends_on(*names, default: nil)
       names.flatten.each do |name|
-        Helpers::ModuleDependency.add self, name, default
+        Creators::ModuleDependency.add self, name, default
       end
     end
   end

data/lib/hexx/{helpers → creators}/base.rb

@@ -3,13 +3,9 @@
 module Hexx
 
   # @api hide
-  # The module contains helper classes and modules.
-  #
-  # All the helpers injects some code into corresponding class or module.
-  #
-  # The content of the module is not a part of API, but its implementation
-  # details.
-  module Helpers
+  # The module contains classes that adds specific attributes
+  # to given classes or modules.
+  module Creators
 
     # @api hide
     # @abstract
@@ -25,8 +21,8 @@ module Hexx
       #
       # @param  [Module] target The class or module to inject the attribute to.
       # @param  [String, Symbol] name The name of the attribute.
-      # @raise  (see Hexx::Helpers::Base#validate)
-      # @return [Hexx::Helpers::Base] the base class object.
+      # @raise  (see Hexx::Creators::Base#validate)
+      # @return [Hexx::Creators::Base] the base class object.
       def self.add(*args)
         new(*args).validate.add_getter.add_setter
       end
@@ -44,10 +40,10 @@ module Hexx
       # @api hide
       # Validates parameters of the dependency declaration.
       #
-      # @raise  (see Hexx::Helpers::Base#check_target)
-      # @raise  (see Hexx::Helpers::Base#check_name_type)
-      # @raise  (see Hexx::Helpers::Base#check_name_value)
-      # @return [Hexx::Helpers::Base] +self+
+      # @raise  (see Hexx::Creators::Base#check_target)
+      # @raise  (see Hexx::Creators::Base#check_name_type)
+      # @raise  (see Hexx::Creators::Base#check_name_value)
+      # @return [Hexx::Creators::Base] +self+
       def validate
         check_target
         check_name_type
@@ -57,7 +53,7 @@ module Hexx
 
       # @api hide
       # Adds the parameter getter to the +target+ instance
-      # @return [Hexx::Helpers::Base] +self+
+      # @return [Hexx::Creators::Base] +self+
       def add_getter
         target.class_eval getter
         self
@@ -65,7 +61,7 @@ module Hexx
 
       # @api hide
       # Adds the parameter setter to the +target+ instance
-      # @return [Hexx::Helpers::Base] +self+
+      # @return [Hexx::Creators::Base] +self+
       def add_setter
         target.class_eval setter
         self

data/lib/hexx/{helpers → creators}/coercion.rb

@@ -2,7 +2,7 @@
 require_relative "base"
 
 module Hexx
-  module Helpers
+  module Creators
 
     # @api hide
     # Coerces class attribute getter and setter with given type.
@@ -22,11 +22,11 @@ module Hexx
       # Reloads the Base class initializer by adding the type of the attribute
       # to coerce with.
       #
-      # @example (see Hexx::Helpers::Coercion)
-      # @param  (see Hexx::Helpers::Base.add)
+      # @example (see Hexx::Creators::Coercion)
+      # @param  (see Hexx::Creators::Base.add)
       # @param  [Module] type The type of the attribute.
-      # @raise  (see Hexx::Helpers::Coercion#validate)
-      # @return [Hexx::Helpers::Coercion] the coercion object.
+      # @raise  (see Hexx::Creators::Coercion#validate)
+      # @return [Hexx::Creators::Coercion] the coercion object.
       def initialize(target, name, type)
         super target, name
         @type = type
@@ -43,9 +43,9 @@ module Hexx
       # Adds validation of the coercion type to the
       # {Hexx::Helper::Base#validate}.
       #
-      # @raise  (see Hexx::Helpers::Base.validate)
-      # @raise  (see Hexx::Helpers::Coercion#check_type)
-      # @return [Hexx::Helpers::Coercion] +self+
+      # @raise  (see Hexx::Creators::Base.validate)
+      # @raise  (see Hexx::Creators::Coercion#check_type)
+      # @return [Hexx::Creators::Coercion] +self+
       def validate
         check_type
         super

data/lib/hexx/{helpers → creators}/dependency.rb

@@ -2,7 +2,7 @@
 require_relative "base"
 
 module Hexx
-  module Helpers
+  module Creators
 
     # @api hide
     # @abstract
@@ -15,10 +15,10 @@ module Hexx
       # Reloads the Base class initializer by adding the default implementation
       # for the dependency.
       #
-      # @param  (see Hexx::Helpers::Base)
+      # @param  (see Hexx::Creators::Base)
       # @param  [Module] default The default implementation for the dependency.
-      # @raise  (see Hexx::Helpers::Dependency#validate)
-      # @return [Hexx::Helpers::Dependency] the dependency object.
+      # @raise  (see Hexx::Creators::Dependency#validate)
+      # @return [Hexx::Creators::Dependency] the dependency object.
       def initialize(target, name, default)
         super target, name
         @default = default
@@ -35,9 +35,9 @@ module Hexx
       # Adds validation of the dependency default implementation to the
       # {Hexx::Helper::Base#validate}.
       #
-      # @raise  (see Hexx::Helpers::Base#validate)
-      # @raise  (see Hexx::Helpers::Dependency#check_default)
-      # @return [Hexx::Helpers::Dependency] +self+
+      # @raise  (see Hexx::Creators::Base#validate)
+      # @raise  (see Hexx::Creators::Dependency#check_default)
+      # @return [Hexx::Creators::Dependency] +self+
       def validate
         check_default
         super
@@ -64,7 +64,7 @@ module Hexx
              @#{ name } = value;
              #{ name };
            else;
-             fail TypeError.new \"DI: value.inspect is not a module\";
+             fail TypeError.new \"DI: \#{ value.inspect } is not a module\";
            end;
          end"
       end

data/lib/hexx/{helpers → creators}/module_dependency.rb

@@ -2,7 +2,7 @@
 require_relative "dependency"
 
 module Hexx
-  module Helpers
+  module Creators
 
     # @api hide
     # Module dependency constructor.
@@ -24,7 +24,7 @@ module Hexx
 
       # @api hide
       # Adds the dependency to given module
-      # @example (see Hexx::Helpers::ModuleDependency)
+      # @example (see Hexx::Creators::ModuleDependency)
       # @param [Module] target The module to declare the dependency of.
       # @param [String, Symbol] name The name of the dependency.
       # @param [Module] default The default implementation of the dependency.

data/lib/hexx/{helpers → creators}/parameter.rb

@@ -2,7 +2,7 @@
 require_relative "base"
 
 module Hexx
-  module Helpers
+  module Creators
 
     # @api hide
     # Adds setter and getter for the instance parameter.

data/lib/hexx/dependable.rb

@@ -45,7 +45,7 @@ module Hexx
     # @option  options [String, Symbol, Class] :default (nil) Optional default
     #   implementation for the dependency.
     def depends_on(name, default: nil)
-      Helpers::Dependency.add self, name, default
+      Creators::Dependency.add self, name, default
     end
   end
 end

data/lib/hexx/helpers/exceptions.rb

@@ -0,0 +1,53 @@
+# encoding: utf-8
+require_relative "messages"
+
+module Hexx
+  module Helpers
+
+    # @api hide
+    # The module declares instance helper methods to provide validations
+    module Exceptions
+      extend ActiveSupport::Concern
+      include ActiveModel::Validations
+      include Messages
+
+      # @api hide
+      # Class helper methods
+      module ClassMethods
+
+        def raises(*names)
+          fail ArgumentError if (types = names.flatten.map(&:to_s)) == []
+          types.each { |type| add_exception(type) }
+        end
+
+        private
+
+        def add_exception(type)
+          check type
+          class_eval "class #{ type } < StandardError; end"
+        end
+
+        def check(type)
+          return if type[/([A-Z][a-z]+)+/]
+          fail TypeError.new(
+            %(Wrong exception name "#{ type }". Use words in camel-case only.)
+          )
+        end
+      end
+
+      def on_error(messages)
+        messages.map(&:text).each { |text| errors.add :base, text }
+        fail Hexx::ServiceInvalid.new(self)
+      end
+
+      def escape
+        yield
+      rescue Hexx::ServiceInvalid => err
+        raise err
+      rescue => err
+        errors.add :base, err.message
+        raise Hexx::ServiceInvalid.new(self)
+      end
+    end
+  end
+end