ecoportal-api-v2 2.0.12 → 2.0.15

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

@@ -0,0 +1,76 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class DoubleModel
+          module Attributable
+            module Nesting
+              module Embeddable
+                class << self
+                  include Content::Includer
+
+                  def included(base)
+                    super
+                    base.extend Content::ClassHelpers
+
+                    include_missing(base, DoubleModel::VarTracking)
+                    include_missing(base, DoubleModel::Modifiers)
+                    include_missing(base, Attributable::Base)
+
+                    include_missing(base, Nesting::Keyable)
+                    include_missing(base, Nesting::CascadedCallback)
+
+                    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
+
+                    _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)
+
+                      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.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
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,136 @@
+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
+      module Content
+        class DoubleModel
+          module Attributable
+            module Nesting
+              class << self
+                include Content::Includer
+
+                def included(base)
+                  super
+                  base.extend Content::ClassHelpers
+
+                  include_missing(base, DoubleModel::VarTracking)
+                  include_missing(base, DoubleModel::Modifiers)
+
+                  include_missing(base, Attributable::Base)
+                  include_missing(base, Keyable)
+                  include_missing(base, CascadedCallback)
+                  include_missing(base, Embeddable)
+
+                  base.extend ClassMethods
+                end
+              end
+
+              module ClassMethods
+                # 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)
+                  methods.each do |method|
+                    method = method.to_s.freeze
+                    var    = instance_variable_name(method)
+
+                    _cascaded_attribute!(method)
+
+                    dim_class = new_class(method, inherits: ArrayModel) do |klass|
+                      klass.order_matters = order_matters
+                      klass.uniq          = uniq
+                    end
+
+                    define_method method do
+                      return instance_variable_get(var) if instance_variable_defined?(var)
+
+                      dim_class.new(
+                        parent:    self,
+                        key:       method,
+                        read_only: read_only?
+                      ).tap do |new_obj|
+                        variable_set(var, new_obj)
+                        _cascaded_attribute!(method)
+                      end
+                    end
+                  end
+                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
+                # @param nullable [Boolean] to specify if this object can be `nil`
+                # @param read_only [Boolean] if the subjacent model should be read_only
+                # @param klass [Class, String] the class of the embedded object
+                def embeds_one(method, klass:, key: method, read_only: read_only?, nullable: false)
+                  embed(
+                    method,
+                    key:       key,
+                    nullable:  nullable,
+                    read_only: read_only,
+                    multiple:  false,
+                    klass:     klass
+                  )
+                end
+
+                # @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 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
+                # @param read_only [Boolean] whether or not should try to **work around** items `klass` missing a `key`
+                #   - If set to `true` this is meant only for read purposes (won't be able to successufully insert)
+                def embeds_many(
+                  method,
+                  key:           method,
+                  klass:         nil,
+                  enum_class:    nil,
+                  order_matters: false,
+                  order_key:     nil,
+                  read_only:     read_only?
+                )
+                  if enum_class
+                    eclass = enum_class
+                  elsif klass
+                    eclass = new_class("#{method}::#{klass}", inherits: CollectionModel) do |dim_class|
+                      # NOTE: new_class may resolve the namespace of the class to an already existing class
+                      dim_class.klass       ||= klass
+                      dim_class.order_matters = order_matters
+                      dim_class.order_key     = order_key
+                      dim_class.read_only! if read_only
+                    end
+                  else
+                    raise "You should either specify the 'klass' of the elements or the 'enum_class'"
+                  end
+
+                  embed(
+                    method,
+                    key:       key,
+                    multiple:  true,
+                    klass:     eclass,
+                    read_only: read_only
+                  ) do |instance_of_called_method|
+                    # keep reference to the original class to resolve the `klass` dependency
+                    # See stackoverflow: https://stackoverflow.com/a/73709529/4352306
+                    referrer_class = instance_of_called_method.class
+                    # eclass is of type CollectionModel, it must have `::klass` class method.
+                    eclass.klass   = {referrer_class => klass} if klass
+                    # This helps `resolve_class` to correctly resolve a symbol
+                    # by using referrer_class as a base module to resolve it
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class DoubleModel
+          module Attributable
+            module Passthrough
+              class << self
+                include Content::Includer
+
+                def included(base)
+                  super
+
+                  include_missing(base, Attributable::Base)
+
+                  base.extend ClassMethods
+                end
+              end
+
+              module ClassMethods
+                # 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
+
+                    define_method method do
+                      value = send(:doc)[method]
+                      value = yield(value) if block_given?
+                      value
+                    end
+                  end
+                  self
+                end
+
+                # 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
+
+                    define_method "#{method}=" do |value|
+                      value = yield(value) if block_given?
+                      send(:doc)[method] = value
+                    end
+                  end
+                  self
+                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)
+                  pass_writer(*methods) unless read_only
+                  self
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class DoubleModel
+          module Attributable
+            module Simple
+              class << self
+                include Content::Includer
+
+                def included(base)
+                  super
+
+                  include_missing(base, Attributable::Passthrough)
+
+                  base.extend ClassMethods
+                end
+              end
+
+              module ClassMethods
+                # 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)}
+                  pass_writer(*methods) {|value| to_time(value)&.iso8601} unless read_only
+                  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}
+                  pass_writer(*methods) {|value| !!value} unless read_only
+                  self
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+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'
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class DoubleModel
+          module Attributable
+            class << self
+              include Content::Includer
+
+              def included(base)
+                super
+
+                include_missing(base, Base)
+                include_missing(base, Passthrough)
+                include_missing(base, Enforce)
+                include_missing(base, Simple)
+                include_missing(base, Nesting)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class DoubleModel
+          module Base
+            class << self
+              include Content::Includer
+
+              def included(base)
+                super
+                base.extend(Content::ClassHelpers)
+                include_missing(base, Content::ModelHelpers)
+              end
+
+              NOT_USED = ClassHelpers::NOT_USED
+
+              private
+
+              def used_param?(val)
+                self.class.used_param?(val)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class DoubleModel
+          module DiffableModel
+            class << self
+              include Content::Includer
+
+              def included(base)
+                super
+
+                include_missing(base, DoubleModel::HashHelpers)
+                include_missing(base, DoubleModel::DoubleDoc::LinkableDoc)
+                include_missing(base, DoubleModel::Attributable::Nesting::CascadedCallback)
+              end
+            end
+
+            # INSTANCE METHODS
+
+            # @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
+              )
+            end
+
+            # @return [Boolean] stating if there are changes.
+            def dirty?
+              au = as_update
+              return false if au.nil?
+              return false if au == {}
+
+              true
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class DoubleModel
+          module DoubleDoc
+            module Base
+              class << self
+                include Content::Includer
+
+                def included(base)
+                  super
+
+                  include_missing(base, DoubleModel::Modifiers)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class DoubleModel
+          module DoubleDoc
+            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
+                  super(msg)
+                end
+              end
+
+              class << self
+                include Content::Includer
+
+                def included(base)
+                  super
+
+                  include_missing(base, DoubleDoc::Base)
+                  include_missing(base, DoubleDoc::RootedKey)
+                end
+              end
+
+              # INSTANCE METHODS
+
+              def to_json(*args)
+                doc.to_json(*args)
+              end
+
+              def as_json
+                doc
+              end
+
+              def print_pretty
+                puts JSON.pretty_generate(as_json)
+                self
+              end
+
+              # @return [nil, Hash] the underlying `Hash` model as is (carrying current changes)
+              def doc
+                return @doc if doc_var?
+                return @doc if root?
+
+                unless linked?
+                  raise UnlinkedModel.new(
+                    from: "#{self.class}##{__method__}",
+                    key:  _parent_key
+                  )
+                end
+
+                _parent.doc.dig(*resolved_rooted_doc_key)
+              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
+                return @original_doc if root?
+
+                unless linked?
+                  raise UnlinkedModel.new(
+                    from: "#{self.class}##{__method__}",
+                    key:  _parent_key
+                  )
+                end
+
+                _parent.original_doc.dig(*resolved_rooted_doc_key)
+              end
+
+              protected
+
+              # @return [Boolean] can the subjecent model be fetched?
+              def linked?
+                return true if root?
+                return true if _parent.doc
+
+                false
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end