service_objects 0.1.0 → 1.0.0

data/Rakefile

@@ -9,7 +9,7 @@ end
 # Loads bundler tasks
 Bundler::GemHelper.install_tasks
 
-# Loads the Hexx::Suit and its tasks
+# Loads the Hexx::RSpec and its tasks
 begin
   require "hexx-suit"
   Hexx::Suit.install_tasks
@@ -18,5 +18,5 @@ rescue LoadError
   Hexx::RSpec.install_tasks
 end
 
-# Sets the Hexx::RSpec task by default
-task default: :test
+# Sets the Hexx::RSpec :test task to default
+task default: "test:coverage:run"

data/config/metrics/churn.yml

@@ -2,5 +2,5 @@
 ignore_files:
 - spec
 - config
-minimum_churn_count: 2
+minimum_churn_count: 0
 start_date: "1 year ago"

data/config/metrics/flay.yml

@@ -1,2 +1,2 @@
 ---
-minimum_score: 8
+minimum_score: 5

data/config/metrics/metric_fu.yml

@@ -1,6 +1,7 @@
 ---
 folders: # The list of folders to be used by any metric.
 - lib
+- app
 metrics: # The list of allowed metrics. The other metrics are disabled.
 - cane
 - churn

data/config/metrics/rubocop.yml

@@ -3,6 +3,10 @@
 # output: "tmp/rubocop"
 # format: "html"
 
+AllCops:
+  Exclude:
+    - '**/db/schema.rb'
+
 Lint/HandleExceptions:
   Exclude:
     - '**/*_spec.rb'
@@ -46,10 +50,6 @@ Style/FileName:
 Style/RaiseArgs:
   EnforcedStyle: compact
 
-Style/RescueModifier:
-  Exclude:
-    - '**/*_spec.rb'
-
 Style/SingleLineMethods:
   Exclude:
     - '**/*_spec.rb'

data/config/metrics/simplecov.yml

@@ -3,4 +3,4 @@ output: tmp/coverage
 filters: # The list of paths to be excluded from coverage checkup
 - "spec/"
 - "config/"
-groups: []
+groups: []

data/lib/service_objects.rb

@@ -1,14 +1,11 @@
 # encoding: utf-8
 
-# The namespace for the 'service_objects' gem code
-module ServiceObjects
+require_relative "service_objects/version"
+require_relative "service_objects/message"
+require_relative "service_objects/listener"
+require_relative "service_objects/base"
 
-  require_relative "service_objects/version"
-  require_relative "service_objects/null"
-  require_relative "service_objects/utils/normal_hash"
-  require_relative "service_objects/listener"
-  require_relative "service_objects/message"
-  require_relative "service_objects/invalid"
-  require_relative "service_objects/base"
+# Namespace for the code of the 'service_objects' gem
+module ServiceObjects
 
 end # module ServiceObjects

data/lib/service_objects/base.rb

@@ -1,36 +1,209 @@
 # encoding: utf-8
+
+require "attestor"
+require "attr_coerced"
+require "virtus"
 require "wisper"
 
 module ServiceObjects
 
-  require_relative "helpers"
-
   # Base class for service objects
   #
   # @example
-  #   AddItem = Class.new(ServiceObjects::Base)
+  #   class ChangeFoo < ServiceObjects::Base
+  #
+  #     # Attributes definition
+  #     attribute    :id,   Integer
+  #     attribute    :name
+  #     attr_coerced :name, String
+  #
+  #     # Object validation rules
+  #     validate { invalid :blank_id   unless id }
+  #     validate { invalid :blank_name unless name }
+  #
+  #     # Injectable dependencies
+  #     dependency :get_foo, default: GetFoo
+  #
+  #     private
+  #
+  #     # The main algorithm
+  #     def run!
+  #       validate
+  #       get_foo
+  #       change_foo
+  #     end
+  #
+  #     attr_accessor :foo
   #
-  # @see http://www.rubydoc.info/github/krisleech/wisper
-  #   'wisper' gem by Kris Leech
-  # @see http://apidock.com/rails/v4.1.8/ActiveModel/Validations
-  #   ActiveModel::Validations
+  #     def get_foo
+  #       run_service get_foo.new(id: id), Listener.new(self)
+  #     end
+  #
+  #     def change_foo
+  #       foo.save! name: name
+  #       publish :changed, foo, message(:success, :changed, name: name)
+  #     rescue => error
+  #       publish :error, message(:error, error.message)
+  #     end
+  #
+  #     class Listener < ServiceObjects::Listener
+  #       def on_found(foo, *)
+  #         self.foo = foo
+  #       end
+  #
+  #       def otherwise
+  #         publish :not_found, message(:error, :not_found, id: id)
+  #       end
+  #     end
+  #   end
+  #
+  # @see https://github.com/solnic/virtus
+  #   Virtus API
+  # @see http://www.rubydoc.info/gems/wisper
+  #   Wisper::Publisher API
+  # @see http://www.rubydoc.info/gems/attestor
+  #   Attestor API
+  # @see http://www.rubydoc.info/gems/attr_coerced
+  #   AttrCorerced API
   class Base
 
-    extend Helpers::Dependable
-    extend Helpers::Parameterized
-
-    include Helpers::Exceptions
-    include Helpers::Validations
+    # @!parse include Virtus::Model::Core
+    __send__ :include, Virtus.model
+    include AttrCoerced
+    include Attestor::Validations
     include Wisper::Publisher
-    # @!parse include ServiceObjects::Helpers::Parameters
-    # @!parse include ServiceObjects::Helpers::Messages
-    # @!parse include ActiveModel::Validations
 
-    # @abstract
-    # Runs service object
+    # Declares the dependency from another class
+    #
+    # @param  [#to_sym] name
+    # @option [Class] :default
+    #
+    # @return [undefined]
+    def self.dependency(name, default: nil)
+      attr_accessor(name)
+      return unless default
+      define_method(name) { instance_eval "@#{ name } ||= #{ default }" }
+    end
+
+    # @!method subscribe(listener, prefix: nil)
+    # Subscribes a listener for the service object's notifications
+    #
+    # @param  [Object] listener
+    # @option [#to_sym, nil] :prefix
+    #
+    # @return [undefined]
+    #
+    # @see https://github.com/krisleech/wisper 'wisper' gem API
+
+    # Runs the service by calling {#run!} and catching its :published throws
+    #
+    # @raise [NotImplementedError] if {#run!} method not implemented yet
     #
     # @return [undefined]
     def run
+      catch(:published) { run! }
+    end
+
+    # Validates the object in given context
+    #
+    # Publishes error if validation fails
+    #
+    # @param [#to_sym] context
+    #
+    # @return [undefined]
+    def validate(context)
+      validate!(context)
+    rescue Attestor::InvalidError => error
+      publish :error, error.messages.map { |text| Message.new :error, text }
+    end
+
+    # Runs the service and receives its notifications to listener
+    #
+    # @param [ServiceObjects::Base] service
+    # @param [ServiceObjects::Listener] listener
+    #
+    # @return [undefined]
+    def run_service(service, listener)
+      service.subscribe listener, prefix: :on
+      service.run
+      listener.finalize
+    end
+
+    # @!method message(type, key, options)
+    # Creates the message of given type
+    #
+    # @overload message(type, key, options)
+    #   Translates the symbolic key
+    #
+    #   @example
+    #     # config/locales/en.yml
+    #     en:
+    #       service_objects:
+    #         get_foo:
+    #           info:
+    #             found: "Item with id %{id} has been found"
+    #
+    #   @example
+    #     result = GetFoo.new.message(:info, :found, id: 1)
+    #
+    #     result.class # => ServiceObjects::Message
+    #     result.type  # => :info
+    #     result.text  # => "Item with id 1 has been found"
+    #
+    #   @param [Symbol] type
+    #   @param [Symbol] key
+    #   @param [Hash] options
+    #
+    #   @return [ServiceObjects::Message]
+    #
+    # @overload message(type, key)
+    #   Stringifies non-symbolic key
+    #
+    #   @example
+    #     result = GetFoo.new.message(:info, 1)
+    #
+    #     result.class # => ServiceObjects::Message
+    #     result.type  # => :info
+    #     result.text  # => "1"
+    #
+    #   @param [Symbol] type
+    #   @param [#to_s] key
+    #
+    #   @return [ServiceObjects::Message]
+    def message(type, *args)
+      Message.new type, translate(type, *args)
+    end
+
+    # @!method publish(notification, *args)
+    # Notifies subscribers and then throws :published
+    #
+    # @param [#to_sym] notification
+    # @param [Array] args
+    #
+    # @raise [UncaughtThrowError] :published
+    #
+    # @return [undefined]
+    #
+    # @see https://github.com/krisleech/wisper 'wisper' gem API
+    def publish(*)
+      super
+      throw :published
+    end
+
+    private
+
+    def run!
+      fail NotImplementedError.new "#{ self.class }#run! not implemented"
+    end
+
+    def __class_path__
+      @__class_path__ ||= self.class.name.to_const_path.to_sym
+    end
+
+    def translate(type, message, **options)
+      return message unless message.instance_of? Symbol
+      scope = [:service_objects, __class_path__, type]
+      I18n.t message, options.merge(scope: scope)
     end
 
   end # class Base

data/lib/service_objects/listener.rb

@@ -1,110 +1,56 @@
 # encoding: utf-8
 
+require "chronicles"
+
 module ServiceObjects
 
-  # The base class for service listeners
-  #
-  # @example (see #new)
-  #
-  # @example (see #finalize)
-  #
-  # @api public
+  # Describes a decorator with callbacks to receive notifications from services
   class Listener
+    include Chronicles
 
     # @!scope class
     # @!method new(object)
-    # Listener object constructor
-    #
-    # Decorates given object by adding methods to be called by service objects
-    #
-    # @example Decorates an object
-    #   object = Object.new
-    #
-    #   listener = ServiceObjects::Listener.new object
-    #   listener.send :object
-    #   # => object
+    # Creates the listener decorator for given object
     #
     # @param [Object] object
     #
     # @return [ServiceObjects::Listener]
-    #
-    # @api public
+
+    # @private
     def initialize(object)
-      @object = object
+      @__getobj__ = object
+      start_chronicles except: %i(finalize __getobj__)
     end
 
-    # The method called by {#finalize} when no other method has been checked
+    # @abstract
     #
-    # @return [undefined]
+    # The method to be called by {#finalize} when no own methods has been called
     #
-    # @abstract
+    # @return [undefined]
     def otherwise
     end
 
-    # Calls {#otherwise} in case no existing method has been checked
-    #
-    # @example Calls {#otherwise} in case no method has been checked
-    #   class MyListener < ServiceObjects::Listener
-    #     def on_success
-    #       "success"
-    #     end
-    #
-    #     def otherwise
-    #       "nothing"
-    #     end
-    #   end
+    # Calls {#otherwise} when no own methods has been called
     #
-    #   listener = MyListener.new
-    #   listener.finalize
-    #   # => "nothing"
+    # Clears chronicles.
     #
-    # @example Calls {#otherwise} in case an undefined method has been checked
-    #
-    #   listener = MyListener.new
-    #   listener.respond_to? :on_error
-    #   # => false
-    #
-    #   listener.finalize
-    #   # => "nothing"
-    #
-    # @example Skips {#otherwise} in case a defined method has been checked
-    #
-    #   listener = MyListener.new
-    #   listener.respond_to? :on_success
-    #   # => true
-    #
-    #   listener.finalize
-    #   # => nil
-    #
-    # @return [self]
+    # @return [undefined]
     def finalize
-      otherwise unless @notified
-
-      self
-    end
-
-    # Checks whether the method is defined
-    #
-    # Remembers the fact that any defined method has been checked
-    #
-    # @return [Boolean]
-    #
-    # @api private
-    def respond_to?(*)
-      super ? (@notified = true) : false
+      otherwise unless chronicles.empty?
+      chronicles.clear
     end
 
     # @private
     def respond_to_missing?(*args)
-      object.respond_to?(*args)
+      __getobj__.respond_to?(*args)
     end
 
     private
 
-    attr_reader :object
+    attr_reader :__getobj__
 
-    def method_missing(*args, &block)
-      object.send(*args, &block)
+    def method_missing(*args)
+      __getobj__.__send__(*args)
     end
 
   end # class Listener

data/lib/service_objects/message.rb

@@ -1,116 +1,35 @@
 # encoding: utf-8
-require "json"
 
 module ServiceObjects
 
-  # Describes messages published by service objects
+  # Describes messages to be returned by service objects
   class Message
-    include Comparable
-
-    # @!attribute [r] type
-    # The type of the message
-    #
-    # @return [String]
-    attr_reader :type
-
-    # @!attribute [r] text
-    # The text of the message
-    #
-    # @return [String]
-    attr_reader :text
-
-    # @!attribute [r] priority
-    # The priority level for the message
-    #
-    # If priority hasn't been set on initialization, sets it to -1.0 for errors,
-    # or 0.0 otherwise.
-    #
-    # @return [Float]
-    def priority
-      return @custom_priority.to_f if @custom_priority
-      type == "error" ? -1.0 : 0.0
-    end
 
     # @!scope class
-    # @!method new(type:, text:, priority:)
-    # Constructs and freezes the message object
-    #
-    # @example
-    #   Message.new type: "info", text: "foo", priority: 3
+    # @!method new(type, text)
+    # Creates the immutable message with type and text
     #
-    # @param [#to_s] type
+    # @param [#to_sym] type
     # @param [#to_s] text
-    # @param [#to_f] priority
-    #   optional custom priority of the message (the less the higher)
     #
     # @return [ServiceObjects::Message]
-    #   the frozen message object
-    def initialize(type:, text:, priority: nil)
-      @type = type.to_s.freeze
+
+    # @private
+    def initialize(type, text)
+      @type = type.to_sym
       @text = text.to_s.freeze
-      @custom_priority = priority
       freeze
     end
 
-    # Checks equality of the message to the other object
-    #
-    # @param [Object] other
-    #
-    # @return [true]
-    #   if messages has the same attributes
-    # @return [false]
-    #   if the other object is not a message or has different argument(s)
-    def ==(other)
-      (self <=> other) == 0
-    end
-
-    # Compares the message with the other object
-    #
-    # @param [Object] other
-    #
-    # @return [-1, 0, 1]
-    #   if the argument is a message
-    # @return [nil]
-    #   if the other object is not a message
-    def <=>(other)
-      return unless other.is_a? self.class
-      [:priority, :type, :text]
-        .map { |key| __compare_to__ other, by: key }
-        .detect { |value| value } || 0
-    end
-
-    # Converts the message object to hash
-    #
-    # @return [Hash]
-    def to_h
-      { type: type, text: text }
-    end
-
-    # Converts the message object to json
-    #
-    # @return [String]
-    def to_json
-      to_h.to_json
-    end
-
-    # A human-readable representation of the message
-    #
+    # @!attribute [r] text
+    # The text of the message
     # @return [String]
-    def inspect
-      %W(
-        #<ServiceObjects::Message:#{ object_id }
-        type=\"#{ type }\"
-        text=\"#{ text }\"
-        priority=#{ priority }>
-      ).join(" ")
-    end
-
-    private
+    attr_reader :text
 
-    def __compare_to__(other, by:)
-      value = (send(by) <=> other.send(by))
-      value == 0 ? nil : value
-    end
+    # @!attribute [r] type
+    # The type of the message
+    # @return [Symbol]
+    attr_reader :type
 
   end # class Message