ecoportal-api-v2 2.0.16 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2770623463a726f2c3d92064d30467e6434b722b35bf3e8a14173734eb8512b6
-  data.tar.gz: 10002dd8043af489fde4ed17e061e5ddd499935261406ffdf1a61b2ad4c85958
+  metadata.gz: 9f6265c8e79e49dfb8c121860260f99abf957c9f1649764ee66fcab3e7f136fd
+  data.tar.gz: 4de91b16581dbe57f9a23b8eb48a9fe64f365b558844f663d7471bf84a6dff75
 SHA512:
-  metadata.gz: d09b7396ff7abb9d065d7f519d2fe9f0bf22f2c147d681dee4ae5ad7bde68c484a6849f723f4df98165adac3fe5d89ce87c03ee89859cb0c51fec4b226868c2b
-  data.tar.gz: f8e11c08ac97beb4a47b044216e07237be2e07c1eaaa74d69268b135c42ca8222f4379e69e63de7b0cad57a7b18395a37ed477e4ed9060ee94575bcfa674b938
+  metadata.gz: e73d7760680b0a3966610195c674bd7aacc6a4b8e117140edc29d42de7cb47f69eda51a36900062bbe3043d9b6581a833994e34a32a738f979ae1a64497b5284
+  data.tar.gz: 584efdc89b150aad2ea3d0e214a11133fc56cc9b9335cb05bb0b994617dd2fc24187ccc5df46ea06bc1a450f3e212971aa8a30fc17b8ad6b025950f700a94c68

data/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to this project will be documented in this file.
 
-## [2.0.17] - 2025-03-xx
+## [3.1.2] - 2025-05-xx
 
 ### Added
 
@@ -10,6 +10,29 @@ All notable changes to this project will be documented in this file.
 
 ### Fixed
 
+## [3.1.1] - 2025-05-xx
+
+### Added
+
+- `Ecoportal::API::Common::Content::DoubleModel::HashHelpers`
+  - `Added` `#dig_path?` to check if `path` exists.
+
+### Changed
+
+- upgraded `ecoportal-api` gem
+- `Ecoportal::API::Common::Content::HashPatchDiff` as well as a **concern**.
+- Renamed `Ecoportal::API::Common::Content::DoubleModel::DiffableModel` to
+  - `Ecoportal::API::Common::Content::DoubleModel::Diffable`
+  - **Move** `diff` to **service class**.
+- `require` to `require_relative` where applicable.
+- **Renamed** `#dig_set` and `#dig_delete` to `#dig_set!` and `#dig_delete!`
+
+### Fixed
+
+- `inheritable_class_vars`
+  - Some objects should be **dupped** or even **cloned**
+  - `inherited` should be private
+
 ## [2.0.16] - 2025-03-14
 
 ### Fixed

data/ecoportal-api-v2.gemspec

@@ -33,7 +33,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop-rake', '~> 0'
   spec.add_development_dependency 'yard',         '~> 0.9'
 
-  spec.add_dependency 'ecoportal-api', '~> 0.10', '>= 0.10.8'
+  spec.add_dependency 'ecoportal-api', '~> 0.10', '>= 0.10.10'
   spec.add_dependency 'mime-types',    '~> 3.5',  '>= 3.5.2'
 end
 

data/lib/ecoportal/api/common/concerns.rb

@@ -7,5 +7,5 @@ module Ecoportal
   end
 end
 
-require 'ecoportal/api/common/concerns/threadable'
-require 'ecoportal/api/common/concerns/benchmarkable'
+require_relative 'concerns/threadable'
+require_relative 'concerns/benchmarkable'

data/lib/ecoportal/api/common/content/class_helpers.rb

@@ -128,7 +128,7 @@ module Ecoportal
           #   Think if would be possible to join them somehow.
           def inheritable_class_vars(*vars)
             @inheritable_class_vars ||= [:inheritable_class_vars]
-            @inheritable_class_vars += vars
+            @inheritable_class_vars  |= vars
           end
 
           # Builds the attr_reader and attr_writer of `attrs` and registers the associated instance variable as inheritable.
@@ -140,22 +140,57 @@ module Ecoportal
                 end                      # end
               DEF_CLSS_ATTR
             end
+
             inheritable_class_vars(*attrs)
           end
 
+          private
+
           # 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.
+          # @note Mutating methods would reflect the changes on other classes as well, for this
+          #   reason:
+          #   - Immutable objects are copied as they are (i.e. `Symbol`)
+          #   - Enumerables are deep dupped.
+          #   - Mutable objects, such as `String` or `Date` are frozen (`freeze`). This
+          #     might be changed later on and just dup them.
           def inherited(subclass)
             super
 
             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)
+              subclass.instance_variable_set(
+                instance_var,
+                freeze_or_dup(value)
+              )
+            end
+          end
+
+          def freeze_or_dup(value)
+            case value
+            when FalseClass, TrueClass, Symbol, NilClass, Numeric
+              value
+            when Date, Time, String, Range
+              value.freeze
+            when Enumerable
+              case value
+              when Array
+                value.map { |elem| freeze_or_dup(elem) }
+              when Hash
+                value.each.with_object({}) do |(key, val), out|
+                  out[key] = freeze_or_dup(val)
+                end
+              else
+                return value.dup   if respond_to?(:dup)
+                return value.clone if respond_to?(:clone)
+
+                value
+              end
+            else
+              return value.dup   if respond_to?(:dup)
+              return value.clone if respond_to?(:clone)
+
+              value
             end
           end
         end

data/lib/ecoportal/api/common/content/client.rb

@@ -6,7 +6,8 @@ module Ecoportal
         class Client < Ecoportal::API::Common::Client
           attr_accessor :logger
 
-          # @note the `api_key` will be automatically added as parameter `X-ECOPORTAL-API-KEY` in the header of the http requests.
+          # @note the `api_key` will be automatically added as parameter
+          #   `X-ECOPORTAL-API-KEY` in the header of the http requests.
           def initialize(
             api_key:,
             version: 'v2',

data/lib/ecoportal/api/common/content/collection_model/doc/rooted_key.rb

@@ -25,9 +25,8 @@ module Ecoportal
                 #   - This method would have been better called `_doc_pos` :)
                 # @note this method shouldn't be protected nor private. See DoubleModel#_rooted_doc_key
                 def _rooted_doc_key(value)
-                  fetchable_position = value.is_a?(Hash) || value.is_a?(Content::DoubleModel)
                   #print "*(#{value.class})"
-                  return super unless fetchable_position
+                  return super unless fetchable_position?(value)
 
                   if (id = get_key(value))
                     # fetch position
@@ -37,9 +36,16 @@ module Ecoportal
                     raise UnlinkedModel, "Can't find child: #{show_str}"
                   end
                 end
+                alias_method :_doc_pos, :_rooted_doc_key
 
                 private
 
+                def fetchable_position?(value)
+                  return true if value.is_a?(Hash)
+
+                  value.is_a?(Content::DoubleModel)
+                end
+
                 def cant_find_child_explanation(value)
                   case value
                   when Hash
@@ -53,12 +59,6 @@ module Ecoportal
                   end
                 end
               end
-
-              # INSTANCE METHODS
-
-              def _doc_pos(value)
-                _rooted_doc_key(value)
-              end
             end
           end
         end

data/lib/ecoportal/api/common/content/collection_model/doc.rb

@@ -1,5 +1,5 @@
-require 'ecoportal/api/common/content/collection_model/doc/items'
-require 'ecoportal/api/common/content/collection_model/doc/rooted_key'
+require_relative 'doc/items'
+require_relative 'doc/rooted_key'
 
 module Ecoportal
   module API

data/lib/ecoportal/api/common/content/collection_model/doc_mutation.rb

@@ -1,6 +1,6 @@
-require 'ecoportal/api/common/content/collection_model/doc_mutation/delete'
-require 'ecoportal/api/common/content/collection_model/doc_mutation/position'
-require 'ecoportal/api/common/content/collection_model/doc_mutation/upsert'
+require_relative 'doc_mutation/delete'
+require_relative 'doc_mutation/position'
+require_relative 'doc_mutation/upsert'
 
 module Ecoportal
   module API

data/lib/ecoportal/api/common/content/collection_model/model.rb

@@ -1,9 +1,9 @@
-require 'ecoportal/api/common/content/collection_model/model/items'
-require 'ecoportal/api/common/content/collection_model/model/iterable'
-require 'ecoportal/api/common/content/collection_model/model/numeric_key'
-require 'ecoportal/api/common/content/collection_model/model/cache'
-require 'ecoportal/api/common/content/collection_model/model/var_tracking'
-require 'ecoportal/api/common/content/collection_model/model/lookup'
+require_relative 'model/items'
+require_relative 'model/iterable'
+require_relative 'model/numeric_key'
+require_relative 'model/cache'
+require_relative 'model/var_tracking'
+require_relative 'model/lookup'
 
 module Ecoportal
   module API

data/lib/ecoportal/api/common/content/collection_model/modifiers.rb

@@ -1,6 +1,6 @@
-require 'ecoportal/api/common/content/collection_model/modifiers/items_key'
-require 'ecoportal/api/common/content/collection_model/modifiers/items_klass'
-require 'ecoportal/api/common/content/collection_model/modifiers/items_order'
+require_relative 'modifiers/items_key'
+require_relative 'modifiers/items_klass'
+require_relative 'modifiers/items_order'
 
 module Ecoportal
   module API

data/lib/ecoportal/api/common/content/collection_model/mutation.rb

@@ -1,6 +1,6 @@
-require 'ecoportal/api/common/content/collection_model/mutation/delete'
-require 'ecoportal/api/common/content/collection_model/mutation/upsert'
-require 'ecoportal/api/common/content/collection_model/mutation/clear'
+require_relative 'mutation/delete'
+require_relative 'mutation/upsert'
+require_relative 'mutation/clear'
 
 module Ecoportal
   module API

data/lib/ecoportal/api/common/content/collection_model.rb

@@ -6,11 +6,11 @@ module Ecoportal
         # @note to be able to refer to the correct element of the Collection,
         #   it is required that those elements have a unique `key` that allows to identify them
         class CollectionModel < Content::DoubleModel
-          require 'ecoportal/api/common/content/collection_model/modifiers'
-          require 'ecoportal/api/common/content/collection_model/doc'
-          require 'ecoportal/api/common/content/collection_model/model'
-          require 'ecoportal/api/common/content/collection_model/doc_mutation'
-          require 'ecoportal/api/common/content/collection_model/mutation'
+          require_relative 'collection_model/modifiers'
+          require_relative 'collection_model/doc'
+          require_relative 'collection_model/model'
+          require_relative 'collection_model/doc_mutation'
+          require_relative 'collection_model/mutation'
 
           include Modifiers
           include Doc

data/lib/ecoportal/api/common/content/double_model/attributable/nesting/cascaded_callback.rb

@@ -1,104 +1,209 @@
-module Ecoportal
-  module API
-    module Common
-      module Content
-        class DoubleModel
-          module Attributable
-            module Nesting
-              class << self
-                def included(base)
-                  super
-                  base.extend Content::ClassHelpers
-
-                  base.extend ClassMethods
-                  base.inheritable_class_vars :_cascaded_attributes
-                end
-              end
-
-              module ClassMethods
-                def _cascaded_attribute!(meth, doc_key = meth, inherited: false)
-                  meth          = meth.to_sym
-                  doc_key       = doc_key.to_s
-
-                  dont_override = _cascaded_attributes.key?(meth) && inherited
-                  return _cascaded_attributes[meth] if dont_override
-
-                  _cascaded_attributes[meth] = doc_key
-                  subclasses.each do |subclass|
-                    subclass._cascaded_attribute!(meth, doc_key, inherited: true)
-                  end
-                end
-
-                def _cascaded_attributes
-                  @_cascaded_attributes ||={}
-                end
-
-                def _cascaded_methods
-                  _cascaded_attributes.keys
-                end
-
-                def _cascaded_doc_keys
-                  _cascaded_attributes.values.uniq
-                end
-              end
-
-              # INSTANCE METHODS
-
-              # We offer helpers to implement cascaded callbacks to nested objects
-              # i.e. `#as_update` or `#dirty?`
-              # @note this happens at instance level (not tracked at class level)
-              module CascadedCallback
-                def cascaded_callback(value = nil, method:, args: [], kargs: {}, path: [], &block)
-                  method = method.to_sym
-                  return value unless respond_to?(method, true)
-
-                  value =
-                    if path.empty?
-                      send(method, *args, **kargs)
-                    else
-                      yield(value, send(method, *args, **kargs), path, self)
-                    end
-
-                  return value unless respond_to?(:_cascaded_attributes)
-
-                  _cascaded_attributes.reduce(value) do |mem, (attribute, obj_k)|
-                    next mem unless (obj = send(attribute))
-                    next mem unless obj.respond_to(method, true)
-
-                    obj_path = path.dup.push(obj_k)
-
-                    unless obj.respond_to?(:cascaded_callback)
-                      next yield(
-                        mem,
-                        obj.send(method, *args, **kargs),
-                        obj_path,
-                        obj
-                      )
-                    end
-
-                    obj.cascaded_callback(
-                      mem,
-                      method: method,
-                      path:   obj_path,
-                      &block
-                    )
-                  end
-                end
-
-                private
-
-                def _cascaded_attribute!(...)
-                  self.class._cascaded_attribute!(...)
-                end
-
-                def _cascaded_attributes
-                  self.class._cascaded_attributes
-                end
-              end
-            end
+module Ecoportal::API::Common::Content::DoubleModel::Attributable::Nesting
+  module CascadedCallback
+    class << self
+      def included(base)
+        super
+
+        base.extend Ecoportal::API::Common::Content::ClassHelpers
+
+        base.extend ClassMethods
+        base.inheritable_class_vars :_cascaded_attributes
+        base.send :include, InstanceMethods
+      end
+    end
+
+    module ClassMethods
+      # @note it also tracks `doc_key` as cascaded attribute on
+      #   child classes.
+      def _cascaded_attribute!(meth, doc_key = meth, inherited: false)
+        meth          = meth.to_sym
+        doc_key       = doc_key.to_s
+
+        dont_override = _cascaded_attributes.key?(meth) && inherited
+        return _cascaded_attributes[meth] if dont_override
+
+        _cascaded_attributes[meth] = doc_key
+
+        subclasses.each do |subclass|
+          subclass._cascaded_attribute!(meth, doc_key, inherited: true)
+        end
+      end
+
+      def _cascaded_attributes
+        @_cascaded_attributes ||={}
+      end
+
+      def _cascaded_methods
+        _cascaded_attributes.keys
+      end
+
+      def _cascaded_doc_keys
+        _cascaded_attributes.values.uniq
+      end
+    end
+
+    # INSTANCE METHODS
+
+    # We offer helpers to implement cascaded callbacks to nested objects
+    # i.e. `#as_update` or `#dirty?`
+    # @note this happens at instance level (not tracked at class level)
+    module InstanceMethods
+      # Method to go through all the embedded properties recursively.
+      # @note **Be aware** that
+      #   1. It does NOT natively discard `root?` objects. You will need to
+      #     explicitly do this in the block callback.
+      #   2. If `method` calls in turn to `cascaded_callback`, to prevent
+      #     **double-recursion** you MUST use `recurs: false`.
+      #     The **problem** with this approach is that **`key_path`**
+      #     from the original object that called `cascaded_callback`
+      #     **is lost**.
+      #     For which you should probably rather use `cascaded_reduce`.
+      #   3. It already does a first call on `self.method`, might it respond to.
+      #     And it will not `yield` in this first call.
+      # @note the `cascaded_callback` will end were:
+      #   1. The current object does NOT respond to `method`.
+      #   2. The current object does NOT have nested properties. So where
+      #     the object does not have any `_cascaded_attributes`.
+      # @yield [result, value, key_path, object] block to accumulate result.
+      #   The block is yielded for the main (root) object, as well as
+      #   per each one of its `_cascaded_attributes` (so nested properties).
+      # @yieldparam result [Hash, Variant] the accumulated value of calling `method`
+      #   across all nested models from root to this point (`object`).
+      # @yieldparam value [Variant] the value of calling `method` on `object`.
+      # @yieldparam key_path [Array<String>] the `Hash` model `path` of **keys** to get
+      #   from root to `objecct`. It is important to **note** that an
+      #   **empty path** means we are on the top object from where this method
+      #   was callled.
+      # @yieldparam object [DoubleModel] the current object.
+      # @yieldreturn [Variant] the accumulated result or the current iteration.
+      # @param value [Variant] the intial value of the cascaded callback.
+      #   - It can also be the accumulated value of cascaded callbacks from
+      #     up to the model hierarchy to the current instance.
+      # @param method [Symbol] to be called on `self` and all nested models.
+      #   Private methods are in scope.
+      # @param args [Array<>] arguments for `method`.
+      # @param kargs [Hash<Symbol,Variant>] named arguments for `method`.
+      # @param path [Array<String>] the `Hash` model `path` of **keys** to get
+      #   from root to `self`.
+      # @param recurs [Boolean] whether it should go beyound the first level.
+      #   This is specially useful to set to `false` when `method` will,
+      #   in turn, call `cascaded_callback`, as that would already have
+      #   a recursion. Noo need to decrease performance with a double recursion,
+      #   in such a case.
+      # @return [Variant] the result of cascaded calling `method` through all the
+      #   the nested models.
+      def cascaded_callback(
+        value = nil,
+        method:,
+        args:   [],
+        kargs:  {},
+        path:   [],
+        recurs: true,
+        &block
+      )
+        method = method.to_sym
+        return value unless respond_to?(method, true)
+
+        value =
+          if path.empty?
+            # Don't yield on the first call
+            send(method, *args, **kargs)
+          else
+            yield(
+              value,
+              send(method, *args, **kargs),
+              path,
+              self
+            )
+          end
+
+        return value unless respond_to?(:_cascaded_attributes)
+
+        _cascaded_attributes.reduce(value) do |val, (attribute, obj_k)|
+          next val unless (obj = send(attribute))
+          next val unless obj.respond_to(method, true)
+
+          obj_path = path.dup.push(obj_k)
+          # next val if obj_path.empty?
+
+          unless obj.respond_to?(:cascaded_callback)
+            next yield(
+              val,
+              obj.send(method, *args, **kargs),
+              obj_path,
+              obj
+            )
+          end
+
+          next val unless recurs
+
+          obj.cascaded_callback(
+            val,
+            method: method,
+            args:   args,
+            kargs:  kargs,
+            path:   obj_path,
+            recurs: recurs,
+            &block
+          )
+        end
+      end
+
+      # Trace = Struct.new(:subject, :nested_attrs, :obj_key_path)
+      def cascaded_reduce(init = nil, recurs: false, trace: nil, &block)
+        trace ||= {}
+        trace   = _cascaded_attributes_trace(recurs: recurs) if trace.empty?
+
+        return init if trace.empty?
+
+        params = %i[subject key key_path attributes]
+        subject, key, key_path, attributes = trace.values_at(*params)
+
+        value = yield(init, subject, key, key_path, trace)
+        return value if attributes.nil? || attributes.empty?
+
+        attributes.reduce(value) do |mem, (_attr, subtrace)|
+          cascaded_reduce(mem, recurs: recurs, trace: subtrace, &block)
+        end
+      end
+
+      private
+
+      def _cascaded_attributes_trace(trace = nil, recurs: false, key_path: [])
+        {
+          subject:      self,
+          attribute:    nil,
+          key:          nil,
+          key_path:     key_path,
+          nested_attrs: _cascaded_attributes.keys,
+          attributes:   {}
+        }.merge(trace || {}).tap do |out_trace|
+          _cascaded_attributes.each.with_object(out_trace) do |out, (attribute, obj_k)|
+            next unless (obj = send(attribute))
+
+            obj_k_path = key_path.dup.push(obj_k)
+
+            sub_trace = out[:attributes][attribute] = {
+              subject:   obj,
+              attribute: attribute,
+              key:       obj_k,
+              key_path:  obj_k_path
+            }
+
+            next unless recurs
+
+            _cascaded_attributes_trace(sub_trace, recurs: true, key_path: obj_k_path)
           end
         end
       end
+
+      def _cascaded_attribute!(...)
+        self.class._cascaded_attribute!(...)
+      end
+
+      def _cascaded_attributes
+        self.class._cascaded_attributes
+      end
     end
   end
 end