service_operation 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2a9c91b80daec619f0ac9a118b0f906f5696b6b5ddc922bad13e0d1442b34579
+  data.tar.gz: f1cfb8bb8ce55ed003407fb459fed455f8eb69d702985053c2a54bb05a23b940
+SHA512:
+  metadata.gz: edef05436b475d604291d233d04782e559e6d12c5236a4a1e95b926d21995a93432da0b20bc5875791d0606214ae7c2ff4a227250b397759fc5d8eb6cc75fd02
+  data.tar.gz: 5366dea3df77fb13306e4f4b825fcca84b717bc406d4d71abce5b2c85c6b0425608d04f7d93f06adee992ca38df77cb8f6d4304734bdd15be6133f90c80c2f0d

data/lib/service_operation.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# ServiceOperation
+module ServiceOperation
+  autoload :Base, 'service_operation/base'
+  autoload :Context, 'service_operation/context'
+  autoload :Delay, 'service_operation/delay'
+  autoload :Errors, 'service_operation/errors'
+  autoload :ErrorHandling, 'service_operation/error_handling'
+  autoload :Failure, 'service_operation/failure'
+  autoload :Hooks, 'service_operation/hooks'
+  autoload :Input, 'service_operation/input'
+  autoload :Params, 'service_operation/params'
+  autoload :RackMountable, 'service_operation/rack_mountable'
+  autoload :Validations, 'service_operation/validations'
+  autoload :VERSION,  'service_operation/version'
+end

data/lib/service_operation/base.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# ServiceOperation
+module ServiceOperation
+  # Base
+  module Base
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+
+        include Delay
+        include ErrorHandling
+        include Hooks
+        include Params
+        include Validations
+
+        attr_reader :context
+      end
+    end
+
+    #
+    # Class Methods
+    #
+    module ClassMethods
+      def call(context = {})
+        new(context).tap(&:run).context
+      end
+
+      def call!(context = {})
+        new(context).tap(&:run!).context
+      end
+
+      # Allow use via ProxyAction
+      def allow_remote!
+        @allow_remote = true
+      end
+
+      def allow_remote
+        @allow_remote || false
+      end
+    end
+
+    #
+    # Instance Methods
+    #
+
+    def initialize(context = {})
+      @context = Context.build(context)
+    end
+
+    def call
+      nil
+    end
+
+    def run
+      run!
+    rescue Failure
+      nil
+    end
+
+    def run!
+      with_hooks { fail_if_errors! || skip || call } && true
+    end
+
+    def skip
+      context.skip || false
+    end
+
+    def skip!
+      context.skip = true
+    end
+  end
+end

data/lib/service_operation/context.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'ostruct'
+
+module ServiceOperation
+  # Context for an Operation
+  class Context < OpenStruct
+    CALLER_NAME_REGEXP = /`(rescue in |)([^']*)'$/
+
+    #
+    # Class Methods
+    #
+
+    def self.build(context = {})
+      self === context ? context : new(context) # rubocop:disable Style/CaseEquality
+    end
+
+    #
+    # Instance Methods
+    #
+
+    # Fixes stack loop issue with OpenStruct
+    # @requires ActiveModel::Serializers
+    def as_json(*args)
+      to_h.as_json(*args)
+    end
+
+    def fail!(context = {})
+      context.each { |k, v| send("#{k}=", v) }
+      @failure = true
+
+      raise Failure, self
+    end
+
+    # Use in the Operation class to create eager loading objects:
+    #
+    # @example
+    #   def Operation#record
+    #     context.coerce_if(Integer, String) { |name| Model.find_by_param(name) }
+    #   end
+    #
+    #  Operation.call(record: 'something').record == <Model name='something'>
+    def coerce_if(*klasses)
+      field = klasses.shift if klasses.first.is_a?(Symbol)
+      field ||= caller(1..1).first[CALLER_NAME_REGEXP, 2] # method name fetch was called from
+      self[field] = yield(self[field]) if klasses.any? { |k| self[field].is_a?(k) }
+      self[field]
+    end
+
+    # @example
+    #   fetch(:field, 'value')
+    # @example
+    #   fetch(:field) { 'value' }
+    # @example will infer field name from enclosing method name
+    #   def enclosing_method
+    #     context.fetch { 'value' }
+    #   end
+    # @example
+    #   def enclosing_method
+    #     context.fetch 'value'
+    #   end
+    def fetch(*args)
+      if !block_given? && args.length == 1 # context.fetch 'value'
+        new_value = args.first
+      else
+        field, new_value = args
+      end
+
+      field ||= caller(1..1).first[CALLER_NAME_REGEXP, 2] # method name fetch was called from
+
+      # field is already set
+      value = send(field)
+      return value if value
+
+      # context.fetch { block }
+      if block_given?
+        begin
+          value ||= yield
+        rescue StandardError => e
+          # apply if this context to the field, if this is first instance of this error being raised
+          self[field] = e.context if e.respond_to?(:context) &&
+                                     e.context.is_a?(self.class) &&
+                                     e.context != self &&
+                                     e.context.not_yet_raised
+
+          raise e
+        end
+      end
+
+      value ||= new_value
+
+      self[field] = value
+
+      value
+    end
+
+    # @return [true, false] first call returns false, after that true.
+    def not_yet_raised
+      if @already_raised
+        false
+      else
+        @already_raised = true
+      end
+    end
+
+    def failure?
+      @failure || false
+    end
+
+    def success?
+      !failure?
+    end
+
+    def to_h(*args)
+      if args.any?
+        super().slice(*args)
+      else
+        super()
+      end
+    end
+  end
+end

data/lib/service_operation/delay.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ServiceOperation
+  # Callback logic for integration with delayed_job or similar
+  module Delay
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # Class Methods
+    module ClassMethods
+      def queue(input)
+        if respond_to?(:delay)
+          delay.call(input).id
+        else
+          call(input)
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/service_operation/error_handling.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ServiceOperation
+  # ActiveModel compatable ErrorHandling
+  # depends on {Base#context} and {Errors}
+  module ErrorHandling
+    def errors
+      @errors ||= Errors.new
+    end
+
+    # @param [Failure, Hash, nil] error(s) merge into {#errors}
+    def fail!(error = {}, more = {})
+      return unless error
+
+      error = errors_from_error_code(error)
+      errors.coerced_merge error
+
+      more[:errors] ||= errors.merge(more[:errors] || {})
+
+      context.fail! more
+    end
+
+    # fail if there {#errors} Hash has any contents
+    def fail_if_errors!
+      invalid? && fail!
+    end
+
+    def invalid?
+      errors.any?
+    end
+
+    def valid?
+      !invalid?
+    end
+
+    private
+
+    # convert :error into 'Error' based on lookup in hash {ERRORS}
+    def errors_from_error_code(error_code)
+      return error_code unless error_code.is_a?(Symbol)
+
+      return { error_code => send(error_code) } if attribute_exists?(error_code) # ?
+
+      context.error_code = error_code
+      errors = defined?(self.class::ERRORS) ? self.class::ERRORS : {}
+      Array(errors[error_code] || error_code.to_s)
+    end
+
+    #
+    # Method Missing
+    #
+
+    FAIL_IF_UNLESS_REGEXP = /^fail_(if|unless)_{0,1}([a-z_]*)!$/.freeze
+
+    def fail_conditional_object(conditional, object_method, object, errors = nil)
+      bool, errors = extract_bool_errors(object_method, object, errors)
+
+      case conditional
+      when 'if'
+        fail!(errors) if bool
+      when 'unless'
+        fail!(errors) unless bool
+      end
+    end
+
+    def extract_bool_errors(object_method, object, errors)
+      # fail_if(object)
+      if object_method == '?'
+        [object, errors]
+      # fail_if(object.method?)
+      elsif object.respond_to?(object_method)
+        [object.send(object_method), errors || object]
+      # unknown
+      else
+        raise(NoMethodError, "#{object.class} does not respond to #{object_method}")
+      end
+    end
+
+    def method_missing(method_name, *args, &block)
+      # {if/unless}, method_name
+      conditional, object_method = (method_name.to_s.match(FAIL_IF_UNLESS_REGEXP) || [])[1..2]
+
+      if conditional
+        fail_conditional_object(conditional, object_method + '?', *args)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      method_name =~ FAIL_IF_UNLESS_REGEXP || super
+    end
+  end
+end

data/lib/service_operation/errors.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ServiceOperation
+  # Error object with minimal compatibility with ActiveModel style errors
+  class Errors < Hash
+    # @example
+    #   add(:attr, 'error1', 'error2')
+    # @param [Symbol] attr to add error to
+    def add(attr, *args)
+      return self if args.empty?
+
+      self[attr] ||= []
+      self[attr] += args.flatten
+
+      self
+    end
+
+    # @param error_hash pass any type of error and it will be normalized to { attr: ['error'] }
+    def coerced_merge(error_hash)
+      ensure_error_hash(error_hash).each do |key, error|
+        object_to_array(error).each { |errors| add(key, *errors) }
+      end
+
+      self
+    end
+
+    private
+
+    # @return [Hash] formatted { attribute: ['error'] }
+    def ensure_error_hash(object)
+      object = object.context.errors || object if object.is_a?(Failure)
+      object = object.errors.to_h if object.respond_to?(:errors)
+      object = object.messages.to_h if object.respond_to?(:messages)
+      object = { base: object } unless object.is_a?(Hash)
+      object
+    end
+
+    # convert ActiveRecord:Base / ActiveModel::Errors to an array
+    def object_to_array(errors)
+      errors = errors.message if errors.respond_to?(:message) # StandardError
+      errors = errors.errors if errors.respond_to?(:errors)
+      errors = errors.messages if errors.respond_to?(:full_messages)
+      Array(errors).compact
+    end
+  end
+end

data/lib/service_operation/failure.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ServiceOperation
+  # StandardError for an operation
+  class Failure < StandardError
+    attr_reader :context
+
+    def initialize(context = nil)
+      @context = context
+      super
+    end
+  end
+end

data/lib/service_operation/hooks.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module ServiceOperation
+  # Simple hooks mechanism with inheritance.
+  module Hooks
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+      end
+    end
+
+    # Hook Methods
+    module ClassMethods
+      # @example
+      #   around do |op|
+      #     result = nil
+      #     ms = Benchmark.ms { result = op.call }
+      #     puts "#{self.class.name} took #{ms}"
+      #     result
+      #   end
+      def around(*hooks, &block)
+        add_hooks(:around, hooks, block)
+      end
+
+      def before(*hooks, &block)
+        add_hooks(:before, hooks, block)
+      end
+
+      def after(*hooks, &block)
+        add_hooks(:after, hooks, block, :unshift)
+      end
+
+      # @return [Array<Symbol, Proc>]
+      def around_hooks
+        @around_hooks ||= initial_hooks(:around_hooks)
+      end
+
+      # @return [Array<Symbol, Proc>]
+      def before_hooks
+        @before_hooks ||= initial_hooks(:before_hooks)
+      end
+
+      # @return [Array<Symbol, Proc>]
+      def after_hooks
+        @after_hooks ||= initial_hooks(:after_hooks)
+      end
+
+      private
+
+      # rubocop:disable Style/SafeNavigation
+      def initial_hooks(name)
+        superclass && superclass.respond_to?(name) ? superclass.send(name).dup : []
+      end
+      # rubocop:enable Style/SafeNavigation
+
+      def add_hooks(name, hooks, block, method = :push)
+        hooks << block if block
+        hooks.each { |hook| send("#{name}_hooks").send(method, hook) }
+      end
+    end
+
+    private
+
+    def with_hooks
+      run_around_hooks do
+        run_before_hooks
+        yield
+        run_after_hooks
+      end
+    end
+
+    def run_around_hooks(&block)
+      self.class.around_hooks.reverse.inject(block) do |chain, hook|
+        proc { run_hook(hook, chain) }
+      end.call
+    end
+
+    def run_before_hooks
+      run_hooks(self.class.before_hooks)
+    end
+
+    def run_after_hooks
+      run_hooks(self.class.after_hooks)
+    end
+
+    def run_hooks(hooks)
+      hooks.each { |hook| run_hook(hook) }
+    end
+
+    # @param [Symbol, Proc] - name of a method defined in the operation or a block
+    def run_hook(hook, *args)
+      return if hook.class.name =~ /Delayed::Backend/ # prevent a clash with delayed_job gem.
+
+      hook.is_a?(Symbol) ? send(hook, *args) : instance_exec(*args, &hook)
+    end
+
+    # unimplemented method from previous project to define "before_call_do_this" style hooks.
+    # def run_before_call_methods
+    #   private_methods.grep(/^before_call_/).map { |m| send(m) }
+    # end
+  end
+end