ecoportal-api-v2 0.8.6 → 0.8.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 484fc9b5ba81835c60c8577578726c548dea573b997f028ac2dcc4b5d2a55c77
-  data.tar.gz: 02d65b9252633b691ee87076566a429f3763e47dcbba28d04ce439dfbfa78609
+  metadata.gz: e8961e37170e3ffe06d26c17daa6672a15d595ff91c5e8fb38253549b166057a
+  data.tar.gz: c9b25eb42cfa9cb45cee3d830067eddc7d4191fa87f0fd4e35620e346ca27922
 SHA512:
-  metadata.gz: 258ba907986e16b304f69ca903a7aba2b3daf3ea8d44b1af819e08bd63dfbce5ee2d904cc94bab14f84ecaa0f9d980f498378b53f8bbc35a237e62621f3ea7fd
-  data.tar.gz: 7340b168c888be83c2c2798614b55bb7893bc1fb3819914f99e207805ef4b709f5f34a0b743e31f0345ce2f0d59ebdf3d3154c6a5e6c30b12e8910b2403486e5
+  metadata.gz: a68c58f62600b78745caff84d7e0dbda83e2f79cba8d41ca08ffbcf361060bd614fc6957f38878bb09d41dc6db1fcff3e307dd0072d21d960073683e6881fdbc
+  data.tar.gz: 998e1409fd0674bc409ab2ff1dcfb68f42a0dd37bca8eab040750cc8cc10ca2651fb98dc61adf3d44b0b0dbdc0bccfe384786cdd79ad1fd9ed96d12a00f3a4b4

data/CHANGELOG.md

@@ -1,34 +1,99 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [0.8.6] - 2021-02-xx
+## [0.8.10] - 2021-08-xx
 
 ### Added
-  - `Ecoportal::API::V2::Page::Component::SelectionField` added methods `#numeric!` `#text!`
+  - `Ecoportal::API::Common::Content::CollectionModel#[]` now supports position as well
+  - `Ecoportal::API::V2::Page::Component::FilesField#add_file`: support for adding files
+  - `Ecoportal::API::V2::Page::Component::PeopleField#viewable_fields`: support for managing `viewable_fields`
 
 ### Changed
+
 ### Fixed
+  - `Ecoportal::API::V2::Page::Component::FilesField`: was not requiring `File`
+  - `Ecoportal::API::V2::Page::Component::NumberField#value`: it was missing :/
+  - `Ecoportal::API::Common::Content::HashDiffPatch` did not support nested objects in Arrays, where the nested object wouldn't have a `patch_ver`. This **fix** allows for it
+    - `Ecoportal::API::Common::Content::DoubleModel.passforced` to define `methods` that should always be present. This allows to define `patch_ver` as a forced `key` in models that have it
+      - The enforcement (`self.class.enforce!`) happens on `initialize`
+      - `passenforced` subjacent model `forced_model_keys` is inheritable
+  - `Ecoportal::API::Common::Content::CollectionModel`:
+    - Method `upsert!` was not working fine the parameters `pos`, `before` and `after`
+    - Method `delete!` did not support position
+
+## [0.8.9] - 2021-08-16
 
+### Added
+  - `Ecoportal::API::Common::Content::ModelHelpers`
+    - Starting with `#same_string?`, this lib aims to offer a full set of helper comparers.
+  - `Ecoportal::API::V2::Page::Components#get_by_id`
+    - In future changes, method `[]` might be overriding the method of the parent class `CollectionModel`.
+  - `Ecoportal::API::V2::Page::PermissionFlags` to offer support to `can_permission`, `subscribed`, etc.
+  - `Ecoportal::API::V2::Page::Section#add_component` super handy helper to add fields to sections.
+  - `Ecoportal::API::V2::Page::Component::PeopleField#delete` to remove people using their ids.
+  - `Ecoportal::API::V2::Page::Component::GeoField` **added** suport for `#coordinates`
+    - With embedded object `Ecoportal::API::V2::Page::Component::GeoCoordinates`
+  - `#configure` method, to all the `Component` types (but `ChartField` s)
+    - This method allows to quickly set field properties.
+  - `Ecoportal::API::V2::Page::Sections#between`, aiming to obtain sections between two other ones
 
-## [0.8.5] - 2021-02-22
+
+### Changed
+  - `Ecoportal::API::V2::Page::Section` real support for `split` sections (right vs left)
+    - This is actually a **FIX**
+  - `Ecoportal::API::V2::Page::Component::DateField#create_event`
+    - Now it switches to _allow future dates_
+  - `Ecoportal::API::V2::Page::Component::SelectionField#add_option`, the `name` parameter is now optional
+    - This change aims to make it consistent with the back-end.
+  - To its actual `Boolean` type some properties
+    - All `Component` types
+
+### Fixed
+  - `Ecoportal::API::Common::Content::HashDiffPatch` did not support `Hash` values without `id` or `patch_ver`
+    - This fix should allow them to flow to the update
+  - `Ecoportal::API::V2::Page::Component::ChartField` did not have `doc` for `mode` based configuration
+  - `Ecoportal::API::Common::Content::ArrayModel#insert_one`
+    - When `pos`, `before` & `after` were `nil` it was failing to attach the element.
+  - `Ecoportal::API::V2::Page::Sections#add` was not adding in the correct order
+  - `Ecoportal::API::V2::Page::Section.new_doc` was unnecessarily giving `9999` as default weight
+
+## [0.8.8] - 2021-08-03
 
 ### Added
+  - `Ecoportal::API::V2::Page::Component::ChartField::Benchmark`
+  - Support to convert selection options between numeric and text type.
+  - Add `Permit` object to `Page` and `Stage`
+
 ### Changed
-  - upgrade
+  - Removed `Stages.ordered_stages`: detected bug with Enumerable iteration
+
+
+## [0.8.7] - 2021-05-25
+
+### Changed
+  - Upgrade `ecoportal-api` gem
+
 ### Fixed
+  - Requiring `api/common` from 2 different ends
+
+## [0.8.6] - 2021-02-23
+
+### Added
+  - `Ecoportal::API::V2::Page::Component::SelectionField` added methods `#numeric!` `#text!`
+
+## [0.8.5] - 2021-02-22
+
+### Changed
+  - upgrade
 
 
 ## [0.8.4] - 2021-02-22
 
-### Added
 ### Changed
   - roll back `ecoportal-api` dependency
 
-### Fixed
-
 ## [0.8.3] - 2021-02-22
 
-### Added
 ### Changed
   - updated `rspec` for expected patch data on `delete` operation.
 
@@ -37,23 +102,16 @@ All notable changes to this project will be documented in this file.
 
 ## [0.8.2] - 2021-02-21
 
-### Added
 ### Changed
   - some necessary changes for the new gem to be active
 
-### Fixed
-
 ## [0.8.1] - 2021-02-21
 
-### Added
 ### Changed
   - renamed parameters (backwards incompatible change):
     - `Ecoportal::API::V2::Pages::Stages` methods `#get` and `#update`
       - updated `Ecoportal::API::V2::Pages#` accordingly
 
-### Fixed
-
-
 ## MOVED TO GEM `ecoportal-api-v2` ##
 
 ## [0.7.5] - 2021-02-21
@@ -147,42 +205,29 @@ All notable changes to this project will be documented in this file.
   - automatic key builder
     - helper: `Ecoportal::API::V2::v2key` method
     - `user_key:` and `org_key:` as constructor methods for `Ecoportal::API::V2`
-### Changed
-### Fixed
 
 ## [0.7.1] - 2020-10-07
 
-### Added
 ### Changed
   - updated dependencies
-### Fixed
-
 
 ## [0.7.0] - 2020-09-10
 
-### Added
 ### Changed
   - updated dependencies
-### Fixed
 
 ## [0.6.1] - 2020-07-11
 
 ### Added
   - `Ecoportal::API::Common::Content::DoubleModel#pretty_print`
-### Changed
-### Fixed
 
 ## [0.6.0] - 2020-07-11
 
-### Added
 ### Changed
   - upgraded `ecoportal-api` gem
-### Fixed
 
 ## [0.5.9] - 2020-07-02
 
 ### Added
   - helper `Ecoportal::API::Common::Content::StringDigest#indexable_label`: to see the part of a label that gets indexed
   - this `CHANGELOG.md` file
-### Changed
-### Fixed

data/bin/console

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 require "bundler/setup"
-require "ecoportal/api"
+require "ecoportal/api-v2"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.

data/ecoportal-api-v2.gemspec

@@ -1,11 +1,11 @@
 
 lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "ecoportal/api/v2/version"
+require "ecoportal/api/v2_version"
 
 Gem::Specification.new do |spec|
   spec.name          = "ecoportal-api-v2"
-  spec.version       = Ecoportal::API::V2::GEM_VERSION
+  spec.version       = Ecoportal::API::GEM2_VERSION
   spec.authors       = ["Oscar Segura"]
   spec.email         = ["rien@ecoportal.co.nz", "oscar@ecoportal.co.nz", "bozydar@ecoportal.co.nz"]
 
@@ -22,12 +22,12 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler",   ">= 2.2.11",  "< 2.3"
+  spec.add_development_dependency "bundler",   ">= 2.2.17", "< 2.3"
   spec.add_development_dependency "rspec",     ">= 3.10.0", "< 3.11"
   spec.add_development_dependency "rake",      ">= 13.0.3", "< 13.1"
   spec.add_development_dependency "yard",      ">= 0.9.26", "< 0.10"
   spec.add_development_dependency "redcarpet", ">= 3.5.1",  "< 3.6"
-  spec.add_development_dependency "pry"      , "~> 0.14"
+  spec.add_development_dependency "pry"      , ">= 0.14"
 
-  spec.add_dependency 'ecoportal-api', '>= 0.8.1', '< 0.9'
+  spec.add_dependency 'ecoportal-api', '>= 0.8.3', '< 0.9'
 end

data/lib/ecoportal/api-v2.rb

@@ -1,10 +1,10 @@
 require "ecoportal/api"
-require "ecoportal/api/v2/version"
+require "ecoportal/api/v2_version"
 
 module Ecoportal
   module API
   end
 end
 
-require_relative "api/common"
+require_relative "api/common.v2"
 require_relative "api/v2"

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

@@ -0,0 +1,8 @@
+module Ecoportal
+  module API
+    module Common
+    end
+  end
+end
+
+require 'ecoportal/api/common/content'

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

@@ -9,6 +9,7 @@ end
 
 require 'ecoportal/api/common/content/class_helpers'
 require 'ecoportal/api/common/content/string_digest'
+require 'ecoportal/api/common/content/model_helpers'
 require 'ecoportal/api/common/content/double_model'
 require 'ecoportal/api/common/content/array_model'
 require 'ecoportal/api/common/content/collection_model'

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

@@ -3,7 +3,8 @@ module Ecoportal
     module Common
       module Content
         # Class to handle a plain Array embedded in a Hashed model.
-        # @note its purpose is to handle an Array of basic objects (i.e. `Date`, `String`, `Number`)
+        # @note
+        #   - Its purpose is to handle an Array of basic objects (i.e. `Date`, `String`, `Number`)
         class ArrayModel < Content::DoubleModel
           class TypeMismatchedComparison < Exception
             def initialize (this: nil, that: msg = "Trying to compare objects with different behavior.")
@@ -222,15 +223,16 @@ module Ecoportal
           def insert_one(value, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
             i = index(value)
             return i if (i && uniq?)
-
             pos = case
                   when used_param?(pos)
-                    pos
+                    pos || length
                   when used_param?(before)
-                    index(before)
+                    before ? index(before) : length
                   when used_param?(after)
-                    if i = index(after)
-                      i + 1
+                    if after
+                      if i = index(after) then i + 1 end
+                    else
+                      length
                     end
                   else
                     length

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

@@ -2,6 +2,9 @@ module Ecoportal
   module API
     module Common
       module Content
+        # CollectionModel aims to deal with Arrays of actual objects.
+        # @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
 
           class << self
@@ -140,17 +143,21 @@ module Ecoportal
           end
 
           # 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
 
+          # @return [Array<Object>] the `items_class` element object
           def values_at(*keys)
             keys.map {|key| self[key]}
           end
 
           # Tries to find the element `value`, if it exists, it updates it
-          # Otherwise it pushes it to the end
-          # @return the element
+          #   Otherwise it pushes it to the end
+          # @value [Hash, Ecoportal::API::Common::Content::DoubleModel] the eleement to be added
+          # @return [Object] the `items_class` element object
           def upsert!(value, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
             unless value.is_a?(Hash) || value.is_a?(Content::DoubleModel)
               raise "'Content::DoubleModel' or 'Hash' doc required"
@@ -160,15 +167,20 @@ module Ecoportal
             if item = self[value]
               item.replace_doc(item_doc)
             else
-              _doc_upsert(item_doc, pos: pos, before: before, after: after)
+              pos_idx = _doc_upsert(item_doc, pos: pos, before: before, after: after)
             end
             (item || self[item_doc]).tap do |item|
               yield(item) if block_given?
             end
           end
 
+          # Deletes `value` from this `CollectionModel` instance
+          # @param value [String, Hash, Ecoportal::API::Common::Content::DoubleModel]
+          #   - When used as `String`, the `key` value (i.e. `id` value) is expected
+          #   - When used as `Hash`, it should be the `doc` of the target element
+          #   - When used as `DoubleModel`, it should be the specific object to be deleted
           def delete!(value)
-            unless value.is_a?(Hash) || value.is_a?(Content::DoubleModel)
+            unless value.is_a?(Hash) || value.is_a?(Content::DoubleModel) || value.is_a?(String)
               raise "'Content::DoubleModel' or 'Hash' doc required"
             end
             if item = self[value]
@@ -186,7 +198,7 @@ module Ecoportal
             variables_remove!
           end
 
-          # Gets the `key` of the object
+          # Gets the `key` of the object `value`
           def get_key(value)
             case value
             when Content::DoubleModel
@@ -195,6 +207,8 @@ module Ecoportal
               value[items_key]
             when String
               value
+            when Numeric
+              get_key(self.to_a[value])
             end
           end
 
@@ -235,27 +249,22 @@ module Ecoportal
             super
           end
 
+          # Deletes `value` from `doc` (here referred as `_doc_items`)
+          # @return [Object] the element deleted from `doc`
           def _doc_delete(value)
             if current_pos = _doc_key(value)
-              _doc_items.delete_at(current_pos)
-              on_change
+              _doc_items.delete_at(current_pos).tap do |deleted|
+                on_change
+              end
             end
           end
 
           def _doc_upsert(value, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
-            current_pos = _doc_key(value)
-            pos = case
-              when used_param?(pos)
-                pos
-              when used_param?(before)
-                _doc_key(before)
-              when used_param?(after)
-                #puts "to add after #{after.id}"
-                if i = _doc_key(after)
-                  i + 1
-                end
-              end
+            current_pos = if elem = self[value]
+              _doc_key(elem)
+            end
 
+            pos   = scope_position(pos: pos, before: before, after: after)
             pos ||= current_pos
 
             if current_pos && pos
@@ -264,7 +273,6 @@ module Ecoportal
             end
 
             pos = (pos && pos < _doc_items.length)? pos : _doc_items.length
-
             pos.tap do |i|
               _doc_items.insert(pos, value)
               on_change
@@ -272,6 +280,23 @@ module Ecoportal
 
           end
 
+          def scope_position(pos: NOT_USED, before: NOT_USED, after: NOT_USED)
+            case
+            when used_param?(pos)
+              if elem = self[pos]
+                _doc_key(elem) - 1
+              end
+            when used_param?(before)
+              if elem = self[before]
+                _doc_key(elem) - 1
+              end
+            when used_param?(after)
+              if elem = self[after]
+                _doc_key(elem)
+              end
+            end
+          end
+
         end
       end
     end

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

@@ -10,6 +10,7 @@ module Ecoportal
         class DoubleModel < Common::BaseModel
           NOT_USED = Common::Content::ClassHelpers::NOT_USED
           extend Common::Content::ClassHelpers
+          include Common::Content::ModelHelpers
 
           class UnlinkedModel < Exception
             def initialize (msg = "Something went wrong when linking the document.", from: nil, key: nil)
@@ -36,6 +37,8 @@ module Ecoportal
 
             # Same as `attr_reader` but links to a subjacent `Hash` model property
             # @note it does **not** create an _instance variable_
+            # @param methods [Array<Symbol>] the method that exposes the value
+            #   as well as its `key` in the underlying `Hash` model.
             def pass_reader(*methods)
               methods.each do |method|
                 method = method.to_s.freeze
@@ -51,6 +54,8 @@ module Ecoportal
 
             # Same as `attr_writer` but links to a subjacent `Hash` model property
             # @note it does **not** create an _instance variable_
+            # @param methods [Array<Symbol>] the method that exposes the value
+            #   as well as its `key` in the underlying `Hash` model.
             def pass_writer(*methods)
               methods.each do |method|
                 method = method.to_s.freeze
@@ -69,6 +74,8 @@ module Ecoportal
             #  no chance you can avoid invinite loop for `get_key` 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)
@@ -90,7 +97,33 @@ module Ecoportal
               self
             end
 
+            # These are methods that should always be present in patch update
+            # @note
+            #    - `DoubleModel` can be used with objects that do not use `patch_ver`
+            #    - This ensures that does that do, will get the correct patch update model
+            # @param method [Symbol] the method that exposes the value
+            #   as well as its `key` in the underlying `Hash` model.
+            # @param default [Value] the default value that
+            #   this `key` will be written in the model when it doesn't exixt
+            def passforced(method, default: , read_only: false)
+              model_forced_keys[method.to_s.freeze] = default
+              passthrough(method, read_only: read_only)
+            end
+
+            # Ensures `doc` has the `model_forced_keys`. If it doesn't, it adds those missing
+            #   with the defined `default` values
+            def enforce!(doc)
+              return unless doc && doc.is_a?(Hash)
+              return if model_forced_keys.empty?
+              model_forced_keys.each do |key, default|
+                doc[key] = default unless doc.key?(key)
+              end
+              doc
+            end
+
             # Same as `attr_accessor` but links to a subjacent `Hash` model property
+            # @param methods [Array<Symbol>] the method that exposes the value
+            #   as well as its `key` in the underlying `Hash` model.
             # @param read_only [Boolean] should it only define the reader?
             def passthrough(*methods, read_only: false)
               pass_reader *methods
@@ -100,6 +133,8 @@ module Ecoportal
 
             # To link as a `Time` date to a subjacent `Hash` model property
             # @see Ecoportal::API::Common::Content::DoubleModel#passthrough
+            # @param methods [Array<Symbol>] the method that exposes the value
+            #   as well as its `key` in the underlying `Hash` model.
             # @param read_only [Boolean] should it only define the reader?
             def passdate(*methods, read_only: false)
               pass_reader(*methods) {|value| to_time(value)}
@@ -109,7 +144,21 @@ module Ecoportal
               self
             end
 
+            # To link as a `Boolean` to a subjacent `Hash` model property
+            # @param methods [Array<Symbol>] the method that exposes the value
+            #   as well as its `key` in the underlying `Hash` model.
+            # @param read_only [Boolean] should it only define the reader?
+            def passboolean(*methods, read_only: false)
+              pass_reader(*methods) {|value| value}
+              unless read_only
+                pass_writer(*methods) {|value| !!value}
+              end
+              self
+            end
+
             # To link as plain `Array` to a subjacent `Hash` model property
+            # @param methods [Array<Symbol>] the method that exposes the value
+            #   as well as its `key` in the underlying `Hash` model.
             # @param order_matters [Boolean] does the order matter
             # @param uniq [Boolean] should it contain unique elements
             def passarray(*methods, order_matters: true, uniq: true)
@@ -131,6 +180,10 @@ module Ecoportal
             end
 
             # Helper to embed one nested object under one property
+            # @param method [Symbol] the method that exposes the embeded object
+            # @param key [Symbol] the `key` that embeds it to the underlying `Hash` model
+            # @nullable [Boolean] to specify if this object can be `nil`
+            # @param klass [Class, String] the class of the embedded object
             def embeds_one(method, key: method, nullable: false, klass:)
               embed(method, key: key, nullable: nullable, multiple: false, klass: klass)
             end
@@ -138,7 +191,11 @@ module Ecoportal
             # @note
             #   - if you have a dedicated `Enumerable` class to manage `many`, you should use `:enum_class`
             #   - otherwise, just indicate the child class in `:klass` and it will auto generate the class
-            # @param
+            # @param method [Symbol] the method that exposes the embeded object
+            # @param key [Symbol] the `key` that embeds it to the underlying `Hash` model
+            # @param order_matters [Boolean] to state if the order will matter
+            # @param klass [Class, String] the class of the individual elements it embeds
+            # @param enum_class [Class, String] the class of the collection that will hold the individual elements
             def embeds_many(method, key: method, order_matters: false, order_key: nil, klass: nil, enum_class: nil)
               if enum_class
                 eclass = enum_class
@@ -151,7 +208,7 @@ module Ecoportal
               else
                 raise "You should either specify the 'klass' of the elements or the 'enum_class'"
               end
-              embed(method, key: key, multiple: true, klass: eclass)              
+              embed(method, key: key, multiple: true, klass: eclass)
             end
 
             private
@@ -175,8 +232,15 @@ module Ecoportal
               end
             end
 
+            # The list of keys that will be forced in the model
+            def model_forced_keys
+              @forced_model_keys ||= {}
+            end
+
           end
 
+          inheritable_class_vars :forced_model_keys
+          
           attr_reader :_parent, :_key
 
           def initialize(doc = {}, parent: self, key: nil)
@@ -184,6 +248,8 @@ module Ecoportal
             @_parent   = parent || self
             @_key      = key    || self
 
+            self.class.enforce!(doc)
+
             if _parent == self
               @doc          = doc
               @original_doc = JSON.parse(@doc.to_json)
@@ -200,11 +266,13 @@ module Ecoportal
             _parent.root
           end
 
+          # @return [String] the `value` of the `key` method (i.e. `id` value)
           def key
             raise "No key_method defined for #{self.class}" unless key_method?
             self.method(key_method).call
           end
 
+          # @param [String] the `value` of the `key` method (i.e. `id` value)
           def key=(value)
             raise "No key_method defined for #{self.class}" unless key_method?
             method = "#{key_method}="
@@ -223,16 +291,25 @@ module Ecoportal
             end
           end
 
+          # @return [nil, Hash] the underlying `Hash` model as is (carrying current changes)
           def doc
             raise UnlinkedModel.new(from: "#{self.class}#doc", key: _key) unless linked?
-            return @doc if is_root?
-            _parent.doc.dig(*[_doc_key(_key)].flatten)
+            if is_root?
+              @doc
+            else
+              _parent.doc.dig(*[_doc_key(_key)].flatten)
+            end
           end
 
+          # The `original_doc` holds the model as is now on server-side.
+          # @return [nil, Hash] the underlying `Hash` model as after last `consolidate!` changes
           def original_doc
             raise UnlinkedModel.new(from: "#{self.class}#original_doc", key: _key) unless linked?
-            return @original_doc if is_root?
-            _parent.original_doc.dig(*[_doc_key(_key)].flatten)
+            if is_root?
+              @original_doc
+            else
+              _parent.original_doc.dig(*[_doc_key(_key)].flatten)
+            end
           end
 
           def as_json
@@ -243,25 +320,37 @@ module Ecoportal
             doc.to_json(*args)
           end
 
+          # @return [nil, Hash] the patch `Hash` model including only the changes between
+          #   `original_doc` and `doc`
           def as_update
             new_doc = as_json
             Common::Content::HashDiffPatch.patch_diff(new_doc, original_doc)
           end
 
+          # @return [Boolean] stating if there are changes
           def dirty?
             as_update != {}
           end
 
+          # It makes `original_doc` to be like `doc`
+          # @note
+          #   - after executing it, there will be no pending changes
+          #   - you should technically run this command, after a successful update request to the server
           def consolidate!
             replace_original_doc(JSON.parse(doc.to_json))
           end
 
+          # It makes `doc` to be like `original`
+          # @note
+          #   - after executing it, changes in `doc` will be lost
+          #   - you should technically run this command only if you want to remove certain changes
+          # @key [Symbol] the specific part of the model you want to `reset`
           def reset!(key = nil)
             if key
-              keys    = [].push(key).compact
+              keys    = [key].flatten.compact
               odoc    = original_doc.dig(*keys)
-              dig_set(doc, key, odoc && JSON.parse(odoc.to_json))
-
+              odoc    = odoc && JSON.parse(odoc.to_json)
+              dig_set(doc, keys, odoc)
             else
               replace_doc(JSON.parse(original_doc.to_json))
             end