lotus-utils 0.3.4 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 339681343526eb287d81d4f52ca29bda0550d8e7
-  data.tar.gz: 3e22d02c21a013f03cb1789e307e59054ba37ff1
+  metadata.gz: fbc9ff8be5d774d9e30695445d43995a66cbf21d
+  data.tar.gz: 4f5ccb96067b17d2c6f77b5b0d5eb5ccd2def30f
 SHA512:
-  metadata.gz: da44a5d936f554ae76be3c7c8195bd416268c5c0f81898df0c4959cc4aee3ab38180fa995943fac286ff464ebed477fb07307562330b0d086162b22fc4dbb41d
-  data.tar.gz: 6e835299ce217838cd487070b1ade2a5b7c8916af0eef233e76716257f99b258360faba93ca4ac8c29c84efc6dbccaf46db99d35b81891e00c76f92b39d62fc5
+  metadata.gz: d254f1b09c52c91198986bc340f17b9cfe35146bcbeed9464c4f99d390e45eb8dbe8e11cb6672b42716e7136294a00300fe0cb207636a8e0e24cbc80f1d2eeef
+  data.tar.gz: 18bcf46df8ab2013f334d962ed859919df1e6711562b89c2a8eec959141551f901b975c2dfdd084f00b894f53cd53f460dca6881add6d63c9cb176a13de3c35c

data/CHANGELOG.md

@@ -1,6 +1,11 @@
 # Lotus::Utils
 Ruby core extentions and class utilities for Lotus
 
+## v0.3.5 - 2015-03-12
+### Added
+- [Luca Guidi] Introduced `Lotus::Interactor`
+- [Luca Guidi] Introduced `Lotus::Utils::BasicObject`
+
 ## v0.3.4 - 2015-01-30
 ### Added
 - [Alfonso Uceda Pompa] Aliased `Lotus::Utils::Attributes#get` with `#[]`

data/lib/lotus/interactor.rb

@@ -0,0 +1,429 @@
+require 'lotus/utils/basic_object'
+require 'lotus/utils/hash'
+
+module Lotus
+  # Lotus Interactor
+  #
+  # @since 0.3.5
+  module Interactor
+    # Result of an operation
+    #
+    # @since 0.3.5
+    class Result < Utils::BasicObject
+      # Concrete methods
+      #
+      # @since 0.3.5
+      # @api private
+      #
+      # @see Lotus::Interactor::Result#respond_to_missing?
+      METHODS = {initialize: true, success?: true, fail!: true, prepare!: true, errors: true, error: true}.freeze
+
+      # Initialize a new result
+      #
+      # @param payload [Hash] a payload to carry on
+      #
+      # @return [Lotus::Interactor::Result]
+      #
+      # @since 0.3.5
+      # @api private
+      def initialize(payload = {})
+        @payload = _payload(payload)
+        @success = true
+      end
+
+      # Check if the current status is successful
+      #
+      # @return [TrueClass,FalseClass] the result of the check
+      #
+      # @since 0.3.5
+      def success?
+        @success && errors.empty?
+      end
+
+      # Force the status to be a failure
+      #
+      # @since 0.3.5
+      def fail!
+        @success = false
+      end
+
+      # Returns all the errors collected during an operation
+      #
+      # @return [Array] the errors
+      #
+      # @since 0.3.5
+      #
+      # @see Lotus::Interactor::Result#error
+      # @see Lotus::Interactor#call
+      # @see Lotus::Interactor#error
+      # @see Lotus::Interactor#error!
+      def errors
+        @payload.fetch(:_errors) { [] }
+      end
+
+      # Returns the first errors collected during an operation
+      #
+      # @return [nil,String] the error, if present
+      #
+      # @since 0.3.5
+      #
+      # @see Lotus::Interactor::Result#errors
+      # @see Lotus::Interactor#call
+      # @see Lotus::Interactor#error
+      # @see Lotus::Interactor#error!
+      def error
+        errors.first
+      end
+
+      # Prepare the result before to be returned
+      #
+      # @param payload [Hash] an updated payload
+      #
+      # @since 0.3.5
+      # @api private
+      def prepare!(payload)
+        @payload.merge!(_payload(payload))
+        self
+      end
+
+      protected
+      # @since 0.3.5
+      # @api private
+      def method_missing(m, *)
+        @payload.fetch(m) { super }
+      end
+
+      # @since 0.3.5
+      # @api private
+      def respond_to_missing?(method_name, include_all)
+        method_name = method_name.to_sym
+        METHODS[method_name] || @payload.key?(method_name)
+      end
+
+      # @since 0.3.5
+      # @api private
+      def _payload(payload)
+        Utils::Hash.new(payload).symbolize!
+      end
+
+      # @since 0.3.5
+      # @api private
+      def __inspect
+        " @success=#{ @success } @payload=#{ @payload.inspect }"
+      end
+    end
+
+    # Override for <tt>Module#included</tt>.
+    #
+    # @since 0.3.5
+    # @api private
+    def self.included(base)
+      super
+
+      base.class_eval do
+        prepend Interface
+      end
+    end
+
+    # Interactor interface
+    #
+    # @since 0.3.5
+    module Interface
+      # Initialize an interactor
+      #
+      # It accepts arbitrary number of arguments.
+      # Developers can override it.
+      #
+      # @param args [Array<Object>] arbitrary number of arguments
+      #
+      # @return [Lotus::Interactor] the interactor
+      #
+      # @since 0.3.5
+      #
+      # @example Override #initialize
+      #   require 'lotus/interactor'
+      #
+      #   class UpdateProfile
+      #     include Lotus::Interactor
+      #
+      #     def initialize(person, params)
+      #       @person = person
+      #       @params = params
+      #     end
+      #
+      #     def call
+      #       # ...
+      #     end
+      #   end
+      def initialize(*args)
+        super
+      ensure
+        @__result = ::Lotus::Interactor::Result.new
+        @_errors  = []
+      end
+
+      # Triggers the operation and return a result.
+      #
+      # All the instance variables will be available in the result.
+      #
+      # ATTENTION: This must be implemented by the including class.
+      #
+      # @return [Lotus::Interactor::Result] the result of the operation
+      #
+      # @raise [NoMethodError] if this isn't implemented by the including class.
+      #
+      # @example Instance variables in result payload
+      #   require 'lotus/interactor'
+      #
+      #   class Signup
+      #     def initialize(params)
+      #       @params = params
+      #       @user   = User.new(@params)
+      #       @foo    = 'bar'
+      #     end
+      #
+      #     def call
+      #       @user = UserRepository.persist(@user)
+      #     end
+      #   end
+      #
+      #   result = Signup.new(name: 'Luca').call
+      #   result.success? # => true
+      #
+      #   result.user   # => #<User:0x007fa311105778 @id=1 @name="Luca">
+      #   result.params # => { :name=>"Luca" }
+      #   result.foo    # => "Bar"
+      #
+      # @example Failed precondition
+      #   require 'lotus/interactor'
+      #
+      #   class Signup
+      #     def initialize(params)
+      #       @params = params
+      #       @user   = User.new(@params)
+      #     end
+      #
+      #     # THIS WON'T BE INVOKED BECAUSE #valid? WILL RETURN false
+      #     def call
+      #       @user = UserRepository.persist(@user)
+      #     end
+      #
+      #     private
+      #     def valid?
+      #       @params.valid?
+      #     end
+      #   end
+      #
+      #   result = Signup.new(name: nil).call
+      #   result.success? # => false
+      #
+      #   result.user   # => #<User:0x007fa311105778 @id=nil @name="Luca">
+      #
+      # @example Bad usage
+      #   require 'lotus/interactor'
+      #
+      #   class Signup
+      #     include Lotus::Interactor
+      #
+      #     # Method #call is not defined
+      #   end
+      #
+      #   Signup.new.call # => NoMethodError
+      def call
+        _call { super }
+      end
+    end
+
+    private
+    # Check if proceed with <tt>#call</tt> invokation.
+    # By default it returns <tt>true</tt>.
+    #
+    # Developers can override it.
+    #
+    # @return [TrueClass,FalseClass] the result of the check
+    #
+    # @since 0.3.5
+    def valid?
+      true
+    end
+
+    # Fail and interrupt the current flow.
+    #
+    # @since 0.3.5
+    #
+    # @example
+    #   require 'lotus/interactor'
+    #
+    #   class CreateEmailTest
+    #     include Lotus::Interactor
+    #
+    #     def initialize(params)
+    #       @params     = params
+    #       @email_test = EmailTest.new(@params)
+    #     end
+    #
+    #     def call
+    #       persist_email_test!
+    #       capture_screenshot!
+    #     end
+    #
+    #     private
+    #     def persist_email_test!
+    #       @email_test = EmailTestRepository.persist(@email_test)
+    #     end
+    #
+    #     # IF THIS RAISES AN EXCEPTION WE FORCE A FAILURE
+    #     def capture_screenshot!
+    #       Screenshot.new(@email_test).capture!
+    #     rescue
+    #       fail!
+    #     end
+    #   end
+    #
+    #   result = CreateEmailTest.new(account_id: 1).call
+    #   result.success? # => false
+    def fail!
+      @__result.fail!
+      throw :fail
+    end
+
+    # Log an error without interrupting the flow.
+    #
+    # When used, the returned result won't be successful.
+    #
+    # @param message [String] the error message
+    #
+    # @since 0.3.5
+    #
+    # @see Lotus::Interactor#error!
+    #
+    # @example
+    #   require 'lotus/interactor'
+    #
+    #   class CreateRecord
+    #     include Lotus::Interactor
+    #
+    #     def initialize
+    #       @logger = []
+    #     end
+    #
+    #     def call
+    #       prepare_data!
+    #       persist!
+    #       sync!
+    #     end
+    #
+    #     private
+    #     def prepare_data!
+    #       @logger << __method__
+    #       error "Prepare data error"
+    #     end
+    #
+    #     def persist!
+    #       @logger << __method__
+    #       error "Persist error"
+    #     end
+    #
+    #     def sync!
+    #       @logger << __method__
+    #     end
+    #   end
+    #
+    #   result = CreateRecord.new.call
+    #   result.success? # => false
+    #
+    #   result.errors # => ["Prepare data error", "Persist error"]
+    #   result.logger # => [:prepare_data!, :persist!, :sync!]
+    def error(message)
+      @_errors << message
+    end
+
+    # Log an error AND interrupting the flow.
+    #
+    # When used, the returned result won't be successful.
+    #
+    # @param message [String] the error message
+    #
+    # @since 0.3.5
+    #
+    # @see Lotus::Interactor#error
+    #
+    # @example
+    #   require 'lotus/interactor'
+    #
+    #   class CreateRecord
+    #     include Lotus::Interactor
+    #
+    #     def initialize
+    #       @logger = []
+    #     end
+    #
+    #     def call
+    #       prepare_data!
+    #       persist!
+    #       sync!
+    #     end
+    #
+    #     private
+    #     def prepare_data!
+    #       @logger << __method__
+    #       error "Prepare data error"
+    #     end
+    #
+    #     def persist!
+    #       @logger << __method__
+    #       error! "Persist error"
+    #     end
+    #
+    #     # THIS WILL NEVER BE INVOKED BECAUSE WE USE #error! IN #persist!
+    #     def sync!
+    #       @logger << __method__
+    #     end
+    #   end
+    #
+    #   result = CreateRecord.new.call
+    #   result.success? # => false
+    #
+    #   result.errors # => ["Prepare data error", "Persist error"]
+    #   result.logger # => [:prepare_data!, :persist!]
+    def error!(message)
+      error(message)
+      fail!
+    end
+
+    # @since 0.3.5
+    # @api private
+    def _call
+      catch :fail do
+        validate!
+        yield
+      end
+
+      _prepare!
+    end
+
+    # @since 0.3.5
+    def validate!
+      fail! unless valid?
+    end
+
+    # @since 0.3.5
+    # @api private
+    def _prepare!
+      @__result.prepare!(_instance_variables)
+    end
+
+    # @since 0.3.5
+    # @api private
+    def _instance_variables
+      Hash[].tap do |result|
+        instance_variables.each do |iv|
+          name = iv.to_s.sub(/\A@/, '')
+          next if name.match(/\A__/)
+
+          result[name.to_sym] = instance_variable_get(iv)
+        end
+      end
+    end
+  end
+end

data/lib/lotus/utils/basic_object.rb

@@ -0,0 +1,53 @@
+module Lotus
+  module Utils
+    # BasicObject
+    #
+    # @since 0.3.5
+    class BasicObject < ::BasicObject
+      # Return the class for debugging purposes.
+      #
+      # @since 0.3.5
+      #
+      # @see http://ruby-doc.org/core/Object.html#method-i-class
+      def class
+        (class << self; self end).superclass
+      end
+
+      # Bare minimum inspect for debugging purposes.
+      #
+      # @return [String] the inspect string
+      #
+      # @since 0.3.5
+      #
+      # @see http://ruby-doc.org/core/Object.html#method-i-inspect
+      def inspect
+        "#<#{ self.class }:#{'%x' % (__id__ << 1)}#{ __inspect }>"
+      end
+
+      # Returns true if responds to the given method.
+      #
+      # @return [TrueClass,FalseClass] the result of the check
+      #
+      # @since 0.3.5
+      #
+      # @see http://ruby-doc.org/core-2.2.1/Object.html#method-i-respond_to-3F
+      def respond_to?(method_name, include_all = false)
+        respond_to_missing?(method_name, include_all)
+      end
+
+      private
+      # Must be overridden by descendants
+      #
+      # @since 0.3.5
+      # @api private
+      def respond_to_missing?(method_name, include_all)
+        ::Kernel.raise ::NotImplementedError
+      end
+
+      # @since 0.3.5
+      # @api private
+      def __inspect
+      end
+    end
+  end
+end

data/lib/lotus/utils/version.rb

@@ -3,6 +3,6 @@ module Lotus
     # Defines the version
     #
     # @since 0.1.0
-    VERSION = '0.3.4'.freeze
+    VERSION = '0.3.5'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lotus-utils
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.5
 platform: ruby
 authors:
 - Luca Guidi
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-30 00:00:00.000000000 Z
+date: 2015-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -64,8 +64,10 @@ files:
 - CHANGELOG.md
 - LICENSE.md
 - README.md
+- lib/lotus/interactor.rb
 - lib/lotus/utils.rb
 - lib/lotus/utils/attributes.rb
+- lib/lotus/utils/basic_object.rb
 - lib/lotus/utils/callbacks.rb
 - lib/lotus/utils/class.rb
 - lib/lotus/utils/class_attribute.rb