service_objects 0.0.1

data/lib/service_objects/invalid.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+
+module ServiceObjects
+
+  # The exception to be risen by invalid services
+  #
+  # @example
+  #   object = ServiceObjects::Base.new
+  #   fail ServiceObjects::Invalid.new object
+  class Invalid < ::RuntimeError
+
+    # @!scope class
+    # @!method new(object)
+    #
+    # Constructs the exception for given service object
+    #
+    # @example (see ServiceObjects::Invalid)
+    #
+    # @param  [#messages] object
+    #
+    # @return [ServiceObjects::Invalid]
+    def initialize(object)
+      @object = object
+      validate
+    end
+
+    # @!attribute [r] object
+    # Invalid service object
+    #
+    # @return [#messages]
+    attr_reader :object
+
+    # The array of messages from the invalid {#object}
+    #
+    # @return [Array<ServiceObjects::Message>]
+    def messages
+      Array(object.messages).flatten
+    end
+
+    private
+
+    # Checks if the {#object} respond to {#messages}
+    #
+    # @raise [TypeError]
+    #   when the validation fails
+    #
+    # @return [undefined]
+    def validate
+      return if object.respond_to? :messages
+      fail TypeError.new "#{ object.inspect } doesn't respond to #messages"
+    end
+
+  end # class Invalid
+
+end # module ServiceObjects

data/lib/service_objects/listener.rb

@@ -0,0 +1,97 @@
+# encoding: utf-8
+
+module ServiceObjects
+
+  # The base class for service listeners
+  #
+  # @example (see #new)
+  #
+  # @example (see #finalize)
+  #
+  # @api public
+  class Listener < SimpleDelegator
+
+    # @!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 :__getobj__
+    #   # => object
+    #
+    # @param [Object] object
+    #
+    # @return [ServiceObjects::Listener]
+    #
+    # @api public
+
+    # The method called by {#finalize} when no other method has been checked
+    #
+    # @return [undefined]
+    #
+    # @abstract
+    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
+    #
+    #   listener = MyListener.new
+    #   listener.finalize
+    #   # => "nothing"
+    #
+    # @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]
+    def finalize
+      otherwise unless @notified
+
+      self
+    end
+
+    # Checks whether the method is defined
+    #
+    # Remembers the fact that any defined method has been checked
+    #
+    # @example
+    #   respond_to? :finalize, false # => true
+    #
+    # @return [Boolean]
+    def respond_to?(*)
+      super ? (@notified = true) : false
+    end
+
+  end # class Listener
+
+end # module ServiceObjects

data/lib/service_objects/message.rb

@@ -0,0 +1,117 @@
+# encoding: utf-8
+require "json"
+
+module ServiceObjects
+
+  # Describes messages published 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
+    #
+    # @param [#to_s] 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
+      @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
+    #
+    # @return [String]
+    def inspect
+      %W(
+        #<ServiceObjects::Message:#{ object_id }
+        type=\"#{ type }\"
+        text=\"#{ text }\"
+        priority=#{ priority }>
+      ).join(" ")
+    end
+
+    private
+
+    def __compare_to__(other, by:)
+      value = (send(by) <=> other.send(by))
+      value == 0 ? nil : value
+    end
+
+  end # class Message
+
+end # module ServiceObjects

data/lib/service_objects/null.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+require "naught"
+
+module ServiceObjects #:nodoc:
+
+  # Implements Null Object pattern
+  #
+  # @note
+  #   The constant is a singleton black hole object that returns
+  #   itself to any method call
+  #
+  # @example
+  #   ServiceObjects::NULL.respond_to? :arbitrary_method
+  #   # => true
+  #
+  #   ServiceObjects::NULL.arbitrary_method
+  #   # => ServiceObjects::NULL
+  #
+  # @see https://github.com/avdi/naught
+  #   documentation for the 'naught' gem by Avdi Grimm
+  NULL = Naught.build do |config|
+    config.black_hole
+    config.singleton
+  end.instance
+
+end # module ServiceObjects

data/lib/service_objects/utils/normal_hash.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+
+module ServiceObjects
+
+  # Utilitites for ServiceObjects module
+  module Utils
+
+    # Constructor of hash with keys, symbolized at any level
+    #
+    # @example
+    #   NormalHash.from { "foo" => "bar", "bar" => { "baz", "bar" => "baz" } }
+    #   # => { foo: "baz", bar: { "baz", bar: "baz" } }
+    #
+    # @api private
+    module NormalHash
+
+      # Recursively symbolizes keys of hash at any level
+      #
+      # @param [Hash] hash
+      #
+      # @return [Hash]
+      def self.from(hash)
+        return {} unless hash.is_a? Hash
+
+        hash.inject({}) do |out, (key, val)|
+          out.merge(key.to_sym => (val.is_a?(Hash) ? from(val) : val))
+        end
+      end
+
+    end # class NormalHash
+
+  end # module Utils
+
+end # module ServiceObjects

data/lib/service_objects/version.rb

@@ -0,0 +1,9 @@
+# encoding: utf-8
+
+module ServiceObjects
+
+  # The semantic version of the module.
+  # @see http://semver.org/ Semantic versioning 2.0
+  VERSION = "0.0.1".freeze
+
+end # module ServiceObjects

data/lib/service_objects.rb

@@ -0,0 +1,12 @@
+# encoding: utf-8
+require "service_objects/null"
+require "service_objects/utils/normal_hash"
+require "service_objects/listener"
+require "service_objects/message"
+require "service_objects/invalid"
+require "service_objects/base"
+
+# The namespace for the 'service_objects' gem code
+module ServiceObjects
+
+end # module ServiceObjects

data/service_objects.gemspec

@@ -0,0 +1,28 @@
+$:.push File.expand_path("../lib", __FILE__)
+require "service_objects/version"
+
+Gem::Specification.new do |s|
+  s.name        = "service_objects"
+  s.version     = ServiceObjects::VERSION.dup
+  s.author      = "Andrew Kozin"
+  s.email       = "andrew.kozin@gmail.com"
+  s.homepage    = "https://github.com/nepalez/service_objects"
+  s.summary     = "Service objects (interactors)."
+  s.description = "Base class for objects, that implements" \
+                  " both the Interactor and Observer design patterns."
+  s.license     = "MIT"
+  s.platform    = Gem::Platform::RUBY
+  s.required_ruby_version = "~> 2.1"
+
+  s.require_paths    = ["lib"]
+  s.files            = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  s.test_files       = Dir["spec/**/*.rb"]
+  s.extra_rdoc_files = Dir["README.md", "LICENSE", "config/metrics/STYLEGUIDE"]
+
+  s.add_runtime_dependency "activemodel", "~> 4.1"
+  s.add_runtime_dependency "extlib", "~> 0.9"
+  s.add_runtime_dependency "naught", "~> 1.0"
+  s.add_runtime_dependency "wisper", "~> 1.6"
+
+  s.add_development_dependency "hexx-suit", "~> 0.0"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+# Loads the RSpec test suit.
+require "hexx-suit"
+
+# Loads the RSpec support files.
+Dir.chdir File.expand_path("..", __FILE__) do
+  Dir["./support/config/*.rb"].each { |file| require file }
+end
+
+# Loads runtime metrics in the current scope
+Hexx::Suit.load_metrics_for(self)
+
+# Loads the code of the module.
+require "service_objects"

data/spec/tests/base_spec.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+
+describe ServiceObjects::Base do
+
+  let(:publisher) { Wisper::Publisher }
+  let(:helpers)   { ServiceObjects::Helpers   }
+
+  it "is Dependable" do
+    expect(described_class).to be_kind_of helpers::Dependable
+  end
+
+  it "is Parameterized" do
+    expect(described_class).to be_kind_of helpers::Parameterized
+  end
+
+  it "includes Messages helper" do
+    expect(described_class).to include helpers::Messages
+  end
+
+  it "includes Parameters helper" do
+    expect(described_class).to include helpers::Parameters
+  end
+
+  it "includes Validations helper" do
+    expect(described_class).to include helpers::Validations
+  end
+
+  it "includes Exceptions helper" do
+    expect(described_class).to include helpers::Exceptions
+  end
+
+  it "includes Wisper::Publisher" do
+    expect(described_class).to include publisher
+  end
+
+  describe "#run" do
+
+    it "is defined" do
+      expect(subject).to respond_to(:run).with(0).arguments
+    end
+  end
+
+end # describe ServiceObjects::Base