ecoportal-api-v2 2.0.12 → 2.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 933cb180c2a1d901d3ec065c20527d8d9ee30db24634c20ae3fa2867042311da
-  data.tar.gz: 5c7bf8198ff1ac64b776538c83f80abde8fba0cf6aa6a9f729444548f6b72936
+  metadata.gz: 426bf1825b51e8170e8c9cad831c19777758f195c62b07d8ba1dde395936ad61
+  data.tar.gz: 3141541feb1e5f108890de72a5bd6d6eddcb427149f009ba3de773ff68bc622e
 SHA512:
-  metadata.gz: c47162752062ca85c5a215ce249c3dee0b702d5b11cf095d0f9d9f68bd178af1e9edb4a3bc5c42792133761c6b036cbe2b8a509b4306327a0c72ce0d77a647bc
-  data.tar.gz: 0b2b8d9ac691e3ba75d599adb23012d01600be0d2888bb6a4f1548c3686d8ccac0a95d1aff5e586b241a185b917cd0f2bff05f82b907670148cf18e372d0e81a
+  metadata.gz: ea725f7615e8f4efb85ed66a8fb15b0b8af0665a9926272390a191cc95e0e021dbec57a203ce22be09fbad56ab756d05500dda24252c0b43889ef54158161808
+  data.tar.gz: 5dacfb6320f60555064f60ef144effb8a3b3ded3586a319344a65893b32a5cf1c2138739927fbe00ebfb92eeedb3416a1ce16723492de4bdb24a592c59ab7e46

data/.gitignore

@@ -9,6 +9,9 @@ Gemfile.lock
 /tmp/
 /pkg/
 
+/.vscode
+.solargraph.yml
+
 # docs
 /.yardoc
 /_yardoc/

data/CHANGELOG.md

@@ -2,16 +2,42 @@
 
 All notable changes to this project will be documented in this file.
 
-## [2.0.14] - 2024-11-xx
+## [2.0.15] - 2024-12-xx
 
 ### Added
 
 ### Changed
 
-- upgrade `ecoportal-api` core gem
-
 ### Fixed
 
+## [2.0.14] - 2025-02-23
+
+### Added
+
+- `Ecoportal::API::Common::DoubleModel::root!` method
+  - To stop the propagation of `read_only`
+  - To define this model as top/root in the hiearchy that hangs from it
+- `Ecoportal::API::Common::ArrayModel`
+  - **Added**
+    - `#added_items` (alias `#added`) to know which elements where added.
+    - `#deleted_items` (alias `#deleted`) to know which elements where removed.
+  - **Changed**
+    - `#push!` (alias `#push`) to accept variadic arguments.
+- `read_only` name arg to `Ecoportal::API::Common::DoubleModel::embeds_one`
+- `Ecoportal:API::Common::DoubleModel::Attributable::Nesting::CascadedCallback`
+  - A helper to track all the nested method/doc_key pairs througout parent and descendant classes thereof.
+  - This allows for cascaded callbacks to implement certain methods.
+
+### Changed
+
+- Upgrade `ecoportal-api` core gem.
+- Code tidy up.
+- **MAJOR REFACTOR**:
+  - Decoupled the code of `DoubleModel` into modular concerns.
+  - Decoupled the code of `CollectionModel` into modular concerns.
+  - Renamed some internal names to better reflect their function.
+  - This major refactor aims to be able to cascade `as_update`, provided that it calls `as_update` on each nested DoubleModel, ensuring that `as_update` can be redefined or fine tunned (rather than generating the diff out of the top model's doc).
+
 ## [2.0.12] - 2024-11-21
 
 ### Changed

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.7'
+  spec.add_dependency 'ecoportal-api', '~> 0.10', '>= 0.10.8'
   spec.add_dependency 'mime-types',    '~> 3.5',  '>= 3.5.2'
 end
 

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

@@ -25,6 +25,7 @@ module Ecoportal
             def same_type?(a, b) # rubocop:disable Naming/MethodParameterName
               msg = "To use this comparison both objects should be `ArrayModel`"
               raise msg unless a.is_a?(ArrayModel) && b.is_a?(ArrayModel)
+
               (a.order_matters? == b.order_matters?) && (a.uniq? == b.uniq?)
             end
           end
@@ -32,7 +33,7 @@ module Ecoportal
           inheritable_class_vars :order_matteres, :uniq
 
           def initialize(doc = [], parent: self, key: nil, read_only: self.class.read_only?)
-            super(doc, parent: parent, key: key, read_only: read_only)
+            super
           end
 
           def order_matters?
@@ -143,20 +144,36 @@ module Ecoportal
             value.all? {|v| _items.include?(v)}
           end
 
+          # @return [Array<Date>, Array<String>, Array<Number] the elements that have
+          #   been added
+          def added_items
+            (doc || []) - (original_doc || [])
+          end
+          alias_method :added, :added_items
+
+          # @return [Array<Date>, Array<String>, Array<Number] the elements that have
+          #   been deleted
+          def deleted_items
+            (original_doc || []) - (doc || [])
+          end
+          alias_method :deleted, :deleted_items
+
           # Adds an element to the subjacent `Array`
           # @note if the class variable `uniq` is `true`, it skips duplicates
           def <<(value)
             _items.concat(into_a(value)).tap do |doc|
               doc.uniq! if uniq?
             end
+
             on_change
             self
           end
 
           # @see #<<
-          def push!(value)
-            self << value
+          def push!(*values)
+            self << values
           end
+          alias_method :push, :push!
 
           # @see #<<
           # @note same as #push! but for multiple elements

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

@@ -5,7 +5,7 @@ module Ecoportal
       module Content
         module ClassHelpers
           include Ecoportal::API::Common::BaseClass
-          NOT_USED = "no_used!".freeze
+          NOT_USED = 'no_used!'.freeze
 
           # Class resolver
           # @note it caches the resolved `klass`es
@@ -124,7 +124,8 @@ module Ecoportal
           #   - 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.
+          # @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
@@ -150,6 +151,7 @@ module Ecoportal
           #   - therefore, `freeze` will be called on the values that are inherited.
           def inherited(subclass)
             super
+
             inheritable_class_vars.each do |var|
               instance_var = instance_variable_name(var)
               value        = instance_variable_get(instance_var)

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

@@ -7,11 +7,16 @@ module Ecoportal
           attr_accessor :logger
 
           # @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", host: "live.ecoportal.com", logger: nil)
-            super(api_key: api_key, version: "v2", host: host, logger: logger)
+          def initialize(
+            api_key:,
+            version: 'v2',
+            host:    'live.ecoportal.com',
+            logger:  nil
+          )
+            super
           end
 
-          def delete(path)
+          def delete(_path)
             raise "DELETE operation does not have integration for api #{@version}"
           end
 
@@ -19,7 +24,7 @@ module Ecoportal
           # @param params [Hash] the header paramters of the http request (not including the api key).
           # @option params [String] :template_id original template.
           def post(path, data:, params: {})
-            instrument("POST", path, params) do
+            instrument('POST', path, params) do
               request do |http|
                 http.post(url_for(path), json: data, params: params)
               end
@@ -30,9 +35,10 @@ module Ecoportal
           # @note It configures HTTP so it only allows body data in json format.
           # @return [HTTP] HTTP object.
           def base_request
-            @base_request ||= HTTP.headers("X-ECOPORTAL-API-KEY" => @api_key).accept(:json)
+            @base_request ||= HTTP.headers(
+              'X-ECOPORTAL-API-KEY' => @api_key
+            ).accept(:json)
           end
-
         end
       end
     end

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

@@ -0,0 +1,33 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class CollectionModel
+          module Doc
+            module Items
+              protected
+
+              def _doc_items
+                replace_doc([]) unless doc.is_a?(Array)
+                doc
+              end
+
+              private
+
+              def to_ini_doc(value)
+                case value
+                when Array
+                  value
+                when Enumerable
+                  value.to_a
+                else
+                  []
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class CollectionModel
+          module Doc
+            module RootedKey
+              class << self
+                include Content::Includer
+
+                def included(base)
+                  super
+                  # to suport call to super:
+                  include_missing(base, DoubleModel::DoubleDoc::RootedKey)
+                  include_missing(base, Doc::Items)
+                  include_missing(base, CollectionModel::Modifiers::ItemsKey)
+                  base.send(:include, InstanceMethods)
+                end
+              end
+
+              module InstanceMethods
+                # Transforms `value` into the actual `key` to access the object in the doc `Array`
+                # @note
+                #   - The name of the method is after the paren't class method
+                #   - 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
+
+                  if (id = get_key(value))
+                    # fetch position
+                    _doc_items.index {|item| get_key(item) == id}
+                  else
+                    show_str = cant_find_child_explanation(value)
+                    raise UnlinkedModel, "Can't find child: #{show_str}"
+                  end
+                end
+
+                private
+
+                def cant_find_child_explanation(value)
+                  case value
+                  when Hash
+                    value.pretty_inspect
+                  when Content::DoubleModel
+                    msg  = "#{value} with key: #{value.class.key} "
+                    msg << "(items_key: #{items_key})"
+                    msg
+                  else
+                    value
+                  end
+                end
+              end
+
+              # INSTANCE METHODS
+
+              def _doc_pos(value)
+                _rooted_doc_key(value)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+require 'ecoportal/api/common/content/collection_model/doc/items'
+require 'ecoportal/api/common/content/collection_model/doc/rooted_key'
+
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class CollectionModel
+          module Doc
+            class << self
+              include Content::Includer
+
+              def included(base)
+                super
+
+                include_missing(base, Items)
+                include_missing(base, RootedKey)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class CollectionModel
+          module DocMutation
+            module Delete
+              class << self
+                def included(base)
+                  super
+                  base.send(:include, CollectionModel::Doc::Items)
+                  base.send(:include, CollectionModel::Doc::RootedKey)
+                end
+              end
+
+              # INSTANCE METHODS
+
+              private
+
+              # Deletes `value` from `doc` (here referred as `_doc_items`)
+              # @return [Object] the element deleted from `doc`
+              def _doc_delete(value)
+                return unless (current_pos = _rooted_doc_key(value))
+
+                _doc_items.delete_at(current_pos)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class CollectionModel
+          module DocMutation
+            module Position
+              class << self
+                def included(base)
+                  super
+                  base.extend Content::ClassHelpers
+                  base.send(:include, CollectionModel::Doc::RootedKey)
+                  base.send(:include, CollectionModel::Model::Lookup)
+                end
+              end
+
+              # INSTANCE METHODS
+
+              private
+
+              def scope_position(pos: NOT_USED, before: NOT_USED, after: NOT_USED)
+                if used_param?(pos)
+                  return unless (elem = self[pos])
+
+                  _rooted_doc_key(elem) - 1
+                elsif used_param?(before)
+                  return unless (elem = self[before])
+
+                  _rooted_doc_key(elem) - 1
+                elsif used_param?(after)
+                  return unless (elem = self[after])
+
+                  _rooted_doc_key(elem)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class CollectionModel
+          module DocMutation
+            module Upsert
+              class << self
+                def included(base)
+                  super
+                  base.send(:include, CollectionModel::Doc::RootedKey)
+                  base.send(:include, DocMutation::Position)
+                end
+              end
+
+              # INSTANCE METHODS
+
+              private
+
+              def _doc_upsert(value, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
+                elem        = self[value]
+                current_pos = nil
+                current_pos = _rooted_doc_key(elem) if elem
+
+                pos   = scope_position(pos: pos, before: before, after: after)
+                pos ||= current_pos
+
+                if current_pos && pos
+                  _doc_items.delete_at(current_pos)
+                  pos -= 1 unless pos <= current_pos
+                end
+
+                pos = _doc_items.length unless pos && pos < _doc_items.length
+
+                pos.tap do |_i|
+                  _doc_items.insert(pos, value)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+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'
+
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class CollectionModel
+          module DocMutation
+            class << self
+              include Content::Includer
+
+              def included(base)
+                super
+
+                include_missing(base, Delete)
+                include_missing(base, Position)
+                include_missing(base, Upsert)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class CollectionModel
+          module Model
+            module Cache
+              class << self
+                include Content::Includer
+
+                def included(base)
+                  super
+
+                  include_missing(base, DoubleModel::VarTracking)
+                  include_missing(base, Model::Items)
+                end
+              end
+
+              # INSTANCE METHODS
+
+              protected
+
+              def on_change
+                @indexed = false
+                #variables_remove! # if ever enabled, move on_change to VarTracking
+              end
+
+              # @note it does not support a change of `id` on an existing item
+              def items_by_key
+                return @items_by_key if @indexed
+
+                {}.tap do |hash|
+                  variable_set(:@items_by_key, hash)
+                  _items.each {|item| hash[item.key] = item}
+                  @indexed = true
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class CollectionModel
+          module Model
+            module Items
+              class << self
+                include Content::Includer
+
+                def included(base)
+                  super
+
+                  include_missing(base, DoubleModel::VarTracking)
+                  include_missing(base, CollectionModel::Modifiers::ItemsKlass)
+                  include_missing(base, CollectionModel::Doc::Items)
+                end
+              end
+
+              # INSTANCE METHODS
+
+              def _items
+                return @_items if @_items
+
+                [].tap do |elements|
+                  # necessary in most cases:
+                  # @todo check if add condition `unless read_only?`
+                  variable_set(:@_items, elements)
+
+                  _doc_items.each do |item_doc|
+                    elements << new_item(item_doc)
+                  end
+
+                  @_items = elements if read_only?
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class CollectionModel
+          module Model
+            module Iterable
+              class << self
+                include Content::Includer
+
+                def included(base)
+                  super
+
+                  include_missing(base, Model::Items)
+                  include_missing(base, Enumerable)
+                end
+              end
+
+              # INSTANCE METHODS
+
+              def each(&block)
+                return to_enum(:each) unless block
+
+                _items.each(&block)
+              end
+
+              def length
+                count
+              end
+
+              def empty?
+                count&.zero?
+              end
+
+              def present?
+                count&.positive?
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class CollectionModel
+          module Model
+            module Lookup
+              class << self
+                include Content::Includer
+
+                def included(base)
+                  super
+
+                  include_missing(base, Model::NumericKey)
+                  include_missing(base, Model::Cache)
+                end
+              end
+
+              # INSTANCE METHODS
+
+              # Get an element usign the `key`.
+              # @param value [String, Hash, Ecoportal::API::Common::Content::DoubleModel]
+              # @return [Object] the `items_class` element object
+              def [](value)
+                items_by_key[get_key(value)]
+              end
+
+              # Checks if an element exists in the collection
+              # @param value [String, Hash, Ecoportal::API::Common::Content::DoubleModel]
+              # @return [Boolean] whether or not it is included
+              def include?(value)
+                items_by_key.key?(get_key(value))
+              end
+
+              # @return [Array<Object>] the `items_class` element object
+              def values_at(*keys)
+                keys.map {|key| self[key]}
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end