eco-helpers 3.0.21 → 3.0.23

data/lib/eco/api/session/batch/searcher.rb

@@ -95,7 +95,8 @@ module Eco
           private
 
           def get(params: {}, silent: false, options: self.options)
-            msg = "cannot batch get without api connnection, please provide a valid api connection!"
+            msg  = "cannot batch get without api connnection, "
+            msg << "please provide a valid api connection!"
             fatal msg unless (people_api = api&.people)
 
             params = {per_page: batch_size(options)}.merge(params)

data/lib/eco/api/session/batch.rb

@@ -27,7 +27,6 @@ end
 
 require_relative 'batch/job'
 require_relative 'batch/feedback'
-require_relative 'batch/request_stats'
 require_relative 'batch/base_policy'
 require_relative 'batch/policies'
 require_relative 'batch/status'

data/lib/eco/api/session/config/workflow.rb

@@ -7,8 +7,9 @@ module Eco
 
           WORKFLOW_MODEL = [
             :options,
-            {load: [{input: %i[get filter]}, {people: %i[get filter]}, :filter]},
-            :usecases, :launch_jobs,
+            {load: [{input: %i[get filter]}, {data: %i[get filter]}, :filter]},
+            :usecases,
+            :launch_jobs,
             {post_launch: %i[usecases launch_jobs]},
             :report,
             :end,
@@ -24,8 +25,11 @@ module Eco
               super || {}
             end
 
-            def validate_stage(stage)
-              "Unknown Workflow stage '#{stage}'. Should be any of #{stages}" unless stages.include?(stage)
+            def validate_stage!(stage)
+              return true if stages.include?(stage)
+
+              msg = "Unknown Workflow stage '#{stage}'. Should be any of #{stages}"
+              raise ArgumentError, msg
             end
 
             def workflow_class(key)
@@ -98,7 +102,8 @@ module Eco
           #   1. if block is provided provided, it returns the **current stage** object (to ease chainig).
           #   2. if block is not provided, it returns the **stage** referred by `key`
           def for(key = nil, &block)
-            raise ArgumentError, "With no 'key', a block should be given." unless key || block_given?
+            msg = "With no 'key', a block should be given."
+            raise ArgumentError, msg unless key || block_given?
 
             tap do
               next yield(self)            unless key
@@ -121,7 +126,8 @@ module Eco
           # @yieldreturn [Eco::API::UseCases::BaseIO] the `io` input/output object carried througout all the _workflow_
           # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
           def on(key = nil, &block)
-            raise ArgumentError, "A block should be given." unless block_given?
+            msg = "A block should be given."
+            raise ArgumentError, msg unless block_given?
 
             if key
               stage(key).on(&block)
@@ -172,13 +178,15 @@ module Eco
           # @yieldreturn [Eco::API::UseCases::BaseIO] `io` the input/output object carried througout all the _workflow_
           # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
           def before(key = nil, &block)
-            raise ArgumentError, "A block should be given." unless block_given?
+            msg = "A block should be given."
+            raise ArgumentError, msg unless block_given?
 
             if key
               stage(key).before(&block)
             else
               @before.push(block)
             end
+
             self
           end
 
@@ -197,13 +205,15 @@ module Eco
           # @yieldreturn [Eco::API::UseCases::BaseIO] `io` the input/output object carried througout all the _workflow_
           # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
           def after(key = nil, &block)
-            raise ArgumentError, "A block should be given." unless block_given?
+            msg = "A block should be given."
+            raise ArgumentError, msg unless block_given?
 
             if key
               stage(key).after(&block)
             else
               @after.push(block)
             end
+
             self
           end
 
@@ -347,7 +357,7 @@ module Eco
           end
 
           def stage(key)
-            self.class.validate_stage(key)
+            self.class.validate_stage!(key)
             @stages[key] ||= self.class.workflow_class(key).new(
               key,
               _parent: self,

data/lib/eco/api/usecases/base_case/model.rb

@@ -0,0 +1,54 @@
+class Eco::API::UseCases::BaseCase
+  module Model
+    class UnsupportedModel < ArgumentError
+      def initialize(msg = nil, model:, models:)
+        msg ||= "Unsupported model. "
+        msg  << " Given model '#{model}'. Valid models: #{models}"
+        super(msg)
+      end
+    end
+
+    MODELS = %i[
+      people
+      contractors
+      other
+    ].freeze
+
+    class << self
+      def included(base)
+        super
+        base.extend(ClassMethods)
+      end
+    end
+
+    module ClassMethods
+      def type_to_default_model(type = nil)
+        return :other if type == :other
+
+        :people
+      end
+
+      def valid_model?(model)
+        models.include?(model)
+      end
+
+      def models
+        MODELS
+      end
+
+      def validate_model!(model, msg: nil, models: self.models)
+        return model if valid_model?(model)
+
+        raise UnsupportedModel.new(msg, model: model, models: models)
+      end
+    end
+
+    # INSTANCE METHODS
+
+    private
+
+    def validate_model!(...)
+      self.class.validate_model!(...)
+    end
+  end
+end

data/lib/eco/api/usecases/base_case/type.rb

@@ -0,0 +1,52 @@
+class Eco::API::UseCases::BaseCase
+  module Type
+    class InvalidType < ArgumentError
+      def initialize(msg = nil, type:, types:)
+        msg ||= "Invalid type. "
+        msg  << " Given type '#{type}'. Valid types: #{types}"
+        super(msg)
+      end
+    end
+
+    TYPES = %i[
+      import
+      filter
+      transform
+      sync
+      error_handler
+      export
+      other
+    ].freeze
+
+    class << self
+      def included(base)
+        super
+        base.extend(ClassMethods)
+      end
+    end
+
+    module ClassMethods
+      def valid_type?(type)
+        types.include?(type)
+      end
+
+      def types
+        self::TYPES
+      end
+
+      def validate_type!(type, msg: nil, types: self.types)
+        return type if valid_type?(type)
+
+        raise InvalidType.new(msg, type: type, types: types)
+      end
+    end
+
+    # INSTANCE METHODS
+
+    private
+
+    def validate_type!(...)
+      self.class.validate_type!(...)
+    end
+  end
+end

data/lib/eco/api/usecases/base_case.rb

@@ -3,37 +3,13 @@ module Eco
     class UseCases
       # Core class of UseCases. It basically defines and manages allowed `types`
       class BaseCase
-        class InvalidType < StandardError
-          def initialize(msg = nil, type:, types:)
-            msg ||= "Invalid type. "
-            msg  << "Given type '#{type}'. Valid types: #{types}"
-            super(msg)
-          end
-        end
+        require_relative 'base_case/type'
+        require_relative 'base_case/model'
 
-        extend Eco::API::Common::ClassHelpers
-
-        @types = %i[
-          import
-          filter
-          transform
-          sync
-          error_handler
-          export
-          other
-        ]
-
-        class << self
-          attr_reader :types
+        include Type
+        include Model
 
-          def valid_type?(type)
-            types.include?(type)
-          end
-
-          def validate_type(type)
-            raise InvalidType.new(type: type, types: types) unless valid_type?(type)
-          end
-        end
+        extend Eco::API::Common::ClassHelpers
       end
     end
   end

data/lib/eco/api/usecases/base_io/chaining.rb

@@ -0,0 +1,48 @@
+class Eco::API::UseCases::BaseIO
+  module Chaining
+    # Shortcut to run a usecase passing this `io` as parameter
+    # @note
+    #   1. It swaps `output` to `input` or `data` depending on `self.type`
+    #   2. does this, **before** the target `case_name` launch and **after
+    # @return [Eco::API::UseCases::BaseIO]
+    def process_case(case_name, case_type, **params)
+      session.process_case(
+        case_name,
+        io:   chained,
+        type: case_type,
+        **params
+      ).chained
+    end
+
+    # Does the switch from output to result in a new IO object.
+    # @note if there isn't `output` it doesn't do the switch,
+    #   provided that it preserves the target parameter
+    #   (otherise it would blank it)
+    # @return [Eco::API::UseCases::BaseIO]
+    def chained(as: type) # rubocop:disable Naming/MethodParameterName
+      base.tap do |io_base|
+        next unless io_base.output
+
+        case as
+        when :import
+          io_base.output_be_input!
+        when :filter
+          io_base.output_be_data!
+          # when :transform, :sync, :export, :error_handler, :other
+        end
+      end
+    end
+
+    protected
+
+    def output_be_input!
+      @input, @output = output, nil # rubocop:disable Style/ParallelAssignment
+      input
+    end
+
+    def output_be_data!
+      @data, @output = output, nil # rubocop:disable Style/ParallelAssignment
+      data
+    end
+  end
+end

data/lib/eco/api/usecases/base_io/validations.rb

@@ -0,0 +1,114 @@
+class Eco::API::UseCases::BaseIO
+  module Validations
+    class MissingParameter < ArgumentError
+      attr_reader :type, :required, :given, :klass
+
+      def initialize(msg = nil, required:, given:, type: nil, usecase: nil)
+        @type     = type
+        @required = required
+        @given    = given
+        @klass    = to_class(usecase)
+
+        msg = "#{msg} of type '#{type}'" if type
+        msg = "#{msg} (#{klass})"        if klass
+        msg = "#{msg} requires an object '#{required}'. Given: #{given}."
+        super(msg)
+      end
+
+      private
+
+      def to_class(value)
+        return       unless value
+        return value if value.is_a?(Class)
+
+        value.class
+      end
+    end
+
+    class << self
+      def included(base)
+        super
+        base.extend(ClassMethods)
+      end
+    end
+
+    module ClassMethods
+      def input_required?(type)
+        return true unless valid_type?(type)
+
+        %i[import sync].include?(type)
+      end
+
+      def data_required?(type)
+        return true unless valid_type?(type)
+
+        %i[filter transform sync error_handler export].include?(type)
+      end
+    end
+
+    # Instance Methods
+
+    private
+
+    def validate_args! # rubocop:disable Metrics/AbcSize
+      return true unless type
+
+      if !session.is_a?(Eco::API::Session)
+        raise MissingParameter.new(
+          'UseCase',
+          required: :session,
+          given:    session.class,
+          usecase:  self
+        )
+      elsif input_required? && !input
+        raise MissingParameter.new(
+          'UseCase',
+          type:     type,
+          required: :input,
+          given:    input.class,
+          usecase:  self
+        )
+      elsif missing_data?
+        raise MissingParameter.new(
+          'UseCase',
+          type:      type,
+          required:  model,
+          given:     data.class,
+          usecase:  self
+        )
+      elsif !options.is_a?(Hash)
+        raise MissingParameter.new(
+          'Use Case options',
+          required: :Hash,
+          given:    options.class,
+          usecase:  self
+        )
+      end
+
+      true
+    end
+
+    def missing_data?
+      return false unless data_required?
+
+      case model
+      when :people
+        !data.is_a?(Eco::API::Organization::People)
+      # when :contractors
+      #   !data.is_a?(Eco::API::Organization::Contractors)
+      when :other
+        false
+      else
+        true
+      end
+    end
+
+    def input_required?
+      self.class.input_required?(type)
+    end
+
+    def data_required?
+      self.class.data_required?(type)
+    end
+  end
+end

data/lib/eco/api/usecases/base_io.rb

@@ -3,74 +3,85 @@ module Eco
     class UseCases
       # Basic class to manage InputOuput for usecases
       class BaseIO < BaseCase
-        @types  = BaseCase.types
-
         include Eco::Language::Methods::DslAble
         include Eco::Language::AuxiliarLogger
 
-        class MissingParameter < StandardError
-          attr_reader :type, :required, :given
-
-          def initialize(msg = nil, required:, given:, type: nil)
-            @type     = type
-            @required = required
-            @given    = given
-            msg += " of type '#{type}'" if type
-            msg += " requires an object '#{required}'. Given: #{given}."
-            super(msg)
-          end
-        end
-
-        class << self
-          def input_required?(type)
-            !valid_type?(type) || %i[import sync].include?(type)
-          end
+        require_relative 'base_io/validations'
+        require_relative 'base_io/chaining'
 
-          def people_required?(type)
-            !valid_type?(type) || %i[filter transform sync error_handler export].include?(type)
-          end
-        end
+        include Validations
+        include Chaining
 
-        attr_reader   :input, :people, :session, :options
-        attr_reader   :type
+        attr_reader   :input, :data, :session, :options
+        attr_reader   :type, :model
         attr_accessor :output
 
         # @param type [Symbol] a valid type (among `self.class.types`)
         # @param input [Eco::API::Common::People::Entries, Eco::API::Organization::People] the input data of reference.
-        # @param people [Eco::API::Organization::People] people object.
+        # @param data [Variant] the base objects that sit in the backend.
+        #   The data as is it exists.
+        #   - people [Eco::API::Organization::People] people object.
         # @param session [Eco::API:Session]
         # @param options [Hash] hash with symbol keys (i.e. behaviour modifiers, cli trackers, filters, etc.)
         def initialize( # rubocop:disable Lint/MissingSuper
           session:,
-          type:    nil, input:  nil, people: nil,
-          options: {},  output: nil, validate: true
+          type:     nil,
+          model:    nil,
+          input:    nil,
+          data:     nil,
+          options:  {},
+          output:   nil,
+          validate: true,
+          people:   nil
         )
-          self.type = type if type
+          people  ||= data # backwards-compatibility
+          data    ||= people
+
+          self.type  = type  if type
+          self.model = model if model
 
-          if self.type && validate # rubocop:disable Style/IfUnlessModifier
-            validate_args(input: input, people: people, session: session, options: options)
-          end
+          @output  = output
+          @input   = input
+          @data    = data
+          @session = session
+          @options = options
 
-          @output      = output
-          @input       = input
-          @people      = people
-          @session     = session
-          @options     = options
+          validate_args! if validate
+        end
+
+        # backwards-compatibility
+        # @todo remove
+        def people
+          data
+        end
+
+        # @note used for DSLs
+        def io
+          self
         end
 
         # @param value [Symbol] a valid type (among `self.class.types`)
         def type=(value)
-          self.class.validate_type(value)
+          validate_type!(value)
+
           @type = value
         end
 
+        # @param value [Symbol] a valid type (among `self.class.models`)
+        def model=(value)
+          validate_model!(value)
+
+          @model = value
+        end
+
         # Helper to obtain an `BaseIO` object from any child class.
         # @return [Eco::API::UseCases::BaseIO]
         def base
           kargs = params(keyed: true).merge({
             type:   type,
+            model:  model,
             output: output
-          }).slice(:type, :input, :people, :session, :options, :output) # :validate <- ?
+          }).slice(*params_for_clone.keys)
 
           Eco::API::UseCases::BaseIO.new(**kargs)
         end
@@ -78,94 +89,33 @@ module Eco
         # @see Eco::API::UseCases::BaseIO#initialize
         # @return [Eco::API::UseCases::BaseIO]
         def new(**kargs)
-          default = {
-            type:     type,
-            input:    input,
-            people:   people,
-            session:  session,
-            options:  options,
-            output:   output,
-            validate: true
-          }
-          self.class.new(**default.merge(kargs))
+          self.class.new(**params_for_clone, **kargs)
         end
 
         # Helper to build a `Hash` of symbol keys or `Array` with params to do callbacks.
+        # @note order matters
         def params(keyed: false, all: false)
           kargs = {}
-          kargs.merge!(input:   input)   if input_required?  || all
-          kargs.merge!(people:  people)  if people_required? || all
+          kargs.merge!(input:   input)   if input_required? || all
+          kargs.merge!(data:    data)    if data_required?  || all
           kargs.merge!(session: session, options: options)
 
           keyed ? kargs : kargs.values
         end
 
-        # Shortcut to run a usecase passing this `io` as parameter
-        # @note
-        #   1. It swaps `output` to `input` or `people` depending on `self.type`
-        #   2. does this, **before** the target `case_name` launch and **after
-        # @return [Eco::API::UseCases::BaseIO]
-        def process_case(case_name, case_type, **params)
-          session.process_case(
-            case_name,
-            io:   chained,
-            type: case_type,
-            **params
-          ).chained
-        end
-
-        # Does the switch from output to result in a new IO object.
-        # @note if there isn't `output` it doesn't do the switch,
-        #   provided that it preserves the target parameter
-        #   (otherise it would blank it)
-        # @return [Eco::API::UseCases::BaseIO]
-        def chained(as: type) # rubocop:disable Naming/MethodParameterName
-          base.tap do |io_base|
-            next unless io_base.output
-
-            case as
-            when :import
-              io_base.output_be_input!
-            when :filter
-              io_base.output_be_people!
-              # when :transform, :sync, :export, :error_handler, :other
-            end
-          end
-        end
-
         protected
 
-        def output_be_input!
-          @input, @output = output, nil # rubocop:disable Style/ParallelAssignment
-          input
-        end
-
-        def output_be_people!
-          @people, @output = output, nil # rubocop:disable Style/ParallelAssignment
-          people
-        end
-
-        private
-
-        def validate_args(input:, people:, session:, options:)
-          if !session.is_a?(Eco::API::Session)
-            raise MissingParameter.new("UseCase", required: :session, given: session.class)
-          elsif input_required? && !input
-            raise MissingParameter.new("UseCase", type: type, required: :input, given: input.class)
-          elsif people_required? && !people.is_a?(Eco::API::Organization::People)
-            raise MissingParameter.new("UseCase", type: type, required: :people, given: people.class)
-          elsif !options || (options && !options.is_a?(Hash))
-            raise MissingParameter.new("Use Case options", required: :Hash, given: options.class)
-          end
-          true
-        end
-
-        def input_required?
-          self.class.input_required?(type)
-        end
-
-        def people_required?
-          self.class.people_required?(type)
+        def params_for_clone
+          {
+            type:     type,
+            model:    model,
+            input:    input,
+            data:     data,
+            session:  session,
+            options:  options,
+            output:   output,
+            validate: true
+          }
         end
       end
     end

data/lib/eco/api/usecases/cli/dsl.rb

@@ -34,6 +34,7 @@ module Eco
           # Unless specified, assume Cli class hangs from its case namespace
           def usecase
             raise "#{self} is to use to extend a class" unless is_a?(Class)
+
             @usecase ||= Kernel.const_get(to_s.split('::')[0..-2].join('::'))
           end
 
@@ -60,6 +61,7 @@ module Eco
 
           def callback(&block)
             return @callback unless block_given?
+
             @callback = block
           end
 
@@ -69,7 +71,7 @@ module Eco
 
           def add_option(arg, desc = nil, &block)
             tap do
-              "Overriding option '#{arg}' on case '#{name}'" if options.key?(arg)
+              puts "Overriding option '#{arg}' on case '#{name}'" if options.key?(arg)
               @options[arg] = Eco::API::UseCases::Cli::Option.new(arg, desc, &block)
             end
           end