service_objects 0.0.1

data/lib/service_objects/base.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+require "wisper"
+
+require "service_objects/helpers/messages"
+require "service_objects/helpers/validations"
+require "service_objects/helpers/exceptions"
+require "service_objects/helpers/dependable"
+require "service_objects/helpers/parameters"
+require "service_objects/helpers/parameterized"
+
+module ServiceObjects
+
+  # Base class for service objects
+  #
+  # @example
+  #   AddItem = Class.new(ServiceObjects::Base)
+  #
+  # @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
+  class Base
+
+    extend Helpers::Dependable
+    extend Helpers::Parameterized
+
+    include Helpers::Exceptions
+    include Helpers::Validations
+    include Wisper::Publisher
+    # @!parse include ServiceObjects::Helpers::Parameters
+    # @!parse include ServiceObjects::Helpers::Messages
+    # @!parse include ActiveModel::Validations
+
+    # @abstract
+    # Runs service object
+    #
+    # @return [undefined]
+    def run
+    end
+
+  end # class Base
+
+end # module ServiceObjects

data/lib/service_objects/helpers/dependable.rb

@@ -0,0 +1,63 @@
+# encoding: utf-8
+
+module ServiceObjects
+
+  module Helpers
+
+    # Features for service dependencies declaration
+    #
+    # @note
+    #   A target class should be **extended** by the module
+    module Dependable
+
+      # Declares the dependency setter and getter
+      #
+      # @example
+      #   class AddFoo
+      #     extend ServiceObjects::Helpers::Dependable
+      #
+      #     depends_on :get_item, default: GetItem
+      #   end
+      #
+      #   service = AddFoo.new
+      #   service.get_item
+      #   # => GetItem
+      #
+      #   # Depencency injection
+      #   service.get_item = FindItem
+      #   service.get_item
+      #   # => FindItem
+      #
+      #   # Resetting to default
+      #   service.get_item = nil
+      #   service.get_item
+      #   # => GetItem
+      #
+      # @example Set to NULL Object by default
+      #   class AddFoo
+      #     extend ServiceObjects::Helpers::Dependable
+      #
+      #     depends_on :get_item
+      #   end
+      #
+      #   service = AddFoo.new
+      #   service.get_item
+      #   # => <ServiceObjects::NULL>
+      #
+      # @param [#to_sym] name
+      #   the name for the dependency
+      # @param [BaseObject] default (ServiceObjects::NULL)
+      #   default implementation for the dependency
+      #
+      # @return [:depends_on]
+      #   the name of the method
+      def depends_on(name, default: NULL)
+        attr_writer name
+        define_method(name) { instance_eval("@#{ name }") || default }
+      end
+
+    end # Dependable
+
+  end # module Helpers
+
+end # module ServiceObjects

data/lib/service_objects/helpers/exceptions.rb

@@ -0,0 +1,64 @@
+# encoding: utf-8
+
+module ServiceObjects
+
+  module Helpers
+
+    # Features for escaping from runtime errors
+    #
+    # @note
+    #   A target class should **include** the module
+    module Exceptions
+
+      # Re-raises standard errors as <tt>ServiceObjects::Invalid</tt>
+      #
+      # Mutates the current object by adding error messages
+      #
+      # @example
+      #   class MyClass
+      #     includes ServiceObjects::Helpers::Exceptions
+      #   end
+      #
+      #   begin
+      #     MyClass.new.escape { fail StandardError.new "foo" }
+      #   rescue => err
+      #     puts err.class.name
+      #     puts messages
+      #   end
+      #
+      #   # => ServiceObjects::Invalid
+      #   # => [<ServiceObject::Message type="error" text="foo" ...>]
+      #
+      # @yield  the block
+      #
+      # @raise  [ServiceObjects::Invalid]
+      #   if the block raises +StandardError+
+      #
+      # @return [Object] the value returned by the block
+      def escape
+        yield if block_given?
+      rescue => error
+        collect_messages_from error
+        raise Invalid.new(self)
+      end
+
+      private
+
+      # @!parse include ServiceObjects::Helpers::Messages
+      def self.included(klass)
+        klass.include Messages
+      end
+
+      def collect_messages_from(error)
+        if error.is_a? Invalid
+          messages.concat(error.messages) if error.object != self
+        else
+          add_message type: "error", text: error.message
+        end
+      end
+
+    end # module Exceptions
+
+  end # module Helpers
+
+end # module ServiceObjects

data/lib/service_objects/helpers/messages.rb

@@ -0,0 +1,96 @@
+# encoding: utf-8
+require "extlib"
+
+module ServiceObjects
+
+  # Contains helper objecs for the base service
+  module Helpers
+
+    # Features for collecting service messages
+    #
+    # @note
+    #   A target class should **include** the module
+    module Messages
+
+      # Translates the text in the current scope with given options
+      #
+      # The method uses I18n.t library method.
+      #
+      # @example Returns a translation for symbolic argument
+      #   class Test
+      #     include ServiceObjects::Helpers::Messages
+      #   end
+      #
+      #   MyClass.new.translate :item
+      #   # => translation not found: en.activemodel.messages.models.test.item
+      #
+      # @example Converts non-symbolic argument to a string.
+      #   class Test
+      #     include ServiceObjects::Helpers::Messages
+      #   end
+      #
+      #   MyClass.new.translate 1
+      #   # => "1"
+      #
+      # @param  [#to_s] text
+      # @param  [Hash] options ({})
+      #
+      # @return [String]
+      def translate(text, options = {})
+        return text.to_s unless text.is_a? Symbol
+        I18n.t text, Utils::NormalHash.from(options).merge(scope: __scope__)
+      end
+
+      # A list of object messages
+      #
+      # @return [Array<ServiceObjects::Message>]
+      def messages
+        @messages ||= []
+      end
+
+      # Translates the text and adds a new message to the list of {#messages}
+      #
+      # @example
+      #   class MyClass
+      #     include ServiceObjects::Helpers::Messages
+      #   end
+      #
+      #   object = MyClass.new
+      #   object.add_message type: "foo", text: "bar", priority: 2.5
+      #   object.messages
+      #   # => [<ServiceObjects::Message type="foo" text="bar" priority=2.5>]
+      #
+      # @param [Hash] options
+      #   the list of options for the message and its translation
+      #
+      # @option options [#to_s] :text
+      #   the text of a new message to be translated via {#translate} method
+      # @option options [#to_s] :type
+      #   the type of a new message
+      # @option options [#to_f] :priority
+      #   optional priority fo a new message
+      #
+      # @return [Array<ServiceObjects::Message>] The updated {#messages}
+      def add_message(options)
+        params   = Utils::NormalHash.from(options)
+        type     = params.delete :type
+        priority = params.delete :priority
+        text     = translate params.delete(:text), params
+        messages << Message.new(text: text, type: type, priority: priority)
+      end
+
+      private
+
+      def __scope__
+        @__scope__ ||= [:activemodel, :messages, :models, __class_name__.to_sym]
+      end
+
+      def __class_name__
+        self.class.name.split("::").map(&:snake_case).join("/")
+      end
+
+    end # module Messages
+
+  end # module Helpers
+
+end # module Services

data/lib/service_objects/helpers/parameterized.rb

@@ -0,0 +1,85 @@
+# encoding: utf-8
+
+module ServiceObjects
+
+  module Helpers
+
+    # Features for service parameters declaration
+    #
+    # @note
+    #   A target class should be **extended** by the module
+    module Parameterized
+
+      # Whitelists {.new} options assigned to params
+      #
+      # Mutates the current class by adding the corresponding attribute
+      # for every parameter.
+      #
+      # @example Whitelists options
+      #   class AddFoo
+      #     extend ServiceObjects::Helpers::Parameterized
+      #
+      #     allows_params :foo
+      #   end
+      #
+      #   service = AddFoo.new foo: "foo", bar: "baz"
+      #   service.params # => { foo: "foo" }
+      #
+      # @example Adds attributes as aliases to corresponding params
+      #   class AddFoo
+      #     extend ServiceObjects::Helpers::Parameterized
+      #
+      #     allows_params :foo
+      #   end
+      #
+      #   service = AddFoo.new foo: "foo"
+      #   service.foo           # => "foo"
+      #
+      #   service.params[:foo] = "bar"
+      #   service.foo           # => "bar"
+      #
+      #   service.foo = "baz"
+      #   service.foo           # => "baz"
+      #   service.params[:foo]  # => "baz"
+      #
+      # @param [Array<#to_sym>] list
+      #
+      # @return [Array<Symbol>]
+      #   the list of arguments
+      def allows_params(*list)
+        @whitelist = list.flatten.map(&:to_sym).freeze
+        __attr_params__
+
+        whitelist
+      end
+
+      private
+
+      # @!parse include ServiceObjects::Helpers::Parameters
+      def self.extended(klass)
+        klass.include Parameters
+        super
+      end
+
+      def __attr_params__
+        whitelist.each(&method(:__attr_param_accessor__))
+      end
+
+      def __attr_param_accessor__(name)
+        __attr_param_reader__ name
+        __attr_param_writer__ name
+      end
+
+      def __attr_param_reader__(name)
+        define_method(name) { params[name] }
+      end
+
+      def __attr_param_writer__(name)
+        define_method("#{ name }=") { |value| params[name] = value }
+      end
+
+    end # module Parameters
+
+  end # module Helpers
+
+end # module ServiceObjects

data/lib/service_objects/helpers/parameters.rb

@@ -0,0 +1,71 @@
+# encoding: utf-8
+
+module ServiceObjects
+
+  module Helpers
+
+    # Features for whitelisting service options
+    #
+    # @note
+    #   A target class should **include** the module
+    module Parameters
+
+      # @!scope class
+      # @!attribute [r] whitelist
+      # Returns the list of allowed parameters
+      #
+      # @return [Array<Symbol>]
+
+      # @!attribute [r] params
+      # Service object parameters
+      #
+      # @return [Hash]
+      attr_reader :params
+
+      # Service object initializer
+      #
+      # @example Normalizing options
+      #   class AddFoo
+      #     include ServiceObjects::Helpers::Parameters
+      #
+      #     @whitelist = [:foo]
+      #   end
+      #
+      #   service = AddFoo.new("foo" => { "bar" => "baz" })
+      #   service.params # => { foo: { bar: "baz" } }
+      #
+      # @example Whitelisting options
+      #   class AddFoo
+      #     include ServiceObjects::Helpers::Parameters
+      #
+      #     @whitelist = [:foo]
+      #   end
+      #
+      #   service = AddFoo.new(foo: "bar", bar: "baz")
+      #   service.params # => { foo: "bar" }
+      #
+      # @param [Hash] options
+      #
+      # @return [undefined]
+      def initialize(options = {})
+        @params = Utils::NormalHash.from(options).slice(*__whitelist__)
+      end
+
+      private
+
+      def self.included(klass)
+        klass
+          .singleton_class
+          .send(:define_method, :whitelist) { @whitelist ||= [] }
+        super
+      end
+
+      def __whitelist__
+        @whitelist ||= self.class.send :whitelist
+      end
+
+    end # module Parameters
+
+  end # module Helpers
+
+end # module ServiceObjects

data/lib/service_objects/helpers/validations.rb

@@ -0,0 +1,54 @@
+# encoding: utf-8
+require "active_model"
+
+module ServiceObjects
+
+  module Helpers
+
+    # Features for service attributes validation
+    #
+    # @note
+    #   A target class should **include** the module
+    #
+    # @see http://apidock.com/rails/v4.1.8/ActiveModel/Validations
+    #   ActiveModel::Validations
+    module Validations
+
+      # @!method valid?
+      # Runs validations and checks if the object is valid
+      # @return [Boolean]
+
+      # Raises <tt>ServiceObjects::Invalid</tt> when {#valid?} method fails
+      #
+      # Mutates the current object by populating its messages
+      # with errors, added by {#valid?}
+      #
+      # @raise [ServiceObjects::Invalid]
+      #   when a validation fails
+      #
+      # @return [self] (not changed)
+      #   when a validation passes
+      def validate!
+        return self if valid?
+        __errors__.each { |text| add_message text: text, type: "error" }
+        fail Invalid.new(self)
+      end
+
+      private
+
+      # @!parse include ServiceObjects::Helpers::Messages
+      # @!parse include ActiveModel::Validations
+      def self.included(klass)
+        klass.include ActiveModel::Validations, Messages
+        super
+      end
+
+      def __errors__
+        errors.messages.values.flatten
+      end
+
+    end # module Validations
+
+  end # module Helpers
+
+end # module ServiceObjects