ecoportal-api-v2 2.0.16 → 3.1.1

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

@@ -1,73 +1,63 @@
-module Ecoportal
-  module API
-    module Common
-      module Content
-        class DoubleModel
-          module Attributable
-            module Nesting
-              module Embeddable
-                class << self
-                  include Content::Includer
+module Ecoportal::API::Common::Content::DoubleModel::Attributable::Nesting
+  module Embeddable
+    class << self
+      include Ecoportal::API::Common::Content::Includer
 
-                  def included(base)
-                    super
-                    base.extend Content::ClassHelpers
+      def included(base)
+        super
 
-                    include_missing(base, DoubleModel::VarTracking)
-                    include_missing(base, DoubleModel::Modifiers)
-                    include_missing(base, Attributable::Base)
+        base.extend Ecoportal::API::Common::Content::ClassHelpers
 
-                    include_missing(base, Nesting::Keyable)
-                    include_missing(base, Nesting::CascadedCallback)
+        include_missing(base, Ecoportal::API::Common::Content::DoubleModel::VarTracking)
+        include_missing(base, Ecoportal::API::Common::Content::DoubleModel::Modifiers)
+        include_missing(base, Ecoportal::API::Common::Content::DoubleModel::Attributable::Base)
 
-                    base.extend ClassMethods
-                  end
-                end
+        include_missing(base, Keyable)
+        include_missing(base, CascadedCallback)
 
-                module ClassMethods
-                  private
+        base.extend ClassMethods
+      end
+    end
+
+    module ClassMethods
+      private
 
-                  def embed(
-                    method,
-                    klass:,
-                    key:       method,
-                    nullable:  false,
-                    multiple:  false,
-                    read_only: read_only?,
-                    &embed_block
-                  )
-                    method = method.to_s.freeze
-                    var    = instance_variable_name(method).freeze
-                    obj_k  = key.to_s.freeze
+      def embed(
+        method,
+        klass:,
+        key:       method,
+        nullable:  false,
+        multiple:  false,
+        read_only: read_only?,
+        &embed_block
+      )
+        method = method.to_s.freeze
+        var    = instance_variable_name(method).freeze
+        obj_k  = key.to_s.freeze
 
-                    _cascaded_attribute!(method, obj_k)
+        _cascaded_attribute!(method, obj_k)
 
-                    # retrieving method (getter)
-                    define_method(method) do
-                      # set item klass as referrer to klass (to allow resolve symbol)
-                      embed_block&.call(self)
-                      return instance_variable_get(var) if instance_variable_defined?(var)
+        # retrieving method (getter)
+        define_method(method) do
+          # set item klass as referrer to klass (to allow resolve symbol)
+          embed_block&.call(self)
+          return instance_variable_get(var) if instance_variable_defined?(var)
 
-                      doc[obj_k] ||= (multiple ? [] : {}) unless nullable
-                      return variable_set(var, nil)       if (doc_value = doc[obj_k]).nil?
+          doc[obj_k] ||= (multiple ? [] : {}) unless nullable
+          return variable_set(var, nil)       if (doc_value = doc[obj_k]).nil?
 
-                      embedded_class = self.class.resolve_class(klass)
-                      items_key_setup!(embedded_class, doc_value) if multiple && read_only
+          embedded_class = self.class.resolve_class(klass)
+          items_key_setup!(embedded_class, doc_value) if multiple && read_only
 
-                      embedded_class.new(
-                        doc_value,
-                        parent:    self,
-                        key:       obj_k,
-                        read_only: read_only? || read_only
-                      ).tap do |collection|
-                        variable_set(var, collection)
-                        _cascaded_attribute!(method, obj_k)
-                      end
-                    end
-                  end
-                end
-              end
-            end
+          embedded_class.new(
+            doc_value,
+            parent:    self,
+            key:       obj_k,
+            read_only: read_only? || read_only
+          ).tap do |collection|
+            variable_set(var, collection)
+            # ensure children classes propagation!
+            _cascaded_attribute!(method, obj_k)
           end
         end
       end

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

@@ -1,118 +1,106 @@
-module Ecoportal
-  module API
-    module Common
-      module Content
-        class DoubleModel
-          module Attributable
-            module Nesting
-              module Keyable
-                class NoKeyMethod < StandardError
-                end
-
-                class << self
-                  include Content::Includer
-
-                  def included(base)
-                    super
-                    base.extend Content::ClassHelpers
-
-                    include_missing(base, DoubleModel::VarTracking)
-
-                    base.extend ClassMethods
-                    base.inheritable_class_vars :key
-                  end
-                end
-
-                module ClassMethods
-                  attr_reader :key
-
-                  def key?
-                    !!key
-                  end
-
-                  # key property (and method) of this model
-                  # @note this is auto-set when `passkey` is used
-                  def key=(value)
-                    @key = value.to_s.freeze
-                  end
-
-                  # This method is essential to give stability to the model
-                  # @note `Content::CollectionModel` needs to find elements in the doc `Array`.
-                  #  The only way to do it is via the access key (i.e. `id`). However, there is
-                  #  no chance you can avoid infinite loop for `get_key` (CollectionModel)
-                  #  without setting an instance variable key at the moment of the object creation,
-                  #  when the `doc` is firstly received
-                  # @param method [Symbol] the method that exposes the value
-                  #   as well as its `key` in the underlying `Hash` model.
-                  def passkey(method)
-                    method   = method.to_s.freeze
-                    var      = instance_variable_name(method)
-                    self.key = method
-
-                    define_method method do
-                      return instance_variable_get(var) if instance_variable_defined?(var)
-
-                      value = send(:doc)[method]
-                      value = yield(value) if block_given?
-                      value
-                    end
-
-                    define_method "#{method}=" do |value|
-                      variable_set(var, value)
-                      value = yield(value) if block_given?
-                      send(:doc)[method] = value
-                    end
-
-                    self
-                  end
-                end
-
-                # INSTANCE METHODS
-
-                # @return [String] the `value` of the `key` method (i.e. `id` value)
-                def key
-                  msg = "No key_method defined for #{self.class}"
-                  raise NoKeyMethod, msg unless key_method?
-
-                  method(key_method).call
-                end
-
-                # @param [String] the `value` of the `key` method (i.e. `id` value)
-                def key=(value)
-                  msg = "No key_method defined for #{self.class}"
-                  raise NoKeyMethod, msg unless key_method?
-
-                  method("#{key_method}=").call(value)
-                end
-
-                private
-
-                def key_method?
-                  self.class.key?
-                end
-
-                def key_method
-                  self.class.key
-                end
-
-                # It allows to work-around missing item_key
-                def items_key_setup!(embedded_class, obj_doc)
-                  # only if is going to be a collection
-                  return unless obj_doc.is_a?(Array) && embedded_class < CollectionModel
-                  return unless (item_class = embedded_class.klass)
-                  # if already has key don't need to work around
-                  return if     item_class&.key
-
-                  # apply work around
-                  item_class.passkey :id
-                  obj_doc.each_with_index do |item_doc, idx|
-                    item_doc['id'] = idx.to_s unless item_doc.key?('id')
-                  end
-                end
-              end
-            end
-          end
+module Ecoportal::API::Common::Content::DoubleModel::Attributable::Nesting
+  module Keyable
+    class NoKeyMethod < StandardError
+    end
+
+    class << self
+      include Ecoportal::API::Common::Content::Includer
+
+      def included(base)
+        super
+        base.extend Ecoportal::API::Common::Content::ClassHelpers
+
+        include_missing(base, Ecoportal::API::Common::Content::DoubleModel::VarTracking)
+
+        base.extend ClassMethods
+        base.inheritable_class_vars :key
+      end
+    end
+
+    module ClassMethods
+      attr_reader :key
+
+      def key?
+        !!key
+      end
+
+      # key property (and method) of this model
+      # @note this is auto-set when `passkey` is used
+      def key=(value)
+        @key = value.to_s.freeze
+      end
+
+      # This method is essential to give stability to the model
+      # @note `Content::CollectionModel` needs to find elements in the doc `Array`.
+      #  The only way to do it is via the access key (i.e. `id`). However, there is
+      #  no chance you can avoid infinite loop for `get_key` (CollectionModel)
+      #  without setting an instance variable key at the moment of the object creation,
+      #  when the `doc` is firstly received
+      # @param method [Symbol] the method that exposes the value
+      #   as well as its `key` in the underlying `Hash` model.
+      def passkey(method)
+        method   = method.to_s.freeze
+        var      = instance_variable_name(method)
+        self.key = method
+
+        define_method method do
+          return instance_variable_get(var) if instance_variable_defined?(var)
+
+          value = send(:doc)[method]
+          value = yield(value) if block_given?
+          value
+        end
+
+        define_method "#{method}=" do |value|
+          variable_set(var, value)
+          value = yield(value) if block_given?
+          send(:doc)[method] = value
         end
+
+        self
+      end
+    end
+
+    # INSTANCE METHODS
+
+    # @return [String] the `value` of the `key` method (i.e. `id` value)
+    def key
+      msg = "No key_method defined for #{self.class}"
+      raise NoKeyMethod, msg unless key_method?
+
+      method(key_method).call
+    end
+
+    # @param [String] the `value` of the `key` method (i.e. `id` value)
+    def key=(value)
+      msg = "No key_method defined for #{self.class}"
+      raise NoKeyMethod, msg unless key_method?
+
+      method("#{key_method}=").call(value)
+    end
+
+    private
+
+    def key_method?
+      self.class.key?
+    end
+
+    def key_method
+      self.class.key
+    end
+
+    # It allows to work-around missing item_key
+    def items_key_setup!(embedded_class, obj_doc)
+      # only if is going to be a collection
+      return unless obj_doc.is_a?(Array) && embedded_class < CollectionModel
+      return unless (item_class = embedded_class.klass)
+      # if already has key don't need to work around
+      return if     item_class&.key
+
+      # apply work around
+      item_class.passkey :id
+      obj_doc.each_with_index do |item_doc, idx|
+        item_doc['id'] = idx.to_s unless item_doc.key?('id')
       end
     end
   end

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

@@ -1,6 +1,3 @@
-require 'ecoportal/api/common/content/double_model/attributable/nesting/keyable'
-require 'ecoportal/api/common/content/double_model/attributable/nesting/cascaded_callback'
-require 'ecoportal/api/common/content/double_model/attributable/nesting/embeddable'
 module Ecoportal
   module API
     module Common
@@ -8,6 +5,10 @@ module Ecoportal
         class DoubleModel
           module Attributable
             module Nesting
+              require_relative 'nesting/keyable'
+              require_relative 'nesting/cascaded_callback'
+              require_relative 'nesting/embeddable'
+
               class << self
                 include Content::Includer
 
@@ -56,6 +57,7 @@ module Ecoportal
                         read_only: read_only?
                       ).tap do |new_obj|
                         variable_set(var, new_obj)
+                        # ensure children classes propagation!
                         _cascaded_attribute!(method)
                       end
                     end

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

@@ -1,8 +1,8 @@
-require 'ecoportal/api/common/content/double_model/attributable/base'
-require 'ecoportal/api/common/content/double_model/attributable/passthrough'
-require 'ecoportal/api/common/content/double_model/attributable/enforce'
-require 'ecoportal/api/common/content/double_model/attributable/simple'
-require 'ecoportal/api/common/content/double_model/attributable/nesting'
+require_relative 'attributable/base'
+require_relative 'attributable/passthrough'
+require_relative 'attributable/enforce'
+require_relative 'attributable/simple'
+require_relative 'attributable/nesting'
 module Ecoportal
   module API
     module Common

data/lib/ecoportal/api/common/content/double_model/diffable/diff_service.rb

@@ -0,0 +1,33 @@
+module Ecoportal::API::Common::Content::DoubleModel::Diffable
+  class DiffService
+    include Ecoportal::API::Common::Content::HashDiffPatch
+
+    attr_reader :subject
+
+    def initialize(subject)
+      @subject = subject
+    end
+
+    def path_diff
+      super(
+        curr_doc,
+        prev_doc
+      )
+    end
+
+    private
+
+    def prev_doc(obj = subject)
+      return obj.original_doc if obj.respond_to?(:original_doc)
+
+      raise "Instance of (#{subject.class}): can't fetch original underlying model"
+    end
+
+    def curr_doc(obj = subject)
+      return obj.as_json if obj.respond_to?(:as_json)
+      return obj.doc     if obj.respond_to?(:doc)
+
+      raise "Instance of (#{subject.class}): can't fetch underlying document"
+    end
+  end
+end

data/lib/ecoportal/api/common/content/double_model/{diffable_model.rb → diffable.rb}

@@ -3,7 +3,11 @@ module Ecoportal
     module Common
       module Content
         class DoubleModel
-          module DiffableModel
+          module Diffable
+            require_relative 'diffable/diff_service'
+
+            DIFF_CLASS = DiffService
+
             class << self
               include Content::Includer
 
@@ -21,10 +25,7 @@ module Ecoportal
             # @return [nil, Hash] the patch `Hash` model including only
             #   the changes between `original_doc` and `doc`.
             def as_update
-              HashDiffPatch.patch_diff(
-                as_json,
-                original_doc
-              )
+              diff_class.new(self).path_diff
             end
 
             # @return [Boolean] stating if there are changes.
@@ -35,6 +36,12 @@ module Ecoportal
 
               true
             end
+
+            private
+
+            def diff_class
+              self.class::DIFF_CLASS
+            end
           end
         end
       end

data/lib/ecoportal/api/common/content/double_model/double_doc/linkable_doc.rb

@@ -7,8 +7,10 @@ module Ecoportal
             module LinkableDoc
               class UnlinkedModel < StandardError
                 def initialize(msg = "Something went wrong when linking the document.", from: nil, key: nil)
-                  msg += " From: #{from}." if from
-                  msg += " key: #{key}."   if key
+                  msg ||= ''
+                  msg  << " From: #{from}." if from
+                  msg  << " key: #{key}."   if key
+
                   super(msg)
                 end
               end
@@ -26,8 +28,8 @@ module Ecoportal
 
               # INSTANCE METHODS
 
-              def to_json(*args)
-                doc.to_json(*args)
+              def to_json(...)
+                doc.to_json(...)
               end
 
               def as_json
@@ -39,6 +41,9 @@ module Ecoportal
                 self
               end
 
+              # @note when `doc` isn't rooted, it relies to the `_parent.doc`.
+              #   This does a `doc` recursive resolve, where `resolved_rooted_doc_key`
+              #   can only have 1 level at each iteration.
               # @return [nil, Hash] the underlying `Hash` model as is (carrying current changes)
               def doc
                 return @doc if doc_var?

data/lib/ecoportal/api/common/content/double_model/double_doc/replaceable_doc.rb

@@ -32,7 +32,11 @@ module Ecoportal
                   )
                 end
 
-                dig_set(_parent.doc, resolved_rooted_doc_key, new_doc)
+                dig_set!(
+                  _parent.doc,
+                  resolved_rooted_doc_key,
+                  new_doc
+                )
 
                 _parent.variable_remove!(_parent_key) unless new_doc
                 #variables_remove!
@@ -50,7 +54,11 @@ module Ecoportal
                   )
                 end
 
-                dig_set(_parent.original_doc, resolved_rooted_doc_key, new_doc)
+                dig_set!(
+                  _parent.original_doc,
+                  resolved_rooted_doc_key,
+                  new_doc
+                )
               end
             end
           end

data/lib/ecoportal/api/common/content/double_model/double_doc/reset_consolidate.rb

@@ -40,7 +40,7 @@ module Ecoportal
                   keys    = [key].flatten.compact
                   odoc    = original_doc.dig(*keys)
                   odoc  &&= JSON.parse(odoc.to_json)
-                  dig_set(doc, keys, odoc)
+                  dig_set!(doc, keys, odoc)
                 else
                   replace_doc(JSON.parse(original_doc.to_json))
                 end

data/lib/ecoportal/api/common/content/double_model/double_doc/rooted_key.rb

@@ -19,9 +19,17 @@ module Ecoportal
 
               # Offers a method for child classes to transform the key,
               # provided that the child's `doc` can be accessed.
+              # @note this method was introduced with `CollectionModel`. The individual
+              #   elements/items wouldn't know how to fetch their own model via their
+              #   parent. This required to introduce _rooted_doc_key in all DoubleModel
+              #   ancestors. It just delegates up the resolution of a `value` key.
               # @note this method can't be protected. It might be accessed by cousing classes.
-              #   See last line of this method.
               #   parent class to a child class.
+              #   See last line of this method.
+              # @param value [Content::DoubleModel, Array<String>, String]
+              #   - `String` or `Array<String>`: is mirrored.
+              #   - `DoubleModel` and `root?`:   is mirrored.
+              #   - non `root?` `DoubleModel`:   deletages to `_parent`
               def _rooted_doc_key(value)
                 #print "!(#{value}<=#{self.class})" if value.is_a?(Content::DoubleModel) && !value.root?
                 return value unless value.is_a?(Content::DoubleModel)
@@ -30,16 +38,15 @@ module Ecoportal
                 #print "?(#{value.class}<=#{value._parent.class})"
                 value._parent._rooted_doc_key(value)
               end
-              # alias_method :_doc_key, :_rooted_doc_key
 
               protected
 
+              # @note it assumes it is `Parented`
               # @note this method can be protected... not accessed from
               #   parent class to child class.
               def resolved_rooted_doc_key
                 [_rooted_doc_key(_parent_key)].flatten
               end
-              # alias_method :resolved_doc_key, :resolved_rooted_doc_key
             end
           end
         end

data/lib/ecoportal/api/common/content/double_model/double_doc.rb

@@ -1,8 +1,8 @@
-require 'ecoportal/api/common/content/double_model/double_doc/base'
-require 'ecoportal/api/common/content/double_model/double_doc/rooted_key'
-require 'ecoportal/api/common/content/double_model/double_doc/linkable_doc'
-require 'ecoportal/api/common/content/double_model/double_doc/replaceable_doc'
-require 'ecoportal/api/common/content/double_model/double_doc/reset_consolidate'
+require_relative 'double_doc/base'
+require_relative 'double_doc/rooted_key'
+require_relative 'double_doc/linkable_doc'
+require_relative 'double_doc/replaceable_doc'
+require_relative 'double_doc/reset_consolidate'
 
 module Ecoportal
   module API

data/lib/ecoportal/api/common/content/double_model/hash_helpers.rb

@@ -6,14 +6,30 @@ module Ecoportal
           module HashHelpers
             private
 
+            # @return [Boolean] whether the path (beginning) of the last key
+            #   exists from `obj`.
+            def dig_path?(obj, keys)
+              return false unless obj.respond_to?([])
+              return true  if keys.length == 1
+
+              dig_path?(
+                obj[keys.first],
+                keys[1..]
+              )
+            end
+
             # It sets `value` on the last object that you would get
             # via `obj.dig(*keys[0..-1])`
             # @note equivalent to `obj.dig(*keys[0..-1])&[keys.last] = value`
-            def dig_set(obj, keys, value)
+            def dig_set!(obj, keys, value)
               if keys.length == 1
                 obj[keys.first] = value
               else
-                dig_set(obj[keys.first], keys.slice(1..-1), value)
+                dig_set!(
+                  obj[keys.first],
+                  keys[1..],
+                  value
+                )
               end
             end
 
@@ -23,13 +39,16 @@ module Ecoportal
             #   1. `parent = obj.dig(*keys[0..-1])`
             #   2. `parent.delete(keys.last) if parent.is_a?(Hash)`
             # @return [Variant] the value of that key
-            def dig_delete(obj, keys)
+            def dig_delete!(obj, keys)
               if keys.length == 1
                 return unless obj.respond_to?(:delete)
 
                 obj.delete(keys.first)
               else
-                dig_delete(obj[keys.first], keys.slice(1..-1))
+                dig_delete!(
+                  obj[keys.first],
+                  keys[1..]
+                )
               end
             end
           end

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

@@ -1,5 +1,5 @@
-require 'ecoportal/api/common/content/double_model/modifiers/rootable'
-require 'ecoportal/api/common/content/double_model/modifiers/read_only_able'
+require_relative 'modifiers/rootable'
+require_relative 'modifiers/read_only_able'
 
 module Ecoportal
   module API