eco-helpers 2.4.4 → 2.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c2d5e728987bee135ac2297b0a84858dfb14eab79b3decebc59ced1a74ccc4a
-  data.tar.gz: b906c449d80dbc1440c1b7e7d91565bad53409167cae3c07b0788870f842cf5e
+  metadata.gz: 333d58d63c6ffad6b06865c89dce3e48a50347ba998361f34eb9a2e230ea83f2
+  data.tar.gz: 7be152e20c00765217b6650790dfd4aeba729bb614e6d0928a7e7ea82d94de33
 SHA512:
-  metadata.gz: e7a9781490f01e1d9ffafdec19179d492d760c9dca676e2e6f2771b61a8f422d5c9f481bb03c71563c91df97b72f89cee0e8aa664be42dcf1dd5d99576177add
-  data.tar.gz: 44eed6e779b8ffdfdc1bea5913090713cc15dba649b7c2eddc9f333a8be67f92afa1ec6e1d06b0c31bcf2b29d062b92cac26c7c53b07404e50d089ae56698202
+  metadata.gz: 3cb79f7d5429bf4c3cd8b8b37cbbdb2b8208da2161559fb6a09b08a67cea1ded2d08355928af4ee136b39bc10fda3f82ece275f5991c65bfcf41c4290d7d7269
+  data.tar.gz: 78723001238f02cac999e2af5200e1e13f444572366291357a70ec951732ded65bd708be9b6c0259a9e6bf797fc5c803df17a28167d01b1bf1223900f8226cc7

data/CHANGELOG.md

@@ -1,12 +1,27 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [2.4.5] - 2023-03-xx
+## [2.4.6] - 2023-03-xx
 
 ### Added
 ### Changed
 ### Fixed
 
+## [2.4.5] - 2023-03-31
+
+### Added
+  - `Eco::API:Organization::TagTree` support for `archived` and `weight` properties
+  - `Eco::Data::Hashes::ArrayDiff` and `Eco::Data::Hashes::DiffResult`
+    - Enable easy comparison of array of hashes
+    - Input data can be diverse
+
+### Fixed
+  - `Eco::API::UseCases::DefaultCases::CsvToTree`
+    - Fixed the missed alignment children that jump levels
+  - `Eco::API::UseCases::DefaultCases::CsvToTree::Node`
+    - `to_h`: attrs param was being ingnored.
+
+
 ## [2.4.4] - 2023-03-29
 
 ### Added

data/lib/eco/api/common/people/entry_factory.rb

@@ -9,6 +9,7 @@ module Eco
         # Helper factory class to generate entries (input entries).
         # @attr_reader schema [Ecoportal::API::V1::PersonSchema] person schema to be used in this entry factory
         class EntryFactory < Eco::API::Common::Session::BaseSession
+          include Eco::Data::Files
 
           attr_reader :schema, :person_parser
 
@@ -111,7 +112,10 @@ module Eco
             end
             # Get content only when it's not :xls
             # note: even if content was provided, file takes precedence
-            content = get_file_content(file, format, encoding) if (format != :xls) && file
+            if (format != :xls) && file
+              content = get_file_content(file, encoding)
+            end
+            #content = get_file_content(file, format, encoding) if (format != :xls) && file
 
             case content
             when Hash
@@ -142,10 +146,8 @@ module Eco
                 entry_hash["source_file"] = file
               end
             end
-
           end
 
-
           # Helper that generates a file out of `data:`.
           # @raise Exception
           #   - if you try to provide `data:` in the wrong format.
@@ -164,7 +166,7 @@ module Eco
             fatal("There is no parser/serializer for format ':#{format.to_s}'") unless @person_parser.defined?(format)
 
             run = true
-            if Eco::API::Common::Session::FileManager.file_exists?(file)
+            if self.class.file_exists?(file)
               prompt_user("Do you want to overwrite it? (Y/n):", explanation: "The file '#{file}' already exists.", default: "Y") do |response|
                 run = (response == "") || response.upcase.start_with?("Y")
               end
@@ -183,41 +185,10 @@ module Eco
                 fd.write(person_parser.serialize(format, data_entries))
               end
             end
-
           end
 
           private
 
-          def get_file_content(file, format, encoding)
-            unless Eco::API::Common::Session::FileManager.file_exists?(file)
-              logger.error("File does not exist: #{file}")
-              exit(1)
-            end
-            #ext        = File.extname(file)
-            encoding ||= Eco::API::Common::Session::FileManager.encoding(file)
-            encoding   = (encoding == "bom") ? "#{encoding}|utf-8": encoding
-            puts "File encoding: '#{encoding}'" unless !encoding || encoding == 'utf-8'
-            read_with_tolerance(file, encoding: encoding)
-          end
-
-          def read_with_tolerance(file, encoding:)
-            if content = File.read(file, encoding: encoding)
-              content = content.encode("utf-8") unless encoding.include?('utf-8')
-              tolerance = 5
-              content.scrub do |bytes|
-                replacement = '<' + bytes.unpack('H*')[0] + '>'
-                if tolerance <= 0
-                  logger.error("There were more than 5 encoding errors in the file '#{file}'.")
-                  return content
-                else
-                  tolerance -= 1
-                  logger.error("Encoding problem in file '#{file}': '#{replacement}'.")
-                  replacement
-                end
-              end
-            end
-          end
-
           def fatal(msg)
             logger.fatal(msg)
             raise msg

data/lib/eco/api/common/session/file_manager.rb

@@ -88,7 +88,6 @@ module Eco
             File.open(file, mode) { |fd| fd << content + "\n" } # '\n' won't add line
             return file
           end
-
         end
       end
     end

data/lib/eco/api/organization/tag_tree.rb

@@ -5,7 +5,7 @@ module Eco
       class TagTree
         attr_accessor :id
         alias_method :tag, :id
-        attr_accessor :name
+        attr_accessor :name, :archived, :weight
 
         attr_reader :parent
         attr_reader :nodes, :children_count
@@ -24,7 +24,7 @@ module Eco
         #    ]}]
         #    tree = TagTree.new(tree.to_json)
         # @param tagtree [String] representation of the tagtree in json.
-        def initialize(tagtree = [], name: nil, id: nil, depth: -1, path: [], parent: nil, enviro: nil)
+        def initialize(tagtree = [], name: nil, id: nil, depth: -1, path: [], parent: nil, _weight: nil, enviro: nil)
           @depth  = depth
           @parent = parent
 
@@ -39,25 +39,31 @@ module Eco
           @enviro = enviro
 
           if @source.is_a?(Array)
-            @id    = id
-            @name  = name
+            @id        = id
+            @name      = name
             @row_nodes = @source
           else
-            @id    = @source.values_at('tag', 'id').compact.first&.upcase
-            @name  = @source['name']
+            @id        = @source.values_at('tag', 'id').compact.first&.upcase
+            @name      = @source['name']
+            @archived  = @source.fetch('archived', false)
+            @weight    = @source.fetch('weight', _weight)
             @row_nodes = @source['nodes'] || []
           end
 
           @path  = path || []
           @path.push(@id) unless top?
 
-          @nodes = @row_nodes.map do |cnode|
-            TagTree.new(cnode, depth: depth + 1, path: @path.dup, parent: self, enviro: @enviro)
+          @nodes = @row_nodes.map.with_index do |cnode, idx|
+            TagTree.new(cnode, depth: depth + 1, path: @path.dup, parent: self, _weight: idx, enviro: @enviro)
           end
 
           init_hashes
         end
 
+        def archived?
+          @archived
+        end
+
         # @return [Eco::API::Organization::TagTree]
         def dup
           self.class.new(as_json)

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

@@ -20,9 +20,9 @@ module Eco
           end
 
           # Among all the locations structures it selects the one with more location nodes
-          def live_tree(enviro: nil)
+          def live_tree(enviro: nil, include_archived: false)
             return @live_tree if instance_variable_defined?(:@live_tree) && @live_tree.enviro == enviro
-            trees = live_trees(enviro: enviro)
+            trees = live_trees(enviro: enviro, include_archived: include_archived)
             @live_tree = trees.reject do |tree|
               tree.empty?
             end.max do |a,b|
@@ -36,12 +36,12 @@ module Eco
           end
 
           # Retrieves all the location structures of the organisation
-          def live_trees(enviro: nil)
+          def live_trees(enviro: nil, include_archived: false)
             [].tap do |eco_trees|
               next unless apis.active_api.version_available?(:graphql)
               next unless graphql = apis.api(version: :graphql)
               kargs = {
-                includeArchived: false,
+                includeArchived:    include_archived,
                 includeUnpublished: false
               }
               next unless trees = graphql.currentOrganization.locationStructures(**kargs)

data/lib/eco/api/session.rb

@@ -45,7 +45,7 @@ module Eco
       end
 
       # @see Eco::API::Session::Config#live_tree
-      def live_tree
+      def live_tree(include_archived: false)
         config.live_tree(enviro: enviro)
       end
 

data/lib/eco/api/usecases/default_cases/csv_to_tree_case/helper.rb

@@ -14,9 +14,9 @@ class Eco::API::UseCases::DefaultCases::CsvToTree
         result
       end
 
-      def csv_nodes(filename)
+      def nodes_from_csv(csv)
         i = 1; prev_level = nil; prev_node = nil; prev_nodes = Array(1..11).zip(Array.new(11, nil)).to_h
-        nodes = csv_from(filename).each_with_object([]) do |row, out|
+        nodes = csv.each_with_object([]) do |row, out|
           values = row.fields.map do |value|
             value = value.to_s.strip
             value.empty?? nil : value
@@ -41,6 +41,10 @@ class Eco::API::UseCases::DefaultCases::CsvToTree
         tidy_nodes(nodes)
       end
 
+      def csv_nodes(filename)
+        nodes_from_csv(csv_from(filename))
+      end
+
       private
 
       def csv_from_content(filename)

data/lib/eco/api/usecases/default_cases/csv_to_tree_case/node.rb

@@ -25,19 +25,29 @@ class Eco::API::UseCases::DefaultCases::CsvToTree
 
     def tag
       raw_tag.yield_self do |str|
-        partial = replace_not_allowed(str)
+        blanks_x2 = has_double_blanks?(str)
+        partial   = replace_not_allowed(str)
         remove_double_blanks(partial).tap do |result|
+          next if invalid_warned?
           if partial != str
             invalid_chars = identify_invalid_characters(str)
             puts "• (Row: #{self.row_num}) Invalid characters _#{invalid_chars}_ (removed): '#{str}' (converted to '#{result}')"
+          elsif blanks_x2
+            puts "• (Row: #{self.row_num}) Double blanks (removed): '#{str}' (converted to '#{result}')"
           end
-          if result != partial
-            #puts "• There were DOUBLE BLANKS: tag '#{str}' (converted to '#{result}')"
-          end
+          invalid_warned!
         end
       end
     end
 
+    def invalid_warned?
+      @invalid_warned ||= false
+    end
+
+    def invalid_warned!
+      @invalid_warned = true
+    end
+
     def raw_tag
       values_at(*TAGS_ATTRS.reverse).compact.first
     end
@@ -163,7 +173,7 @@ class Eco::API::UseCases::DefaultCases::CsvToTree
 
     def to_h(*attrs)
       attrs = ALL_ATTRS if attrs.empty?
-      ALL_ATTRS.zip(values_at(*ALL_ATTRS)).to_h
+      attrs.zip(values_at(*attrs)).to_h
     end
 
     def slice(*attrs)
@@ -188,6 +198,11 @@ class Eco::API::UseCases::DefaultCases::CsvToTree
       TAGS_ATTRS.length
     end
 
+    def has_double_blanks?(str)
+      return false if str.nil?
+      str.match(DOUBLE_BLANKS)
+    end
+
     def remove_double_blanks(str)
       return nil if str.nil?
       str.gsub(DOUBLE_BLANKS, ' ').strip

data/lib/eco/api/usecases/default_cases/csv_to_tree_case/nodes_cleaner.rb

@@ -12,7 +12,7 @@ class Eco::API::UseCases::DefaultCases::CsvToTree
       nodes.tap do |nodes|
         prev_nodes = Array(1..11).zip(Array.new(11, nil)).to_h
         nodes.each do |node|
-          if parent_node = prev_nodes[node.raw_level - 1]
+          if parent_node = prev_nodes[node.actual_level - 1]
             node.parentId = parent_node.id
           end
           prev_nodes[node.raw_level] = node

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

@@ -15,10 +15,16 @@ class Eco::API::UseCases::GraphQL::Base < Eco::API::Common::Loaders::UseCase
     raise "You need to inherit from this class ('#{self.class}') and call super with a block"
   end
 
+  private
+
   def graphql
     @graphql ||= session.api(version: :graphql)
   end
 
+  def simulate?
+    options.dig(:simulate)
+  end
+
   def exit_error(msg)
     logger.error(msg)
     exit(1)

data/lib/eco/api/usecases/graphql/helpers/locations/commands.rb

@@ -0,0 +1,4 @@
+module Eco::API::UseCases::GraphQL::Helpers::Locations
+  class Commands
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/locations.rb

@@ -0,0 +1,6 @@
+module Eco::API::UseCases::GraphQL::Helpers
+  module Locations
+  end
+end
+
+require_relative 'locations/commands'

data/lib/eco/api/usecases/graphql/helpers.rb

@@ -0,0 +1,6 @@
+module Eco::API::UseCases::GraphQL
+  module Helpers
+  end
+end
+
+require_relative 'helpers/locations'

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

@@ -8,3 +8,4 @@ module Eco
 end
 
 require_relative 'graphql/base'
+require_relative 'graphql/helpers'

data/lib/eco/data/files/helpers.rb

@@ -9,9 +9,44 @@ module Eco
           base.extend(ClassMethods)
         end
       end
-      
-      module InstanceMethods
 
+      module InstanceMethods
+        include Eco::Language::AuxiliarLogger
+
+        # It offers a resilient way to read content from a file
+        # @tolerance [Integer] the number of allowed encoding errors.
+        # @return [String] the content of the file
+        def get_file_content(file, encoding, tolerance: 5)
+          unless self.class.file_exists?(file)
+            logger.error("File does not exist: #{file}")
+            exit(1)
+          end
+          encoding ||= self.class.encoding(file)
+          encoding   = (encoding == "bom") ? "#{encoding}|utf-8": encoding
+          unless !encoding || encoding == 'utf-8'
+            msg = "File encoding: '#{encoding}'"
+            logger.debug(msg)
+            puts msg
+          end
+          read_with_tolerance(file, encoding: encoding, tolerance: tolerance)
+        end
+
+        def read_with_tolerance(file, encoding:, tolerance: 5)
+          if content = File.read(file, encoding: encoding)
+            content = content.encode("utf-8") unless encoding.include?('utf-8')
+            content.scrub do |bytes|
+              replacement = '<' + bytes.unpack('H*')[0] + '>'
+              if tolerance <= 0
+                logger.error("There were more than 5 encoding errors in the file '#{file}'.")
+                return content
+              else
+                tolerance -= 1
+                logger.error("Encoding problem in file '#{file}': '#{replacement}'.")
+                replacement
+              end
+            end
+          end
+        end
       end
 
       module ClassMethods
@@ -86,12 +121,28 @@ module Eco
           path = File.dirname($0)
           File.join(path, basename)
         end
+
+        def folder_files(folder = ".", pattern = "*", regexp: nil, older_than: nil)
+          target = File.join(File.expand_path(folder), pattern)
+          Dir[target].tap do |dir_files|
+            dir_files.select! {|f| File.file?(f)}
+            if older_than
+              dir_files.select! {|f| File.mtime(f) < (Time.now - (60*60*24*older_than))}
+            end
+            if regexp && regexp.is_a?(Regexp)
+              dir_files.select! {|f| File.basename(f).match(regexp)}
+            end
+          end.sort
+        end
+
+        def csv_files(folder = ".", regexp: nil, older_than: nil)
+          folder_files(folder, "*.csv", regexp: regexp, older_than: older_than).sort
+        end        
       end
 
       class << self
         include Files::ClassMethods
       end
-
     end
   end
 end

data/lib/eco/data/hashes/array_diff.rb

@@ -0,0 +1,154 @@
+module Eco
+  module Data
+    module Hashes
+      class ArrayDiff
+        extend Eco::Language::Models::ClassHelpers
+
+        class << self
+          def key(value = nil)
+            return @key unless value
+            @key = value.to_s
+          end
+
+          def key?
+            !!@key
+          end
+
+          def compare(*attrs)
+            compared_attrs.push(*attrs.map(&:to_s)).uniq!
+          end
+
+          def case_sensitive(value = nil)
+            @case_sensitive = false unless instance_variable_defined?(:@case_sensitive)
+            return @case_sensitive unless value
+            @case_sensitive = !!value
+          end
+
+          def case_sensitive?
+            !!@case_sensitive
+          end
+
+          def compared_attrs
+            @compared_attrs ||= []
+            @compared_attrs
+          end
+        end
+
+        attr_reader :source1, :source2
+        attr_reader :src_h1,  :src_h2
+        attr_reader :logger
+
+        class_resolver :diff_result_class, "Eco::Data::Hash::DiffResult"
+
+        def initialize(source1, source2, logger: ::Logger.new(IO::NULL), **kargs)
+          @logger  = logger
+          @options = kargs
+          @source1 = source1
+          @source2 = source2
+          @src_h1  = by_key(source1)
+          @src_h2  = by_key(source2)
+          raise "Missing source1" unless !!self.src_h1
+          raise "Missing source2" unless !!self.src_h2
+        end
+
+        # @note
+        #   - A `Hash::DiffResult` object, offers `hash_diff` with the attrs that have changed value
+        #   - It also allows to know the original value
+        # @return [Hash] where `key` is the key of the record, and `value` a `DiffResult` object
+        def diffs
+          @diffs ||= paired_sources.each_with_object([]) do |(src1, src2), diffs|
+            args = {
+              key:            key,
+              compare:        compared_attrs,
+              case_sensitive: case_sensitive?
+            }
+            diff_result_class.new(src1, src2, **args).tap do |res|
+              diffs << res if res.diff?
+            end
+          end
+        end
+
+        protected
+
+        # It pairs the hashes of `source1` and `source2`
+        # @note
+        #   - It also ensures they are in their Hash form (with string keys)
+        #   - This will merge entries of the same source that hold the same `key` attr value (latest wins)
+        def paired_sources
+          keys1 = src_h1.keys; keys2 = src_h2.keys
+          all_keys = keys1 | keys2
+          all_keys.map {|key| [src_h1[key], src_h2[key]]}
+        end
+
+        def key
+          @key ||= options_or(:key) do
+            self.class.key
+          end.tap do |k|
+            raise "missing main key attr to pair records. Given: #{k}" unless k.is_a?(String)
+          end
+        end
+
+        def case_sensitive?
+          @case_sensitive ||= options_or(:case_sensitive) { self.class.case_sensitive? }
+        end
+
+        def compared_attrs
+          @compared_attrs ||= options_or(:compared_attrs) do
+            self.class.compared_attrs
+          end.yield_self do |attrs|
+            raise "compared_attrs should be an array" unless attrs.is_a?(Array)
+            attrs.map(&:to_s)
+          end
+        end
+
+        private
+
+        def options_or(opt)
+          opt = opt.to_sym
+          return @options[opt] if @options.key?(opt)
+          yield
+        end
+
+        def symbolize_keys(hash)
+          hash.each_with_object({}) do |(k, v), h|
+            h[k.to_sym] = v
+          end
+        end
+
+        def stringify_keys(hash)
+          hash.each_with_object({}) do |(k, v), h|
+            h[k.to_s] = v
+          end
+        end
+
+        def by_key(content)
+          to_array_of_hashes(content).each_with_object({}) do |item, out|
+            out[item[key]] = item
+          end
+        end
+
+        def to_array_of_hashes(content)
+          case content
+          when Hash
+            logger.error("Input data as 'Hash' not supported. Expecting 'Enumerable' or 'String'")
+            exit(1)
+          when String
+            to_array_of_hashes(Eco::CSV.parse(content))
+          when Enumerable
+            sample = content.to_a.first
+            case sample
+            when Hash, Array, ::CSV::Row
+              Eco::CSV::Table.new(content).to_array_of_hashes
+            else
+              logger.error("Input content 'Array' of '#{sample.class}' is not supported.")
+              exit(1)
+            end
+          else
+            logger.error("Could not obtain any data out content: '#{content.class}'")
+            exit(1)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/data/hashes/diff_result.rb

@@ -0,0 +1,103 @@
+module Eco
+  module Data
+    module Hashes
+      class DiffResult
+
+        attr_reader :key
+        attr_reader :src1, :src2
+
+        # @param [Array<String>, sym]
+        #   - `:all` compares the matching attrs between both hashes only
+        def initialize(src1, src2, key:, compare: :all, case_sensitive: false)
+          @key     = key
+          @compare = compare
+          @case_sensitive = case_sensitive
+          @src1 = src1
+          @src2 = src2
+        end
+
+        def new?
+          !src1 && !!src2
+        end
+
+        def del?
+          !!src1 && !src2
+        end
+
+        def update?
+          !new? && !del? && diff?
+        end
+
+        def diff?
+          new? || del? || !diff_attrs.empty?
+        end
+
+        # Is the key attr value changing?
+        def key?
+          !(new? || del?) && diff_attr?(key)
+        end
+
+        def diff_attr?(attr)
+          return true if new?
+          return true if del?
+          diff_attrs.include?(attr.to_s)
+        end
+
+        def attr(attr)
+          return nil unless src2
+          src2[attr.to_s]
+        end
+
+        def attr_prev(attr)
+          return nil unless src1
+          src1[attr.to_s]
+        end
+
+        def previous(attr)
+          src1 && src1[attr.to_s]
+        end
+
+        def diff_hash
+          target_attrs = [key] | compared_attrs
+          return src2.slice(*target_attrs) if new?
+          return src1.slice(key)           if del?
+          src2.slice(key, *diff_attrs)
+        end
+
+        def diff_attrs
+          @diff_attrs ||= comparable_attrs.each_with_object([]) do |attr, out|
+            out << attr unless eq?(src1[attr], src2[attr])
+          end
+        end
+
+        def eq?(val1, val2)
+          return true  if val1 == val2
+          return false if case_sensitive?
+          return false if !val2 || !val1
+          val1.upcase == val2.upcase
+        end
+
+        def case_sensitive?
+          !!@case_sensitive
+        end
+
+        def comparable_attrs
+          return [] if new? || del?
+          compared_attrs
+        end
+
+        def compared_attrs
+          return @compared_attrs if instance_variable_defined?(:@compared_attrs)
+          @compared_attrs = \
+            if @compare == :all
+              src1.keys & src2.keys
+            elsif @compare.is_a?(Array)
+              @compare.map(&:to_s)
+            else
+              raise "Expecting 'compare' to be sym (:all) or Array<String>. Given: #{@compare.class}"
+            end
+        end
+      end
+    end
+  end
+end

data/lib/eco/data/hashes.rb

@@ -0,0 +1,9 @@
+module Eco
+  module Data
+    module Hashes
+    end
+  end
+end
+
+require_relative 'hashes/diff_result'
+require_relative 'hashes/array_diff'

data/lib/eco/data.rb

@@ -7,3 +7,4 @@ require_relative 'data/crypto'
 require_relative 'data/files'
 require_relative 'data/mapper'
 require_relative 'data/fuzzy_match'
+require_relative 'data/hashes'

data/lib/eco/language/auxiliar_logger.rb

@@ -0,0 +1,19 @@
+module Eco
+  module Language
+    # Some modules/classes use logger, but they may not be connected to session.
+    # This prevents errors with this.
+    module AuxiliarLogger
+      def logger
+        if defined?(super)
+          super
+        elsif respond_to?(:session)
+          session.logger
+        elsif instance_variable_defined?(:@session)
+          @session.logger
+        else
+          @logger ||= ::Logger.new(IO::NULL)
+        end
+      end
+    end
+  end
+end

data/lib/eco/language/models/class_helpers.rb

@@ -0,0 +1,134 @@
+module Eco
+  module Language
+    module Models
+      module ClassHelpers
+        NOT_USED = "no_used!"
+
+        def redef_without_warning(const, value)
+          self.class.send(:remove_const, const) if self.class.const_defined?(const)
+          self.class.const_set(const, value)
+        end
+
+        def class_resolver(name, klass)
+          define_singleton_method(name) { resolve_class(klass) }
+          define_method(name) { self.class.resolve_class(klass) }
+        end
+
+        # Class resolver
+        # @note it caches the resolved `klass`es
+        # @raise [Exception] when could not resolve if `exception` is `true`
+        # @param klass [Class, String, Symbol] the class to resolve
+        # @param source_class [Class] when the reference to `klass` belongs to a different inheritance chain.
+        # @param exception [Boolean] if it should raise exception when could not resolve
+        # @return [Class] the `Class` constant
+        def resolve_class(klass, source_class: self, exception: true)
+          @resolved ||= {}
+          @resolved[klass] ||=
+            case klass
+              when Class
+                klass
+              when String
+                begin
+                  Kernel.const_get(klass)
+                rescue NameError => e
+                  raise if exception
+                end
+              when Symbol
+                source_class.resolve_class(source_class.send(klass))
+              when Hash
+                referrer, referred = klass.first
+                resolve_class(referred, source_class: referrer, exception: exception)
+              else
+                raise "Unknown class: #{klass}" if exception
+            end
+        end
+
+        # Helper to normalize `key` into a correct `ruby` **constant name**
+        # @note it removes namespace syntax `::`
+        # @param key [String, Symbol] to be normalized
+        # @return [String] a correct constant name
+        def to_constant(key)
+          str_name = key.to_s.strip.split(/::/).compact.map do |str|
+            str.slice(0).upcase + str.slice(1..-1)
+          end.join("").split(/[\-\_ :]+/i).compact.map do |str|
+            str.slice(0).upcase + str.slice(1..-1)
+          end.join("")
+        end
+
+        # Helper to create an instance variable `name`
+        # @param [String, Symbol] the name of the variable
+        # @reutrn [String] the name of the created instance variable
+        def instance_variable_name(name)
+          str = name.to_s
+          str = "@#{str}" unless str.start_with?("@")
+          str
+        end
+
+        # If the class for `name` exists, it returns it. Otherwise it generates it.
+        # @param name [String, Symbol] the name of the new class
+        # @param inherits [Class] the parent class to _inherit_ from
+        # @param namespace [Class, String] an existing `constant` (class or module) the new class will be namespaced on
+        # @yield [child_class] configure the new class
+        # @yieldparam child_class [Class] the new class
+        # @return [Class] the new generated class
+        def new_class(name = "Child#{uid}", inherits: self, namespace: inherits)
+          name            = name.to_s.to_sym.freeze
+          class_name      = to_constant(name)
+
+          unless target_class = resolve_class("#{namespace}::#{class_name}", exception: false)
+            target_class = Class.new(inherits)
+            Kernel.const_get(namespace.to_s).const_set class_name, target_class
+          end
+
+          target_class.tap do |klass|
+            yield(klass) if block_given?
+          end
+        end
+
+        # Helper to determine if a paramter has been used
+        # @note to effectivelly use this helper, you should initialize your target
+        #  paramters with the constant `NOT_USED`
+        # @param val [] the value of the paramter
+        # @return [Boolean] `true` if value other than `NOT_USED`, `false` otherwise
+        def used_param?(val)
+          val != NOT_USED
+        end
+
+        # Keeps track on class instance variables that should be inherited by child classes.
+        # @note
+        #   - subclasses will inherit the value as is at that moment
+        #   - any change afterwards will be only on the specific class (in line with class instance variables)
+        #   - adapted from https://stackoverflow.com/a/10729812/4352306
+        # TODO: this separates the logic of the method to the instance var. Think if would be possible to join them somehow.
+        def inheritable_class_vars(*vars)
+          @inheritable_class_vars ||= [:inheritable_class_vars]
+          @inheritable_class_vars += vars
+        end
+
+        # Builds the attr_reader and attr_writer of `attrs` and registers the associated instance variable as inheritable.
+        def inheritable_attrs(*attrs)
+          attrs.each do |attr|
+            class_eval %(
+              class << self; attr_accessor :#{attr} end
+            )
+          end
+          inheritable_class_vars(*attrs)
+        end
+
+        # This callback method is called whenever a subclass of the current class is created.
+        # @note
+        #   - values of the instance variables are copied as they are (no dups or clones)
+        #   - the above means: avoid methods that change the state of the mutable object on it
+        #   - mutating methods would reflect the changes on other classes as well
+        #   - therefore, `freeze` will be called on the values that are inherited.
+        def inherited(subclass)
+          inheritable_class_vars.each do |var|
+            instance_var = instance_variable_name(var)
+            value        = instance_variable_get(instance_var)
+            subclass.instance_variable_set(instance_var, value.freeze)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/language/models.rb

@@ -5,6 +5,7 @@ module Eco
   end
 end
 
+require_relative 'models/class_helpers'
 require_relative 'models/modifier'
 require_relative 'models/collection'
 require_relative 'models/parser_serializer'

data/lib/eco/language.rb

@@ -10,3 +10,4 @@ require_relative 'language/hash_transform'
 require_relative 'language/values_at'
 require_relative 'language/match_modifier'
 require_relative 'language/match'
+require_relative 'language/auxiliar_logger'

data/lib/eco/version.rb

@@ -1,3 +1,3 @@
 module Eco
-  VERSION = "2.4.4"
+  VERSION = "2.4.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eco-helpers
 version: !ruby/object:Gem::Version
-  version: 2.4.4
+  version: 2.4.5
 platform: ruby
 authors:
 - Oscar Segura
@@ -591,6 +591,9 @@ files:
 - lib/eco/api/usecases/default_cases/upsert_case.rb
 - lib/eco/api/usecases/graphql.rb
 - lib/eco/api/usecases/graphql/base.rb
+- lib/eco/api/usecases/graphql/helpers.rb
+- lib/eco/api/usecases/graphql/helpers/locations.rb
+- lib/eco/api/usecases/graphql/helpers/locations/commands.rb
 - lib/eco/api/usecases/ooze_cases.rb
 - lib/eco/api/usecases/ooze_cases/export_register_case.rb
 - lib/eco/api/usecases/ooze_samples.rb
@@ -657,14 +660,19 @@ files:
 - lib/eco/data/fuzzy_match/score.rb
 - lib/eco/data/fuzzy_match/stop_words.rb
 - lib/eco/data/fuzzy_match/string_helpers.rb
+- lib/eco/data/hashes.rb
+- lib/eco/data/hashes/array_diff.rb
+- lib/eco/data/hashes/diff_result.rb
 - lib/eco/data/mapper.rb
 - lib/eco/language.rb
+- lib/eco/language/auxiliar_logger.rb
 - lib/eco/language/curry.rb
 - lib/eco/language/hash_transform.rb
 - lib/eco/language/hash_transform_modifier.rb
 - lib/eco/language/match.rb
 - lib/eco/language/match_modifier.rb
 - lib/eco/language/models.rb
+- lib/eco/language/models/class_helpers.rb
 - lib/eco/language/models/collection.rb
 - lib/eco/language/models/modifier.rb
 - lib/eco/language/models/parser_serializer.rb