hexx 2.2.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d010b19ba275b8486d80e503db0486446a407e4e
-  data.tar.gz: e0f93d5c6656747d41f70dea4d7f5f71f11ed5f8
+  metadata.gz: fb67d554082720fe92957b12996f0a313b3b3ae8
+  data.tar.gz: 197971ca631d755c770543cf8393d173bff65ff3
 SHA512:
-  metadata.gz: d76d30cf7bf4d130790c9cae1cf3affee4dcd4d09d2643c098c31b1eb167a8ad86127b50460d1bacdeb8bfbd368a962d649eab3f50beb67ee142b0381bc798fb
-  data.tar.gz: 6b4cff429dd38d0188849e697c89aa25d66365aabbe33ad0026d299906f0335d0172d2f7f2ba82b2927504d72e846efc9c9af3ea4b825b59581f7e1aebf3c087
+  metadata.gz: 2616e0e816e014aba36151690e5d5546ace6adcd2e1ec08bef86191526bf594576359ed0b3eace7ce4380eb629c00d675cd0bb1aef3e1ab5eb6918a6b8e018ef
+  data.tar.gz: b811fd9b51612ea91d71c75b0c87fedfe2146a10f78b4327953390fc7cd430dec07f9475e5d72b7aa5f00660b1309b81a859805fd37c7b8ead676f666e11c3f8

data/.rubocop.yml

@@ -14,6 +14,9 @@ Style/AccessorMethodName:
   Exclude:
     - 'spec/**/*'
 
+Style/AsciiComments:
+  Enabled: false
+
 Style/ClassAndModuleChildren:
   Exclude:
     - 'spec/**/*'

data/README.rdoc

@@ -63,7 +63,7 @@ A typical service object is shown below:
     # runs a service
     def run
       # a wrapper sends :error notification to listeners in case of any exception raised.
-      transaction
+      escape
         MyModel.save! name: name # name is defined by allow_params helper.
         publish :success         # notifies its listeners.
       end

data/Rakefile

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

data/lib/hexx.rb

@@ -1,9 +1,16 @@
+# encoding: utf-8
 require "active_model"
 require "wisper"
 
-# Application files to be loaded.
-def files
-  @files ||= Dir[File.expand_path("../hexx/**/*.rb", __FILE__)]
-end
+# Loading gem code (the order is essential).
+root = File.expand_path "../hexx", __FILE__
+Dir[
+  "#{ root }/models/**/*.rb",
+  "#{ root }/service/**/*.rb",
+  "#{ root }/**/*.rb"
+].each { |f| require f }
 
-files.each { |file| require file }
+# @api show
+# Namespace for the gem.
+module Hexx
+end

data/lib/hexx/models.rb

@@ -1,8 +1,8 @@
-require_relative "models/base_coercer"
+# encoding: utf-8
 
 module Hexx
 
-  # Declares the +.attr_coerced+ private class method.
+  # Declares the +attr_coerced+ private class method.
   #
   # @example
   #
@@ -14,14 +14,28 @@ module Hexx
   #     attr_coerced :name, type: ActiveSupport::Multibyte::Chars
   #   end
   #
+  #   # This will coerce user name with mb chars:
+  #   user = User.new name: "Иоанн"
+  #   user.name
+  #   # => #<ActiveSupport::Multibyte::Chars @wrapped_string = "Иоанн">
   module Models
 
     private
 
+    # @!method attr_coerced(*names, options)
+    # Coerced the attribute(s) with given type.
+    # @example (see Hexx::Models)
+    # @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
     end

data/lib/hexx/models/base_coercer.rb

@@ -1,10 +1,18 @@
 module Hexx
   module Models
 
-    # Coerces PORO attribute's getter and setter with given type.
+    # @api hide
+    # Coerces class attribute getter and setter with given type.
     class BaseCoercer < Struct.new(:klass, :name, :type)
 
       # Coerces class attribute's getter and setter.
+      #
+      # @example
+      #   BaseCoercer.new SomeModel, :name, StrippedString
+      #   BaseCoercer.coerce
+      #
+      #   model = SomeModel.new name: "string"
+      #   model.name.class # => StrippedString
       def coerce
         coerce_setter
         coerce_getter

data/lib/hexx/service.rb

@@ -1,23 +1,271 @@
-# Service modules the +Service+ class depends on.
-def service_modules
-  Dir[File.expand_path("../service/*.rb", __FILE__)]
-end
-
-service_modules.each { |file| require file }
+# encoding: utf-8
 
 module Hexx
 
-  # Base class for service objects.
+  # @abstract
+  # The base class for service objects.
+  #
+  # @example
+  #   require "hexx"
+  #   class GetItem < Hexx::Service
+  #     allow_params :name
+  #     def run
+  #       publish :found, item = Item.where(name: name).first
+  #     end
+  #   end
+  #
+  #   service = GetItem.new name: name
+  #   service.subscribe listener, prefix: :on
+  #   service.run
+  #   # => This will call the listener's method #on_found(item).
   class Service
-    include Messages, Parameters, Transactions, Validations, Callbacks
+    include Wisper::Publisher
+    include ActiveModel::Validations
+    include Parameters
 
-    # Runs the service object.
+    # @!scope class
+    # @!method new(options = {})
+    # Constructs the service object.
+    #
+    # @example
+    #   service = Hexx::Service.new name: name
+    #
+    # @param [Hash] options The options to be assigned to the {#params}.
+    # @return [Hexx::Service] The service object.
+
+    # @!scope class
+    # @!visibility private
+    # @!method allow_params(*params)
+    # Whitelists {#params} and declares a parameter for corresponding keys.
+    #
+    # @example (see Hexx::Service#params)
+    #
+    # @example Defines corresponding readonly attributes.
+    #   class GetItem < Hexx::Service
+    #     allow_params :name
+    #   end
     #
-    # The method must be defined in a specific service class,
-    # inherited from <tt>Hexx::Service</tt>.
+    #   service = GetItem.new name: "Олег", family: "Рюрикович"
+    #   service.name # => "Олег"
+    #
+    # @param [Array<Symbol, String>] params The list of allowed keys.
+
+    # @!scope class
+    # @!method validates(attribute, options)
+    # Adds a standard validation for the attribute.
+    # @note The method is defined in the {ActiveModel::Validations} module.
+
+    # @!scope class
+    # @!method validate(method, options)
+    # Adds a custom validation (calls given method).
+    # @note The method is defined in the {ActiveModel::Validations} module.
+
+    # @!attribute params [r] The list of service object parameters.
+    #   The attribute is assigned via the {.new} method options.
+    #   The keys should be explicitly declared by the {.allow_params} helper.
+    #
+    #   @example Only whitelisted params are being assigned.
+    #     class GetItem < Hexx::Service
+    #       allow_params :name
+    #     end
+    #
+    #     service = GetItem.new name: "Олег", family: "Рюрикович"
+    #     service.params # => { "name" => "Олег" }
+
+    # @!method subscribe(listener, options = {})
+    # Subscribes the listener to service object's notifications.
+    # The <tt>:prefix</tt> sets the prefix to be added to a notification name
+    # to provide a corresponding listener method, that should be called by
+    # the publisher.
     #
+    # @example (see Hexx::Service)
+    # @param [Object] listener The object that should receive notifications from
+    #   the service object.
+    # @param [Hash] options The list of the subscription options.
+    # @option options [Symbol] :prefix The prefix for the listener's callbacks.
+
+    # @abstract
+    # Runs the service object.
+    # @note The method must be reloaded by a specific service class,
+    #   inherited from <tt>Hexx::Service</tt>.
+    # @raise [NotImplementedError] if a child class hasn't redefined the method.
     def run
       fail NotImplementedError.new "#{ self.class.name }#run not implemented."
     end
+
+    # Makes private methods with given prefix public.
+    #
+    # @example Opens private methods.
+    #   def GetItem < Hexx::Service
+    #     private
+    #     def on_success
+    #       publish :success
+    #     end
+    #   end
+    #
+    #   service = GetItem.new
+    #   service.respond_to? :on_success
+    #   # => false
+    #
+    #   service_with_callbacks = service.with_callbacks
+    #   service_with_callbacks.respond_to? :on_success
+    #   # => true
+    #
+    # @return [Hexx::Service::WithCallbacks<Hexx::Service>]
+    #   The decorator that allows access to the service's private methods.
+    def with_callbacks(prefix: nil)
+      WithCallbacks.new(self, prefix: prefix)
+    end
+
+    private
+
+    # The helper runs another service object and subscribes +self+ for the
+    # service object's notifications.
+    #
+    # @example
+    #   class AddItem < Hexx::Service
+    #     allow_params :id
+    #
+    #     # Runs a service for finding an item.
+    #     # Service notifications to be received with a prefix :on_item
+    #     def find_item
+    #       run_service GetItem, :on_item, id: params["id"]
+    #     end
+    #
+    #     private
+    #
+    #     attr_reader :item
+    #
+    #     # Receives GetItem's :found notification
+    #     def on_item_found(item)
+    #       @item = item
+    #       publish :found, item
+    #     end
+    #
+    #     # Receives GetItem's :not_found notification
+    #     def on_item_not_found(*)
+    #       # ... do some stuff here
+    #     end
+    #   end
+    #
+    # @param [Class] service_class The service class to instantiate and run
+    #   a service object.
+    # @param [Symbol] prefix The prefix for callbacks to receive the service
+    #   object's notifications.
+    # @param [Hash] options ({}) The options for the service object initializer.
+    # @raise [TypeError] when the service_class is not a <tt>Hexx::Service</tt>.
+    def run_service(service_class, prefix, options = {})
+      fail TypeError unless service_class.ancestors.include? Hexx::Service
+      service = service_class.new(options)
+      service.subscribe with_callbacks, prefix: prefix
+      service.run
+    end
+
+    # @!method escape
+    #
+    # The method rescues block runtime errors and publishes the :error
+    # notification.
+    #
+    # @example
+    #   class GetItem < Hexx::Service
+    #     def run
+    #       escape do
+    #         errors.add :base, :error
+    #         fail Invalid.new self
+    #       end
+    #     end
+    #   end
+    #
+    #   service = GetItem.new
+    #   service.subscribe listener
+    #   service.run
+    #   # => the listener will be sent the error(messages).
+    #
+    # @yield the block.
+    # @return the value returned by the block.
+    def escape
+      yield
+    rescue Service::Invalid => err
+      publish :error, Message.from(err.service)
+    rescue => err
+      publish :error, [Message.new(type: "error", text: err.message)]
+    end
+
+    # Translates given key in current service's scope.
+    #
+    # @note The method uses I18n.t library method.
+    #
+    # @example Returns a translation if the first argument is a symbol.
+    #   class Test < Hexx::Service
+    #   end
+    #   service = Test.new
+    #   service.t :name
+    #   # => "translation not found: en.activemodel.messages.models.test.name"
+    #
+    # @example Returns the string argument.
+    #   service = Hexx::Service.new
+    #   service.t "name"
+    #   # => "name"
+    #
+    # @param [Symbol, String] text The text to be translated.
+    # @param [Hash] options The translation options.
+    # @return [String] The translation.
+    def t(text, options = {})
+      return text unless text.is_a? Symbol
+      scope = %w(activemodel messages models) << self.class.name.underscore
+      I18n.t text, options.merge(scope: scope)
+    end
+
+    # The array of service messages, added by the {#add_message} helper.
+    #
+    # @example
+    #   class Test < Hexx::Service
+    #     def run
+    #       add_message "info", :ok
+    #       messages
+    #     end
+    #   end
+    #   result = Test.new.run.first
+    #   result.type
+    #   # => "info"
+    #   result.text
+    #   # => "translation not found: en.activemodel.messages.models.test.ok"
+    #
+    # @return [Array<Hexx::Service::Message>] The array of message objects.
+    def messages
+      @messages ||= []
+    end
+
+    # Adds the translated message to the {#messages} array.
+    # @example (see Service#messages)
+    # @param [String] type The type of the message ("error", "info", "success")
+    # @param [String, Symbol] text The text of the message. The symbol will
+    #   be translated using the {#t} method.
+    # @param [Hash] options The translation options.
+    # @return The updated {#messages} array.
+    def add_message(type, text, options = {})
+      messages << Message.new(type: type, text: t(text, options))
+    end
+
+    # Runs validations and fails if the service is invalid.
+    #
+    # @example (see Hexx::Service::Invalid)
+    #
+    # @example Safe usage (recommended) with the {#escape} wrapper.
+    #   service GetItem < Hexx::Service
+    #     allow_params :uuid
+    #     validates :uuid, presence: true
+    #     def run
+    #       escape { validate! }
+    #     end
+    #   end
+    #
+    #   service = GetItem.new
+    #   service.run # => publishes :error notification
+    #
+    # @raise [Hexx::Service::Invalid] when the service object isn't valid.
+    def validate!
+      fail Invalid.new(self) unless valid?
+    end
   end
 end

data/lib/hexx/service/invalid.rb

@@ -3,43 +3,63 @@ require_relative "message"
 module Hexx
   class Service
 
-    # Exception to be raised by invalid services.
+    # The exception to be raised by invalid services.
+    #
+    # @example
+    #   service GetItem < Hexx::Service
+    #     allow_params :uuid
+    #     validates :uuid, presence: true
+    #     def run
+    #       validate!
+    #     end
+    #   end
+    #
+    #   service = GetItem.new
+    #   service.run # => fails with the {Hexx::Service::Invalid}.
     class Invalid < ::RuntimeError
 
-      # An invalid service object with error messages.
+      # @!attribute [r] service
+      # @return [Hexx::Service] The invalid service object.
       attr_reader :service
 
+      # @!scope class
+      # @!method new(service)
       # Initializes the exception.
       #
       # @example
-      #     fail Hexx::Service::Invalid.new(service)
-      #
-      # Params:
-      # +service+:: a Hexx::Service object containing error messages.
+      #   fail Hexx::Service::Invalid.new service
       #
+      # @param  [Hexx::Service] service The invalid service.
+      # @raise  [ArgumentError] if the argument is not a service object.
+      # @return [Hexx::Service::Invalid] The exception.
+
+      # @api hide
       def initialize(service)
         @service = service
         fail ArgumentError unless self.service.is_a? Hexx::Service
       end
 
+      # @!attribute [r] message
       # Returns a default text message for the exception.
       #
       # @example
-      #     error = Hexx::Service::Invalid.new service
-      #     error.message # => "Service invalid: #<Hexx::Service... >"
+      #   error = Hexx::Service::Invalid.new service
+      #   error.message # => "Service invalid: #<Hexx::Service... >"
       #
+      # @return [String] The message.
       def message
         "Service invalid: #{ service.inspect }"
       end
 
-      # Returns a list of <tt>Hexx::Service::Message</tt> messages of
-      # +error+ type.
+      # @!attribute [r] messages
+      # Returns a list of error messages from the service.
       #
       # @example
-      #     error = Hexx::Service::Invalid.new service
-      #     error.messages            # => [#<Hexx::Message... >, ...]
-      #     error.messages.first.type # => "error"
+      #   error = Hexx::Service::Invalid.new service
+      #   error.messages            # => [#<Hexx::Message... >]
+      #   error.messages.first.type # => "error"
       #
+      # @return [Array<Hexx::Service::Message>] The list of messages.
       def messages
         service.errors.values.flatten.map do |text|
           Message.new type: "error", text: text

data/lib/hexx/service/message.rb

@@ -5,18 +5,39 @@ module Hexx
     class Message
       include Comparable
 
-      # A stringified type and a text of the message.
-      attr_reader :type, :text
+      # @!attribute [r] type
+      # The type of the message
+      #
+      # @example
+      #   message = Message.new type: :error, text: "message"
+      #   message.type = "error"
+      #
+      # @return [String] The type of the message.
+      attr_reader :type
 
-      # Initializes the message.
+      # @!attribute [r] text
+      # The text of the message
       #
       # @example
-      #     Message.new type: "success", text: "Object created!"
+      #   message = Message.new type: :error, text: "message"
+      #   message.text = "message"
+      #
+      # @return [String] The text of the message.
+      attr_reader :text
+
+      # @!scope class
+      # @!method new(options)
+      # Constructs the message with type and text.
       #
-      # Params:
-      # <tt>:type</tt>:: string/symbolic message type (:error, :info, :success).
-      # <tt>:text</tt>:: message text.
+      # @example
+      #   Message.new type: "success", text: "Object created."
       #
+      # @param  [Hash] options The list of the message attributes.
+      # @option options [String, Symbol] :type The type of the message.
+      # @option options [String, Symbol] :text The text of the message.
+      # @return [Hexx::Service::Message] The message.
+
+      # @api hide
       def initialize(type:, text:)
         @type, @text = type.to_s, text.to_s
       end
@@ -24,11 +45,11 @@ module Hexx
       # Extracts error messages from ActiveRecord or ActiveModel objects.
       #
       # @example
-      #     Message.from(object) # => [#<Hexx::Service::Message ...>]
-      #
-      # Params:
-      # +object+:: an object to extract messages from.
+      #   Message.from(object)
+      #   # => [#<Hexx::Service::Message ...>]
       #
+      # @param  [ActiveRecord::Base] object The object to extract messages from.
+      # @return [Array<Hexx::Service::Message>] The array of extracted messages.
       def self.from(object)
         object.errors.values.flatten.map do |text|
           new type: "error", text: text
@@ -38,18 +59,17 @@ module Hexx
       # Distinguishes two messages by type and text.
       #
       # @example
-      #     a = Message.new(type: "a", text: "a")
-      #     b = Message.new(type: "a", text: "a")
-      #     c = Message.new(type: "b", text: "a")
-      #     d = Message.new(type: "a", text: "b")
+      #   a = Message.new(type: "a", text: "a")
+      #   b = Message.new(type: "a", text: "a")
+      #   c = Message.new(type: "b", text: "a")
+      #   d = Message.new(type: "a", text: "b")
       #
-      #     a == b # => true
-      #     a == c # => false
-      #     a == d # => false
-      #
-      # Params:
-      # +other+:: other message to distinguish from.
+      #   a == b # => true
+      #   a == c # => false
+      #   a == d # => false
       #
+      # @param [Object] other The object for the comparison.
+      # @return [Boolean] The result of the comparison.
       def ==(other)
         return false unless other.is_a? self.class
         [type, text] == [other.type, other.text]
@@ -58,13 +78,14 @@ module Hexx
       # Compares messages by type and text.
       #
       # @example
-      #     ab = Message.new(type: "a", text: "b")
-      #     ba = Message.new(type: "b", text: "a")
-      #     ab < ba # => true
-      #
-      # Params:
-      # +other+:: other message to compare with.
+      #   ab = Message.new(type: "a", text: "b")
+      #   ba = Message.new(type: "b", text: "a")
+      #   ab < ba # => true
       #
+      # @param [Object] other The object for the comparison.
+      # @return [-1, 0, 1] The result of the comparison if the argument is
+      #   comparable with the message.
+      # @return [nil] if the result is incomparable with the message.
       def <=>(other)
         fail ArgumentError unless other.is_a? self.class
         [type, text] <=> [other.type, other.text]

data/lib/hexx/service/parameters.rb

@@ -1,6 +1,7 @@
 module Hexx
   class Service
 
+    # @api hide
     # Contains methods to declare parameters and set their values.
     module Parameters
       extend ActiveSupport::Concern
@@ -8,7 +9,19 @@ module Hexx
       # Methods to declare and allow services params.
       module ClassMethods
 
-        # A list of allowed params for the service objects.
+        # @!attribute [r] params
+        # The list of allowed instance parameters. The parameters are added
+        # to the list by the {.allow_params} method.
+        #
+        # @example
+        #   class Service
+        #     include Parameters
+        #     allow_params :name
+        #   end
+        #
+        #   Service.params # => "name"
+        #
+        # @return [Array<String>] The list of allowed instance parameters.
         def params
           @params ||= []
         end
@@ -16,26 +29,32 @@ module Hexx
         private
 
         # Sets a list of allowed parameters for the class constructor and
-        # adds corresponding attributes to instance methods.
+        # defines the corresponding instance attributes.
+        #
+        # @example (see Hexx::Service::Parameters.params)
+        # @param [Array<Symbol, String>] keys The list of allowed parameters.
         def allow_params(*keys)
           @params = keys.map(&:to_s)
           attr_accessor(*params)
         end
       end
 
-      # Initializes a service object with a hash of parameters.
+      # @!method new(params)
+      # Constructs a service object with a hash of parameters.
       #
       # @example
-      #   Service.new(hash = {})
+      #   Service.new name: "name"
       #
-      # Params:
-      # +hash+:: a hash of parameters for the service.
-      #
-      def initialize(hash = {})
-        extract_params_from hash
-        params.each { |key, value| public_send "#{ key }=", value }
+      # @param [Hash] params ({}) The parameters of the service object.
+      def initialize(params = {})
+        extract_params_from params
+        @params.each { |key, value| public_send "#{ key }=", value }
       end
 
+      # @!attribute [r] params
+      # The parameters of the service objects. The parameters are set on
+      # the object initialization, then are stringified and whitelisted.
+      # @return [Hash] the service object parameters.
       attr_reader :params
 
       private

data/lib/hexx/service/with_callbacks.rb

@@ -0,0 +1,107 @@
+module Hexx
+  class Service
+
+    # Wraps the service object and grants access to its private methods.
+    #
+    # @example
+    #   class GetItem < Hexx::Service
+    #     private
+    #     attr_reader :on_something, :something
+    #   end
+    #
+    #   service = GetItem.new
+    #   service.respond_to? :on_something # => false
+    #   service.respond_to? :something    # => false
+    #
+    #   wrapper = Hexx::Service::WithCallbacks.new service, prefix: :on
+    #   wrapper.respond_to? :on_something # => true
+    #   wrapper.respond_to? :something    # => false
+    class WithCallbacks
+
+      # @!scope class
+      # @!method new(object, options)
+      # Initializes the decorator of given object.
+      #
+      # @example (see Hexx::Service::WithCallbacks)
+      #
+      # @param [Hexx::Service] object The service object to be decorated.
+      # @param [Hash] options The list of wrapper options.
+      # @option options [Symbol] :prefix (nil) The prefix for private methods
+      #   to be accessible.
+
+      # @api hide
+      def initialize(object, prefix: nil)
+        @object = object
+        @prefix = Regexp.new(prefix ? "^#{ prefix }_" : "")
+      end
+
+      # @api hide
+      # Redefines the +respond_to?+ to allow access to object's methods.
+      #
+      # @example
+      #   service = WithCallbacks(some_service, prefix: :on)
+      #   service.respond_to? :on_something # => true
+      #
+      # @param [Symbol] method The name of the method to check access to.
+      def respond_to?(method, *)
+        object.respond_to?(method) || valid_callback?(method) || super
+      end
+
+      # Compares the object with another service object.
+      # The wrapper is equal to another wrapper for the same object and prefix.
+      #
+      # @example Wrappers are equal if they have the same objects and prefixes
+      #   service = Hexx::Service.new
+      #   a = Hexx::Service::WithCallbacks.new service, prefix: :on
+      #   b = Hexx::Service::WithCallbacks.new service, prefix: :on
+      #   a == b # => true
+      #
+      # @example Wrappers are different if they have different prefixes
+      #   service = Hexx::Service.new
+      #   a = Hexx::Service::WithCallbacks.new service, prefix: :on
+      #   b = Hexx::Service::WithCallbacks.new service, prefix: :when
+      #   a == b # => false
+      #
+      # @example Wrappers are different if they have different objects
+      #   a = Hexx::Service::WithCallbacks.new Hexx::Service.new, prefix: :on
+      #   b = Hexx::Service::WithCallbacks.new Hexx::Service.new, prefix: :on
+      #   a == b # => false
+      #
+      # @example A wrapper differs from any non-wrapper
+      #   service = Hexx::Service.new
+      #   a = Hexx::Service::WithCallbacks.new service, prefix: :on
+      #   a == service # => false
+      #
+      # @param  [Object] other The other object to compare the wrapper to.
+      # @return [Boolean].
+      def ==(other)
+        return false unless other.is_a?(Service) || other.is_a?(self.class)
+        value == other.value
+      end
+
+      protected
+
+      # @api hide
+      # The value to compare wrappers by.
+      # @return [String] value.
+      def value
+        object.inspect + prefix.inspect
+      end
+
+      private
+
+      # @api hide
+      attr_reader :object, :prefix
+
+      # @api hide
+      def method_missing(method, *args, &block)
+        valid_callback?(method) ? object.send(method, *args, &block) : super
+      end
+
+      # @api hide
+      def valid_callback?(method)
+        method.to_s[prefix] && object.respond_to?(method, include_all: true)
+      end
+    end
+  end
+end

data/lib/hexx/version.rb

@@ -2,5 +2,5 @@
 module Hexx
 
   # Current release.
-  VERSION = "2.2.0"
+  VERSION = "3.0.0"
 end

data/spec/hexx/service_spec.rb

@@ -5,8 +5,8 @@ module Hexx
 
     around :each do |example|
       class Test < Service
-        private
         attr_reader :on_something, :something
+        private :on_something, :something
       end
       example.run
       Hexx.send :remove_const, :Test
@@ -77,19 +77,6 @@ module Hexx
       end
     end
 
-    describe "#validate!" do
-
-      it "passes when object is valid" do
-        expect { subject.validate! }.not_to raise_error
-      end
-
-      it "fails when object is invalid" do
-        allow(subject).to receive(:valid?).and_return false
-        expect { subject.validate! }
-          .to raise_error { Service::Invalid.new(subject) }
-      end
-    end
-
     describe "#run" do
 
       it "fails with NotImplementedError" do
@@ -106,7 +93,8 @@ module Hexx
 
     describe "private" do
 
-      subject { Service.new.with_callbacks }
+      let!(:service) { Service.new }
+      subject { service.with_callbacks }
 
       describe ".allow_params" do
 
@@ -121,6 +109,19 @@ module Hexx
         end
       end
 
+      describe "#validate!" do
+
+        it "passes when service is valid" do
+          expect { subject.validate! }.not_to raise_error
+        end
+
+        it "fails when service is invalid" do
+          allow(service).to receive(:valid?).and_return false
+          expect { subject.validate! }
+            .to raise_error { Service::Invalid.new(service) }
+        end
+      end
+
       describe "#t" do
 
         let(:scope)      { %w(activemodel messages models hexx/service) }
@@ -158,40 +159,22 @@ module Hexx
         end
       end
 
-      describe "#transaction" do
+      describe "#escape" do
 
         let(:listener) { double "listener" }
         before { subject.subscribe listener }
 
         it "yields a block" do
           value  = "Hello!"
-          result = subject.transaction { value }
+          result = subject.escape { value }
           expect(result).to eq value
         end
 
-        context "when a service invalid" do
-
-          before do
-            allow_any_instance_of(Service).to receive(:validate!) { fail }
-          end
-
-          it "doesn't yield a block" do
-            value  = "Hello!"
-            result = subject.transaction { value }
-            expect(result).not_to eq value
-          end
-
-          it "publishes an :error" do
-            expect(listener).to receive(:error)
-            subject.transaction
-          end
-        end
-
         context "when a block raises Service::Invalid error" do
 
           before { subject.errors.add :base, :text }
           let(:run) do
-            subject.transaction { fail Service::Invalid.new(subject) }
+            subject.escape { fail Service::Invalid.new(subject) }
           end
 
           it "rescues" do
@@ -206,7 +189,7 @@ module Hexx
 
         context "when a block raises StandardError" do
 
-          let(:run) { subject.transaction { fail "text" } }
+          let(:run) { subject.escape { fail "text" } }
 
           it "rescues" do
             expect { run }.not_to raise_error
@@ -221,6 +204,37 @@ module Hexx
           end
         end
       end
+
+      describe "#run_service" do
+
+        let!(:other) { double "other", subscribe: nil, run: nil }
+        before { allow(Test).to receive(:new).and_return other }
+
+        it "if wrong class given it fails with TypeError" do
+          expect { subject.run_service String, :on_string }
+            .to raise_error { TypeError }
+        end
+
+        it "creates a service object" do
+          options = { "name" => "some name" }
+          expect(Test).to receive(:new).with options
+          subject.run_service Test, :on_service, options
+        end
+
+        it "subscribes self for the service notifications" do
+          expect(other).to receive(:subscribe) do |listener, params|
+            expect(listener).to eq subject.with_callbacks
+            expect(params).to eq(prefix: :on_service)
+          end
+          subject.run_service Test, :on_service
+        end
+
+        it "runs the service object after subscriptions" do
+          expect(other).to receive(:subscribe).ordered
+          expect(other).to receive(:run).ordered
+          subject.run_service Test, :on_service
+        end
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hexx
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Andrew Kozin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-26 00:00:00.000000000 Z
+date: 2014-12-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -122,6 +122,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.23'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.3'
 description: Defines domain service object and model attributes coercion.
 email: andrew.kozin@gmail.com
 executables: []
@@ -138,13 +152,10 @@ files:
 - lib/hexx/models.rb
 - lib/hexx/models/base_coercer.rb
 - lib/hexx/service.rb
-- lib/hexx/service/callbacks.rb
 - lib/hexx/service/invalid.rb
 - lib/hexx/service/message.rb
-- lib/hexx/service/messages.rb
 - lib/hexx/service/parameters.rb
-- lib/hexx/service/transactions.rb
-- lib/hexx/service/validations.rb
+- lib/hexx/service/with_callbacks.rb
 - lib/hexx/version.rb
 - spec/hexx/models_spec.rb
 - spec/hexx/service/invalid_spec.rb

data/lib/hexx/service/callbacks.rb

@@ -1,77 +0,0 @@
-module Hexx
-  class Service
-
-    # Allows to expose private callbacks to notifiers.
-    module Callbacks
-
-      # Grants access to object methods with given prefix.
-      #
-      # @example
-      #     WithCallbacks.new(object, prefix: :on)
-      #
-      # Params:
-      # +object+:: (required) ...a service object to access to.
-      # <tt>prefix:</tt>:: (optional, symbol or string, default: +nil+)
-      #                    ...prefix for private methods to be accessible.
-      #
-      class WithCallbacks
-
-        def initialize(object, prefix: nil)
-          @object = object
-          @prefix = Regexp.new(prefix ? "^#{ prefix }_" : "")
-        end
-
-        # Redefines the +respond_to?+ to allow access to object's methods.
-        #
-        # @example
-        #     service = WithCallbacks(some_service, prefix: :on)
-        #     service.respond_to? :on_something # => true
-        #
-        # Params:
-        # +method+:: a method name to check access to.
-        #
-        def respond_to?(method, *)
-          object.respond_to?(method) || valid_callback?(method) || super
-        end
-
-        private
-
-        def method_missing(method, *args, &block)
-          valid_callback?(method) ? object.send(method, *args, &block) : super
-        end
-
-        def valid_callback?(method)
-          method.to_s[prefix] && object.respond_to?(method, include_all: true)
-        end
-
-        attr_reader :object, :prefix
-      end
-
-      # Makes private methods with given prefix public.
-      #
-      # @example
-      #     class MyService < Hexx::Service
-      #       def call
-      #         # ...
-      #         other_service = OtherService.new
-      #         other_service.subscribe(self.with_callbacks(prefix: :on))
-      #       end
-      #
-      #       private
-      #
-      #       # private, but is made publicly accessible
-      #       def on_success
-      #         # ...
-      #       end
-      #     end
-      #
-      # Params:
-      # <tt>prefix:</tt>:: (optional, symbol or string, default: +nil+)
-      #                    ...prefix of private methods to be accessible.
-      #
-      def with_callbacks(prefix: nil)
-        WithCallbacks.new(self, prefix: prefix)
-      end
-    end
-  end
-end

data/lib/hexx/service/messages.rb

@@ -1,34 +0,0 @@
-require_relative "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

data/lib/hexx/service/transactions.rb

@@ -1,30 +0,0 @@
-require_relative "invalid"
-
-module Hexx
-  class Service
-
-    # Declares the <tt>##transaction</tt> private instance method.
-    module Transactions
-      include Wisper::Publisher
-
-      private
-
-      # Yields the block and publishes :error notification with
-      # error messages in case of any standard exception being raised.
-      def transaction
-        run_and_rescue do
-          validate!
-          yield
-        end
-      end
-
-      def run_and_rescue
-        yield
-      rescue Service::Invalid => err
-        publish :error, Message.from(err.service)
-      rescue => err
-        publish :error, [Message.new(type: "error", text: err.message)]
-      end
-    end
-  end
-end

data/lib/hexx/service/validations.rb

@@ -1,24 +0,0 @@
-require_relative "invalid"
-
-module Hexx
-  class Service
-
-    # Defines methods for active record validation.
-    module Validations
-
-      # Includes the <tt>ActiveModel::Validations</tt> module to the service.
-      #
-      # Params
-      # +klass+:: a class that includes the module.
-      #
-      def self.included(klass)
-        klass.include ActiveModel::Validations
-      end
-
-      # Runs validations and raises <tt>Service::Error</tt> if validations fail.
-      def validate!
-        fail Invalid.new(self) unless valid?
-      end
-    end
-  end
-end