eco-helpers 3.0.37 → 3.1.1

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

@@ -2,9 +2,7 @@ module Eco
   module API
     class Session
       class Config
-        class Workflow
-          extend Eco::API::Common::ClassHierarchy
-
+        class Workflow < Eco::API::UseCases::Workflow
           WORKFLOW_MODEL = [
             :options,
             {load: [{input: %i[get filter]}, {data: %i[get filter]}, :filter]},
@@ -16,377 +14,7 @@ module Eco
             :close
           ].freeze
 
-          class << self
-            def stages
-              model_attrs
-            end
-
-            def model
-              super || {}
-            end
-
-            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)
-              class_name = to_constant(key.to_s)
-
-              new_class(class_name, inherits: Eco::API::Session::Config::Workflow) do |klass|
-                klass.model = model[key]
-              end
-            end
-          end
-
           self.model = WORKFLOW_MODEL
-          attr_reader :config
-
-          def initialize(name = nil, config:, _parent: self) # rubocop:disable Lint/UnderscorePrefixedVariableName
-            @config   = config
-            @name     = name
-
-            @stages   = {}
-            @_parent  = _parent
-
-            @pending  = true
-            # moments
-            @on       = nil
-            @before   = []
-            @after    = []
-          end
-
-          def name(with_path: false)
-            return @name if !with_path || root?
-
-            [@_parent.name(with_path: true), @name].compact.join('.')
-          end
-
-          # Has this stage run yet?
-          # @note it does **not** include _sub-stages_ that run `before`
-          # @return [Boolean] `true` if it has run, `false` otherwise
-          def pending?
-            @pending
-          end
-
-          # Do not run this stage!
-          def skip!
-            @skip    = true
-            @pending = false
-          end
-
-          # Has this stage been marked as to be skipped
-          # @return [Boolean] depends on this order:
-          #   - `true` if `skip!` was called
-          #   - `false` if the current _stage_ is `root?` (the top stage of the hierarchy)
-          #   - `true` if its parent task is to be skipped
-          def skip?
-            return @skip if instance_variable_defined?(:@skip)
-            return false if root?
-
-            @_parent.skip?
-          end
-
-          # Used in **configuration** time **to configure** the _workflow_ of the target (sub)stage `key`
-          # @note
-          #   1. if a `block` is provided it will `yield` the target stage immediately
-          #   2. a `block` is only required when `key` has not been specified.
-          # @param key [Symbol, nil] cases:
-          #   - if `key` is not provided, it targets the _current stage_
-          #   - if `key` is provided, it targets the specific _sub-stage_
-          # @yield [stage_workflow] further _workflow_ configuration `for` the target stage `key`
-          # @yieldparam stage_workflow [Eco::API::Session::Config::Workflow] the _target stage_  referred by `key`
-          # @return [Eco::API::Session::Config::Workflow]
-          #   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)
-            msg = "With no 'key', a block should be given."
-            raise ArgumentError, msg unless key || block_given?
-
-            tap do
-              next yield(self)            unless key
-              next stage(key).for(&block) if block_given?
-
-              return stage(key)
-            end
-          end
-          alias_method :with, :for
-
-          # Used in **configuration** time **to define** the **behaviour**  the target (sub)stage `key`
-          # @note if a `block` is provided it will **not** `yield` the target stage immediately,
-          #   but when the _workflow_ reaches the stage
-          # @param key [Symbol, nil] cases:
-          #   - if `key` is not provided, it targets the _current stage_
-          #   - if `key` is provided, it targets the specific _sub-stage_
-          # @yield [stage_workflow, io] the behaviour of the target stage `key` when the _workflow_ reaches it
-          # @yieldparam stage_workflow [Eco::API::Session::Config::Workflow] the _target stage_  referred by `key`
-          # @yieldparam io [Eco::API::UseCases::BaseIO] the input/output object carried througout all the _workflow_
-          # @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)
-            msg = 'A block should be given.'
-            raise ArgumentError, msg unless block_given?
-
-            if key
-              stage(key).on(&block)
-            else
-              @on = block
-            end
-
-            self
-          end
-
-          # When there is an `Exception`, you might have defined some `callback`
-          # to do something with it (i.e. register, email)
-          # @yield [exception, io] the `callback` to do something with
-          #   an `Exception` raised within this _workflow_ stage
-          # @yieldparam exception [Exception] the exception object that was raised
-          # @yieldparam io [Eco::API::UseCases::BaseIO] the input/output object carried througout all the _workflow_
-          # @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 rescue(&block)
-            return @rescue unless block_given?
-
-            @rescue = block
-            self
-          end
-          # Prevent reserved word clash on DSL
-          alias_method :exception, :rescue
-
-          # Called on `SystemExit` exception
-          def exit_handle(&block)
-            return @exit_handle unless block_given?
-
-            @exit_handle = block
-            self
-          end
-
-          # Used in **configuration** time **add previous** `callbacks`
-          # **before** the `on` _callback_ of the (sub)stage `key` is actually `run`
-          # @note
-          #   - it will **not** `yield` it immediately, but when the _workflow_ reaches the target stage
-          #   - in this case, you can define multiple `callbacks`
-          # @param key [Symbol, nil] cases:
-          #   - if `key` is not provided, it targets the _current stage_
-          #   - if `key` is provided, it targets the specific _sub-stage_
-          # @yield [stage_workflow, io] one of the things to do **before** the
-          #  `on` _callback_ of the (sub)stage `key` is actually `run`
-          # @yieldparam stage_workflow [Eco::API::Session::Config::Workflow] the _target stage_  referred by `key`
-          # @yieldparam io [Eco::API::UseCases::BaseIO] the input/output object carried througout all the _workflow_
-          # @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)
-            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
-
-          # Used in **configuration** time **add previous** `callbacks` **after** the `on` _callback_
-          # of the (sub)stage `key` is actually `run`
-          # @note
-          #   - it will **not** `yield` it immediately, but when the _workflow_ reaches the target stage
-          #   - in this case, you can define multiple `callbacks`
-          # @param key [Symbol, nil] cases:
-          #   - if `key` is not provided, it targets the _current stage_
-          #   - if `key` is provided, it targets the specific _sub-stage_
-          # @yield [stage_workflow, io] one of the things to do **after** the
-          #   `on` _callback_ of the (sub)stage `key` is actually `run`
-          # @yieldparam stage_workflow [Eco::API::Session::Config::Workflow] the _target stage_  referred by `key`
-          # @yieldparam io [Eco::API::UseCases::BaseIO] the input/output object carried througout all the _workflow_
-          # @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)
-            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
-
-          # Used in run time to **execute the workflow** of the (sub)stage `key`
-          # @note if a `block` is **not** provided:
-          #   - it will run the `before` _callbacks_ defined during the configuration time
-          #   - it will run the _workflow_ of any defined _**substage**_ of the `key` stage
-          #   - it will run the `on` _callback_ defined during the configuration time
-          #   - it will mark the stage as **not** `pending?`.
-          #   - it will run the `after` _callbacks_ defined during the configuration time
-          # @note if a `block` is provided:
-          #   - it will **not** run the workflow of the substages to `key` stage
-          #   - it will **not** run the `callback` for `on` defined during the configuration time
-          #   - it will rather `yield` the target stage after all the `before` _callbacks_ have been run
-          #   - aside of this, the rest will be the same as when the _block_ is provided (see previous note)
-          # @note [if the object returned by `before`, `after` and `run` callbacks
-          #   is not an `Eco::API::UseCases::BaseIO`, the original `io` object will be returned instead.
-          # @param key [Symbol, nil] cases:
-          #   - if `key` is not provided, it targets the _current stage_
-          #   - if `key` is provided, it targets the specific _sub-stage_
-          # @param io [Eco::API::UseCases::BaseIO] the input/output object
-          # @yield [stage_workflow, io] if a `block` is provided, see `note`
-          # @yieldparam stage_workflow [Eco::API::Session::Config::Workflow] the _target stage_ referred by `key`
-          # @yieldparam io [Eco::API::UseCases::BaseIO] the input/output object carried througout all the _workflow_
-          # @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 run(key = nil, io:, &block)
-            raise 'Missing BaseIO object' unless io.is_a?(Eco::API::UseCases::BaseIO)
-
-            rescuable(io) do
-              if key
-                io = io_result(io: io) do
-                  stage(key).run(io: io, &block)
-                end
-              elsif pending?
-                io = run_before(io)
-                io = run_it(io, &block) unless skip?
-                io = run_after(io)
-              end
-              io
-            ensure
-              @pending = false
-            end
-          end
-
-          protected
-
-          def root?
-            @_parent == self
-          end
-
-          def path
-            return name if root?
-
-            "#{@_parent.path}:#{name}"
-          end
-
-          def ready?
-            !!@on
-          end
-
-          def run_before(io)
-            @before.each do |c|
-              io = io_result(io: io) do
-                io.evaluate(self, io, &c)
-              end
-            end
-
-            io
-          end
-
-          def run_after(io)
-            @after.each do |c|
-              io = io_result(io: io) do
-                io.evaluate(self, io, &c)
-              end
-            end
-
-            io
-          end
-
-          def run_it(io, &block)
-            io.session.log(:debug) {
-              "(Workflow: #{path}) running now"
-            }
-
-            if block
-              io = io_result(io: io) do
-                io.evaluate(self, io, &block)
-              end
-            else
-              existing_stages.each do |stg|
-                io = io_result(io: io) do
-                  stg.run(io: io)
-                end
-              end
-
-              unless ready?
-                io.session.log(:debug) {
-                  "(Workflow: #{path}) 'on' callback is not defined, nor block given"
-                }
-              end
-
-              io = io_result(io: io) do
-                io.evaluate(self, io, &@on)
-              end
-            end
-
-            io
-          ensure
-            @pending = false
-          end
-
-          # It ensures an `Eco::API::UseCases::BaseIO` is returned
-          # @note it always brings the IO to be a `BaseIO`.
-          #   As the `output` and the type is captured, it just cleans usecase related
-          #   logic from the object.
-          # @raise ArgumentError if `klass` isn't child of `Eco::API::UseCases::BaseIO`
-          # @return [Eco::API::UseCases::BaseIO] the `io` input/output object carried througout the _workflow_
-          def io_result(io:, klass: Eco::API::UseCases::BaseIO)
-            msg = "Expecting class to be child of Eco::API::UseCases::BaseIO. Given: #{klass}"
-            raise ErrorArgument, msg unless klass <= Eco::API::UseCases::BaseIO
-
-            result = yield
-            io = result if result.is_a?(klass)
-            io.instance_of?(klass) ? io : io.base
-          end
-
-          def existing_stages
-            # sort defined stages by stage order
-            sorted_keys = self.class.stages & @stages.keys
-            sorted_keys.map {|k| stage(k)}
-          end
-
-          def ready_stages
-            exiting_stages.select(&:ready?)
-          end
-
-          def stages_ready?
-            existing_stages.all?(&:ready?)
-          end
-
-          def stage(key)
-            self.class.validate_stage!(key)
-            @stages[key] ||= self.class.workflow_class(key).new(
-              key,
-              _parent: self,
-              config:  config
-            )
-          end
-
-          # helper to treat trigger the exit and rescue handlers
-          def rescuable(io)
-            yield
-          # rescue SystemStackError => err
-          #   puts err.patch_full_message(trace_count: 100)
-          #   exit 1
-          rescue SystemExit => err
-            io = io_result(io: io) do
-              io.evaluate(err, io, &exit_handle)
-            end
-
-            exit err.status
-          rescue Interrupt => _int
-            raise
-          rescue StandardError => err
-            # raise unless self.rescue
-            io = io_result(io: io) do
-              io.evaluate(err, io, &self.rescue)
-            end
-
-            raise
-          end
         end
       end
     end

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

@@ -209,8 +209,8 @@ module Eco
 
         def require(file = nil, match: nil)
           if match
-            file_manager.dir.dir_files(pattern: match).each do |file|
-              require_relative File.expand_path(file)
+            file_manager.dir.dir_files(pattern: match).each do |filename|
+              require_relative File.expand_path(filename)
             end
           else
             target = File.expand_path(file_manager.dir.file(file))
@@ -235,15 +235,36 @@ module Eco
         def location_codes
           org['location_codes']
         end
+        alias_method :locations_map_file, :location_codes
+
+        # @param internal [Symbol] either `:first` (default) or `:last`
+        # @param insensitive [Boolean] default `false`. Whether lookups are
+        #   case sensitive.
+        # @param maps_file [String] the location maps file (default: `locations_map_file`).
+        #   - Via `file_manager` it will try to spot the most recently changed.
+        #   - The lookup to spot the **path** of the file, tries first as a **relative**
+        #     path from `env/config/...`. If it fails, it tries it as an absolute path.
+        # @return [Eco::Data::Mapper, NilClass]
+        def locations_mapper(**kargs)
+          kargs = {
+            internal:    :first,
+            insensitive: false,
+            maps_file:   nil
+          }.merge(kargs)
 
-        def locations_mapper(insensitive: false)
-          return @locations_mapper if instance_variable_defined?(:@locations_mapper)
+          kargs[:maps_file] ||= locations_map_file
+          kargs[:maps_file]   = file_manager.newest(kargs[:maps_file])
 
-          file = file_manager.newest(location_codes)
-          @locations_mapper = Eco::Data::Mapper.new(
-            file_manager.load_json(file),
-            internal:    :first,
-            insensitive: insensitive
+          return unless kargs[:maps_file]
+
+          @locations_mapper ||= {}
+
+          return @locations_mapper[kargs] if @locations_mapper.key?(kargs)
+
+          @locations_mapper[kargs] = Eco::Data::Mapper.new(
+            file_manager.load_json(kargs[:maps_file]),
+            internal:    kargs[:internal],
+            insensitive: kargs[:insensitive]
           )
         end
 

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

@@ -1,5 +1,11 @@
 class Eco::API::UseCases::BaseCase
   module Model
+    MODELS = %i[
+      people
+      contractors
+      other
+    ].freeze
+
     class UnsupportedModel < ArgumentError
       def initialize(msg = nil, model:, models:)
         msg ||= "Unsupported model. "
@@ -8,12 +14,6 @@ class Eco::API::UseCases::BaseCase
       end
     end
 
-    MODELS = %i[
-      people
-      contractors
-      other
-    ].freeze
-
     class << self
       def included(base)
         super

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

@@ -9,7 +9,7 @@ module Eco
         include Type
         include Model
 
-        extend Eco::API::Common::ClassHelpers
+        extend Eco::Language::Klass::HelpersBuilt
       end
     end
   end

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

@@ -3,7 +3,7 @@ module Eco
   module API
     class UseCases
       class Cli
-        extend Eco::API::Common::ClassHelpers
+        extend Eco::Language::Klass::HelpersBuilt
 
         require_relative 'cli/dsl'
         extend DSL

data/lib/eco/api/usecases/default/locations/tagtree_extract_case.rb

@@ -1,16 +1,15 @@
 # Use case to export an org tree into some of the offered forms.
 class Eco::API::UseCases::Default::Locations::TagtreeExtract < Eco::API::UseCases::GraphQL::Samples::Location
   require_relative 'cli/tagtree_extract_cli'
-  #cli self::Cli
 
-  name "tagtree-extract"
+  name 'tagtree-extract'
   type :other
 
   include Eco::Data::Files
 
-  OUT_FOLDER      = "sftp".freeze
+  OUT_FOLDER      = 'sftp'.freeze
   OUT_TIME_FORMAT = '%Y%m%dT%H%M%S'.freeze
-  OUT_FILENAME    = "live_tree".freeze
+  OUT_FILENAME    = 'live_tree'.freeze
 
   def process
     case format
@@ -39,7 +38,7 @@ class Eco::API::UseCases::Default::Locations::TagtreeExtract < Eco::API::UseCase
   private
 
   def compact_name(str)
-    str.gsub(/\s+/, "_").gsub(/\W/, '')[0..30]
+    str.gsub(/\s+/, '_').gsub(/\W/, '')[0..30]
   end
 
   def str_node_attrs
@@ -80,7 +79,7 @@ class Eco::API::UseCases::Default::Locations::TagtreeExtract < Eco::API::UseCase
   end
 
   def indentation
-    options.dig(:output, :indent) || "  "
+    options.dig(:output, :indent) || '  '
   end
 
   def output_file_format
@@ -169,7 +168,7 @@ class Eco::API::UseCases::Default::Locations::TagtreeExtract < Eco::API::UseCase
       out_str   = str_ary.join("\n") unless str_ary.empty?
 
       unless tree.top?
-        node_name = tree.as_json(include_children: false).values_at(*attrs.map(&:to_s)).join(" ## ")
+        node_name = tree.as_json(include_children: false).values_at(*attrs.map(&:to_s)).join(' ## ')
         out_head  = "#{indent * level}#{node_name}"
         out_str   = out_str ? "#{out_head}\n#{out_str}" : out_head
       end
@@ -178,7 +177,7 @@ class Eco::API::UseCases::Default::Locations::TagtreeExtract < Eco::API::UseCase
   end
 
   def csv(filename, header = [])
-    CSV.open(filename, "w") do |csv|
+    CSV.open(filename, 'w') do |csv|
       csv << header unless header.empty?
 
       yield(csv)
@@ -188,7 +187,7 @@ class Eco::API::UseCases::Default::Locations::TagtreeExtract < Eco::API::UseCase
   end
 
   def file(filename, &block)
-    File.open(filename, "w", &block)
+    File.open(filename, 'w', &block)
   ensure
     log(:info) { "Created file: #{filename}" }
   end

data/lib/eco/api/usecases/default_cases/to_csv_case.rb

@@ -88,7 +88,10 @@ class Eco::API::UseCases::DefaultCases::ToCsvCase < Eco::API::Common::Loaders::U
   def out_filename
     return options_file unless options_folder?
 
-    File.join(options_file, "#{config.active_enviro}_#{OUT_FILENAME}.csv")
+    File.join(
+      options_file,
+      "#{config.active_enviro}_#{OUT_FILENAME}.csv"
+    )
   end
 
   def in_folder(filename)

data/lib/eco/api/usecases/graphql/samples/location/command/dsl.rb

@@ -17,8 +17,8 @@ class Eco::API::UseCases::GraphQL::Samples::Location
     #       end
     #     end
     def inputs(*_args, force_continue: force_continue?, **_kargs, &_block) # rubocop:disable Lint/UnusedMethodArgument
-      msg  = "You should implement this method in your child class.\n'
-      msg << 'Which should yield the input Hash and the stage or descriptor."
+      msg  = "You should implement this method in your child class.\n"
+      msg << 'Which should yield the input Hash and the stage or descriptor.'
       raise Eco::API::UseCases::GraphQL::Base::NotImplementedMethod, msg
     end
 

data/lib/eco/api/usecases/lib/base/env.rb

@@ -1,6 +1,6 @@
 module Eco::API::UseCases::Lib::Base
   # Basic stuff you would need in any use case
-  # @note this is intended to be at the foremost part upfront
+  # @note this is intended to be at the foremost part upfront: with **prepend**.
   module Env
     class << self
       def included(base)
@@ -14,32 +14,30 @@ module Eco::API::UseCases::Lib::Base
     module InstanceMethods
       private
 
-      def config
-        session.config
-      end
-
       def session(required: true)
-        if instance_variable_defined?(:@session) && !@session.nil?
-          @session
-        elsif defined?(super) && !super.nil?
-          super
-        elsif Object.const_defined?(:ASSETS)
-          ASSETS.session
-        elsif required
-          raise 'Missing session object'
-        end
+        return @session       if instance_variable_defined?(:@session) && !@session.nil?
+        return super()        if defined?(super()) && !super().nil?
+        return ASSETS.session if Object.const_defined?(:ASSETS)
+        return                unless required
+
+        raise 'Missing session object'
       end
 
       def options(required: true)
-        if instance_variable_defined?(:@options) && !@options.nil?
-          @options
-        elsif defined?(super) && !super.nil?
-          super
-        elsif Object.const_defined?(:ASSETS)
-          ASSETS.cli.options
-        else
-          raise 'Missing options object'
-        end
+        return @options           if instance_variable_defined?(:@options) && !@options.nil?
+        return super()            if defined?(super()) && !super().nil?
+        return ASSETS.cli.options if Object.const_defined?(:ASSETS)
+        return                    unless required
+
+        raise 'Missing options object'
+      end
+
+      def config
+        session.config
+      end
+
+      def micro
+        session.micro
       end
     end
   end